# 更新与分发

## 更新通道

默认构建使用 `JunWan666/astrbot-for-android` 的 GitHub 签名通道。目录在 `updates` 分支，程序包是不可变的 Release 附件。

| 对象 | 目录 | 行为 |
| --- | --- | --- |
| 管理器 APK | `stable/manager.json` | 验证包名、版本、签名和架构后交给系统安装器 |
| AstrBot 与 Dashboard | `stable/astrbot.json` | 独立下载，安装前备份，检查实际启动和迁移 |
| NapCat 程序与 WebUI | `stable/napcat.json` | 下载上游官方 Shell 包，保留配置、插件与 QQ 会话 |
| Ubuntu / Linux QQ / Python 与依赖 | 匹配 APK 内置环境 | 依赖发生变化时升级运行环境，可整套回退 |

目录地址为：

```text
https://raw.githubusercontent.com/JunWan666/astrbot-for-android/updates/stable/manager.json
https://raw.githubusercontent.com/JunWan666/astrbot-for-android/updates/stable/astrbot.json
https://raw.githubusercontent.com/JunWan666/astrbot-for-android/updates/stable/napcat.json
```

组件和管理器分别发布。兼容的 NapCat 新版无需重新发布 APK；升级 QQ 或原生依赖时才需要匹配环境。目录只发布已确认兼容的版本，不自动接受所有上游新版。当前已是最新兼容版本时，组件页仍支持查看说明、重新下载和校验。下载成功后需再次确认安装。

完整 APK 在 [Releases](https://github.com/JunWan666/astrbot-for-android/releases/latest) 下载。管理器正式版使用 `vMAJOR.MINOR.PATCH` 标签并设为最新发布；独立组件包单独发布，不设为最新发布，保留已有下载地址，确保默认下载入口始终指向 App。

## 签名与构建参数

Android keystore 签署 APK，决定是否允许覆盖安装。ECDSA P-256 密钥签署更新目录和 AstrBot 程序包。两类私钥分别保管，均不进入仓库或 APK。

| 参数 | 默认值或作用 |
| --- | --- |
| `managerCatalogUrl` | 上述管理器目录 |
| `updateCatalogUrl` | 上述 AstrBot 目录 |
| `napcatCatalogUrl` | 上述 NapCat 目录 |
| `updatePublicKeyFile` | `runtime/update-public-key.der` |
| `appVersionName` / `appVersionCode` | 显示版本与递增的 Android 版本号 |

分叉项目应更换自己的公钥和通道。将通道参数显式设为空可关闭对应在线入口；应用会说明未配置，不将缺少通道当作最新版。

## 管理器 APK

构建完整 Release 后，用长期 Android keystore 签名，再生成管理器目录：

使用已完成正式签名和校验的 APK，目录条目绑定包名、版本、架构、证书指纹、文件大小及 SHA-256。签署目录后再开放安装入口。

生成器读取 APK 的真实身份、签名、架构和摘要，只接受完整运行资源包。覆盖安装要求包名、签名集合相同且 versionCode 更高。尚未发布管理器新版时，目录可保留空条目，App 会提示没有适用的新版本。

## AstrBot 程序包

先在 `runtime/maintenance-candidates.lock.json` 记录新版本的上游来源与摘要，核对现有 Python 依赖和启动迁移适配，再生成程序包及目录：

独立发行工具生成签名程序包，再将其下载地址、字节数、SHA-256、版本和运行环境摘要写入签名目录。发行工具由发布者单独管理，不是 APK 构建依赖。

AstrBot 程序包必须绑定匹配的完整运行环境，同时包含对应 WebUI，不能只升级后端或前端。

## NapCat 程序包

获取上游正式版 `NapCat.Shell.zip`，独立核对官方附件摘要并确认与现有 Linux QQ 的兼容性，再签署目录。无需重新打包、修改或转存上游 ZIP：

目录条目记录已核对的上游版本、下载地址、ZIP 摘要、后台程序摘要和适配的 QQ 版本，由发布者签名后发布。

发布工具绑定实际程序摘要、QQ 版本及运行环境。App 下载原始 ZIP，安装时再次验证。QQ 原本停止时不会为更新检查而登录；原本运行时会在更新后重启并检查后台接口。失败恢复原程序和对应数据。

## 发布与续期

1. 固定版本、来源和兼容组合，准备适用的许可及源码材料。
2. 先上传不可变 Release 资源，NapCat 使用上游既有附件。
3. 生成更高 `sequence` 的签名目录，提交到 `updates` 分支的 `stable/`。
4. 不改写已公开的附件；撤回版本也通过更高目录序号发布。

目录有效期最多 31 天，默认每次签署 30 天。`Renew update catalogs` 工作流每周续期，也可手动运行；只重新签署既有条目，不自动引入未经适配的上游新版本。仓库 Actions Secret `UPDATE_SIGNING_KEY` 保存独立的更新目录私钥。应保留工程外离线副本，续期工作流需位于默认分支；发布主分支后同样保留此工作流。工作流先检出 `updates` 分支，再使用该分支自带的发行工具；主分支不需要保存这些工具。

协议与恢复细节见[在线更新协议](在线更新协议.md)、[更新包格式与恢复协议](更新包格式与恢复协议.md)，第三方材料要求见[发行材料](发行材料.md)。