120 lines
4.5 KiB
Markdown
120 lines
4.5 KiB
Markdown
# VPS-Commander 详细技术规格与开发实施方案 (v1.1.0)
|
||
|
||
## 一、 系统架构角色划分
|
||
|
||
整个系统划分为两个独立二进制产物（单一代码库仓库编译）：
|
||
1. **`vps-commander-hub` (中央网关 + 控制面板)**：
|
||
- 部署在有公网域名或反代的主机上（当前主力机 `wjyhk`）。
|
||
- 监听端口：`127.0.0.1:9521`（由 Lucky 负责 TLS 证书卸载与反代）。
|
||
- 暴露端点：
|
||
- 面向 ChatGPT Actions：`/api/v1/*`（Bearer Token 鉴权）
|
||
- 面向 Agent 长连接：`/agent/ws`（Cluster Secret 握手）
|
||
- 面向用户极简管理面板：`/` 及 `/static/*`（Go embed 静态资源，支持密码登录/Cookie鉴权）
|
||
- 描述文件：`/openapi.json`
|
||
- 本身内置 Local Executor（直接代表本地主力机，设备名：`local` 或自定义主机名）。
|
||
2. **`vps-commander-agent` (节点轻量客户端)**：
|
||
- 部署在其他受管节点（如 `hwsg` 等）。
|
||
- 主动向 Hub 发起安全 WebSocket 连接（支持断线指数退避重连）。
|
||
- 纯受控执行器，只响应 Hub 下发指令，不开放任何公网入站端口（彻底规避防火墙/NAT问题）。
|
||
|
||
---
|
||
|
||
## 二、 协议设计 (RPC over WebSocket)
|
||
|
||
### 2.1 握手与注册 (Handshake)
|
||
Agent 连接 URL: `wss://hub.domain.com/agent/ws?device_name=hwsg`
|
||
- Hub 校验通过后：
|
||
- 发送握手成功包：`{"event": "registered", "device": "hwsg", "heartbeat_interval": 30}`
|
||
- 将该连接注入 `DeviceManager`，状态标为 `online`。
|
||
|
||
### 2.2 心跳 (Ping/Pong)
|
||
- 每 30 秒由 Hub 发送 `{"event": "ping", "ts": 1727049600}`。
|
||
- Agent 回复 `{"event": "pong", "ts": 1727049600}`。连续 2 次无响应标记为 `offline`。
|
||
|
||
### 2.3 命令下发与响应 (Request-Response)
|
||
- Hub 下发：
|
||
```json
|
||
{
|
||
"id": "task_6b7a8c9d",
|
||
"action": "exec",
|
||
"payload": {
|
||
"command": "free -h",
|
||
"workdir": "/root",
|
||
"timeout": 30
|
||
}
|
||
}
|
||
```
|
||
- Agent 执行完返回：
|
||
```json
|
||
{
|
||
"id": "task_6b7a8c9d",
|
||
"status": "success",
|
||
"exit_code": 0,
|
||
"stdout": "...",
|
||
"stderr": "",
|
||
"duration_ms": 45
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、 ChatGPT Actions (OpenAPI 3.1) 接口定义
|
||
|
||
完整的 `openapi.json` 规范定义了以下 4 个原子能力：
|
||
|
||
1. **`list_devices`**:
|
||
- `GET /api/v1/devices`
|
||
- 返回受管设备名、IP、状态（online/offline）、最后心跳。
|
||
2. **`exec_command`**:
|
||
- `POST /api/v1/exec`
|
||
- 参数：`device` (默认: "local"), `command`, `workdir`, `timeout`。
|
||
3. **`read_file`**:
|
||
- `POST /api/v1/file/read`
|
||
- 参数：`device`, `path`, `offset`, `limit`。
|
||
4. **`write_file`**:
|
||
- `POST /api/v1/file/write`
|
||
- 参数：`device`, `path`, `content`。
|
||
|
||
---
|
||
|
||
## 四、 Hub Web 控制面板功能规范
|
||
|
||
### 4.1 技术实现
|
||
- 单二进制静态内嵌：基于 Go `embed.FS` 打包 HTML5 + TailwindCSS + Vanilla JS。
|
||
- 零外部 npm/node 依赖，开箱即用。
|
||
|
||
### 4.2 功能矩阵
|
||
1. **设备看板 (Devices Dashboard)**：
|
||
- 节点列表展示（名称、IP、状态、架构/系统版本、最后活跃时间）。
|
||
- 一键生成 Agent 安装注册命令（带 Token 参数）。
|
||
- 手动注销/踢出无效节点。
|
||
2. **ChatGPT Actions 向导 (Actions Guide)**：
|
||
- 动态渲染 `openapi.json` 并提供一键复制。
|
||
- API Key 凭据生成、轮换与撤销。
|
||
- 预设 System Prompt 最佳实践一键复制。
|
||
3. **安全审计追踪 (Audit Trails)**：
|
||
- 实时日志流水：时间戳、来源 IP、目标节点、操作类型、执行命令、执行耗时、退出状态。
|
||
- 支持日志按设备名、时间区间筛选。
|
||
4. **快速网页终端 (Quick Console)**：
|
||
- 应急测试控制台，免切 ChatGPT 直接在 Web 端选择节点跑指令验证联通性。
|
||
|
||
---
|
||
|
||
## 五、 存储与安全审计 (SQLite)
|
||
|
||
- 数据库文件：`data/commander.db`
|
||
- 数据表结构：
|
||
1. `devices`：记录设备名、备注、添加时间、密钥 Hash。
|
||
2. `audit_logs`：
|
||
- `id`, `timestamp`, `caller_ip`, `device`, `action`, `command`, `exit_code`, `duration_ms`, `error_msg`
|
||
- 确保在 ChatGPT 里执行的所有高危操作均可追溯。
|
||
|
||
---
|
||
|
||
## 六、 开发实施里程碑 (Milestones)
|
||
|
||
- [ ] **M1: 基础骨架与单机执行**（完成本地 Local Executor + Gin API + Bearer 鉴权 + `/openapi.json`）
|
||
- [ ] **M2: Agent WebSocket 协议与多节点分发**（完成 Agent 注册、心跳保活、Hub 路由转发）
|
||
- [ ] **M3: 审计日志与嵌入式 Web 管理页**（完成前端内嵌、看板交互、命令历史审计与快速控制台）
|
||
- [ ] **M4: 本机 Lucky 证书反代与 ChatGPT 联调上线**
|