NFarmsd 后端平台文档（docs）¶
NFarms 后端服务（nfarmsd）平台级说明。模块级文档按服务分类存放于本目录， 与本总览构成完整后端文档体系。
平台定位¶
nfarmsd 是 NFarms 生态的统一后端服务平台：一个可执行、三种运行形态（模块）， 对外提供统一认证、统一消息、统一告警、统一数据、统一菜单（商城）、统一证书等 管理域，并通过 WebSocket 网关承载零信任 VPN 认证骨架。前端各平台 （console / online / store / hub / mcp / tools / index）与各客户端应用 （nfvpn / nfprinter / nf-agent / nflive）均统一接入 nfarmsd。
架构总览¶
nfarmsd.exe --module api -> HTTP API （规范端口 9990；本地默认 127.0.0.1:9600）
nfarmsd.exe --module gateway -> VPN WS 网关 （规范端口 9991；本地默认 127.0.0.1:9994）
nfarmsd.exe --module worker -> 后台任务 （订单超时/消息重投/证书巡检）
│
├── SQLite（持久化主库：users/messages/menus/certs/orders/vpn_*）
├── NATS JetStream（消息总线，规范端口 9996；离线自动降级 SQLite 队列）
└── Prometheus /metrics + /health
端口规划（9990-9999 段）与配置迁移见
../nfos/NFarmsd后端规范文档.md§2。
- API 模块：命令框架 + 六大统一管理域 REST API；
- Gateway 模块：VPN WebSocket 认证骨架（JWT 校验 → 虚拟 IP 池分配 → 会话登记 → NATS 审计事件 → 30s 定时心跳），2.md §4.3；
- Worker 模块：订单超时扫描、pending 消息重投（NATS 恢复后）、证书到期巡检。
服务模块地图（本目录）¶
| 服务分类 | 模块 | 说明 | 文档 |
|---|---|---|---|
| 代理服务 | AI 代理 | AI 模型接入 / MCP 网关路由 | 代理服务/ai-Modules.md |
| 代理服务 | 菜单（商城） | 统一菜单（商城）管理域 | 代理服务/menu-Modules.md |
| 代理服务 | 打印代理 | 打印作业代理（nfprinter）接入 | 代理服务/print-Modules.md |
| 安全服务 | 统一认证 | JWT / 角色 / 口令散列（统一用户管理） | 安全服务/auth-Modules.md |
| 安全服务 | 零信任 VPN | WS 网关 / 虚拟 IP 池 / 会话审计 | 安全服务/vpn-Modules.md |
| 安全服务 | WAF | 防火墙规则（在线规则热加载） | 安全服务/waf-Modules.md |
| 通信服务 | IoT 物联 | 端-边-云设备接入 | 通信服务/iot-Modules.md |
| 通信服务 | 统一消息 | NATS JetStream + SQLite 降级队列 | 通信服务/msg-Modules.md |
| 通信服务 | 工单 | 工单流转引擎 | 通信服务/ticket-Modules.md |
| 通信服务 | 告警陷阱 | 统一告警（飞书/邮件/SNMP trap） | 通信服务/trap-Modules.md |
| 交易服务 | 支付 | 订单支付通道（商城） | pay-Modules.md |
六大统一管理域（nfarmsd v2.3.0 已实现）¶
| 管理域 | 表 / 模块 | 说明 |
|---|---|---|
| 统一用户管理 | users | PBKDF2-SHA256 口令散列、角色白名单（admin/devops/service/auditor）、JWT HS256 签发/验证 |
| 统一消息管理 | messages | 先落 SQLite（审计+降级队列）再投递 NATS JetStream；GET /messages、POST /messages/publish |
| 统一告警管理 | alerts | 告警登记/恢复/上报，飞书 webhook 推送（本地可禁用） |
| 统一数据管理 | data_backups | VACUUM INTO 热备份、prune_backups(keep) 保留策略 |
| 统一菜单（商城）管理 | menus | 菜单树 upsert、父节点校验、子节点删除保护；种子 6 商城菜单 |
| 统一证书管理 | certificates | 注册（SHA-256 指纹 + PEM 落盘）、吊销、删除、到期巡检告警 |
命令框架与接口约定¶
- 命令框架：
/commands、/commands/{id}/execute、/commands/executions、/commands/policy； - 身份模型：客户端 → 网关（JWT 验证）→ 注入
X-User-ID/X-User-Roles→ 后端命令级权限校验（零信任）； - 遥测接入：
POST /api/v1/telemetry（nf-agent / nfprinter 上报，主题telemetry.agent.*）； - 统一响应：错误
{code, message}；时间戳统一 RFC3339 UTC。
与前端 / 客户端对应关系¶
| 后端能力 | 前端平台 | 客户端应用 |
|---|---|---|
| 命令框架 / 指标 / 零信任 | console / online | nf-agent（采集上报） |
| 商城菜单 / 订单 | store | nflive（下单/生活服务） |
| VPN 网关 | console（vpn 页） | nfvpn |
| 打印代理 | tools | nfprinter |
| 消息 / 通知 | hub / online（publish） | 各端通知 |
| AI / MCP 网关 | mcp | ai 客户端 |
部署布局（服务器，见仓库 scripts/deploy）¶
后端文件：/opt/Cy/services/system.d/nfarmsd （三模块 systemd：api/gateway/worker）
日志： /opt/Cy/logs/backend/ （api.log / gateway.log / worker.log）
证书： /opt/Cy/certs/backend/ （nfarmsd TLS/JWT 相关）
配置： config/nfarmsd.toml （环境变量 NATS_SERVER/JWT_SECRET/VPN_IP_POOL/
LISTEN_ADDR/READ_ONLY/MODULE 可覆盖）
运维与容灾（规范：../nfos/backup.md）¶
- 备份：每日 02:00 数据库+日志 → 阿里云盘（token）上传（已弃用 NFS）； 成功后清服务器缓存并重启；
- 告警链：关机触发初始化系统告警 → 重启完成触发恢复完成初始化告警； 备份失败触发备份失败告警，每 30 分钟重试至 06:00，仍失败升级 CRITICAL 转人工；
- 双机通道：主服务器只走 VPN 主通道；备通道与 WireGuard VPN 可视化走从服务器 （见 vpn-Modules 主备通道规划）。
文档体系¶
- 本目录
docs.md：后端平台总览（本文档）； - 子目录模块文档：代理服务 / 安全服务 / 通信服务 下各
*-Modules.md为模块级说明； - 后端完整规范与字段约定另见
../nfos/（变量字段统一规范表、依赖关系等）。