# 控制台操作

从上传文件到发布、调整比例和回滚，按按钮一步步操作。

## 开始前拿到这些 {#before}

如果你负责运营发布，请先让开发同事提供：

- 控制台里的应用名称和平台，例如“商城 Android”。
- 已上传的原生版本和渠道，例如 `1.0.0 / huawei`。
- 本次更新的 `.ppk` 文件、版本名称和更新说明。
- 一个装好对应 Release App 的测试设备。

原生安装包需要开发用 CLI 上传。控制台“添加热更新包”上传的是 `.ppk`，不能上传 APK、IPA 或 Harmony `.app`。开发准备步骤见[首次发布](/docs/publish#register-native)。

## 认识页面 {#navigation}

登录后，从左侧**应用**进入具体应用。

| 页面 | 在这里做什么 |
| --- | --- |
| 热更新包 | 上传 `.ppk`、发布、调整比例、恢复历史版本 |
| 原生包体 | 检查已上传安装包的渠道和版本，编辑原生包状态 |
| 渠道目录 | 创建渠道、设置下载地址、开关渠道更新 |
| 实时数据 | 查看设备检查、下载、生效和错误事件 |
| 操作日志 | 查看谁在什么时候执行了什么操作 |
| API Key | 给开发或 CI 创建调用凭据 |

第一次没有应用时，在**应用**页点击创建按钮，填写名称并选择平台。Android、iOS 和 HarmonyOS 分别创建应用，把对应 appKey 交给开发接入。

## 1. 确认发布目标已准备好 {#native}

1. 进入应用，切到**原生包体**。
2. 找到本次要更新的渠道和版本，例如 `huawei / 1.0.0`。
3. 确认它没有暂停或过期，再到**渠道目录**确认该渠道启用了热更新。

列表为空时，让开发上传实际分发的安装包，然后点击**刷新**。在渠道目录创建一个名字，不会自动生成可发布的原生版本。

## 2. 上传热更新文件 {#upload}

1. 切到**热更新包**，点击**添加热更新包**。
2. 选择开发提供的 `.ppk` 文件。
3. 填写本次更新名称，例如 `fix-checkout-001`，并写清更新说明。
4. 没有自定义数据需求时，Meta Info 保持 `{}`。
5. 提交，等上传完成后确认列表中出现本次更新。

上传成功还不等于用户会收到更新。接下来需要选择渠道、原生版本和发布比例。

如果开发已经用 CLI 发布，本页会显示现有记录，直接检查目标即可。需要归档 sourcemap 还原报错代码时，让开发使用[带 sourcemap 的发布命令](/docs/publish#publish)。

## 3. 选择用户范围并发布 {#publish}

1. 在本次更新的行上点击**发布**。
2. 点击**选择第一个目标**；已有目标时点**添加目标**。
3. 在弹窗中找到渠道，勾选原生版本，例如 `huawei → 1.0.0`，点击**添加 1 个目标**。
4. 把**发布比例**设为 `10`。独立测试应用可以设为 `100`。
5. 普通发布保持**强制救砖**关闭。
6. 点击**预览并应用**，逐行确认渠道、原生版本、比例，以及是否会替换已有更新。
7. 点击**确认提交**，回到列表确认该目标已经发布。

| 目标示例 | 谁可能收到 |
| --- | --- |
| `huawei / 1.0.0 / 10%` | 安装华为渠道 1.0.0 包的部分设备 |
| `xiaomi / 1.0.0 / 100%` | 安装小米渠道 1.0.0 包且符合更新条件的设备 |

目标列表找不到版本时，返回**原生包体**核对。没有登记的版本不能在发布窗口手工输入出来。

## 4. 检查效果，再扩大比例 {#rollout}

1. 在测试设备中检查更新，等待下载，按 App 设置重新启动或确认更新。
2. 打开左侧**实时数据**，选本次应用、渠道和发布时间范围。
3. 查看是否有下载成功、启动和确认成功事件；有错误时先点开设备记录排查。
4. 确认关键业务可用后，回到**热更新包**，点击目标标签调整比例，或用**发布**打开编辑窗口。
5. 依次扩大到团队约定的比例，最后设为 `100`；每次预览、确认后再观察。

10% 的发布不保证你的测试手机一定收到。首次验收用独立测试渠道 100%。下载成功也不等于已经运行成功，事件含义见[验证更新是否成功](/docs/analytics)。

## 停止更新 {#stop}

**只停一个更新目标：**在热更新包列表点对应目标标签，选择**取消发布**，检查预览并确认。取消后可以重新发布这份包。

**暂停整个渠道：**打开**渠道目录**，点渠道的**配置**，关闭**启用热更新**并保存。恢复时重新打开此开关；恢复前先检查该渠道现有的发布内容。

这两种操作都不卸载手机已经下载并运行的更新。不要用“删除热更新包”代替停止发布，删除会移除包记录及其发布关系。

## 恢复到稳定版本 {#rollback}

1. 先停止问题版本继续发布。
2. 在**热更新包**列表找到之前验证过的稳定包。
3. 点该包相同渠道、原生版本的历史目标，选择**回滚为全量**。
4. 若已没有该目标，用**发布 → 添加目标**重新选择相同渠道和原生版本，比例设为 `100`。
5. 查看预览，确认只影响需要恢复的目标，再提交。
6. 用问题设备重新检查并按 App 设置生效，确认页面恢复；然后观察实时数据。

这里会重新发布稳定内容。手机仍需联网检查和下载，并不会在你按下按钮时立即退回旧版。

## App 打不开时 {#rescue}

让开发提供修复后的更新包，按发布步骤选择受影响的渠道和原生版本，在预览前打开**强制救砖**。

设备必须已经集成并启用 SDK 的原生启动检查。它可以在 JS 无法运行时下载修复，安排后续启动生效。此开关无法给未接入的旧安装包补上能力，也不能绕过设备对已回滚版本的保护。先让开发用同一原生包复现并验证恢复过程。

## 日常核对与常见卡点 {#troubleshooting}

| 现象 | 下一步 |
| --- | --- |
| 没有任何发布目标 | 让开发上传原生包，核对平台与应用，然后刷新 |
| 渠道选对了但设备收不到 | 核对安装包内渠道；见[配置渠道](/docs/channels#verify) |
| 上传成功但没有更新 | 打开发布窗口，确认已添加目标并提交 |
| 提示冲突或预览失败 | 查看报错行；刷新目标数据后重新预览，不要反复提交旧预览 |
| 修改比例后部分用户没变 | 比例只影响后续更新选择，不能撤销已安装内容 |
| 不知道谁改了设置 | 打开**操作日志**，按操作时间和关键词筛选 |
| 下载成功后仍是旧页面 | 等待 App 设定的生效时机；见[设备验收](/docs/publish#verify) |

每次发布留存：应用、渠道、原生版本、更新名称、比例、操作时间和测试结果。自动化发布见[API Key 与 CI](/docs/api-token)。