HarmonyOS开发：灰度发布分阶段发布

📌 核心要点：灰度发布是版本发布的安全网——先让一小部分用户用上新版本，确认没问题再逐步扩大。配置好灰度规则、监控好灰度数据、准备好回滚方案，你的每次发布都能稳如老狗。

背景与动机

你有没有见过这种事故？

某大厂App推送了一个新版本，结果几百万用户同时遭遇闪退。热搜上了，股价跌了，CEO出来道歉了。

如果他们用了灰度发布，这种事根本不会发生。先让1%的用户更新，发现闪退立刻停掉，影响范围缩小到几万人而不是几百万人。

灰度发布不是什么高深技术，但它是版本发布中最实用的一道保险。你不需要每次都用，但当你改了核心逻辑、重构了关键模块、引入了新的第三方SDK时，灰度发布就是你的救命稻草。

这篇文章，把灰度发布的策略设计、规则配置、监控回滚、数据分析全部讲透。

核心原理

灰度发布核心流程

graph TD
    A[提交新版本] --> B[配置灰度规则]
    B --> C[第1轮: 1-5%用户]
    C --> D{监控数据正常?}
    D -->|是| E[扩大灰度范围]
    D -->|否| F[暂停灰度/回滚]
    F --> G[定位问题]
    G --> H[修复后重新灰度]
    E --> I[第2轮: 10-20%用户]
    I --> J{监控数据正常?}
    J -->|是| K[继续扩大]
    J -->|否| F
    K --> L[第3轮: 50%用户]
    L --> M{监控数据正常?}
    M -->|是| N[全量发布]
    M -->|否| F

    classDef startStyle fill:#FF6B35,stroke:#D4551F,color:#fff,font-weight:bold
    classDef processStyle fill:#4ECDC4,stroke:#3BA99C,color:#fff
    classDef decisionStyle fill:#FFE66D,stroke:#D4B93C,color:#333,font-weight:bold
    classDef dangerStyle fill:#FF6B6B,stroke:#CC5555,color:#fff
    classDef successStyle fill:#96CEB4,stroke:#6DAF8E,color:#fff,font-weight:bold
    
    class A,B startStyle
    class C,E,I,K,L,N processStyle
    class D,J,M decisionStyle
    class F,G,H dangerStyle

灰度发布的本质就是：控制爆炸半径。让新版本的潜在问题只影响一小部分用户，而不是全量用户。

灰度规则维度

灰度规则可以从多个维度配置，不同维度组合使用效果更好：

灰度节奏设计

灰度不是一蹴而就的，要分阶段推进。每阶段之间留出观察窗口，收集数据后再决定是否继续。

推荐节奏：

代码实战

基础用法：灰度规则配置

// entry/src/main/ets/utils/GrayPublishManager.ets
// 灰度发布管理器——控制用户是否命中灰度策略

import { hilog } from '@kit.PerformanceAnalysisKit';
import { preferences } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';

// 灰度规则
interface GrayRule {
  enabled: boolean;              // 是否启用灰度
  percentage: number;            // 灰度比例（0-100）
  regions: string[];             // 灰度地域
  deviceTypes: string[];         // 灰度设备类型
  minOsVersion: string;          // 最低系统版本
  userTags: string[];            // 用户标签
  startTime: number;             // 灰度开始时间
  endTime: number;               // 灰度结束时间
}

// 灰度阶段
interface GrayPhase {
  name: string;                  // 阶段名称
  percentage: number;            // 灰度比例
  durationHours: number;         // 持续时长
  crashRateThreshold: number;    // 崩溃率阈值
  anrRateThreshold: number;      // ANR率阈值
  autoRollback: boolean;         // 是否自动回滚
}

export class GrayPublishManager {
  private static instance: GrayPublishManager;
  private context: common.Context | null = null;
  private currentRule: GrayRule | null = null;
  private phases: GrayPhase[] = [];

  static getInstance(): GrayPublishManager {
    if (!GrayPublish.instance) {
      GrayPublish.instance = new GrayPublishManager();
    }
    return GrayPublish.instance;
  }

  // 初始化
  async init(context: common.Context): Promise<void> {
    this.context = context;
    await this.loadGrayRule();
    this.initDefaultPhases();
  }

  // 判断当前用户是否命中灰度
  async isGrayUser(): Promise<boolean> {
    if (!this.currentRule || !this.currentRule.enabled) {
      return false;
    }

    // 检查时间范围
    const now = Date.now();
    if (now < this.currentRule.startTime || now > this.currentRule.endTime) {
      return false;
    }

    // 检查地域
    if (this.currentRule.regions.length > 0) {
      const userRegion = await this.getUserRegion();
      if (!this.currentRule.regions.includes(userRegion)) {
        return false;
      }
    }

    // 检查设备类型
    if (this.currentRule.deviceTypes.length > 0) {
      const deviceType = this.getDeviceType();
      if (!this.currentRule.deviceTypes.includes(deviceType)) {
        return false;
      }
    }

    // 按用户比例灰度
    const userId = await this.getUserId();
    const hash = this.hashUserId(userId);
    const threshold = this.currentRule.percentage * 0.01;
    
    return (hash % 100) < (threshold * 100);
  }

  // 获取当前灰度阶段
  getCurrentPhase(): GrayPhase | null {
    if (this.phases.length === 0) return null;
    
    // 根据当前灰度比例匹配阶段
    if (!this.currentRule) return null;
    
    for (const phase of this.phases) {
      if (this.currentRule.percentage <= phase.percentage) {
        return phase;
      }
    }
    return this.phases[this.phases.length - 1];
  }

  // 获取灰度状态信息
  getGrayStatus(): {
    isGrayUser: boolean;
    currentPhase: string;
    percentage: number;
    remainingPhases: number;
  } {
    const phase = this.getCurrentPhase();
    return {
      isGrayUser: false, // 需要异步获取，这里简化
      currentPhase: phase?.name ?? '未配置',
      percentage: this.currentRule?.percentage ?? 0,
      remainingPhases: phase ? this.phases.indexOf(phase) + 1 : 0
    };
  }

  // 用户ID哈希——确保同一用户始终命中相同结果
  private hashUserId(userId: string): number {
    let hash = 0;
    for (let i = 0; i < userId.length; i++) {
      const char = userId.charCodeAt(i);
      hash = ((hash << 5) - hash) + char;
      hash = hash & hash; // 转为32位整数
    }
    return Math.abs(hash);
  }

  // 获取用户ID
  private async getUserId(): Promise<string> {
    if (!this.context) return 'anonymous';
    
    try {
      const pref = await preferences.getPreferences(this.context, 'user_config');
      let userId = await pref.get('user_id', '') as string;
      
      if (!userId) {
        userId = `user_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
        await pref.put('user_id', userId);
        await pref.flush();
      }
      
      return userId;
    } catch (error) {
      return 'anonymous';
    }
  }

  // 获取用户地域
  private async getUserRegion(): Promise<string> {
    // 实际项目中通过定位或IP获取
    return 'beijing';
  }

  // 获取设备类型
  private getDeviceType(): string {
    // 实际项目中通过设备信息获取
    return 'phone';
  }

  // 加载灰度规则
  private async loadGrayRule(): Promise<void> {
    if (!this.context) return;
    
    try {
      const pref = await preferences.getPreferences(this.context, 'gray_config');
      const enabled = await pref.get('gray_enabled', false) as boolean;
      const percentage = await pref.get('gray_percentage', 0) as number;
      
      this.currentRule = {
        enabled,
        percentage,
        regions: [],
        deviceTypes: [],
        minOsVersion: '12.0.0',
        userTags: [],
        startTime: Date.now() - 86400000,
        endTime: Date.now() + 86400000 * 7
      };
    } catch (error) {
      hilog.warn(0x0000, 'GrayPublish', '加载灰度规则失败，使用默认配置');
      this.currentRule = {
        enabled: false,
        percentage: 0,
        regions: [],
        deviceTypes: [],
        minOsVersion: '12.0.0',
        userTags: [],
        startTime: 0,
        endTime: 0
      };
    }
  }

  // 初始化默认灰度阶段
  private initDefaultPhases(): void {
    this.phases = [
      {
        name: '内测阶段',
        percentage: 5,
        durationHours: 48,
        crashRateThreshold: 1,
        anrRateThreshold: 2,
        autoRollback: true
      },
      {
        name: '小范围灰度',
        percentage: 20,
        durationHours: 24,
        crashRateThreshold: 1.5,
        anrRateThreshold: 3,
        autoRollback: true
      },
      {
        name: '中范围灰度',
        percentage: 50,
        durationHours: 12,
        crashRateThreshold: 2,
        anrRateThreshold: 4,
        autoRollback: true
      },
      {
        name: '全量发布',
        percentage: 100,
        durationHours: 0,
        crashRateThreshold: 2,
        anrRateThreshold: 4,
        autoRollback: false
      }
    ];
  }
}

进阶用法：灰度监控与回滚

灰度发布最核心的不是"怎么发"，而是"发了之后怎么看"和"出了问题怎么回"。

// entry/src/main/ets/utils/GrayMonitor.ets
// 灰度监控与回滚——灰度发布的安全网

import { hilog } from '@kit.PerformanceAnalysisKit';

// 灰度监控指标
interface GrayMetrics {
  timestamp: number;
  versionCode: number;
  grayPercentage: number;
  totalUsers: number;
  grayUsers: number;
  
  // 稳定性指标
  crashRate: number;          // 崩溃率（百分比）
  anrRate: number;            // ANR率（百分比）
  launchSuccessRate: number;  // 启动成功率（百分比）
  
  // 性能指标
  coldLaunchTime: number;     // 冷启动时间（毫秒）
  hotLaunchTime: number;      // 热启动时间（毫秒）
  
  // 业务指标
  coreFeatureUsage: number;   // 核心功能使用率（百分比）
  userRetention: number;      // 次日留存率（百分比）
  negativeFeedback: number;   // 差评数
}

// 对比数据（新版本 vs 旧版本）
interface GrayComparison {
  metric: string;
  oldValue: number;
  newValue: number;
  changeRate: number;  // 变化率（百分比）
  isWorse: boolean;    // 是否恶化
}

// 回滚决策
interface RollbackDecision {
  shouldRollback: boolean;
  confidence: number;    // 置信度（0-1）
  reasons: string[];
  affectedMetrics: string[];
  recommendedAction: string;
}

export class GrayMonitor {
  private metricsHistory: GrayMetrics[] = [];
  private baselineMetrics: GrayMetrics | null = null; // 旧版本基线数据

  // 设置基线数据（旧版本的数据）
  setBaseline(metrics: GrayMetrics): void {
    this.baselineMetrics = metrics;
    hilog.info(0x0000, 'GrayMonitor', '基线数据已设置');
  }

  // 上报灰度指标
  reportMetrics(metrics: GrayMetrics): void {
    this.metricsHistory.push(metrics);
    
    // 只保留最近200条
    if (this.metricsHistory.length > 200) {
      this.metricsHistory.shift();
    }

    hilog.info(0x0000, 'GrayMonitor', 
      `灰度指标上报: 崩溃率=${metrics.crashRate.toFixed(2)}%, ` +
      `ANR率=${metrics.anrRate.toFixed(2)}%, ` +
      `灰度用户=${metrics.grayUsers}`);
  }

  // 对比新旧版本数据
  compareWithBaseline(): GrayComparison[] {
    if (!this.baselineMetrics || this.metricsHistory.length === 0) {
      return [];
    }

    const latest = this.metricsHistory[this.metricsHistory.length - 1];
    const baseline = this.baselineMetrics;

    const comparisons: GrayComparison[] = [
      this.createComparison('崩溃率', baseline.crashRate, latest.crashRate, true),
      this.createComparison('ANR率', baseline.anrRate, latest.anrRate, true),
      this.createComparison('启动成功率', baseline.launchSuccessRate, latest.launchSuccessRate, false),
      this.createComparison('冷启动时间', baseline.coldLaunchTime, latest.coldLaunchTime, true),
      this.createComparison('核心功能使用率', baseline.coreFeatureUsage, latest.coreFeatureUsage, false),
      this.createComparison('次日留存率', baseline.userRetention, latest.userRetention, false),
      this.createComparison('差评数', baseline.negativeFeedback, latest.negativeFeedback, true)
    ];

    return comparisons;
  }

  // 创建对比项
  private createComparison(
    metric: string, 
    oldValue: number, 
    newValue: number, 
    lowerIsBetter: boolean
  ): GrayComparison {
    const changeRate = oldValue > 0 
      ? ((newValue - oldValue) / oldValue) * 100 : 0;
    const isWorse = lowerIsBetter 
      ? newValue > oldValue * 1.2  // 恶化超过20%视为显著
      : newValue < oldValue * 0.8;

    return { metric, oldValue, newValue, changeRate, isWorse };
  }

  // 生成回滚决策
  makeRollbackDecision(): RollbackDecision {
    if (this.metricsHistory.length === 0) {
      return {
        shouldRollback: false,
        confidence: 0,
        reasons: ['无监控数据'],
        affectedMetrics: [],
        recommendedAction: '等待数据上报'
      };
    }

    const latest = this.metricsHistory[this.metricsHistory.length - 1];
    const reasons: string[] = [];
    const affectedMetrics: string[] = [];
    let severityScore = 0;

    // 崩溃率检查
    if (latest.crashRate > 5) {
      reasons.push(`崩溃率${latest.crashRate.toFixed(1)}%严重超标（阈值5%）`);
      affectedMetrics.push('崩溃率');
      severityScore += 3;
    } else if (latest.crashRate > 2) {
      reasons.push(`崩溃率${latest.crashRate.toFixed(1)}%偏高（阈值2%）`);
      affectedMetrics.push('崩溃率');
      severityScore += 1;
    }

    // ANR率检查
    if (latest.anrRate > 10) {
      reasons.push(`ANR率${latest.anrRate.toFixed(1)}%严重超标（阈值10%）`);
      affectedMetrics.push('ANR率');
      severityScore += 3;
    } else if (latest.anrRate > 4) {
      reasons.push(`ANR率${latest.anrRate.toFixed(1)}%偏高（阈值4%）`);
      affectedMetrics.push('ANR率');
      severityScore += 1;
    }

    // 启动成功率检查
    if (latest.launchSuccessRate < 95) {
      reasons.push(`启动成功率${latest.launchSuccessRate.toFixed(1)}%低于95%`);
      affectedMetrics.push('启动成功率');
      severityScore += 2;
    }

    // 冷启动时间检查
    if (latest.coldLaunchTime > 5000) {
      reasons.push(`冷启动时间${latest.coldLaunchTime}ms超过5秒`);
      affectedMetrics.push('冷启动时间');
      severityScore += 1;
    }

    // 与基线对比
    const comparisons = this.compareWithBaseline();
    const worseMetrics = comparisons.filter(c => c.isWorse);
    if (worseMetrics.length >= 3) {
      reasons.push(`${worseMetrics.length}项指标相比旧版本恶化`);
      severityScore += 2;
    }

    // 计算置信度（数据越多置信度越高）
    const confidence = Math.min(this.metricsHistory.length / 10, 1);

    // 生成建议
    let recommendedAction = '继续灰度';
    if (severityScore >= 5) {
      recommendedAction = '立即回滚，全量恢复旧版本';
    } else if (severityScore >= 3) {
      recommendedAction = '暂停灰度扩大，持续观察24小时';
    } else if (severityScore >= 1) {
      recommendedAction = '继续灰度但加强监控';
    }

    return {
      shouldRollback: severityScore >= 5,
      confidence,
      reasons: reasons.length > 0 ? reasons : ['各项指标正常'],
      affectedMetrics,
      recommendedAction
    };
  }

  // 生成灰度监控报告
  generateReport(): string {
    const decision = this.makeRollbackDecision();
    const comparisons = this.compareWithBaseline();
    
    let report = '=== 灰度监控报告 ===\n\n';
    
    if (this.metricsHistory.length > 0) {
      const latest = this.metricsHistory[this.metricsHistory.length - 1];
      report += `灰度比例: ${latest.grayPercentage}%\n`;
      report += `灰度用户: ${latest.grayUsers}/${latest.totalUsers}\n`;
      report += `崩溃率: ${latest.crashRate.toFixed(2)}%\n`;
      report += `ANR率: ${latest.anrRate.toFixed(2)}%\n`;
      report += `启动成功率: ${latest.launchSuccessRate.toFixed(1)}%\n`;
      report += `冷启动时间: ${latest.coldLaunchTime}ms\n\n`;
    }

    // 新旧版本对比
    if (comparisons.length > 0) {
      report += '--- 新旧版本对比 ---\n';
      comparisons.forEach(c => {
        const icon = c.isWorse ? '⚠️' : '✅';
        report += `${icon} ${c.metric}: ${c.oldValue.toFixed(1)} → ${c.newValue.toFixed(1)} (${c.changeRate >= 0 ? '+' : ''}${c.changeRate.toFixed(1)}%)\n`;
      });
      report += '\n';
    }

    // 回滚决策
    report += '--- 回滚决策 ---\n';
    report += `是否回滚: ${decision.shouldRollback ? '是' : '否'}\n`;
    report += `置信度: ${(decision.confidence * 100).toFixed(0)}%\n`;
    report += `原因: ${decision.reasons.join('; ')}\n`;
    report += `建议: ${decision.recommendedAction}\n`;

    return report;
  }
}

完整示例：灰度发布全流程管理

把灰度规则、监控、回滚整合在一起，实现完整的灰度发布管理。

// entry/src/main/ets/utils/GrayPublishController.ets
// 灰度发布全流程控制器——从规则配置到监控回滚的一站式管理

import { hilog } from '@kit.PerformanceAnalysisKit';
import { common } from '@kit.AbilityKit';
import { preferences } from '@kit.ArkData';

// 灰度发布状态
enum GrayPublishState {
  IDLE = 'idle',               // 空闲
  CONFIGURING = 'configuring', // 配置中
  PHASE_1 = 'phase_1',        // 第1轮灰度
  PHASE_2 = 'phase_2',        // 第2轮灰度
  PHASE_3 = 'phase_3',        // 第3轮灰度
  FULL = 'full',              // 全量发布
  PAUSED = 'paused',          // 已暂停
  ROLLED_BACK = 'rolled_back' // 已回滚
}

// 灰度发布事件
interface GrayPublishEvent {
  type: 'phase_change' | 'alert' | 'rollback' | 'complete';
  message: string;
  timestamp: number;
  data?: Record<string, Object>;
}

export class GrayPublishController {
  private static instance: GrayPublishController;
  private context: common.Context | null = null;
  private state: GrayPublishState = GrayPublishState.IDLE;
  private events: GrayPublishEvent[] = [];
  private onStateChange?: (state: GrayPublishState) => void;

  static getInstance(): GrayPublishController {
    if (!GrayPublishController.instance) {
      GrayPublishController.instance = new GrayPublishController();
    }
    return GrayPublishController.instance;
  }

  // 初始化
  async init(context: common.Context): Promise<void> {
    this.context = context;
    await this.restoreState();
    hilog.info(0x0000, 'GrayController', `灰度控制器初始化, 当前状态: ${this.state}`);
  }

  // 开始灰度发布
  async startGrayPublish(): Promise<void> {
    if (this.state !== GrayPublishState.IDLE) {
      hilog.warn(0x0000, 'GrayController', `当前状态${this.state}不允许启动灰度`);
      return;
    }

    // 进入第1轮灰度
    this.setState(GrayPublishState.PHASE_1);
    this.addEvent('phase_change', '灰度发布启动，进入第1轮（5%用户）');
    
    hilog.info(0x0000, 'GrayController', '灰度发布已启动');
  }

  // 推进到下一阶段
  async advanceToNextPhase(): Promise<boolean> {
    const nextStateMap: Record<string, GrayPublishState> = {
      [GrayPublishState.PHASE_1]: GrayPublishState.PHASE_2,
      [GrayPublishState.PHASE_2]: GrayPublishState.PHASE_3,
      [GrayPublishState.PHASE_3]: GrayPublishState.FULL
    };

    const nextState = nextStateMap[this.state];
    if (!nextState) {
      hilog.warn(0x0000, 'GrayController', `当前状态${this.state}无法推进`);
      return false;
    }

    const phaseNames: Record<string, string> = {
      [GrayPublishState.PHASE_1]: '第1轮（5%）',
      [GrayPublishState.PHASE_2]: '第2轮（20%）',
      [GrayPublishState.PHASE_3]: '第3轮（50%）',
      [GrayPublishState.FULL]: '全量发布（100%）'
    };

    this.setState(nextState);
    this.addEvent('phase_change', `灰度推进到${phaseNames[nextState]}`);
    
    if (nextState === GrayPublishState.FULL) {
      this.addEvent('complete', '灰度发布完成，已全量发布');
    }

    return true;
  }

  // 暂停灰度
  pauseGrayPublish(): void {
    if (this.state === GrayPublishState.IDLE || 
        this.state === GrayPublishState.PAUSED ||
        this.state === GrayPublishState.ROLLED_BACK) {
      return;
    }

    this.setState(GrayPublishState.PAUSED);
    this.addEvent('phase_change', '灰度发布已暂停');
    hilog.warn(0x0000, 'GrayController', '灰度发布已暂停');
  }

  // 恢复灰度
  resumeGrayPublish(): void {
    if (this.state !== GrayPublishState.PAUSED) return;
    
    // 恢复到暂停前的状态（简化处理，回到第1轮）
    this.setState(GrayPublishState.PHASE_1);
    this.addEvent('phase_change', '灰度发布已恢复');
  }

  // 回滚
  async rollback(): Promise<void> {
    this.setState(GrayPublishState.ROLLED_BACK);
    this.addEvent('rollback', '灰度版本已回滚，恢复到旧版本');
    
    // 在AGC控制台执行回滚操作
    // 实际项目中需要调用AGC API
    hilog.error(0x0000, 'GrayController', '灰度版本已回滚！');
  }

  // 获取当前灰度比例
  getCurrentPercentage(): number {
    const percentageMap: Record<string, number> = {
      [GrayPublishState.IDLE]: 0,
      [GrayPublishState.CONFIGURING]: 0,
      [GrayPublishState.PHASE_1]: 5,
      [GrayPublishState.PHASE_2]: 20,
      [GrayPublishState.PHASE_3]: 50,
      [GrayPublishState.FULL]: 100,
      [GrayPublishState.PAUSED]: 0,
      [GrayPublishState.ROLLED_BACK]: 0
    };
    return percentageMap[this.state] ?? 0;
  }

  // 获取事件历史
  getEvents(): GrayPublishEvent[] {
    return [...this.events];
  }

  // 设置状态变更回调
  setOnStateChange(callback: (state: GrayPublishState) => void): void {
    this.onStateChange = callback;
  }

  // 更新状态
  private setState(newState: GrayPublishState): void {
    const oldState = this.state;
    this.state = newState;
    
    hilog.info(0x0000, 'GrayController', `状态变更: ${oldState} → ${newState}`);
    
    // 持久化状态
    this.saveState();
    
    // 触发回调
    this.onStateChange?.(newState);
  }

  // 添加事件
  private addEvent(type: GrayPublishEvent['type'], message: string, data?: Record<string, Object>): void {
    this.events.push({
      type,
      message,
      timestamp: Date.now(),
      data
    });

    // 只保留最近50条事件
    if (this.events.length > 50) {
      this.events.shift();
    }
  }

  // 持久化状态
  private async saveState(): Promise<void> {
    if (!this.context) return;
    
    try {
      const pref = await preferences.getPreferences(this.context, 'gray_state');
      await pref.put('gray_state', this.state);
      await pref.flush();
    } catch (error) {
      hilog.error(0x0000, 'GrayController', '保存灰度状态失败');
    }
  }

  // 恢复状态
  private async restoreState(): Promise<void> {
    if (!this.context) return;
    
    try {
      const pref = await preferences.getPreferences(this.context, 'gray_state');
      const savedState = await pref.get('gray_state', GrayPublishState.IDLE) as string;
      this.state = savedState as GrayPublishState;
    } catch (error) {
      this.state = GrayPublishState.IDLE;
    }
  }
}

踩坑与注意事项

坑1：灰度比例设置不合理

第一轮就设50%的灰度——那还叫灰度吗？那叫半量发布，风险和全量差不多。

正确做法：第一轮最多5%，观察没问题再逐步扩大。宁可慢一点，也不要冒进。

坑2：灰度观察时间太短

灰度刚上线2小时就看数据，觉得没问题就扩大到100%——2小时的数据能说明什么？很多问题在特定场景下才会出现，比如弱网环境、低内存设备、特定时区。

正确做法：每轮灰度至少观察24小时，确保覆盖不同时段的用户行为。

坑3：灰度用户哈希不稳定

用时间戳做灰度哈希，结果用户每次打开应用可能命中不同的灰度结果——今天用新版本，明天用旧版本。

正确做法：灰度哈希必须基于稳定的用户标识（如用户ID），确保同一用户始终命中相同的结果。

坑4：回滚操作不彻底

回滚了新版本，但忘记通知服务端回滚对应的API变更——客户端用旧版本，服务端已经是新接口，结果接口不兼容。

正确做法：回滚是全链路操作。客户端回滚的同时，服务端也要回滚或者保证接口向后兼容。

坑5：灰度期间修改灰度规则

灰度进行到一半，突然改了灰度比例或者地域规则——之前的数据就不具备参考价值了，因为你改了实验条件。

正确做法：灰度规则一旦确定就不要改。如果必须改，重新开始灰度流程。

坑6：忽略灰度用户反馈

灰度用户反馈了问题，但你觉得"只是个别用户的问题"，没当回事。结果全量发布后，这个问题影响了大量用户。

正确做法：灰度期间的每一条用户反馈都要认真对待。灰度阶段的问题，全量后会放大10倍、100倍。

HarmonyOS 6适配说明

HarmonyOS 6对灰度发布做了几项增强：

1. AGC控制台灰度配置增强：新增按折叠屏状态（展开/折叠）分别设置灰度比例的功能。

2. 灰度数据实时看板：AGC控制台新增灰度版本与基线版本的实时对比看板，崩溃率、ANR率、启动时间等指标一目了然。

3. 自动回滚功能：可以在AGC控制台配置自动回滚规则。当灰度版本的崩溃率超过设定阈值时，系统自动回滚到上一版本。

4. 灰度A/B测试：AGC新增了灰度A/B测试功能，可以同时发布多个灰度版本，对比不同版本的关键指标。

// HarmonyOS 6 灰度配置示例（AGC控制台配置，代码端读取）
// 通过远程配置获取灰度规则
import { remoteConfig } from '@hms.core.remoteconfig';

async function loadGrayConfig(): Promise<void> {
  // 从远程配置获取灰度比例
  const grayPercentage = remoteConfig.getValueAsLong('gray_percentage');
  const grayRegions = remoteConfig.getValueAsString('gray_regions'); // "beijing,shanghai"
  const grayDeviceTypes = remoteConfig.getValueAsString('gray_device_types'); // "phone,tablet"
  
  hilog.info(0x0000, 'GrayConfig', 
    `灰度配置: 比例=${grayPercentage}%, 地域=${grayRegions}, 设备=${grayDeviceTypes}`);
}

5. 灰度版本管理API：HarmonyOS 6新增了版本管理API，可以在应用内查询当前灰度状态和版本信息。

总结

灰度发布是版本发布中最重要的安全机制。核心记住三点：

1. 灰度节奏要稳：5%→20%→50%→100%，每轮观察24小时以上
2. 监控数据要全：崩溃率、ANR率、启动时间、用户反馈，缺一不可
3. 回滚方案要熟：出问题能快速回滚，回滚要全链路（客户端+服务端）