openclaw/vps-commander

Fork 0

Files

T

kory f084ac5bae

Release / Build & Release (push) Canceled after 0s

Details

feat: isolate release source for installers and provisioning

2026-10-02 15:25:19 +08:00

7.4 KiB

Raw Permalink Blame History

VPS-Commander

面向 AI Agent、MCP 与个人运维的高性能、轻量、多节点私有基础设施调度中枢

🌟 核心特性

⚡ 轻量单体部署：纯 Go 原生编译，Hub、Agent、MCP stdio 均可独立部署。
🤖 原生 AI / MCP 接入：提供 HTTP API、MCP SSE、stdio 以及 Agent WebSocket，多种客户端可以共用同一套安全模型。
🌐 Hub & Agent 双通道架构：Hub 负责控制与授权，Agent 通过 WSS 主动回连，不要求远端开放入站管理端口。
🛡️ 认证与授权分离：HTTP/MCP 使用 Bearer API Key；Agent 使用每设备独立 Credential；Tool Registry + Security Snapshot 实现 Low / Medium / High 风险门禁。
📋 完整审计链：SQLite 持久化设备、凭据哈希、策略版本、操作审计与 Webhook 配置。
🧩 多节点能力聚合：文件、Shell、进程、Session、Agent MCP 等能力由 Hub 统一调度。
🖥️ 内嵌 Web 管理面板：Go embed 打包，无需 Node.js 运行时。

🏁 研发最初目标

VPS-Commander 最初并不是一个简单的远程 Shell 工具，而是为 AI Agent 建立一个用户自己控制的私有化 Linux 运维控制面。

1.1 私有化

运维请求通过用户自己的 Hub 和 VPS 节点完成。
不依赖第三方运维 Relay。
凭据、策略和审计数据由用户自己的基础设施控制。

1.2 Host-centric 运维

全局 Shell。
全局文件读写。
进程与长任务 Session。
远程 Agent MCP。

1.3 多节点统一调度

一个 Hub 管理多个 VPS。
使用节点名称选择目标。
节点离线后保留设备身份与持久化状态。

1.4 AI 原生接口

HTTP API。
MCP。
OpenAPI 契约。
Web 管理面板。

🏗️ 当前总体架构

                  +--------------------------------------+
                  |      AI / MCP Client / Web Panel    |
                  +------------------+-------------------+
                                     | HTTPS / MCP / WSS
                                     v
                  +--------------------------------------+
                  |       Reverse Proxy / TLS            |
                  +------------------+-------------------+
                                     | 127.0.0.1:9521
                                     v
        +-----------------------------------------------------------+
        |                    VPS-Commander Hub                     |
        |-----------------------------------------------------------|
        | Auth / API / MCP / Web Panel                             |
        | Security Snapshot / Tool Registry / Audit                |
        | Cluster Router / Session / Rate Limiter                  |
        +----------------------+-------------------+---------------+
                               |                   |
                         Local Executor       Agent WSS
                               |                   |
                               v                   v
                         Hub 本机             Remote VPS
                                                   |
                                            Host Executor
                                            File / Shell / Process

🔐 当前安全模型

1. Client Authentication

Authorization: Bearer <API_KEY> 是 HTTP / MCP 的主要客户端认证方式。

2. Agent Authentication

每个 Agent 使用独立的 VPS_COMMANDER_AGENT_TOKEN。 Hub SQLite 只保存 Credential Hash，不保存明文 Token。

3. Authorization

Tool Registry 首先确定操作风险：

风险	典型能力
Low	读取、搜索、设备/进程观察
Medium	文件修改、目录创建/移动、Agent MCP
High	Shell、进程启动、交互、终止

未知设备、未知身份或策略无法解析时不得获得 High 权限。

4. Shared Secret

生产环境已经关闭 Cluster Secret / Shared Secret fallback。

🤖 当前 MCP 能力

目前共 12 个 MCP Tools：

Tool	Risk	功能
`list_devices`	Low	节点列表与状态
`exec_command`	High	Shell 执行
`read_file`	Low	分页读取文件
`read_multiple_files`	Low	批量读取文件
`create_directory`	Medium	创建目录
`move_file`	Medium	移动/重命名
`list_processes`	Low	进程观察
`edit_block`	Medium	原子文本修改
`write_file`	Medium	创建/覆写文件
`list_agent_mcp`	Low	查看 Agent MCP
`call_agent_mcp`	Medium	调用 Agent MCP

远程 MCP 当前使用 legacy HTTP + SSE；本地客户端使用 stdio。 Streamable HTTP 作为下一阶段 transport 演进方向。

📊 HTTP / Web 能力

接口	方法	功能
`/api/v1/devices`	GET	设备状态与资源画像
`/api/v1/exec`	POST	远程 Shell
`/api/v1/file/read`	POST	文件读取
`/api/v1/file/list`	POST	目录列表
`/api/v1/file/info`	POST	文件信息
`/api/v1/file/search`	POST	文件搜索
`/api/v1/file/write`	POST	文件写入
`/api/v1/devices/file/edit_block`	POST	安全块编辑
`/api/v1/process/session`	POST	Session 操作
`/api/v1/mcp/*`	GET/POST/DELETE	MCP 服务管理与调用
`/api/v1/security/*`	GET/POST	安全策略
`/api/v1/notifications/webhook*`	GET/POST/DELETE	Webhook
`/agent/ws`	WebSocket	Agent 长连接
`/panel/*`	GET/POST	Web 管理面板

🚀 生产部署

Hub：

/opt/vps-commander/vps-commander-hub
/etc/vps-commander/hub.env
/opt/vps-commander/data/commander.db
127.0.0.1:9521

Agent：

/opt/vps-commander/vps-commander-agent
/etc/vps-commander/agent.env
wss://vpstool.kory.kdns.fr/agent/ws

Agent 只主动连接 Hub，不需要公网入站端口。

生产发布顺序： backup → clean build → 单节点灰度 → Hub restart recovery → rolling Agent → MCP/security/audit 验收。

🚀 一键安装与升级

一键安装

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

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

一键升级 Agent

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

升级脚本下载目标 Release、校验文件大小、备份旧版本并在启动失败时自动回滚。

生产环境的 Agent 凭据以独立设备凭据为准；不要将 Cluster Secret 作为长期生产凭据重新启用。

📄 文档索引

📜 开源协议

本项目基于 MIT 协议开源。

7.4 KiB Raw Permalink Blame History Unescape Escape