docs: synchronize architecture deployment and MCP documentation
Release / Build & Release (push) Canceled after 0s
Release / Build & Release (push) Canceled after 0s
This commit is contained in:
kory
+39
-139
@@ -1,148 +1,48 @@
|
||||
# VPS-Commander（自托管私有化多节点运维管家）架构与开发设计规范
|
||||
# VPS-Commander 当前系统架构规范
|
||||
|
||||
## 1. 项目立项背景与目标
|
||||
### 1.1 背景与痛点
|
||||
- 当前市面方案（如 Desktop Commander）严重依赖公共第三方中继（SaaS Relay），存在严重的命令与数据泄漏风险、Token 明文暴露风险以及第三方额度/速率限制。
|
||||
- 现有纯开发网关（如 CodePier）采用项目目录沙箱隔离，无法进行系统级运维（如查看全局进程、管理 Lucky/Docker、修改全盘系统配置等），且不支持 ChatGPT 原生 Actions 插件生态。
|
||||
## 1. 研发起点
|
||||
项目最初不是远程终端 UI，而是私有化 AI 运维控制面：用户自己的 Hub 作为控制中枢，多 VPS 通过 Agent 汇聚，AI 通过标准 API/MCP 发起操作，高权限能力可认证、可授权、可审计、可回滚。
|
||||
|
||||
### 1.2 核心目标
|
||||
- **100% 私有化部署**：数据仅在 OpenAI 官方服务器和用户私有 VPS 之间传输，零第三方中转。
|
||||
- **全权宿主运维 (Host-centric)**：提供全局 Shell、进程管理、文件读写能力。
|
||||
- **多节点别名调度**：通过单一 Hub 统一管理多台 VPS/客户端节点，支持在 ChatGPT 中通过自然语言昵称（如 "hwsg"、"wjyhk"）随时切换目标节点。
|
||||
- **原生 ChatGPT 插件集成**：提供标准 OpenAPI 3.1 规范与 Actions 端点，在 ChatGPT 手机端/网页端呈现为原生交互卡片。
|
||||
- **超轻量 Go 架构**：Hub 常驻 RSS 目标 ≤ 20MB、硬上限 25MB；Agent 常驻 RSS 目标 ≤ 10MB、硬上限 12MB。
|
||||
## 2. 双通道
|
||||
控制通道：AI/MCP/HTTP → Hub → Local Executor 或 Agent RPC。
|
||||
节点通道：Agent → WSS → Hub。
|
||||
Hub 同时承担身份、策略、路由、审计和资源门禁；任何 MCP 或 Agent MCP 调用都不能绕过 Hub。
|
||||
|
||||
---
|
||||
## 3. Hub
|
||||
生产 binary：/opt/vps-commander/vps-commander-hub。
|
||||
监听：127.0.0.1:9521。
|
||||
数据库：/opt/vps-commander/data/commander.db。
|
||||
systemd：vps-commander-hub.service。
|
||||
职责：HTTP API、MCP、Panel、设备状态、Agent RPC、Policy Snapshot、credential、audit、Webhook、本地执行。
|
||||
|
||||
## 2. 总体架构设计
|
||||
## 4. Agent
|
||||
Agent 是目标主机上的最小执行面，主动连接 /agent/ws，不要求远端开放管理端口。
|
||||
握手包含 protocol version、AgentVersion、capabilities、per-device credential。
|
||||
设备身份必须来自已认证 credential，不能信任客户端自报 device/name。
|
||||
|
||||
```text
|
||||
[ 用户在 ChatGPT APP / Web 端发指令 ]
|
||||
│
|
||||
▼ (HTTPS POST + Bearer API Key)
|
||||
[ 用户私有域名反代 (Lucky SSL) ]
|
||||
│
|
||||
▼ (反向代理至 127.0.0.1:28800)
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ VPS-Commander Hub (中央管理网关) │
|
||||
│ │
|
||||
│ ├─ OpenAPI / Actions Engine (/openapi.json, /api/v1) │
|
||||
│ ├─ 鉴权与安全过滤中间件 (Auth Middleware) │
|
||||
│ ├─ 设备拓扑注册表 (Device Registry & State Machine) │
|
||||
│ ├─ 审计日志存储 (SQLite: audit.db) │
|
||||
│ └─ 路由分发器 (Router Dispatcher) │
|
||||
└───────────┬────────────────────────────────┬───────────┘
|
||||
│ │
|
||||
(本地进程直连: target="local") (安全 WebSocket 长连接 / mTLS)
|
||||
│ │
|
||||
▼ ▼
|
||||
[ 本机 Local Executor ] [ 远程 Agent (Node: hwsg) ]
|
||||
- bash -c ... - Client Agent Daemon
|
||||
- 文件/进程直接操作 - 接收 JSON-RPC 指令并执行
|
||||
```
|
||||
## 5. 安全模型
|
||||
Client：Bearer API Key；Panel：Panel Session；Agent：per-device credential。
|
||||
Tool Registry 定义静态风险；Policy Snapshot 定义设备运行时权限。
|
||||
Low / Medium / High 是权限上限；unknown device → deny。
|
||||
生产 Shared Secret fallback 已关闭。
|
||||
|
||||
---
|
||||
## 6. Tool Registry
|
||||
Low：read_file、read_multiple_files、list_directory、get_file_info、start_search、get_more_search_results、list_processes、list_sessions、read_process_output。
|
||||
Medium：edit_block、write_file、create_directory、move_file、mcp_call。
|
||||
High：exec_command、start_process、interact_with_process、kill_process、force_terminate。
|
||||
|
||||
## 3. 核心接口与协议规范 (OpenAPI 3.1)
|
||||
## 7. Policy Snapshot
|
||||
SQLite 保存策略版本，Hub 使用内存 Snapshot 处理读路径。
|
||||
version 单调递增；发布失败不替换旧 Snapshot；unknown device 不继承 GlobalRisk High。
|
||||
v2.1 将彻底消除 EffectiveRisk 的 GlobalRisk fail-open fallback。
|
||||
|
||||
ChatGPT Actions 识别的标准接口集合：
|
||||
## 8. Session 与文件安全
|
||||
Session：默认 RingBuffer 2MB，总 buffer 8MB，hard TTL 30m，idle TTL 10m，LastAccess + cleanup。
|
||||
kill/terminate 使用 Session 内部 process handle，不接受客户端 PID；Principal 强隔离属于 v2.1。
|
||||
edit_block：唯一匹配、generation fingerprint、临时文件、fsync、atomic rename、保留权限。
|
||||
|
||||
### 3.1 `/api/v1/devices` (GET)
|
||||
- **说明**：获取当前所有在线/受管设备列表及健康状态。
|
||||
- **返回**：`[{"name": "wjyhk", "is_local": true, "status": "online"}, {"name": "hwsg", "status": "online"}]`
|
||||
|
||||
### 3.2 `/api/v1/exec` (POST)
|
||||
- **说明**：在指定节点执行 Shell 命令。
|
||||
- **请求体**：
|
||||
```json
|
||||
{
|
||||
"device": "hwsg", // 节点昵称，缺省默认 local / wjyhk
|
||||
"command": "free -h", // 要执行的命令
|
||||
"workdir": "/root", // 可选工作目录
|
||||
"timeout": 30 // 超时时间（秒）
|
||||
}
|
||||
```
|
||||
- **响应体**：
|
||||
```json
|
||||
{
|
||||
"device": "hwsg",
|
||||
"exit_code": 0,
|
||||
"stdout": "...",
|
||||
"stderr": "",
|
||||
"duration_ms": 120
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 `/api/v1/fs/read` (POST)
|
||||
- **说明**：受控读取指定设备的文件内容。
|
||||
- **参数**：`device`, `path`, `offset_bytes`, `limit_bytes`（防止大文件撑爆模型上下文）。
|
||||
|
||||
### 3.4 `/api/v1/fs/write` (POST)
|
||||
- **说明**：在指定设备创建或覆写文件。
|
||||
- **参数**：`device`, `path`, `content`。
|
||||
|
||||
---
|
||||
|
||||
## 4. Hub 与 Agent 节点通信规范
|
||||
|
||||
1. **Agent 注册与鉴权**：
|
||||
- Agent 启动时通过 `wss://hub.domain.com/agent/ws` 发起长连接。
|
||||
- 握手使用 `Authorization: Bearer <cluster-secret>` Header；Cluster Secret 不进入 URL。
|
||||
- 握手成功后，Hub 内存注册表更新该设备为 `online`，并启动双向 Heartbeat ping/pong（30s 周期）。
|
||||
|
||||
2. **指令下发 (JSON-RPC)**：
|
||||
- Hub 收到 ChatGPT 请求 ➡️ 生成 `task_id` ➡️ 通过 WS 发送 `{"action": "exec", "task_id": "...", "command": "..."}`。
|
||||
- Agent 执行完毕后返回 `{"task_id": "...", "result": {...}}`。
|
||||
- Hub 审计日志落库后返回给 ChatGPT。
|
||||
|
||||
---
|
||||
|
||||
## 5. 项目工程结构与技术选型
|
||||
|
||||
- **开发语言**：Go 1.22+（高性能、低内存、单二进制交叉编译友好）
|
||||
- **Web 框架**：Gin 或纯标准库 `net/http` + `gorilla/websocket`
|
||||
- **存储**：SQLite (纯粹用于审计日志与持久化配置)
|
||||
|
||||
```
|
||||
vps-commander/
|
||||
├── cmd/
|
||||
│ ├── hub/ # 中央控制网关主入口
|
||||
│ └── agent/ # 节点客户端主入口
|
||||
├── internal/
|
||||
│ ├── api/ # ChatGPT Actions HTTP 接口
|
||||
│ ├── auth/ # Bearer Token 与 Secret 鉴权
|
||||
│ ├── cluster/ # 节点连接池、心跳与 WebSocket 管理
|
||||
│ ├── executor/ # 本地/远程执行器抽象
|
||||
│ └── storage/ # 审计日志与设备配置持久化
|
||||
├── web/ # 极简设备状态面板（纯 HTML/CSS 嵌入二进制）
|
||||
├── openapi/ # 供 ChatGPT 导入的 openapi.json
|
||||
├── Makefile # 多架构编译 (linux/amd64, linux/arm64)
|
||||
└── README.md # 部署与 ChatGPT 配置指南
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Hub Web 控制面板设计规范
|
||||
|
||||
### 6.1 定位与设计原则
|
||||
- **极简独立**：前端采用纯 HTML5 + TailwindCSS/原生CSS + Vanilla JS，不引入复杂 node 构建工具链，通过 Go 1.16+ `embed.FS` 直接打包进单一二进制产物。
|
||||
- **开箱即用**：零外部静态资源依赖，访问 `https://hub.yourdomain.com/` 即可直接加载。
|
||||
- **低资源消耗**：Web 面板由 Hub 服务原生托管，静态文件常驻开销基本为零。
|
||||
|
||||
### 6.2 核心功能模块
|
||||
1. **设备看板 (Device Overview)**
|
||||
- 受管设备列表：别名（Alias）、当前状态（Online/Offline）、系统架构与内核、IP 地址、最后心跳（Heartbeat）。
|
||||
- 快速连接指引：点击“添加节点”，自动生成带 Token 的单行一键安装/运行命令（如 `curl -sL https://... | bash -s -- --hub=... --token=...`）。
|
||||
- 设备启停与踢出操作：支持在面板主动注销失效/弃用节点。
|
||||
|
||||
2. **ChatGPT Actions 配置与向导中心**
|
||||
- 托管与展示 `/openapi.json` 规范预览。
|
||||
- 提供专属 API Key 生成、轮换与撤销功能。
|
||||
- 提供直接导入 ChatGPT Custom GPT 的一键复制 Schema 按钮与预设 System Prompt 建议。
|
||||
|
||||
3. **实时操作审计与日志 (Audit Log)**
|
||||
- 记录来源（ChatGPT / Web 手动）、目标设备、动作（exec / file_read / file_write）、执行内容、执行耗时、退出码与结果摘要。
|
||||
- 支持按设备、关键字实时搜索过滤。
|
||||
|
||||
4. **Web 快速调试终端 (Quick Terminal / Console)**
|
||||
- 提供快速测试输入框，选择目标设备后可直接输入命令测试执行并查看即时输出，无需打开 ChatGPT 即可验证节点联通性。
|
||||
## 9. 部署与回滚
|
||||
Internet → TLS Reverse Proxy → 127.0.0.1:9521；Agent 仅出站 WSS。
|
||||
生产节点：wjyhk、N3450、hwhk、hwsg、m4-live-agent、qnvn。
|
||||
backup → clean build → single-node gray → Hub recovery → rolling Agent → audit → acceptance。
|
||||
发现断联、授权绕过、credential 泄露或协议不兼容，立即停止 rollout 并回滚。
|
||||
|
||||
Reference in New Issue
Block a user