# VPS-Commander 部署与运维指南

本文档介绍 VPS-Commander 的生产环境部署架构、配置规范与运维操作。

---

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

- **Hub 服务端**：统一监听本地 `127.0.0.1:9521`，不对公网直接暴露端口。
- **反向代理 (Lucky)**：
  - 域名：`https://vpstool.kory.kdns.fr`
  - 转发目标：`http://127.0.0.1:9521`
  - 核心要求：开启 **WebSocket Upgrade** 支持，转发透传所有子路径（`/.well-known/*`、`/oauth/*`、`/mcp/*`、`/api/v1/*`、`/agent/ws`、`/panel/*`）。
  - SSL 终止于反代层，反代自动携带 `X-Forwarded-Proto: https` 头以保障 Cookie 的 `Secure` 属性。
- **Agent 客户端**：
  - 运行于受控的远程 VPS 机器上。
  - 通过公网 WSS 长连接主动回连 Hub：`wss://vpstool.kory.kdns.fr/agent/ws`。

---

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

1. **绝对禁止命令行参数传密**：
   - 二进制不再支持 `--api-key`、`--cluster-secret`、`--web-password` 命令行参数。
   - 彻底杜绝在 `/proc/*/cmdline` 和 `ps aux` 中泄露明文密码。
2. **凭据存储位置与权限**：
   - 凭据文件保存在 `/etc/vps-commander/hub.env` 与 `/etc/vps-commander/agent.env`。
   - 权限必须严格设置为 `0600`（仅 root 可读写）。

---

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

### 1. 编译并安装二进制
```bash
cd /root/.openclaw/workspace/vps-commander
make linux-amd64
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
```

### 2. 配置环境变量文件 (`/etc/vps-commander/hub.env`)
```bash
cat << 'ENV' > /etc/vps-commander/hub.env
VPS_COMMANDER_API_KEY=your_generated_api_key_here
VPS_COMMANDER_CLUSTER_SECRET=your_generated_cluster_secret_here
VPS_COMMANDER_WEB_PASSWORD=your_generated_web_password_here
ENV
chmod 0600 /etc/vps-commander/hub.env
```

### 3. 配置 Systemd 托管 (`/etc/systemd/system/vps-commander-hub.service`)
```ini
[Unit]
Description=VPS-Commander Hub
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/vps-commander
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
KillSignal=SIGTERM
TimeoutStopSec=10s
LimitNOFILE=65536
Environment=GOGC=50

[Install]
WantedBy=multi-user.target
```

### 4. 启动服务
```bash
systemctl daemon-reload
systemctl enable --now vps-commander-hub
systemctl status vps-commander-hub
```

---

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

若要将其他 VPS 纳入受控列表，在该远程 VPS 上执行：

### 1. 安装 Agent 二进制
将编译生成的 `bin/vps-commander-agent-linux-amd64`（或 ARM64 版本）上传至目标 VPS 的 `/opt/vps-commander/vps-commander-agent` 并赋予执行权限 `chmod +x`。

### 2. 配置 Agent 环境变量 (`/etc/vps-commander/agent.env`)
```bash
install -d -m 0750 /etc/vps-commander
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_CLUSTER_SECRET=与Hub相同的CLUSTER_SECRET
ENV
chmod 0600 /etc/vps-commander/agent.env
```

### 3. 配置 Systemd 托管 (`/etc/systemd/system/vps-commander-agent.service`)
```ini
[Unit]
Description=VPS-Commander Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/vps-commander
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
KillSignal=SIGTERM
TimeoutStopSec=10s
LimitNOFILE=65536
Environment=GOGC=50

[Install]
WantedBy=multi-user.target
```

### 4. 启动并连入集群
```bash
systemctl daemon-reload
systemctl enable --now vps-commander-agent
```
启动后，Hub 控制面板与 `/api/v1/devices` 接口将立即展示该节点并标记为 `online`。

---

## 五、 控制面板与 Actions 使用

1. **管理后台地址**：`https://vpstool.kory.kdns.fr/panel/login`
2. **后台功能**：
   - **设备看板**：查看所有在线/离线节点、系统架构与延迟。
   - **快速控制台**：直接在网页端向指定节点执行 Shell 指令。
   - **审计日志**：实时监控 GPT 与用户的全部执行调用、命令详情与耗时。
   - **Actions 向导**：一键复制 Schema 地址、System Prompt 与 API 密钥。