Proxmox VE

本指南介绍如何利用社区维护的 Proxmox VE Helper-Scripts 项目（基于 LXC 的“单条命令”安装脚本），在 Proxmox VE 上部署 Kaiwu。

方案包含

专属 Debian LXC 容器，运行内置 PGlite 嵌入式数据库的 Kaiwu Server。
可选的内置 Web UI 服务，由同一容器直接提供。
可选的开机自启，通过容器内的 systemd 系统服务实现。
可选的 Tailscale，用于远程访问与 HTTPS（推荐用于手机端访问）。

安装（推荐方式）

在浏览器中打开 helper-scripts.com 并搜索 Kaiwu。
从脚本页面复制安装命令。
粘贴到 Proxmox Shell（宿主机控制台）中，并按提示完成操作。

如果 helper-scripts.com 上尚未收录该脚本，可以直接从我们的 ProxmoxVE 分支运行安装程序：

tmp="$(mktemp)" \
  && curl -fsSL "https://raw.githubusercontent.com/KAIWU-dev/ProxmoxVE/main/ct/KAIWU.sh" -o "$tmp" \
  && bash "$tmp" \
  && rm -f "$tmp"

安装完成后，安装程序会输出：

容器的 IP 地址与本地 HTTP URL
公网 HTTPS URL（如果已配置）
“连接终端”链接与二维码（包含移动端深层链接与 Web URL），其中已包含 server=...，方便 App 或 Web UI 自动切换服务器
连接终端/守护进程的后续步骤（若安装了 Dev box，还包含启动或重启服务的说明）

本地访问地址：

http://⟦K5⟧:3005（局域网）

若在安装过程中选择了 Tailscale，该栈通常会绑定到 loopback，此时将无法通过局域网 IP 访问。这种情况下，请改用安装程序输出的 HTTPS URL。

快速入门（推荐流程）

运行上文的 Proxmox 辅助脚本完成安装。
选择一种远程访问方案：
- Tailscale（推荐）：无需在公网开放端口即可获得 HTTPS URL。
- 反向代理：适合已部署 Caddy、Nginx 或 Traefik 的环境。
在需要运行守护进程/终端的电脑上执行：
- kaiwu server add --server-url https://⟦K6⟧ --use
- kaiwu auth login --method=mobile
在手机上扫描二维码（或打开深层链接）。App 会提示切换服务器（如需要），随后即可登录或注册账号，并确认批准终端连接。
如果安装了 Dev box，请通过 SSH 进入容器并运行：
- sudo -u kaiwu -H kaiwu auth login
- （必要时）systemctl restart 'kaiwu-daemon.*.service'

安装后：推荐上手流程

Kaiwu 包含两个独立的连接环节：

将 App 或 Web UI 配置为连接你的服务器
将终端或守护进程连接到该服务器上的对应账号

Proxmox 安装程序不会替你自动完成认证，但会输出完整流程所需的具体命令和链接。

1) 确保拥有公网 HTTPS URL（用于远程访问）

如果仅在局域网内访问 Kaiwu，普通的 HTTP 即可满足需求。

如需远程访问（手机端或局域网外），Web UI 则必须在安全上下文（HTTPS）下运行。可选择以下方案之一：

Tailscale Serve（推荐）：实现端到端 HTTPS 最简便的方式
反向代理（Caddy / Nginx / Traefik）：由代理层终止 TLS 并转发到容器

若使用反向代理，Proxmox 安装程序会提示输入公网 HTTPS URL，并将其保存到：

默认（推荐的安装方式）：写入 /etc/kaiwu/server.env（兼容 /etc/KAIWU/server.env），分别配置为：
- KAIWU_PUBLIC_SERVER_URL=https://⟦K7⟧（规范/共享 URL，用于二维码和深层链接）
- KAIWU_WEBAPP_URL=https://⟦K8⟧（在容器提供 Web UI 服务时生效）
源码安装（KAIWU_PVE_INSTALL_METHOD=from_source）：写入 /home/kaiwu/.kaiwu/stacks/main/env

日后如需修改，编辑对应文件并重启栈或服务即可。

进阶：反向代理（Caddy / Nginx）

采用反向代理配置时，通常在代理层终止 TLS，并转发到：

http://⟦K9⟧:3005

请确保代理支持 WebSocket，并转发通用的真实 URL 请求头：

Host
X-Forwarded-Proto
X-Forwarded-Host
X-Forwarded-For

同时确保该栈能够识别自身的公网 URL（以生成正确的深层链接与二维码）：

默认（推荐的安装方式）：在 /etc/kaiwu/server.env 中配置 KAIWU_PUBLIC_SERVER_URL=https://⟦K10⟧
源码安装：在 /home/kaiwu/.kaiwu/stacks/main/env 中配置 KAIWU_PUBLIC_SERVER_URL=https://⟦K11⟧

配置完成后重启：

默认（推荐的安装方式）：systemctl restart kaiwu-server
源码安装：
- su - kaiwu -c "/home/kaiwu/.kaiwu-stack/bin/hstack service restart --mode=system"（已启用开机自启）
- su - kaiwu -c "/home/kaiwu/.kaiwu-stack/bin/hstack start --restart"（手动启动）

Caddy（推荐，配置 HTTPS 最为简单）

Caddyfile：

kaiwu.example.com {
  reverse_proxy http://<container-ip>:3005
}

如果 Caddy 运行在 Proxmox 宿主机或其他设备上，请将 ⟦K12⟧ 替换为容器的局域网 IP。

Nginx（手动配置）

server 块配置片段：

server {
  listen 443 ssl http2;
  server_name kaiwu.example.com;

  # TLS config omitted (use certbot, or your existing TLS setup)

  location / {
    proxy_pass http://<container-ip>:3005;
    proxy_http_version 1.1;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }
}

若使用带图形界面的反向代理（如 Nginx Proxy Manager 或 Traefik），请务必开启“WebSocket 支持”，并将上游地址设为 http://⟦K13⟧:3005。

2) 配置 App 或 Web UI 连接你的服务器

大多数情况下，你无需专门执行“配置服务器”操作：终端连接链接已包含 server=...，App 或 Web UI 会在确认连接前安全地提示你切换服务器。

若想在 App 中手动添加或切换服务器：

打开设置 → 中继，添加中继 URL。

若选择不通过 Proxmox 容器提供 Web UI 服务，可使用：

移动端 App（推荐），或
托管版 Web 应用 https://kaiwu.wujilabs.cn，并在其中配置服务器

3) 连接终端/守护进程

继续按照 kaiwu auth login 的输出进行操作：

使用移动端 App：扫描二维码或打开移动端深层链接
使用 Web 应用：在已登录的浏览器中打开该 URL

由于链接中已包含服务器 URL，App 或 Web UI 可以在批准连接前安全地提示你切换服务器（如需要）。

4) 启动（或重启）守护进程（Dev box 模式）

如果安装的是 Dev box（server-light + 守护进程），在首次安装时守护进程会默认等待认证完成。

登录完成后：

默认（推荐的安装方式）：
- 若已启用开机自启，守护进程将作为容器内的 systemd 系统服务运行。
- 必要时可重启该服务：systemctl restart 'kaiwu-daemon.*.service'
源码安装：
- 若已启用开机自启，服务检测到凭据就绪后会自动启动守护进程。
- 否则（手动启动）需要手动重启，以便守护进程加载新凭据启动：
  - /home/kaiwu/.kaiwu-stack/bin/hstack start --restart

从其他设备使用 Kaiwu（常见架构）

如果 Proxmox 上仅安装了 Server only，通常会在笔记本或台式电脑上运行守护进程/终端，并将其指向 Proxmox 服务器。

在你的笔记本/台式电脑上：

保存并切换至自托管服务器：
- kaiwu server add --server-url https://⟦K14⟧ --use
随后连接终端/守护进程：
- kaiwu auth login

该命令会将服务器 URL 保存到本地，随后输出：

“连接终端”链接（移动端二维码/深层链接以及 Web URL），便于确认批准设备连接

如需在 App 或 Web UI 中显式配置或切换服务器（通常无需此操作），可运行：

kaiwu auth login --print-configure-links

有关配置文件切换及多服务器日常使用的详细说明，请参阅特性 → 多服务器。

安装提示选项说明

安装类型

Dev box (server-light + daemon)：同时安装服务器和守护进程工具链。安装程序会自动启动服务器；守护进程可能需要完成认证后方可运行。
Server only (no daemon)：仅安装服务器组件。

提供 Web UI 服务

Yes：构建 Web 界面并由服务器直接托管提供服务。
No：跳过 Web UI 依赖及构建流程，以加快安装速度。

开机自启

Yes：在容器内安装 systemd 系统服务。
No：由用户手动启动。

远程访问 / HTTPS

Tailscale (recommended)：在容器中安装 Tailscale，并可通过 Tailscale Serve 配置 HTTPS URL。
Reverse proxy：自行配置并终止 TLS（如使用 Caddy、Nginx、Traefik 等）。
None：仅限局域网访问。

若选择 Tailscale，可按需粘贴 Tailscale 预授权密钥（pre-auth key）（推荐使用临时一次性密钥）。若跳过或留空，安装程序仍会安装 Tailscale，后续可在容器内部手动加入网络。

Tailscale 加入网络（自动与手动）

Tailscale 的设备接入操作是可选的，取决于你的 tailnet 安全策略：

**自动接入（可选）：**在安装期间提供预授权密钥。密钥有效时，安装程序会尝试将节点上线并启用 Tailscale Serve。
**手动接入（始终适用）：**在安装时跳过密钥（或留空），后续在容器内运行 tailscale up。

若接入失败，或者密钥被拒绝、过期、吊销，安装程序会输出“登录 URL”（若可用）以及需要执行的具体手动命令。

手动接入命令（在容器内运行）：

tailscale up
tailscale set --operator=kaiwu
tailscale serve --bg http://127.0.0.1:3005
tailscale serve status

HStack 发布通道

默认情况下，Proxmox 辅助脚本使用托管的中继运行时（底层基于 kaiwu relay host）安装 Kaiwu，支持 stable、preview 和 dev 通道，并支持就地热更新。

若倾向于使用 npx ... hstack setup-from-source 从源码编译安装，可通过环境变量进行设置（见下文）。

非交互式参数替换：

KAIWU_PVE_INSTALL_METHOD=installers|from_source（兼容 KAIWU_PVE_INSTALL_METHOD，默认值：installers）
KAIWU_PVE_HSTACK_CHANNEL=stable|preview|dev（兼容 KAIWU_PVE_HSTACK_CHANNEL，preview 对应 npm @next）
KAIWU_PVE_HSTACK_PACKAGE='@KAIWU-dev/stack@⟦K15⟧'（仅限源码安装；优先级最高）

HTTPS 配置指南（重要）

在远程访问场景下，Kaiwu Web UI 必须运行在 HTTPS 环境（安全上下文）中。常见配置方案如下：

Tailscale Serve（最简便）：无需在防火墙开放端口，即可直接获取 HTTPS URL。
反向代理：在网络边界终止 TLS，并反向代理至 http://⟦K16⟧:3005（请确保已开启 WebSocket 支持）。

安装后：常用命令

从 Proxmox 宿主机进入容器：

pct enter ⟦K17⟧

服务管理（推荐的安装方式）：

服务器：
- systemctl status kaiwu-server
- journalctl -u kaiwu-server -f
Dev box 守护进程（如已安装）：
- systemctl status 'kaiwu-daemon.*.service'
- journalctl -u 'kaiwu-daemon.*.service' -f

服务管理（源码安装）：

su - kaiwu -c "/home/kaiwu/.kaiwu-stack/bin/hstack service status --mode=system"
su - kaiwu -c "/home/kaiwu/.kaiwu-stack/bin/hstack service logs --mode=system"
su - kaiwu -c "/home/kaiwu/.kaiwu-stack/bin/hstack service tail"

Dev box 模式：连接守护进程（推荐）

如果选择了 Dev box（server-light + daemon），在守护进程完成认证前，服务器与 Web UI 即可正常启动。连接步骤如下：

进入容器：
- pct enter ⟦K18⟧
以 kaiwu 用户身份执行登录（推荐在移动端操作）：
- sudo -u kaiwu -H kaiwu auth login

登录成功后：

推荐的安装方式：
- 若已安装守护进程系统服务，它会持续重试，并在凭据就绪后自动连接。
- 必要时可手动重启：systemctl restart 'kaiwu-daemon.*.service'
源码安装：
- 若已启用开机自启，服务检测到新凭据后会自动启动守护进程（通常只需数秒）。
- 若采用手动启动栈（未配置服务），需重启以使守护进程加载新凭据：
  - /home/kaiwu/.kaiwu-stack/bin/hstack start --restart

可通过以下命令检查运行状态：

推荐的安装方式：sudo -u kaiwu -H kaiwu auth status
源码安装：/home/kaiwu/.kaiwu-stack/bin/hstack auth status

若启用了 Tailscale 但在安装时跳过了密钥，后续可按如下方式接入：

tailscale up
tailscale set --operator=kaiwu
tailscale serve --bg http://127.0.0.1:3005
tailscale serve status

更新升级

推荐的安装方式：

使用 Proxmox 辅助脚本自带的“Update”更新操作（该操作会执行 kaiwu relay host install，若已安装 Kaiwu CLI，也会一并更新）。
或在容器内部直接更新：
- kaiwu relay host install --mode system --channel stable|preview|dev
- kaiwu self update --channel stable|preview|dev（仅限 Dev box）

源码安装：

暂不完全支持就地热更新。请在全新容器中重新运行安装脚本，或手动更新拉取的工作区代码（适合高级用户）。

On this page