最近用纯 Node.js 原生模块（不依赖 Express / Koa / 任何 npm 包）搭建了一套面向快消行业的分销代理管理系统。本文记录其中的几个架构决策：零依赖后端、合规护栏引擎、交易驱动的佣金状态机，以及 nginx 多层安全防护的实践与踩坑。
一、为什么不引入任何 npm 依赖？
后端 package.json 的 dependencies 是空的：
做出这个选择有三个考量。
供应链安全。 依赖链投毒事件近几年屡见不鲜。对于需要通过客户安全审计的系统而言，"零依赖"本身就是最直接的供应链安全声明——npm audit 永远返回 0 漏洞，审计沟通成本大幅下降。
Node 原生能力够用。 node:http 起服务、原生 URL 与 URLSearchParams 做路由解析、node:crypto 完成 JWT 签名验签、node:test 跑测试用例。一个最简路由分发器核心代码量在 100 行以内：
部署与构建。 服务器上只需一个 Node 22 运行时；Docker 镜像不必 npm install，构建时间秒级，从根本上消除"本地能跑、线上跑不了"的环境漂移。
零依赖并非银弹——ORM、复杂校验等都要自行实现。但当业务量级可控、且对可控性要求高时，这个权衡是值得的。
二、合规护栏：把业务约束编译进系统
面向中国快消分销场景，宣传话术不能含医疗功效暗示、佣金比例有上限、用户数据需脱敏。和法务一起评审出 15 项护栏（G01-G15） ，分三级固化进代码：
- P0（7 项，硬锁定） ：佣金率上限 0.5、敏感词强制过滤（"根治""百分百有效"等医疗话术）、用户手机号对管理端脱敏——代码里直接锁死，管理界面只读
- P1（7 项，可配置） ：提现审核阈值、举报处理时限——可开关、可调参数，但每次修改进审计日志
- P2（1 项，建议项） ：定期合规自检报告
敏感词过滤是运行时的：词库可增删，代理发布的素材和海报文案都过这道闸。越权访问也做了对应防护：代理端访问订单写操作直接 403，订单查询按角色强制数据隔离。
三、交易驱动的佣金状态机
不少同类系统的订单靠管理员手工录入，对账时极易出错。本系统的设计反过来：管理端对订单只查不改。
订单是一个严格状态机：
佣金计算考虑了真实业务中的若干脏情况：代理被冻结时订单降级为无佣金归因；商品级分润率可覆盖品牌规则，但仍受 P0 上限约束；对账同时匹配订单创建时间和结算时间两个维度。这些边界都被测试覆盖。
四、504 个测试用例的分层策略
测试用 Node 原生 node --test（同样零依赖），23 个文件、97 个 suite、共 504 个用例。铺测试的优先级排序很明确：合规护栏 > 金额计算 > 安全边界 > 功能。
合规护栏的测试不仅验证"该拦的拦了"，还要验证"P0 项管理员也改不动"——把法务约束变成可回归的断言。金额计算覆盖了支付成功、取消回补、持久化恢复等边界场景。
五、nginx 12 层安全防护实践与踩坑
线上部署为 Docker Compose（Node 后端 + PHP Portal + nginx + Redis），nginx 层叠加了 12 层防护：
- 30+ 恶意 UA 拦截（SemrushBot、sqlmap、nikto 等）
- 全站限速：通用 10r/s、API 5r/s、登录 1r/s，外加单 IP 并发连接上限
- WAF 正则匹配拦截 SQL 注入 / XSS / 路径穿越 / 命令注入
- 敏感文件（
.git/.env/.bak等）一律 404、HTTP 方法白名单
- 7 个安全响应头 + HSTS
这里有一个值得记录的坑：安全加固把 HTTP 方法收紧到只放行 GET / POST / HEAD，结果把管理端的 DELETE / PUT 全拦成了 405——安全策略反而砸了自己的业务。回归测试抓出来后统一放行了 PUT / PATCH / DELETE。这个教训记在了项目文档里：安全策略上线必须跟业务回归测试绑在一起，否则就是隐性故障。
六、小结
这套架构的核心权衡是：用一定的自行实现成本，换取供应链安全、部署简洁、合规可验证三个收益。其中合规护栏引擎和佣金状态机两个部分，对做分销、私域、代理体系相关系统的同学有直接的参考价值。完整源码（Apache 2.0）和架构文档放在 GitHub：github.com/yaoteng/dis… ，欢迎技术交流。
