NexusGate/docs/ARCHITECTURE.md

架构说明

控制路径

1. 管理员在控制面创建服务器、客户和链路草稿。
2. 编排器为每位客户生成独立凭据，并从各服务器端口池分配端口。
3. 转发线路为每位客户生成一个出口资源和一个或多个入口资源；单机直连只生成入口资源。
4. Agent 通过 HTTPS 主动轮询任务，控制面无需登录目标机。
5. Agent 把资源片段写入 /etc/nexusgate/agent/resources/，合并为完整 sing-box 配置。
6. Agent 运行 sing-box check；只有通过校验才替换生效配置并重启 sing-box。
7. Agent 回报 Reality 公钥、任务结果、心跳、流量增量和 IP 观察。

数据路径

数据流量不经过控制面：

flowchart LR
  C[客户端] --> R[入口资源]
  R --> E[出口资源]
  E --> I[互联网]
  C -. 单机直连 .-> D[直连资源]
  D --> I

入口协议和链路传输协议使用独立适配器，因此无需相同。例如入口可以是 VLESS Reality Vision，而中转到落地使用 Shadowsocks 2022。

资源隔离

• 每个客户在每条链路中拥有独立 UUID 或密码。
• 每个资源使用唯一 inbound、outbound 和 routing tag。
• 入口资源只把对应 inbound 路由到对应出口 outbound。
• 出口资源只把对应 inbound 路由到独立 freedom outbound。
• 单机资源把对应 inbound 直接路由到独立 freedom outbound。
• Reality 私钥位于 /etc/nexusgate/keys.json，权限 0600。

故障行为

• 新配置校验失败：删除或恢复刚修改的资源片段，不切换运行配置。
• sing-box 重启失败：恢复上一份完整配置并再次尝试启动。
• Agent 离线：控制面保留任务；运行任务租约超时后自动重试，最多 3 次。
• Agent 重新注册：撤销旧密钥，为该设备重新生成已有部署的对账任务。
• 任务失败：部署标记为失败、线路标记为异常，可只修复失败项或完整重建。
• 控制面离线：已运行的数据面继续工作，只有新配置和统计暂停。

存储

当前版本使用单个 JSON 数据文件和原子 rename。它减少了中小规模部署的依赖与维护成本。写入通过进程内队列串行化，不适合多个控制面实例共享写入；需要主动—主动高可用时应迁移到后续 PostgreSQL 存储。