更新
Kaiwu 应用、CLI、安装程序、Docker 镜像及发布资产的更新机制。
Kaiwu（无极开物）包含多个应用与工具，具体的更新机制取决于各组件的安装方式。
本文档是以下内容的权威参考：
- 哪些构件支持自动更新，哪些需要手动更新
- 各类安装方式对应的更新命令
- 稳定版、预览版和开发版通道如何映射到滚动发布标签
- 自托管部署中“内置 UI”的获取途径
更新通道
大多数构件都会发布到以下通道中：
stable（生产通道）preview（预发布 / 抢先体验通道）dev（滚动 nightly / 最新的公开dev分支构建版本）
对外提供的公开承诺仅包含这三个通道名称。 内部的发布通道标识符属于流水线与配置层的实现细节，不应出现在用户命令或公开文档中。
在底层，通道是通过滚动发布标签（例如 cli-stable、cli-preview、cli-dev、server-preview、ui-web-dev）来实现的。这些标签会持续更新，始终指向对应通道中的最新版本。
各通道的可用性仍取决于具体构件。例如，部分构件提供了全部三个公开通道（stable、preview、dev），而其他构件目前可能仅开放其中一部分。
更新矩阵（完整构件一览）
下表列出了所有面向用户的已发布构件及其更新机制。
| 发布的构件 | 获取方式 | 更新触发时机 | 是否自动更新？ | 如何更新 / 控制 |
|---|---|---|---|---|
| 桌面端应用（Tauri，“Tori” / Kaiwu 桌面版） | 已安装的应用包（.app / 安装程序） | 应用检查经签名的更新源，并在应用内提示更新 | 自动检查，由用户手动确认安装 | 确认应用内的更新提示即可；所跟踪的通道由最初安装的构建版本决定 |
| 移动端应用（iOS/Android） | App Store / Play Store | (1) 可能拉取 JS/静态资源 OTA 更新；(2) 原生更新来自应用商店 | OTA 更新支持自动下载 + 用户手动应用；原生更新由应用商店统一管理 | 点击应用内“有可用更新”横幅即可应用 OTA 更新（并重载应用）。原生更新则需在应用商店中安装新版本 |
| Web 端应用（托管版） | 直接打开托管的 Web UI | 新版本上线后，用户刷新页面即可获取 | 是（刷新后生效） | 刷新页面即可（如果浏览器缓存严重，请执行强制刷新） |
自托管 Web UI 静态包（kaiwu-ui-web） | 由自托管服务器、Docker 镜像或运行器内置/提供服务 | 随服务端运行时更新而变化（或在运行器下载更新的 UI 静态包时变更） | 取决于宿主方式（见下文） | 通过宿主方式控制更新（执行 Docker pull、kaiwu relay host install、重启运行器，或锁定标签） |
中继服务器 Docker 镜像（KAIWUdev/relay-server） | docker run … KAIWUdev/relay-server:⟦K15⟧ | 拉取更新的镜像标签并重启容器时更新 | 否 | 执行 docker pull …，随后重启或重建容器；如需严格受控，可固定为不可变标签或摘要 |
| 中继服务器 Docker 镜像内置 UI | 包含在 Docker 镜像构建产物中 | 随 Docker 镜像一同更新 | 否 | 与 Docker 镜像更新方式相同（拉取新镜像并重启） |
中继服务器 npm 包（@KAIWU-dev/relay-server） | npx … @KAIWU-dev/relay-server KAIWU-server … | 运行器启动时，会拉取所选滚动标签对应的最新服务端运行时与 UI 静态包 | 是（重启后生效） | 重启运行器即可拉取最新的滚动标签；可通过 --tag server-vX.Y.Z 与 --ui-tag ui-web-vX.Y.Z 锁定版本；通过 --without-ui 或 KAIWU_SERVER_UI_DIR= 禁用 UI |
| 中继服务器 npm 运行器“内置” UI | 由运行器动态下载并缓存（未直接打包在 npm tarball 中） | 运行器在需要时自动下载 UI 静态包 | 是（重启后生效） | 控制方式与运行器相同：使用 --ui-tag …、--without-ui，或将 KAIWU_SERVER_UI_DIR 指向固定目录 |
托管中继运行时（kaiwu relay host …） | 安装 Kaiwu CLI 后运行 kaiwu relay host install … | 重新运行 kaiwu relay host install 时更新 | 否 | 运行 kaiwu relay host install（在本地执行或配合 --ssh user@host 执行） |
CLI 安装程序（https://kaiwu.wujilabs.cn/install） | curl …install | bash / irm …install.ps1 | 重新运行安装程序（或通过 CLI 的自我更新功能进行更新） | 否 | 重新运行安装程序，或使用 self update 配合运行对应通道的专用命令（kaiwu、hprev 或 hdev） |
| CLI 安装程序产物 | 安装于 ~/.kaiwu/cli{,-preview,-dev}/{versions,current,previous} 下（兼容读取 ~/.KAIWU），并在 ~/.kaiwu/bin 和 ~/.local/bin（或 Windows 对应路径）中提供通道专属 shim 脚本 | 运行 kaiwu self update、hprev self update、hdev self update 或重新运行安装程序时更新 | 否（但会显示更新提示） | 安装程序对应的通道包括 stable（kaiwu）、preview（hprev）和 dev（hdev）。你仍可显式指定 `--channel preview |
CLI npm 包（@KAIWU-dev/cli） | npm install -g @KAIWU-dev/cli | 升级该 npm 包时更新 | 否（但会显示更新提示） | 运行 npm install -g @KAIWU-dev/cli@latest（预览版运行 @next） |
栈 npm 包（@KAIWU-dev/stack） | npm install -g @KAIWU-dev/stack | 升级该 npm 包（或使用 hstack self update 运行时安装）时更新 | 否（但会显示更新提示） | 运行 hstack self update（在栈内部推荐使用）或 npm install -g @KAIWU-dev/stack@latest |
完整性校验（二进制文件与静态包）
自托管以及中继运行时的下载包在安装前均会经过校验：
- SHA256：校验下载的压缩包是否与发布的校验和文件匹配。
- minisign：使用内置的 Kaiwu minisign 公钥校验该校验和文件本身。
桌面端应用（Tauri）
桌面端应用采用 Tauri 的 updater 插件机制：
- 自动检查更新源
- 检测到新版本时，在应用内弹出横幅或提示
- 确认安装更新后，会自动下载经签名的安装包并重启应用
所属的稳定版或预览版通道，取决于最初安装的桌面构建版本。
开发版构建采用完全相同的更新机制，但会指向 dev 更新源。
应用端（移动端与 Web 端）
Web 端应用（托管版）
托管的 Web UI 更新通过常规部署下发：用户只要刷新页面即可获取最新版本。
移动端应用（iOS/Android）
包含两类不同的更新方式：
- 原生更新（新的二进制应用）：通过 App Store / Play Store 分发。
- OTA 更新（JS / 静态资源）：启用后，应用每次切换至前台活跃状态都会检查 OTA 更新，拉取新资源，并展示“有可用更新”横幅供用户点击应用（重载应用生效）。
OTA 更新受服务端特性门控 updates.ota 控制（若服务端禁用此项，则默认关闭）。
CLI 更新（二进制版本与 npm 版本）
更新提示（可选择关闭）
CLI 可在 TTY 交互式会话中定期打印“有可用更新”提示，并在后台执行版本检查。
提示信息中会包含执行更新的命令：
kaiwu self update
禁用更新检查与提示：
KAIWU_CLI_UPDATE_CHECK=0（兼容KAIWU_CLI_UPDATE_CHECK=0）
调整检查频率：
KAIWU_CLI_UPDATE_CHECK_INTERVAL_MSKAIWU_CLI_UPDATE_NOTIFY_INTERVAL_MS
hstack（栈工具）遵循相同的更新模式：
- 提示信息包含：
hstack self update - 禁用命令：
KAIWU_STACK_UPDATE_CHECK=0
如果是通过官方安装程序安装 CLI（二进制版本）
检查 / 更新：
kaiwu self check
kaiwu self update预览版通道：
kaiwu self update --channel=preview开发版通道：
hdev self update锁定到特定版本（或类似 latest/next 的滚动标签）：
kaiwu self update --to 0.1.2重新运行安装程序同样是有效的更新途径：
curl -fsSL https://kaiwu.wujilabs.cn/install | bash如果是通过 npm 安装 CLI
使用 npm 进行更新（运行 kaiwu self update 时 CLI 会打印出确切的命令）：
npm install -g @KAIWU-dev/cli@latest预览版：
npm install -g @KAIWU-dev/cli@next安装程序与二进制版本（自动与手动更新划分）
安装程序和二进制安装包不会在后台自动更新。
其中自动执行的部分：
- 交互式 CLI 会话（TTY）中的更新提示：
kaiwu会打印提示，引导你运行kaiwu self updatehstack会打印提示，引导你运行hstack self update
需要手动执行的部分：
- 实际执行版本更新（运行更新命令或重新执行安装程序）
CLI 安装程序（install）
该安装程序支持若干适用于自动化脚本的操作参数：
# Check the installed binary + PATH shim
curl -fsSL https://kaiwu.wujilabs.cn/install | bash -s -- --check
# Print the latest version available on the selected channel
curl -fsSL https://kaiwu.wujilabs.cn/install | bash -s -- --version
# Update/reinstall to latest on the selected channel
curl -fsSL https://kaiwu.wujilabs.cn/install | bashWindows（PowerShell）下的更新方式与此相同（重新运行安装程序）。
托管中继运行时（kaiwu relay host …）
运行以下命令安装或更新托管中继运行时：
kaiwu relay host install --mode system远程主机（通过 SSH）：
kaiwu relay host install --ssh user@host --mode system随后即可使用 kaiwu relay host status 与 kaiwu relay host start|stop|restart 进行管理。
服务端 / 自托管更新
目前支持多种自托管部署形态。另请参阅：自托管运行时（安装程序与运行器对比）。
托管中继运行时（kaiwu relay host …）
更新 / 重新安装（即 install-or-update）：
kaiwu relay host install --mode system随后根据需要重启：
kaiwu relay host restart --mode system中继服务器运行器（@KAIWU-dev/relay-server）
默认情况下，该运行器会跟踪以下滚动标签：
- 服务端运行时：
server-stable/server-preview/server-dev - UI Web 静态包：
ui-web-stable/ui-web-preview/ui-web-dev
更新在重启后生效（运行器每次启动时都会获取最新的标签元数据）。
注意：
- 解压后的构件会缓存于当前平台的缓存目录下。
- 如果启用了 UI 且未设置
KAIWU_SERVER_UI_DIR，运行器会自动下载 UI 静态包并设置KAIWU_SERVER_UI_DIR。
版本锁定示例：
npx --yes --package @KAIWU-dev/relay-server KAIWU-server \
--tag server-v0.1.0 \
--ui-tag ui-web-v0.3.0中继服务器 Docker 镜像
只有在拉取更新的标签并重启容器时，Docker 镜像才会更新：
docker pull KAIWUdev/relay-server:preview
docker compose up -d --force-recreate内置的 UI 会随镜像一同更新。
发布构件
有关构件命名规范、受支持的平台目标以及清单文件详情，请参阅发布构件。