NFarmsd 后端规范文档¶
NFarms 后端服务（nfarmsd）平台规范：架构、模块、端口规划（9990-9999）、 接口约定与部署布局。模块级文档见
../NFarmsd/，前端平台文档见../nfarms/。
1. 平台定位¶
nfarmsd 是 NFarms 生态的统一后端服务平台：一个可执行、三种运行形态（模块）， 对外提供统一认证、统一消息、统一告警、统一数据、统一菜单（商城）、统一证书等 管理域，并通过 WebSocket 网关承载零信任 VPN 认证骨架（2.md §4.3）。 前端各平台与各客户端应用（nfvpn / nfprinter / nf-agent / nflive）统一接入。
2. 端口规范（9990-9999）¶
平台所有对外/内部服务端口统一规划在 9990-9999 段，段内按序号分配如下：
| 端口 | 服务 | 协议 | 绑定 | 说明 |
|---|---|---|---|---|
| 9990 | nfarmsd-api | HTTP/JSON | 内网/回环 | API 模块 REST（命令框架 + 六大管理域 + 遥测） |
| 9991 | nfarmsd-gateway | WebSocket | 内网/回环 | VPN 网关 /vpn/ws（零信任认证骨架） |
| 9992 | nfarmsd-metrics | HTTP | 内网 | Prometheus /metrics + /health（可并入 9990，独立更佳） |
| 9993 | nfarmsd-worker | 内部 | 回环 | Worker 无监听端口，保留用于状态探针 |
| 9994 | nfprinter | HTTP/JSON | 内网 | 打印编辑代理收单（原 9101） |
| 9995 | nflive | HTTP | 回环 | 生活+商城本地客户端 Web（仅 127.0.0.1） |
| 9996 | NATS JetStream | TCP/NATS | 内网 | 消息中间件（默认 4222，生产迁移段内） |
| 9997 | MCP 网关 | HTTP/WS | 内网 | AI 代理/MCP 路由（规划） |
| 9998 | IoT 接入 | TCP/HTTP | 内网 | 设备接入（规划） |
| 9999 | 预留 | - | - | 扩展预留（支付回调/告警 webhook 按序申请） |
端口规约¶
- 段内申请：新服务端口在 9990-9999 内申请，本表登记后使用；不足时 扩展段位需版本变更评审；
- 绑定策略：9990-9994/9996-9998 仅绑定内网/专线网卡，9995 仅回环； 公网统一经 Nginx（443）反代暴露，不得直接对公网监听；
- 安全组：云服务器（阿里云 ECS 等）安全组仅放行 80/443 与运维管理口， 段内端口由同机/内网访问；
- 配置迁移（当前默认值 → 段内规范端口）：
nfarmsd api 模块: LISTEN_ADDR=127.0.0.1:9990 （或 config server.listen_addr） nfarmsd gateway: LISTEN_ADDR=127.0.0.1:9991 nfprinter 收单: NFPRINTER_LISTEN=127.0.0.1:9994 （config listen = 同上） nflive 本地: NFLIVE_LISTEN=127.0.0.1:9995 NATS: NATS_SERVER=nats://127.0.0.1:9996 nfvpn 网关地址: gateway_ws = ws://<host>:9991/vpn/ws nfarmsd API 地址: NFVPN_API / NFLIVE_BACKEND = http://<host>:9990 - 域名规划：对外经 Nginx（server_name 见前端文档）路由：
/api/→ 9990、/vpn/ws→ 9991。
3. 架构¶
nfarmsd --module api -> HTTP API （9990，默认内网）
nfarmsd --module gateway -> VPN WS （9991）
nfarmsd --module worker -> 后台任务 （订单超时/消息重投/证书巡检）
│
├── SQLite（持久化主库：users/messages/menus/certs/orders/vpn_*）
├── NATS JetStream（9996；离线自动降级 SQLite 队列）
└── /metrics + /health（9992）
4. 六大统一管理域¶
| 管理域 | 表 / 模块 | 说明 |
|---|---|---|
| 统一用户管理 | users | PBKDF2-SHA256 口令散列、角色白名单（admin/devops/service/auditor）、JWT HS256 签发/验证 |
| 统一消息管理 | messages | 先落 SQLite（审计+降级队列）再投递 NATS JetStream |
| 统一告警管理 | alerts | 告警登记/恢复/上报，飞书 webhook 推送（本地可禁用） |
| 统一数据管理 | data_backups | VACUUM INTO 热备份、prune_backups(keep) |
| 统一菜单（商城）管理 | menus | 菜单树 upsert、父节点校验、子节点删除保护 |
| 统一证书管理 | certificates | 注册（SHA-256 指纹 + PEM 落盘）、吊销、删除、到期巡检 |
5. 服务模块地图（文档导航）¶
| 分类 | 模块 | 文档 |
|---|---|---|
| 代理服务 | AI（MCP 网关） / 菜单（商城） / 打印 | 代理服务 ai · menu · print |
| 安全服务 | 统一认证 / 零信任 VPN / WAF | 安全服务 auth · vpn · waf |
| 通信服务 | IoT / 统一消息 / 工单 / 告警陷阱 | 通信服务 iot · msg · ticket · trap |
| 交易服务 | 支付 / 订单 | pay-Modules |
注：模块级文档位于同级 NFarmsd/ 目录；本规范文档与 NFarmsd/docs.md（平台总览）
内容一致并增补端口规范。
6. 接口约定¶
- 命令框架：
/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； - 环境变量覆盖：
NATS_SERVER/JWT_SECRET/VPN_IP_POOL/LISTEN_ADDR/READ_ONLY/MODULE/DATABASE_URL。
7. 部署布局（服务器，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）
配置： /opt/Cy/services/system.d/nfarmsd/config/nfarmsd.toml
Nginx： /opt/Cy/services/nginx.d/ （/api/ → 9990，/vpn/ws → 9991）