服务端快速入门

本文是自托管 apps/server 的入门指南。如需查看完整参考，请参阅部署 → 环境变量。

1) 选择规范 URL 或共享 URL（推荐）

请设置一个能在手机或浏览器中正常访问的规范 URL。客户端生成二维码和深层链接时会嵌入该地址，服务端也会通过 GET /v1/features 对外播发此 URL。

推荐方案：

• Tailscale Serve（适合绝大多数自托管场景，推荐）： 无需开放端口即可获得 https://*.ts.net URL。
  • 推荐做法：
    • 保持未设置（最简方案）： 若 tailscale serve 与 apps/server 运行在同一台设备或容器宿主机上，服务端会在启动时尽力推断 https://*.ts.net URL，并将其播发给客户端。
  • 其他情况：
    • 显式设置： KAIWU_PUBLIC_SERVER_URL=https://⟦K2⟧.⟦K3⟧.ts.net
      • 若 Tailscale/Serve 运行在另一台设备上，或者服务端运行时环境中没有 tailscale CLI，通常需要显式配置。
• 自定义域名（反向代理）： 在 Caddy、Nginx 或 Traefik 上终止 TLS，并反向代理至服务端。
  • 设置：KAIWU_PUBLIC_SERVER_URL=https://api.example.com

如果自托管 Web UI（或使用 OAuth 提供商且需要非官方托管的回调 URL），还需要设置：

• KAIWU_WEBAPP_URL=https://app.example.com

若仅在局域网内使用，填写 http://⟦K4⟧:3005 即可，但二维码和深层链接只能在同一局域网或 VPN 内生效。

注意：不使用 Serve 的 Tailscale 通常只会分配 100.x IP。浏览器不会将 http://100.x... 视为安全上下文，导致 Web UI 在纯 HTTP 下无法稳定运行。若需使用 Web 端或移动端流程，请使用 Tailscale Serve (HTTPS) 或反向代理。

2) 配置核心密钥与存储

在生产环境中，大多数部署至少需要配置以下内容：

• HANDY_MASTER_SECRET（较长的随机字符串，重启后保持不变）
• KAIWU_DB_PROVIDER 与数据库配置：
  • postgres/mysql：设置 DATABASE_URL
  • pglite/sqlite：通常无需外部数据库
• KAIWU_FILES_BACKEND：
  • local：配置最简单（适用于单节点部署）
  • s3：需配置 S3_* 凭据与 S3_PUBLIC_URL

标准模板请参考 apps/server/.env.example。

3) 反向代理与 HTTPS（常见配置）

若在反向代理（Caddy、Nginx 或 Traefik）上终止 TLS，还需设置：

• KAIWU_SERVER_TRUST_PROXY=1（典型的单代理环境配置）

这样可以让系统在 X-Forwarded-* 等请求头后正确识别 request.ip 和协议，对限流以及部分 URL 行为至关重要。

注意：反向代理还必须支持 WebSocket 协议升级，以保证 Socket.IO 的实时通信：

• /v1/updates（长轮询 + WebSocket 升级）

若 WebSocket 升级失败，设备虽然可以完成注册，但会一直显示离线（提示“no online machines”或 machine.none_online）。

详见：部署 → 环境变量 → 网络与反向代理

4) 可选：Tailscale Serve 推断

若使用 tailscale serve 且未显式设置 KAIWU_PUBLIC_SERVER_URL，服务端可以在启动时尽力推断 https://*.ts.net URL。

• 设置 KAIWU_TAILSCALE_INFER_PUBLIC_URL=0 可禁用此功能（默认启用）

Tailscale Serve 极简命令（在服务端宿主机上运行，位于容器外部）：

tailscale up
tailscale serve --bg http://127.0.0.1:3005
tailscale serve status

若使用 Kaiwu 栈（hstack），建议优先使用远程访问 (Tailscale)中的引导命令。

5) 可选：认证提供商

若启用了 GitHub 或 OIDC OAuth 提供商，且未使用位于 https://kaiwu.wujilabs.cn 的托管版 Web 应用，请务必设置 KAIWU_WEBAPP_URL（或 KAIWU_WEBAPP_OAUTH_RETURN_URL_BASE），以便服务端能够正确重定向回客户端。

详见服务端 → 认证以及该章节下的各提供商文档。