自托管
运行你自己的 Kaiwu 中继——如何部署、如何配置允许登录的用户，以及服务器会保留哪些数据。
本节介绍如何搭建自己的 Kaiwu 中继（供客户端与设备连接的同步后端）。此处内容完全可选：Kaiwu Cloud 的存在正是为了让你不必自建。
配置完成后，你的客户端和设备将指向你自己的 URL（例如 https://api.example.com），而非云端地址。除此之外，Kaiwu 的使用方式没有任何改变。
选择运行方式
服务端快速入门
生产环境的最小配置，以及哪些环境变量真正起作用。
Docker
用于单容器以及 API/worker 分离部署的 Compose 文件。
自托管运行时
主机或 VPS 上的托管服务——安装程序与运行程序各自负责的内容。
从 monorepo 克隆运行
本地仓库模式，适用于从源码开发或进行二次定制。
Proxmox VE
使用社区辅助脚本进行部署。
如果不确定该如何选择：若已有进程管理器，推荐使用 Docker；若希望在普通主机上运行托管服务，建议使用自托管运行时；若要对服务端本身进行代码修改，请使用本地仓库方式。
配置服务
配置登录权限
这一环节耗时最长，也最容易出现不易察觉的疏漏。因此，我们针对每个提供商单独提供了一篇指南，而不是堆砌在长篇文档中。
- 认证概览 —— 策略模型，以及下列各组件如何协同工作。
- GitHub —— 用于注册和连接的 OAuth，以及允许列表。
- OIDC —— 支持 Okta、Auth0、Entra ID、Keycloak 及其他通用协议。
- mTLS —— 来自 MDM 的客户端证书、自动配置，以及将单人的多台设备映射至统一身份。
- 自定义提供商 —— 无需 fork 核心认证逻辑即可添加自有的提供商。
确定服务端保留的数据
理解运行机制
- Kaiwu 架构总览 —— 三大核心组件，以及它们对其前端代理的具体要求。
- 协议规范 —— 客户端、中继与设备之间的事件契约。
部署版本
两种版本运行相同的 API 和业务逻辑，差异仅在于使用的存储后端不同。
- 完整版（Full） —— 采用外部 Postgres（默认）或 MySQL 8.0.16+，搭配 S3 或兼容存储（默认配置；可通过
KAIWU_FILES_BACKEND=local切换为本地磁盘）。Redis 为可选项，仅在多副本实时同步时才需要。 - 轻量版（Light） —— 基于磁盘的 SQLite（默认）或嵌入式 Postgres（PGlite），本地文件存储由服务端直接通过
GET /files/*提供服务。
若是多用户共享的服务端，请使用完整版；若追求最简便的单节点部署，请使用轻量版。
在搭配 SQLite 且未配置 DATABASE_URL 的情况下，服务端必须设置 KAIWU_SERVER_LIGHT_DATA_DIR，否则将拒绝启动。
角色划分与扩容
单进程运行是最简单的方式。若要拆分角色，可设置 SERVER_ROLE：
SERVER_ROLE | 进程职责 |
|---|---|
未设置（默认 all） | 同时处理 API、实时通信和后台任务 |
api | 仅处理 API 和实时通信 —— 客户端连接此角色 |
worker | 仅处理后台任务，不监听 HTTP 请求 |
在根据上表进行部署前，有两点需要特别注意：
- 无法识别的值不会报错。 任何非
api或worker的取值（包括拼写错误），都会静默回退为all。例如将SERVER_ROLE=wroker拼写错误，启动的将是第二个完整服务端，而不是 Worker。 worker必须配合 Redis 适配器。 除非已设置REDIS_URL且配置了KAIWU_SOCKET_ADAPTER=redis-streams，否则进程会在启动时抛出异常。这是因为 Worker 需要向自身未直接建立 Socket 连接的房间发布消息。
反之亦然：一旦启用了 Redis 适配器，持久化设备在线状态（presence）的写入操作就会转交由 Worker 处理。如果部署全部为 api 且启用了 Redis，系统会记录日志提示需要 Worker，并且在 Worker 运行之前，在线状态将无法持久化写入。
对于多副本 API 部署，请启用 Redis 扇出（fanout），并在负载均衡器上配置会话保持（sticky sessions）。Docker 文档中提供了一个可用的配置示例。
反向代理基础
在生产环境中，应将 API 部署在满足以下条件的反向代理之后：
- 负责 TLS 终结；
- 支持 WebSocket 协议升级 —— Socket.IO 实时通信位于
/v1/updates； - 设置足够长的超时时间以支持长连接；
- 敏感信息保存在平台的环境变量或机密管理器中，而非存入 git。
如果由服务端托管 /files/*（轻量版），还需放行这些路由。
/v1/updates 升级失败是自托管过程中最常见的故障，且表象通常不像网络问题：设备可以正常注册，但随后始终处于离线状态，并显示为 machine.none_online。详情请参阅环境变量 → 网络。
相关内容
本地 stack CLI 还支持通过 SSH 引导配置远程主机，这通常比手动操作更快：
- 远程服务端配置 (SSH) —— 在远程主机上安装自托管服务端。
- 远程守护进程配置 (SSH) —— 在远程主机上安装 Kaiwu 并配置配对凭据。