convez.ai
MCP Server
lokeyxwin

vps-server

lokeyxwin/vps-server

Ver no GitHub
InicialPluginScore · de 0 a 100

VPS 资产管理 + 代理出口自动化 — Python 异步状态机 + MCP 工具集(双壳 admin/user) + 配套 agent skill

Instalação

$npx convez-ai lokeyxwin/vps-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

vps-server

VPS 资产管理 + 代理出口自动化 — 给个人 / 小团队用的后端服务。

你手上有一堆 VPS(自建 / 服务商租) + 一堆上游代理 IP(从代理商买的),想把它们 "自动装好 xray + 自动挂出口 IP + 自动验证可用性"凑成一个可用的代理节点池, agent 一句"给我一个新加坡节点"就能拿到 host:port + 账密。

这就是本项目要解决的事。


目录


1. 这是什么

1.1 业务流(端到端)

用户 / agent
   │  ① register_vps (一台 VPS 凭据)
   ├──▶ 后端: SSH 测连 → 入库 → 派后台装机任务
   │
   │  ② register_ip (一条上游 IP 凭据)
   ├──▶ 后端: 测试机临时挂 outbound 校验账密 → 通则入库 → 派后台部署任务
   │
   ▼
后端常驻 worker (异步)
   ├─ XrayWorker         扫装机任务 → SSH 进 VPS 装 xray + 起 + 自启 +
   │                                    纳管已有出口配置
   └─ ProxyDeployWorker  扫部署任务 → 挑机 + 高位随机端口 + 配上线 +
                                       内外 ping → 入 proxy_record
   ▼
agent 调
   get_available_proxy_nodes("SG") → 返回可用节点 host:port + 账密 + 出口 IP + 地区

1.2 跟谁交互

  • agent / 用户 — 通过 MCP 工具调 register_vps / register_ip / 查询节点
  • VPS — 后端 SSH 远程操作(装 xray / 改 config / 开防火墙端口)
  • 上游代理服务商 — 后端拿凭据测连通,本身不存 API key
  • 数据库 — SQLite (默认 dev) / MySQL (生产)

1.3 当前能力

业务状态
VPS 登记 + xray 装机 + 纳管已有配置✅ 完整闭环
上游 IP 登记 + 校验账密✅
测试机自举 (没装 xray 自动装)✅ (ADR-0009 + T-19)
代理部署 + 内外 ping 验证✅
可用节点查询(按地区)✅
装机失败 / 容量满 / 安全组未放行 等失败状态查询✅
巡检(IP 到期 / VPS 续费)⏸ 封存 worker,后续启用

2. 架构 30 秒

2.1 二进程模型

mcp_server.py        前台收单     接 MCP 协议, 分发工具 handler
                                  (Claude Desktop / OpenClaw / Codex 拉起)
       │
       └─ 调 db/queries.py / workers/ssh_worker / workers/ip_probe_worker

main.py worker-loop  后端常驻     扫 task 表 + 推异步段 worker
                                  (systemd / launchd / Windows 服务 拉起)
       │
       └─ 串行调度 XrayWorker.run_once() + ProxyDeployWorker.run_once()

两进程独立:MCP server 挂了不影响装机 worker,反之亦然。

2.2 四层职责

层位置干啥
协议适配tools/*.pyMCP arguments → 业务函数 → JSON 包 TextContent
异步业务workers/*.py扫 task 表 + 编排原子工具 + 状态机
业务函数db/queries.pyMCP 工具调的所有业务函数(读写都在,白名单 patch)
ORMdb/models.py表结构 + ORM 模型

2.3 MCP 工具暴露面(双壳)

壳端口工具
admin47180register_vps / register_ip / init_db / init_probe_vps / 全部查询
user47181get_available_proxy_nodes / get_vps_registration_status / get_ip_registration_status (只读)

详见 §5 客户端配置。


3. 快速部署 — 从零到能跑

目标:在一台新机器上 5 步起来,先确认能跑通,再考虑 §4 常驻守护。 任何 OS 都能跑(部署本身平台无关),Linux 推荐生产用。

3.1 物料清单

物料说明
Python 3.10+项目用 3.13 开发,3.10+ 应该都能跑
uv项目依赖管理工具
git拉代码
dev 机macOS / Linux / Windows 任一,自己开发 / 测试用
生产机推荐 Ubuntu 22.04+ / Debian 12 / CentOS 9(有 systemd)
.env加密密钥 / 可选 token,项目根目录
测试 VPS × 1给 IPProbeWorker 校验上游 IP 用,自己掏钱租一台

3.2 装依赖

# 1. 装 uv (macOS / Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# Windows PowerShell:
# irm https://astral.sh/uv/install.ps1 | iex

# 2. 拉代码 + 装依赖
git clone <仓库地址> vps_server
cd vps_server
uv sync          # 自动建 .venv + 装依赖

3.3 配 .env(敏感)

必填速查:ENCRYPTION_KEY(缺了不报启动错,第一次登记 VPS 存密码时才炸)

  • PROBE_VPS_1_IP / PROBE_VPS_1_PWD(缺了 register_ip 直接返 probe_vps_unreachable)。 选填:MYSQL_PASSWORD(SQLite 不用)/ IPINFO_TOKEN(不填走匿名小额度)。
cp .env.example .env
chmod 600 .env             # macOS / Linux: 别让别人偷看
# Windows: 用 NTFS 权限或不管 (dev 机)

# 编辑 .env:
# 密码加密密钥 — 首次本地用下面命令生成一次, 之后永远别改
# 改了 = 老 DB 里所有密文全废, 没法解
# 生成命令:
# python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
ENCRYPTION_KEY=<上面命令的输出>

# MySQL 密码 — 用 SQLite 不用填
MYSQL_PASSWORD=

# ipinfo.io token — 查 IP 归属地用, 不填走匿名极小额度
IPINFO_TOKEN=

# 测试 VPS 凭据 (给 IPProbeWorker 校验上游 IP 用, 最多 3 台)
PROBE_VPS_1_IP=
PROBE_VPS_1_PORT=22
PROBE_VPS_1_USER=root
PROBE_VPS_1_PWD=

⚠️ ENCRYPTION_KEY 是生产命脉。换一台机部署同一个 DB → 必须复用同一把 key。 备份到密码管理器,别只存生产机一份。

3.4 初始化(首次必做两步)

# 跑测试确认环境 OK
PYTHONPATH=. VPS_SERVER_TESTING=1 uv run pytest -q

# ① 建 DB 表
PYTHONPATH=. uv run python main.py init-db
# 看到 "init-db 完成: N 张表已就绪" 算成功

# ② 装测试 VPS (xray 装 + 起 + 留 inbound 19000, 幂等)
PYTHONPATH=. uv run python main.py init-probe-vps
# 看到 "init-probe-vps 完成: host=... inbound_port=19000" 算成功

这两步什么时候要重跑:

  • 加新 ORM 表 → 重跑 init-db(已有表不动,只补新表)
  • 换测试 VPS / 测试机 xray 挂了 → 重跑 init-probe-vps
  • agent 查询时看到 probe_vps_not_ready → 重跑 init-probe-vps

⚠️ 关于 SSH 用户权限(T-19 真机验证经验):

init-probe-vps 走的 SSH 用户(PROBE_VPS_N_USER)必须能 写 /usr/local/etc/xray/ + 跑 systemctl reload xray —— 也就是 root 或带免密 sudo 的用户。

云服务商默认给的非 root 账号(ubuntu / centos / admin 等)直接配进去会挂:

阶段报错
installerror: You must run this script as root! → 退码 1
add inbound (步⑤)bash: /usr/local/etc/xray/config.json: Permission denied

错误 message 会清晰返回 probe_vps_not_ready + Permission denied / 必须 root, agent 收到这个 status 应当引导用户切 root,而不是让用户对着权限错误自己排查。

两种修法选一个 ——

1. 直接给 root(推荐,测试机我们自己的,安全可控):

# 测试机上, 在云厂商账号 (如 ubuntu) 的 shell 里
sudo passwd root                                                          # 设 root 密码
sudo sed -i 's/^#*PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config
sudo systemctl restart ssh
# 嫌设新密码麻烦, 可以一行把 root 密码 hash 跟现有用户同步 (密码不入 chat):
# sudo usermod -p "$(sudo getent shadow ubuntu | cut -d: -f2)" root

然后改 ~/.zshrc.local:PROBE_VPS_N_USER="root" + 对应 PWD 改成 root 密码, source ~/.zshrc.local 重新跑 init-probe-vps。

2. 给非 root 账号开免密 sudo(配套要改 xray/service.py 命令加 sudo 前缀, 当前项目未做,真有需求再单独开 task)。

3.5 手动跑通确认

# 看子命令
PYTHONPATH=. uv run python main.py --help
# 应看到: init-db / init-probe-vps / worker-loop 三个子命令

# 起 worker-loop (前台跑, Ctrl+C 退)
PYTHONPATH=. uv run python main.py worker-loop
# 看到:
# HH:MM:SS [INFO] main.worker_loop: main.worker-loop 启动: poll_interval=2s, ...
# (静默轮询, 没 task 时不打日志)
#
# Ctrl+C (= SIGINT) 后看到:
# HH:MM:SS [INFO] main.worker_loop: 收到信号 2, 准备优雅退出
# HH:MM:SS [INFO] main.worker_loop: main.worker-loop 已退出

这一步通过 = 后端能跑了。下一步要么手动跑 MCP server (调一次试试), 要么进 §4 做成守护服务长期跑。


4. 跑成常驻守护服务

上面 §3 是"手动起前台进程",Ctrl+C 就停 + 机器重启就丢。 §4 是"做成守护服务" — 开机自启 + 崩了自动拉起 + 优雅退出。 Linux 用 systemd,macOS 用 launchd,Windows 用 NSSM(三选一,看你部署到哪)。

4.1 什么是"守护 unit / plist / service" + 你要守护几个进程

4.1.1 守护服务管理器(3 OS)

不同 OS 有不同的"守护服务管理器",共同要求:一份文本配置文件告诉操作系统 "这个进程怎么拉起 / 用哪个账号跑 / 崩了怎么处理 / 怎么优雅停"。 我们项目这份配置都放在 deploy/ 目录,3 个 OS 各自一份。

OS管理器配置文件格式我们的文件
Linuxsystemd.service (INI 风格)deploy/vps-server-worker.service
macOSlaunchd.plist (XML)deploy/com.vps-server.worker.plist
WindowsNSSM (推荐)NSSM 控制台 + 命令行deploy/install-windows-nssm.md

4.1.2 守护几个进程 — 看你用哪些 MCP 客户端

核心区别: stdio 客户端自己拉子进程,HTTP 客户端只是连接已监听的端口。

你用的客户端要守护几个进程守护谁
只 Claude Desktop / Claude Code(stdio)1 个main.py worker-loop
只 OpenClaw / Codex(HTTP)3 个worker-loop + mcp_server admin (47180) + mcp_server user (47181)
共存(Claude + OpenClaw + Codex)3 个同上(Claude Desktop 走 stdio,自己拉另一个子进程,不影响其他 3 个)

为什么 stdio 不守护 mcp_server.py:

  • Claude Desktop 启动时按 config 的 command 直接 fork+exec 拉子进程
  • Claude 关闭时子进程被回收
  • 你重启 Claude → 自动拉新子进程
  • 所以 mcp_server.py stdio 模式永远不要进守护管理器 —— 否则两个进程并发抢同一 stdio 会出错

为什么 HTTP 必须守护 mcp_server.py:

  • OpenClaw / Codex 只是按 url 发 HTTP 连接,不会拉子进程
  • 进程没人启动 = 端口没人监听 = 客户端 connection refused
  • 客户端重启不影响 HTTP 进程(进程不归客户端管)
  • 所以 HTTP MCP server admin + user 两个都要守护,跟 worker-loop 一样进 systemd / launchd / NSSM

4.1.3 心智图

[共存场景 — 三客户端通吃, 3 进程守护]

        守护层 (systemd / launchd / NSSM)
        ├── main.py worker-loop                                      ← 进程 1
        ├── mcp_server.py --role admin --http  (127.0.0.1:47180)     ← 进程 2
        └── mcp_server.py --role user  --http  (127.0.0.1:47181)     ← 进程 3
                  ▲                            ▲
                  │ HTTP 连接                   │ HTTP 连接
        ┌─────────┴────────┐         ┌─────────┴───────┐
   OpenClaw 5.12             Codex (GPT auth)        Claude Desktop ─────fork+exec
   (重启不影响后端)            (重启不影响后端)         │
                                                     ▼
                                            mcp_server.py (stdio 子进程)
                                            (Claude 自己拉, 关闭就回收)

只要守护那 3 个进程不挂,所有客户端来去自由,工具永远可见。


4.2 Linux — systemd

# 1. 改 deploy/vps-server-worker.service 里的 4 处占位
#    User= / Group= / WorkingDirectory= / EnvironmentFile=
#    跟你实际的业务账号 + 部署路径对齐

# 2. 装到系统
sudo cp deploy/vps-server-worker.service /etc/systemd/system/
sudo systemctl daemon-reload                     # 让 systemd 看见新 unit

# 3. 起 + 开机自启 (一行)
sudo systemctl enable --now vps-server-worker

# 4. 验证
sudo systemctl status vps-server-worker          # 应看到 Active: active (running)
sudo journalctl -u vps-server-worker -f          # 实时看日志

unit 文件长这样(截选):

[Unit]
Description=VPS Server — worker loop
After=network-online.target

[Service]
Type=simple
User=vps_server
WorkingDirectory=/opt/vps_server
EnvironmentFile=/opt/vps_server/.env
ExecStart=/opt/vps_server/.venv/bin/python main.py worker-loop

KillSignal=SIGTERM
TimeoutStopSec=120           # 给 120s 跑完手头活
Restart=on-failure           # 崩了 5s 后自动拉起
RestartSec=5s
StartLimitBurst=5            # 5 分钟崩 5 次就放弃 (防雪崩)

NoNewPrivileges=yes          # 安全收紧
ProtectSystem=strict

[Install]
WantedBy=multi-user.target

完整文件见 deploy/vps-server-worker.service,顶部注释列了 4 处必改占位。


4.3 macOS — launchd

dev 机用得多,生产偶尔。

# 1. 改 deploy/com.vps-server.worker.plist 里的路径占位
#    把 /Users/<you>/path/to/vps_server 换成你实际路径

# 2. 装到 LaunchAgents (用户级, 当前账号登录就拉起)
cp deploy/com.vps-server.worker.plist ~/Library/LaunchAgents/

# 3. 启 + 注册
launchctl load -w ~/Library/LaunchAgents/com.vps-server.worker.plist

# 4. 验证
launchctl list | grep vps-server                  # 应看到一行带 PID
tail -f /tmp/vps-server-worker.log                # 日志默认输出到这里

# 停 + 取消注册
launchctl unload -w ~/Library/LaunchAgents/com.vps-server.worker.plist

plist 守护机制:

  • RunAtLoad=true — 装上就拉起
  • KeepAlive=true — 崩了自动拉起
  • ProcessType=Background — 标记后台服务
  • 日志重定向到 /tmp/vps-server-worker.log(可改成项目目录下)

完整文件见 deploy/com.vps-server.worker.plist。

⚠️ macOS 盖电脑会挂起进程。dev 用足够,生产别上 macOS。


4.4 Windows — NSSM

NSSM = Non-Sucking Service Manager,Windows 上最简 "把任何 exe / 命令包成 Windows 服务" 的工具。Windows 自带 sc.exe 也能做但麻烦。

# 1. 装 NSSM (Chocolatey 或者下载 zip 解压加 PATH)
choco install nssm

# 2. 注册服务
nssm install vps-server-worker `
  "C:\Path\To\vps_server\.venv\Scripts\python.exe" `
  "main.py worker-loop"

nssm set vps-server-worker AppDirectory "C:\Path\To\vps_server"
nssm set vps-server-worker AppEnvironmentExtra "PYTHONPATH=C:\Path\To\vps_server"
nssm set vps-server-worker AppStdout "C:\Path\To\vps_server\logs\worker.log"
nssm set vps-server-worker AppStderr "C:\Path\To\vps_server\logs\worker.err"
nssm set vps-server-worker Start SERVICE_AUTO_START      # 开机自启
nssm set vps-server-worker AppExit Default Restart       # 崩了自动重启
nssm set vps-server-worker AppRestartDelay 5000          # 5 秒退避

# 3. 启 + 验证
nssm start vps-server-worker
nssm status vps-server-worker                            # 应看到 SERVICE_RUNNING

# 4. 看日志 / 停 / 卸
Get-Content C:\Path\To\vps_server\logs\worker.log -Tail 50 -Wait
nssm stop vps-server-worker
nssm remove vps-server-worker confirm

完整 PowerShell 安装脚本 + NSSM 各参数解释见 deploy/install-windows-nssm.md(含一键脚本 deploy/install-windows.ps1)。

⚠️ Windows 上优雅退出依赖 NSSM 的 SIGINT 模拟(因为 Windows 没 SIGTERM)。 我们 main.py 的 SIGINT handler 一致管,NSSM stop 时会等当前轮跑完。


5. MCP 客户端怎么连

5.1 stdio 模式 — Claude Desktop / Claude Code

最简,客户端自己拉子进程,不用守护。编辑客户端配置文件:

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vps_admin": {
      "command": "/path/to/vps_server/.venv/bin/python",
      "args": ["mcp_server.py", "--role", "admin"],
      "cwd": "/path/to/vps_server",
      "env": { "PYTHONPATH": "/path/to/vps_server" }
    },
    "vps_user": {
      "command": "/path/to/vps_server/.venv/bin/python",
      "args": ["mcp_server.py", "--role", "user"],
      "cwd": "/path/to/vps_server",
      "env": { "PYTHONPATH": "/path/to/vps_server" }
    }
  }
}

Windows 的 command 写 .venv\Scripts\python.exe。

5.2 HTTP 模式 — OpenClaw 5.12 + Codex (GPT auth) 共存

⚠️ 当前 mcp_server.py 是 stdio 实现。走 §5.2 需要后续把 stdio 改成 HTTP transport + 同时挂 /sse 和 /mcp 两个 endpoint (改造任务后续单独开,跟 §5.1 stdio 不冲突 — 同代码两套启动方式)。

5.2.1 为什么必须 4 条注册

admin 壳  127.0.0.1:47180          user 壳  127.0.0.1:47181
├── /sse  → OpenClaw 注册          ├── /sse  → OpenClaw 注册
└── /mcp  → Codex 注册             └── /mcp  → Codex 注册

= 4 条注册全填齐才完整 (2 客户端 × 2 壳)

关键认知:OpenClaw 里 GPT auth 用 Codex 插件,不代表 GPT 自动读到 OpenClaw 的 mcp.servers。两边各自独立:

  • OpenClaw 可见 → ~/.openclaw/openclaw.json 的 mcp.servers
  • Codex / GPT auth 可见 → ~/.codex/config.toml 的 [mcp_servers.*]

5.2.2 客户端 config 模板

OpenClaw 侧 ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "vps_admin": { "url": "http://127.0.0.1:47180/sse", "transport": "sse" },
      "vps_user":  { "url": "http://127.0.0.1:47181/sse", "transport": "sse" }
    }
  }
}

Codex 侧 ~/.codex/config.toml:

[mcp_servers.vps_admin]
url = "http://127.0.0.1:47180/mcp"
startup_timeout_sec = 120

[mcp_servers.vps_user]
url = "http://127.0.0.1:47181/mcp"
startup_timeout_sec = 120

5.2.3 反例 — 别踩

反例后果正解
只在 OpenClaw 注册, 期望 GPT auth 也能看到GPT 调不到工具OpenClaw + Codex 两边都注册
两边写同一个端点Codex 不识别 SSE → 启动报错OpenClaw 走 /sse, Codex 走 /mcp
admin / user 端口写反user 拿到 admin 权限(权限边界破了)严格 47180=admin / 47181=user
监听 0.0.0.0 不绑 127.0.0.1admin 端点对公网暴露,任何人能调 register_vps必须绑 127.0.0.1,agent 同机访问

5.3 配套 skill 安装(连上 MCP 后做)

本仓库 skills/ 目录是 MCP 服务的配套 skill — 教 agent 怎么正确使用这套 MCP 工具(典型场景 / 调用姿势 / 交付格式 / 反例)。连好 MCP 后把 skill 装进 客户端,agent 的使用质量会明显好于裸看工具列表。

skill配套壳干什么
get-available-proxy-nodesuser 壳教 agent 查可用代理节点 + 小火箭交付格式 + 反例

(admin 壳工作流 skill 后续追加,装法相同。)

通用安装方法(各客户端同理):

  1. 找客户端的 skills 目录 — 一般在家目录(或项目根目录)的点目录下找 skills/:

    客户端skills 目录
    Claude Code / Claude Desktop~/.claude/skills/(或项目级 .claude/skills/)
    OpenClaw~/.openclaw/skills/
    Codex$CODEX_HOME/skills/(默认 ~/.codex/skills/)
    Hermes~/.hermes/skills/
    其他在它的根/配置目录里找 skills/,没有就查该客户端文档
  2. 整个 skill 文件夹拷过去(保持目录名 = skill 名):

    cp -r /path/to/vps_server/skills/get-available-proxy-nodes ~/.openclaw/skills/
    
  3. 注册进 runtime:多数客户端自动扫描 skills 目录,重启客户端或新开会话即生效; 需要显式注册的客户端,按其文档把 skill 加进 runtime 配置。

  4. 验证:新开会话问 agent「你有哪些 skill」,确认列表里出现 get-available-proxy-nodes。

模型主动汇报义务:连接本 MCP 的 agent 在首次会话或用户问「你能干嘛」时, 应主动汇报已装的配套 skill(名字 + 一句话用途),让用户知道有现成玩法, 不用自己摸工具列表。


6. 端口配置 + 改端口怎么办

6.1 项目固定端口清单

所有端口常量都在 config.py,改一处即可:

用途默认config.py 常量改了要重启什么
MCP admin 壳监听47180MCP_ADMIN_PORTmcp_server.py admin 实例
MCP user 壳监听47181MCP_USER_PORTmcp_server.py user 实例
MCP 监听地址127.0.0.1MCP_LISTEN_HOST同上
xray 默认 inbound18440XRAY_DEFAULT_PORT(远程 VPS 上,跟本机无关)
测试机 inbound19000probe_vps.config.PROBE_TEST_PORT重跑 init-probe-vps
worker-loop idle 间隔2sPOLL_INTERVAL_SECONDSworker-loop 进程

6.2 改 MCP 端口怎么办

# 1. 改 config.py 一行
# MCP_ADMIN_PORT = 47180  →  47200  (示例)

# 2. 重启 mcp_server (按你部署方式)
#    Linux: sudo systemctl restart vps-server-mcp-admin
#    macOS: launchctl kickstart -k gui/$(id -u)/com.vps-server.mcp-admin
#    Windows: nssm restart vps-server-mcp-admin
#    Claude Desktop: 退 Claude 再开 (client 自己拉的子进程)

# 3. 改客户端 config 4 处 url 里的端口数字
#    (OpenClaw × 2 + Codex × 2)

# 4. 重启客户端

端口被占了怎么办:

# 看哪个进程占了
lsof -iTCP:47180 -sTCP:LISTEN          # macOS / Linux
netstat -ano | findstr :47180          # Windows

# 杀掉, 或改 config.py 用别的端口 (推荐 47000-47999 段避开框架默认)

7. 日常运维

7.1 常用命令(Linux systemd 为例)

# 状态
sudo systemctl status vps-server-worker

# 实时日志
sudo journalctl -u vps-server-worker -f

# 重启(代码改了 / config 改了)
cd /opt/vps_server && sudo -u vps_server git pull && sudo -u vps_server uv sync
# 如果引入新 ORM 表, 先跑 init-db:
# sudo -u vps_server PYTHONPATH=. .venv/bin/python main.py init-db
sudo systemctl restart vps-server-worker

# 停
sudo systemctl stop vps-server-worker

# 关闭开机自启
sudo systemctl disable vps-server-worker

7.2 看业务有没有干活

# 数据库直查(SQLite, 生产 MySQL 类似)
sqlite3 db/vps_server.db "SELECT id, ip, stage, xray_version FROM vps_record;"
sqlite3 db/vps_server.db "SELECT id, ip_id, status, last_error_code FROM ip_task;"

7.3 常见问题

现象排查
systemctl status 立刻 failjournalctl -u xxx -n 50 看日志,常见:ENCRYPTION_KEY 没填 / .venv 不存在 / 路径错
worker 启动但没干活看 vps_task / ip_task 表有没有 pending 任务,没的话就是没人调 register_vps / register_ip
no such table 错误首次部署忘跑 init-db,或加新表后没重跑
MCP 工具调不到看 §5.2.3 反例(4 条注册没填齐 / 端口写反)
probe_vps_not_ready 状态测试机 xray 挂了,重跑 init-probe-vps
频繁崩溃 5 次后挂了systemd 防雪崩兜底,systemctl reset-failed xxx 后排查根因再起

8. 文档导航 + 设计原则

8.1 想看什么找哪里

想知道看哪里
项目当前能干啥 + 怎么部署本文件 (README.md)
业务流细节 / 每个 worker 的行为契约test/<worker>/spec.md(产品视角金标准)
"我们当时为什么这么决定"docs/adr/NNNN-*.md(架构决策档案)
协作守则 / 写代码姿态CLAUDE.md(全局) + CLAUDE.local.md(项目特有)
当前进行中的活task/doing_*.md
已完工的任务回顾task/done_*.md
还没拍板的痛点issue/YYYY-MM-DD-*.md
系统启动配置deploy/(systemd unit / launchd plist / NSSM 脚本)
教 agent 用 MCP 工具的配套 skillskills/(装法见 §5.3)

8.2 设计原则(简版)

  1. 二进程分离 — MCP 收单 vs worker 常驻,职责单一,互不拖累
  2. 异步状态机 — task 表是协调媒介,worker 主动扫 + 软锁防抢
  3. MCP 暴露 3 类工具 — 写入意图 / 状态查询 / 数据查询;绝不暴露内部子动作(SSH / 装机 / 开端口 等)
  4. DB 写入白名单 patch — 业务表只允许 "主键精准定位 + 白名单字段更新",禁止整对象覆盖
  5. 失败有 status code — 每种失败有独立 code,agent 能精确转告用户怎么处理
  6. 失败也写库 — 状态字段配 message 详情,不留"成功一半"灰色地带

详见 docs/adr/(ADR-0001 ~ 0009)。

8.3 测试覆盖

# 跑 mock 测试(快, 几秒, 250+ 个)
PYTHONPATH=. VPS_SERVER_TESTING=1 uv run pytest -q

# 跑某个 worker 的测试
PYTHONPATH=. VPS_SERVER_TESTING=1 uv run pytest test/xray_worker/TC-*.py -v

# 真服务器测试 (默认 skip; 配 env 触发, 走 PROBE_VPS_*)
# 谨慎 — 会真去 SSH

反馈

bug / 改进 / 痛点 → 写 issue/YYYY-MM-DD-主题.md,贴本对话拍板后变 task 落地。

Ver o original no GitHub

Bom para

Relacionados