自托管运行时（安装程序与运行程序）

了解运行自托管 Kaiwu Server 所支持的方式，以及各选项分别安装与管理的内容。

Kaiwu 目前支持三种不同的自托管形态：

由 KAIWU relay host … 驱动的托管安装（服务 + 配置）
Docker 镜像：已将经过验证的服务器运行时与 UI-web 产物预先打包至镜像中
Runner：在启动时下载并校验产物，随后启动服务器进程（@KAIWU-dev/relay-server）

这三种形态互为补充，但定位各不相同。

若需了解所有已发布产物（桌面端/移动端/Web 端、CLI 安装程序、Docker 镜像以及 Runner）的完整“自动更新与手动更新对比表”，请参阅：更新机制。

方案 A：托管自托管安装（需要系统服务时推荐）

在以下场景中，建议使用 KAIWU relay host install：

需要将服务器作为托管服务安装（支持用户模式与系统模式）
针对所选通道，拥有一条可重复执行的安装或更新命令

首先安装 Kaiwu CLI，具体请参阅 CLI 安装。

本地安装：

KAIWU relay host install --mode system

通过 SSH 远程安装：

KAIWU relay host install --ssh user@host --mode system

安装完成后，可通过以下命令进行管理：

KAIWU relay host status
KAIWU relay host start
KAIWU relay host stop
KAIWU relay host restart

如需更新，重新运行 KAIWU relay host install 即可（该命令会安装或更新至对应通道的最新版本）。

本次更新中的身份验证兼容性

请务必保持 HANDY_MASTER_SECRET 不变。持久化身份验证令牌与服务器加密数据均派生自该项；因此轮换它并不能修复身份验证问题，反而会导致现有数据无法读取。

若要从使用 Bun 1.3.5 的预览版中继进行更新，在启动新版本之前，请先停止或排空所有旧版中继进程。在灰度发布期间，切勿在同一个端点后同时运行新旧版本的中继二进制文件：修复后的版本可同时兼容标准历史密钥和 Bun 重试密钥，但旧版进程可能会拒绝使用标准密钥新签发的令牌。彻底重启服务可以消除版本混用引发的异常，同时完整保留既有会话。

方案 B：Docker 镜像（入门推荐）

KAIWUdev/relay-server 镜像基于相同的已签名 server-runtime 和 UI-web 发布产物构建，但在 Docker 镜像构建期间就已完成拉取与校验。容器运行时会直接启动内置的 KAIWU-server 二进制文件。

在以下场景中最为适用：

在 Docker、Compose、Nomad 或 Kubernetes 中运行服务器
希望通过拉取镜像来完成更新
不希望容器在每次重启时都重新下载应用产物

详情请参阅：Docker。

方案 C：Runner（`@KAIWU-dev/relay-server`）

中继服务器包本质上是一个服务器 Runner：

按照滚动标签（server-stable / server-preview / server-dev）拉取服务器运行时
校验产物并解压至缓存目录
可选拉取 UI web 资源包（ui-web-stable / ui-web-preview / ui-web-dev）
设置 KAIWU_SERVER_UI_DIR（若启用了 UI）
随后启动解压后的 KAIWU-server 二进制文件

在以下场景中最为适用：

本地已有进程管理器
希望在重启时自动完成更新（无需托管安装，也无需调度器）
不希望 hstack 在宿主机上安装系统服务、定时器或计划任务

示例（本地 Runner）：

npx --yes --package @KAIWU-dev/relay-server KAIWU-server --help

重要提示：由于该方案采用 Runner 模式，KAIWU relay host … 的服务管理命令对其不适用。

方案选型建议

如果需要系统服务以及托管生命周期 → 选择方案 A。
如果需要自包含的独立容器镜像 → 选择方案 B。
如果已有进程管理器，并希望在重启时拉取产物更新 → 选择方案 C。

如果一时无法确定，建议先从 Docker 方案入手，后续再按需切换为托管安装。