# VPS-Commander 部署与运维指南

本文档介绍 VPS-Commander 当前生产环境部署架构、凭据规范、Agent 接入、升级与回滚流程。

---

## 一、系统架构与端口规划

- **Hub 服务端**：监听 `127.0.0.1:9521`，不直接暴露公网。
- **反向代理**：公网 HTTPS/WSS 入口为 `https://vpstool.kory.kdns.fr`。
- **Agent 客户端**：通过 `wss://vpstool.kory.kdns.fr/agent/ws` 主动回连 Hub。

反代必须支持：
- WebSocket Upgrade；
- `/agent/ws`；
- `/mcp/*`；
- `/api/v1/*`；
- `/panel/*`；
- `/.well-known/*`；
- `/oauth/*`。

---

## 二、凭据安全规范（强制要求）

### 2.1 Hub 凭据
Hub 使用：
- `VPS_COMMANDER_API_KEY`；
- `VPS_COMMANDER_WEB_PASSWORD`。

生产环境不再依赖 `VPS_COMMANDER_CLUSTER_SECRET` 作为 Agent 身份 fallback。

### 2.2 Agent 凭据
每台 Agent 使用独立：
`VPS_COMMANDER_AGENT_TOKEN`。

Hub SQLite 仅保存 Credential Hash。

### 2.3 文件权限
```bash
chmod 0600 /etc/vps-commander/hub.env
chmod 0600 /etc/vps-commander/agent.env
```

### 2.4 v2.1 安全要求
当前 v2.0 代码仍兼容旧的 `-token` 参数；下一版本要求 Secret 不出现在 argv / `/proc/*/cmdline`，优先使用 systemd EnvironmentFile / LoadCredential。

---

## 三、一键安装与升级

### 3.1 一键安装

```bash
curl -fsSL https://gitea.king.nyc.mn/openclaw/vps-commander/raw/branch/main/deploy/install.sh | sudo bash
```

脚本自动识别 `amd64/arm64`，并进入 Hub / Agent 安装流程。

- Hub：自动生成 API Key 与 Web 面板密码。
- Agent：输入 Hub WSS 地址、节点名称和独立 Agent Token。
- 生产环境不再要求 Cluster Secret 作为长期凭据。

### 3.2 一键升级 Agent

```bash
curl -fsSL https://gitea.king.nyc.mn/openclaw/vps-commander/raw/branch/main/deploy/upgrade-agent.sh | sudo bash
```

升级流程：

```text
下载 Release
   ↓
临时文件完整性检查
   ↓
备份当前 Agent
   ↓
原子替换
   ↓
systemd restart
   ↓
健康检查
   ├─ 成功 → 删除备份
   └─ 失败 → 自动恢复旧版本
```

### 3.3 手工安装

如果需要固定版本、离线部署或灰度验证，再使用下面的手工安装流程。

---

## 四、Hub 服务端部署步骤

### 4.1 编译
```bash
cd /root/.openclaw/workspace/vps-commander
go test ./...
go test -race ./...
git diff --check
make clean
make linux-amd64
```

发布前必须确认：
```text
vcs.modified=false
vcs.revision=<release commit>
```

### 4.2 安装
```bash
install -d -m 0750 /opt/vps-commander/data /etc/vps-commander
install -m 0755 bin/vps-commander-hub-linux-amd64 /opt/vps-commander/vps-commander-hub
```

### 4.3 配置
```bash
cat << 'ENV' > /etc/vps-commander/hub.env
VPS_COMMANDER_API_KEY=your_secure_api_key
VPS_COMMANDER_WEB_PASSWORD=your_web_password
ENV
chmod 0600 /etc/vps-commander/hub.env
```

### 4.4 Systemd
```ini
[Service]
EnvironmentFile=-/etc/vps-commander/hub.env
ExecStart=/opt/vps-commander/vps-commander-hub -addr 127.0.0.1:9521 -db /opt/vps-commander/data/commander.db
Restart=always
RestartSec=3s
```

### 4.5 启动
```bash
systemctl daemon-reload
systemctl enable --now vps-commander-hub
systemctl status vps-commander-hub
```

---

## 五、远程 Agent 节点部署步骤

### 5.1 安装二进制
```bash
install -d -m 0750 /etc/vps-commander /opt/vps-commander
install -m 0755 vps-commander-agent-linux-amd64 /opt/vps-commander/vps-commander-agent
```

### 5.2 配置
```bash
cat << 'ENV' > /etc/vps-commander/agent.env
VPS_COMMANDER_HUB_WS_URL=wss://vpstool.kory.kdns.fr/agent/ws
VPS_COMMANDER_AGENT_NAME=vps-node-01
VPS_COMMANDER_AGENT_TOKEN=<per-device-token>
ENV
chmod 0600 /etc/vps-commander/agent.env
```

### 5.3 Systemd
```ini
[Service]
EnvironmentFile=-/etc/vps-commander/agent.env
ExecStart=/opt/vps-commander/vps-commander-agent -hub ${VPS_COMMANDER_HUB_WS_URL} -name ${VPS_COMMANDER_AGENT_NAME}
Restart=always
RestartSec=3s
```

当前 v2.0 生产迁移阶段可兼容显式 token；v2.1 发布后必须改为不出现在 ExecStart 的方式。

### 5.4 启动
```bash
systemctl daemon-reload
systemctl enable --now vps-commander-agent
systemctl status vps-commander-agent
```

Agent 启动后主动连接 Hub，并在设备列表中显示为 `online`。

---

## 六、控制面板与 MCP 使用

### 6.1 管理面板
`https://vpstool.kory.kdns.fr/panel/login`

面板包含设备状态、安全策略、操作控制、审计和相关管理功能。

### 6.2 MCP
远程入口：
`https://vpstool.kory.kdns.fr/mcp/sse`

本地 stdio 使用 `vps-commander-mcp-stdio`。

当前共 12 个 MCP tools，详见 `docs/MCP_INTEGRATION.md`。

---

## 七、生产升级流程

```text
Backup
  ↓
Clean Build
  ↓
Single-node Gray Release
  ↓
Hub Restart Recovery
  ↓
Rolling Agent
  ↓
MCP / Security / Audit Smoke Test
  ↓
Full Acceptance
```

任一节点断联、权限绕过、Credential 泄露或协议不兼容，立即停止发布并回滚。

---

## 八、日常运维检查

```bash
systemctl status vps-commander-hub
journalctl -u vps-commander-hub -n 100
curl -fsS http://127.0.0.1:9521/healthz
```

集群可通过 Web Panel、`/api/v1/devices` 或 MCP `list_devices` 检查。

---

## 九、当前生产审计提示

2026-10-02 审计发现生产 Hub / Agent 曾由 `vcs.modified=true` 的工作树构建。
因此生产现场二进制不能直接视为当前 HEAD 的可复现产物。
下一次正式发布必须 clean rebuild，并重新部署与验证。