blackbird/docs/MODULES.md

模块清单（blackbird / micro_servers）

一套 DIY 的轻量级「进程托管式微服务」（UniServe Framework）。 混合语言：C++20（core/gateway/dnfs2/db2/lib*）、Python（fsys/dnfs/db/ai_review/smtp/captcha/confs/redirect80/BotOps/aibox/actpred/pymsg）、Go（waf）、仓颉/Cangjie（bot4cj）。 由 core 读 init.txt 拉起并守护各子进程；waf:443 → gateway:8443 → 业务服务 为对外主链路。

一、核心与编排

模块	语言	端口	职责
core	C++20	5200	进程托管服务 PMC / Nidus，读 init.txt 拉起守护子进程，提供 HTTP 管理接口（--send/--exec/--list/--kill/--serve）

二、入口与网关层

模块	语言	端口	职责
redirect80	Python	80	HTTP→HTTPS 重定向（GET/HEAD 301，其余 308 保留 body）；纯标准库 http.server
waf	Go	443	唯一对外入口，终止 TLS + coraza 规则匹配（SecLang）+ 反代到 gateway；kill -HUP 热加载；规则库 waf/rules/
gateway	C++20	8443	应用层网关（内部 HTTP），注册/登录鉴权、PBKDF2 密码哈希、RSA Token 签发校验、Cookie 认证、速率限制、反向代理（Proxy.opened 白名单）

三、业务服务（对外，经 gateway 代理）

模块	语言	端口	职责
fsys	Python/Flask	9200	前端托管（社区首页/静态页面/媒体流/文件浏览）；原为 static，2026-08 重命名为 fsys（core/init.txt 已同步），过渡期仍保留 legacy static/ 目录存放 fsys.py
dnfs	Python/Flask	8006	树状菜单（Dendrachy Network File-System），基于 pid 的节点树 CRUD，新增节点前调 ai_review 审核
dnfs2	C++20	8006	dnfs 的 C++20 重实现（libhttp + libmsg），接口兼容可平替，修复 P0/P1（fail-closed 验签/所有权校验/脱敏）
ai_review	Python/Flask	8007	AI 内容审核，DeepSeek + ChromaDB RAG（色情/违禁药/赌博/诈骗/仇恨暴力），fail-closed 宁可误拦

四、基础设施 / 支撑服务（仅内部调用）

模块	语言	端口	职责
db	Python/pymsg	8005	通用数据库服务，SQL-over-TCP（SQLAlchemy Core 参数化防注入），内置集中式日志（Logs 表 + 自动清理）
db2	C++20	8005	db 的 C++20 重实现（libmsg + boost::json + libsqlite3），execute 路由/where 语法/响应格式对齐，可平替
confs	Python/pymsg	8010	统一配置分发，集中存放各服务配置（confs/configs/），内存缓存 + mtime 自动重载，路径遍历防护
smtp	Python/pymsg	8008	邮件服务，注册邮箱验证码后端（路由 send_email/verify_email/health），6 位码内存存储、冷却/限流/熔断
captcha	Python/pymsg	8009	验证码服务，图形验证码（一次性、5 分钟过期），经 gateway GET /captcha/image 代理给浏览器

五、AI 智能体与前端

模块	语言	端口	职责
aibox	Python	8765	独立 AI 智能体系统（DeepSeek + WebSocket），自带技能系统/记忆/任务调度/前端与语音客户端
BotOps	Python/Textual	—	aibox 的终端 TUI 前端，WebSocket 连接 aibox，Markdown 增量流式渲染、思考模式、任务侧栏、自动重连
actpred	Python/PyTorch	—	动作预测（图像 + 动作历史 → 预测下一个动作），bot4cj 的「大脑」配套；支持从 .mt 脚本预训练

六、机器人硬件与嵌入式

模块	语言	端口	职责
bot4cj	仓颉/Cangjie	— (树莓派 I2C)	机器人硬件脚本解析器，解析 .mt 驱动 PCA9685 舵机 / MPU6050 陀螺仪 / 扬声器，面向 Dashun 蜘蛛机器人
lci	C++	— (/dev/fb0)	嵌入式帧缓冲图形界面（无需 X11/Wayland），矢量 GB2312 中文字库、图片渲染、实时数据可视化
3d	— (资产)	—	机器人 / 机械臂 CAD 模型（STEP/STL/SLDPRT），bot4cj 配套硬件资产

七、共享基础库

模块	语言	说明
libth	C++	线程库：Thread、Cv_wait、Fsm、ITask
libhttp	C++	HTTP/WebSocket 库（Boost.Beast）：HttpServer（含 WS 服务/代理）、HttpClient（含 WS 客户端）
libcrypt	C++	加密库：AES_CBC、MyRSA、SHA256、Base64、Crypto_Basic
libsqlite3	C++	SQLite3 header-only 封装
libmsg	C++	pymsg 协议 C++ 实现（4B 大端长度前缀 + UTF-8 载荷），MsgClient/Server、RpcClient/Server、AsyncQueue，与 Python pymsg 字节级兼容
libtry	C	嵌入式脚本解释器（~741 行），手写递归下降，支持中文标识符，用于嵌入式操作界面 shell
pymsg	Python	自研 RPC 基础库（[4B 长度][UTF-8 JSON]），db 服务端与各 log_client.py 的基础依赖（setuptools 包）
memdb	C++	内存数据库（include/src），内部组件，未在主 README 模块表列出

八、测试与文档

模块	说明
tests	黑盒测试套件（test_db_*/test_gateway_*/test_waf_*/test_dnfs_*），子进程 + HTTP 验证，前后自动备份恢复 db
docs	文档聚合（security/ 审计、reviews/ 审查、reports/ 分析、INDEX.md），41+ 篇 md

九、根级构建与部署脚本

• _inst.sh：一键按依赖顺序构建安装（库先行，core 最后）
• _setup.deb.sh / _setup.rhel.sh：系统依赖安装（Debian/Ubuntu、RHEL 系）
• docker.sh / docker-compose.yml：容器化部署
• 部署路径约定 /opt/micro_servers/，core 的 init.txt 即从该路径拉起其余服务

关键链路速记

• 请求主链路：client → redirect80(:80→443) → waf(:443 TLS + WAF) → gateway(:8443 鉴权) → fsys(:9200) / dnfs(:8006)
• 日志链路：各服务 log_client.py（异步批量）→ db:8005 Logs 表（fail-safe，db 不可用时静默丢弃）
• 配置链路：业务服务 → confs:8010（内存缓存 + mtime 重载，confs 不可用时回退本地配置）
• 数据/审核/邮件：dnfs → db:8005（pymsg 持久化）；dnfs → ai_review:8007（审核）；注册邮件 gateway → smtp:8008
• 端口一览：80 redirect80 · 443 waf · 8443 gateway · 5200 core · 9200 fsys · 8006 dnfs/dnfs2 · 8005 db/db2 · 8007 ai_review · 8009 captcha · 8008 smtp · 8010 confs · 8765 aibox