Xray 节点配置管理网页项目开发手顺

目标：在本机开发一个可审计、可回滚的控制面，用于管理线路机、落地机、站点路由与 Clash/Shadowrocket 订阅生成。

一句话架构

不要直接编辑散落的 Xray/Clash 文件；先建立一个节点与路由意图数据库，由它生成订阅与配置草案，再人工确认发布。

MVP 边界

只读导入本机网页生成订阅不自动重启远端

第一版只管理“元数据 + 订阅链接 + 路由策略”，不直接改远端 Xray 主配置。

现有节点事实

已确认 inventory 中有 JPA、SG、JPB、UK、AU、AR、DE、US 等；JPA/SG/JPB/UK/AU 有 Reality 443 信息；AR 有 WireGuard landing 准备记录。

1. 当前节点抽象

概念	含义	你这里的映射
线路机	面向大陆方向的入口/中转/低延迟接入点	建议从 HK/JP/SG/KR 等边缘节点中标记，不要硬编码；字段用 `role=edge`
落地机	最终出站国家/区域，如 AR/UK/US/AU/DE	字段用 `role=landing`；可以与 edge 同机，但逻辑上分开
链路	线路机 → 落地机的组合	例如 `SG → UK`、`JPA → AR`，后续可映射为 WireGuard/Xray outbound chain
站点策略	域名/规则集 → 指定链路或策略组	例如 `openai.com → SG → US`，`bbc.com → SG → UK`
订阅	把节点/链路/策略导出给客户端	Clash YAML、Shadowrocket、V2Ray URI 三类输出分开生成

2. 推荐技术栈

后端

Python 3.11 + FastAPI
SQLite + SQLModel 或 SQLAlchemy
Jinja2 负责订阅模板
APScheduler/后台任务做健康检查

前端

第一版用 HTMX + Alpine.js，避免 React 工程复杂度
后续再升级 Vue/React
页面重点是表单、diff、预览、发布按钮

运行

仅监听 127.0.0.1
通过 SSH tunnel 或 Nginx 私有路径访问
所有写操作先生成草案，不能直接覆盖生产文件

3. 数据模型设计

Node
- id, label, host, domain, region, provider
- roles: edge | landing | subscription_host | management
- protocol: vless-reality | wireguard | mixed
- public_endpoint, public_port
- sni, dest, enabled, tags
- source: inventory | manual | imported

LinkProfile
- id, name
- ingress_node_id     # 线路机
- egress_node_id      # 落地机
- transport: wireguard | xray-chain | client-direct
- health_status, latency_ms, enabled

SiteRule
- id, name
- domains: ["openai.com", "*.openai.com"]
- rule_provider: optional
- link_profile_id 或 policy_group
- priority, enabled, note

Subscription
- id, name
- client_type: clash | shadowrocket | v2ray
- include_nodes, include_links, include_rules
- output_path, public_path, last_rendered_at

PublishRevision
- id, object_type, diff, created_at, applied_by
- backup_path, status: draft | applied | rolled_back

4. 页面设计

Dashboard

节点总数、可用数、最近检查时间
订阅最后生成时间
异常：Cookie/密钥缺失、节点未检查、订阅未同步

节点管理

从 /root/.hermes/vps_inventory/inventory.json 导入
手工标记线路机/落地机
维护 SNI、Reality endpoint、WG 地址

链路管理

选择“线路机 → 落地机”
显示链路健康状态
允许禁用某条链路但保留配置

站点路由

域名列表或规则集 URL
绑定到链路或策略组
冲突检测：同域名多规则、优先级覆盖

订阅编辑

Clash YAML 可视化编辑
节点组、规则组、rules 预览
生成 diff 后发布

发布与回滚

每次发布生成 revision
保留上一版文件备份
支持一键回滚订阅文件

5. 开发手顺

Phase 0：建项目骨架

创建目录 /root/xray-node-manager
FastAPI + SQLite + HTMX
只监听 127.0.0.1:8787
加入简单登录或本机 token

uv init xray-node-manager
cd xray-node-manager
uv add fastapi uvicorn sqlmodel pydantic pyyaml jinja2 python-multipart itsdangerous
mkdir -p app/{models,services,routers,templates,static} data exports backups tests

Phase 1：只读导入 inventory

读取 /root/.hermes/vps_inventory/inventory.json
抽取 label、host、domain、xray_status、wireguard、tags
首次导入到 SQLite，后续用 label/host 做 upsert
页面显示节点列表，不允许编辑生产 inventory

Phase 2：节点角色标记

给每个节点加 role：线路机/落地机/订阅机/管理机
建议默认：JPA/SG/JPB/HK/KR 可作为线路机候选；AR/UK/US/AU/DE 可作为落地机候选
角色是本项目私有元数据，不反写 inventory

Phase 3：链路 Profile

建立 LinkProfile：线路机、落地机、传输方式、启用状态
先支持“客户端直连某落地节点”和“命名链路”，不要急着自动生成远端 chain
每条链路都要显示来源节点、出口节点、状态和备注

Phase 4：站点路由规则

支持手工域名：domain、domain-suffix、domain-keyword
支持规则集：OpenAI、Google、Netflix、Telegram 等
保存时做冲突检查：重复域名、禁用链路、环路策略

Phase 5：Clash 订阅生成

导入现有 Clash YAML 为 baseline
把节点、proxy-groups、rules 拆成结构化对象
先只生成新文件到 exports/，不覆盖线上
输出前展示 diff

# 输出建议
exports/clash/all-nodes.yaml
exports/clash/site-routed.yaml
exports/shadowrocket/all-nodes.conf
exports/v2ray/all-nodes.txt

Phase 6：发布机制

发布前：生成 backups/<timestamp>
发布目标可以是本机 Nginx 静态目录或 DE 的订阅目录
默认 dry-run；确认后才 rsync/scp
发布后 curl 验证 URL 可访问、内容非空、YAML 可解析

Phase 7：健康检查

本地检查：订阅 URL 是否可访问、YAML 是否有效
远端检查：SSH 连接、Xray service active、443 端口
客户端检查：可选生成临时 Clash 配置跑连通性测试

6. MVP 验收标准

能导入 inventory 并显示节点。
能把节点标记为线路机/落地机。
能创建“线路机 → 落地机”的链路配置。
能为域名绑定链路。
能生成 Clash YAML 草案。
能显示 diff，不直接覆盖生产。
能发布到一个测试 URL，并 curl 验证。

7. 必须避免的坑

不要第一版就远程改 Xray 配置：先管订阅与策略，等模型稳定后再做远端配置编排。
不要把密钥写进数据库明文：Reality private key、WG private key、SSH key 只引用路径或密钥 ID。
不要裸露公网：本项目是控制面，只能本机或 allowlist 访问。
不要把线路机/落地机写死：节点角色会变化，应是可编辑标签。
配置存在不等于执行成功：每次发布必须验证订阅可访问、客户端可解析、路由规则无回路。

8. 建议仓库结构

xray-node-manager/
  app/
    main.py
    models/
      node.py
      link.py
      route.py
      subscription.py
    services/
      inventory_importer.py
      clash_renderer.py
      rule_validator.py
      publisher.py
      healthcheck.py
    routers/
      nodes.py
      links.py
      routes.py
      subscriptions.py
    templates/
    static/
  data/app.db
  exports/
  backups/
  tests/
  docs/dev-plan.md

9. 第一轮实现任务清单

创建 FastAPI 项目与 SQLite 连接。
实现 inventory importer，只读导入节点。
实现节点列表页与角色编辑。
实现链路 Profile CRUD。
实现站点规则 CRUD 与冲突检测。
实现 Clash YAML renderer。
实现 diff 预览与 exports 输出。
实现测试发布目录，不接生产订阅。

生成时间：2026-06-04T15:17:45Z。报告不包含密钥或完整订阅内容。