149 lines
7.4 KiB
Markdown
149 lines
7.4 KiB
Markdown
# VPS-Commander（自托管私有化多节点运维管家）架构与开发设计规范
|
||
|
||
## 1. 项目立项背景与目标
|
||
### 1.1 背景与痛点
|
||
- 当前市面方案（如 Desktop Commander）严重依赖公共第三方中继（SaaS Relay），存在严重的命令与数据泄漏风险、Token 明文暴露风险以及第三方额度/速率限制。
|
||
- 现有纯开发网关（如 CodePier）采用项目目录沙箱隔离，无法进行系统级运维（如查看全局进程、管理 Lucky/Docker、修改全盘系统配置等），且不支持 ChatGPT 原生 Actions 插件生态。
|
||
|
||
### 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. 总体架构设计
|
||
|
||
```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 指令并执行
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 核心接口与协议规范 (OpenAPI 3.1)
|
||
|
||
ChatGPT Actions 识别的标准接口集合：
|
||
|
||
### 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 即可验证节点联通性。
|