0 Fork 0

Files

T

qing 2817dbbab2 docs: 收尾同步——waf/smtp README、项目画像、测试套件与遗留模块标注

- waf/smtp README: 链路改 ca:8443 → gateway:8445，启动描述改 services.yaml
- profile/evaluation: 拓扑/请求链路/端口表/模块表同步，口径漂移项标记已解决
- tests/blackbox: README 与 config.py 标注测试条目→生产服务映射（保留历史条目名）
- static/dnfs/db/captcha/confs README 顶部加"已废弃"标注

2026-08-10 12:35:45 +00:00

27 KiB

Raw Blame History

Blackbird / micro_servers 项目资料长文档

文档类型：项目资料 / 综合参考手册（面向开发者、维护者、审计者与潜在贡献者）资料来源：仓库主 README.md、各模块 README.md、docs/INDEX.md、docs/MODULES.md、docs/security/*、docs/reviews/*、docs/reports/blackbird_research_report.md、docs/security/SECURITY_HARDENING_PLAN_20260803.md、docs/blackbird_promo_pack.md 整理日期：2026-08-10 文档状态：advisory（基于仓库现有文档整合；涉及最新代码整改状态的部分标注为 human_review_pending，需结合代码人工复核）

0. 文档说明

本文档将 Blackbird（仓库名 micro_servers，框架名 UniServe Framework）过去分散在 40+ 篇说明、审计与报告中的信息，整合为一份可按章节查阅的项目资料。

事实边界：所有模块职责、端口、协议描述以主 README.md（2026-08-10 口径，已含 ca 中央认证模块与 services.yaml 编排）为准；安全发现以 blackbird_research_report.md（2026-08-08 快照）与 docs/security/ 逐模块审计为准。
口径说明：当前拓扑为 waf:443 → ca:8443 → gateway:8445 → 内部服务；编排清单为 core/services.yaml（2026-08 起 init.txt 已废弃）。
质量状态约定：基于文档推断与整合的结论标记为 advisory；涉及"代码是否已修复某高危项"的判断标记为 human_review_pending，因其需对照最新提交逐文件核验。

1. 项目概述

1.1 一句话定位

Blackbird 是一套 DIY 的轻量级"进程托管式微服务"框架，用 C++20 / Python / Go / 仓颉(Cangjie) 混合实现，让个人与中小团队用一台服务器、一个脚本，拥有「安全入口 + 统一鉴权 + 数据库 + AI 审核 + 业务功能」的完整能力，免去 Kubernetes 等重型基础设施的复杂度。

1.2 设计哲学与核心主张

能力拆分但重量极轻：保留微服务"拆分、统一入口、安全分层、可观测"的真正收益，砍掉服务注册发现、容器编排、消息总线等重型组件。
你完全掌控：数据自托管、代码 MIT 开源，不绑定任何云厂商。
多语言自由组合：核心用 C++（性能/系统），胶水与业务用 Python（效率），边缘网关用 Go（coraza 生态），硬件控制用仓颉（树莓派）。
进程托管式编排：一个 core 进程当"保姆"，读 services.yaml 拉起并守护所有子服务。

1.3 适用对象

群体	诉求	Blackbird 的契合点
独立开发者 / 个人站长	不想被运维压垮	一键脚本 + systemd，对外只记一个域名
中小团队	可控、低成本内部中台	不依赖外部 SaaS，数据握在自己手里
注重数据主权者	数据绝不能出本机	全程自托管，MIT 可改
AI / 硬件爱好者	想玩智能体、嵌入式舵机	aibox 智能体 + bot4cj 舵机 + lci 帧缓冲界面

1.4 与云原生微服务的差异

未引入服务注册发现、容器编排、消息总线；服务地址在 waf/config.yaml 与 gateway 配置中静态配置。对于个人/中小规模 DIY 场景，这种取舍在简洁性与可控性上合理，但也意味着横向扩展需自行演进。

1.5 许可证与归属

各模块均采用 MIT License（详见各目录 LICENSE）。项目由个人开发者「qing」维护，仓库地址 https://git.cancerai.top/qing/blackbird。

2. 架构总览

2.1 UniServe 架构定义

以 core（C++20）为统一宿主进程，读取 services.yaml 声明式配置并经 shell 拉起多语言微服务。各服务通过内部 HTTP 对外暴露业务能力，通过 pymsg/TCP（自研 RPC）做数据访问与日志汇聚。

2.2 当前拓扑（含 ca 认证前置化）

                         ┌──────────────────────────────────────────────┐
                         │              core (PMC / Nidus)              │
                         │   进程托管服务 · 监听 :5200 (HTTP 管理接口)    │
                         │   读取 services.yaml 拉起并守护下列子进程      │
                         │   内嵌 confs :8010 (仅 gateway.ini 分发)      │
                         └───────────────┬──────────────────────────────┘
                                         │ 启动 / 守护
          ┌──────────────┬──────────────┼──────────────┬──────────────────┬──────────────┐
          ▼              ▼              ▼              ▼                  ▼              ▼
   ┌──────────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
   │   redirect80 │ │   waf   │ │    ca    │ │   gateway    │ │    fsys      │ │    dnfs2     │
   │  :80 重定向  │ │ :443 入口│ │ :8443 认证│ │ :8445 纯转发 │ │  :9200 前端  │ │  :8006 树状  │
   └──────────────┘ └────┬────┘ └────┬─────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
                         │ TLS终止   │ 鉴权+前置   │ 反向代理         │ 代理笔记        │ pymsg
                         │ coraza   │ 转发        │ (loopback)       │                 │
                         └──────────┴─────►───────┴──────────────────┴─────────────────┘
   认证链路(v0.9.0 起): waf:443 ──HTTP──► ca:8443 (认证+前置转发) ──HTTP──► gateway:8445 (纯转发, 仅 loopback) ──► 内部服务
   日志链路: 各服务 ──(log_client, pymsg)──► db2:8005 (Logs 表，fail-safe 静默丢弃)
   配置链路: gateway ──(pymsg get)──► core:8010 内嵌 confs（mtime 自动重载）；其余服务配置纯 CLI 传递

db2 / dnfs2 / fsys / captcha2 分别是 db / dnfs / static / captcha 的 C++20 重实现，架构位置与 Python 版一致，接口兼容可平替；confs 已内嵌进 core。BotOps、lci、bot4cj 不在主图中（终端前端 / 帧缓冲界面 / 树莓派硬件，不联网）。

2.3 core 进程托管模型

可执行文件 nidus.out，以 systemd 单元 Nidus.service 常驻（崩溃守护由 systemd 负责，core 自身不含自动重启逻辑）。
两种模式：命令行子系统（--send/--exec/--list/--kill）与 HTTP 伺服器（--serve <port>）。
经命名管道(Pipe)与消息队列(Mq)实现进程间通信；读 services.yaml 自启动清单（-i .），按声明顺序拉起 db2 / ai_review / dnfs2 / smtp / fsys / waf / ca / gateway / captcha2 / aibox / redirect80。

2.4 请求链路（8 步）

客户端以 HTTP 访问 :80，由 redirect80 重定向到 HTTPS :443（GET/HEAD 301，其余 308 保留 body）。
所有请求先打到 waf:443，终止 TLS、运行 coraza 规则，命中即 403。
未命中请求以明文 HTTP 转发到 ca:8443，透传 X-Forwarded-For / X-Forwarded-Proto。
ca 对 /login、/register 做账号鉴权（PBKDF2 + RSA Token + 可选 CAPTCHA + 速率限制；注册经 pymsg/TCP 调 smtp:8008 发码），用户数据走 db2:8005。
其余请求携带 Token，经 ca 验签后注入 X-Auth-User 转发到 gateway:8445（仅 loopback，仅做存在性检查），再由 gateway 反代到 Proxy.opened 放开的内部服务（fsys:9200 / dnfs2:8006）。
db2:8005 与 ai_review:8007 在 Proxy.closed 中，仅允许内部调用。
dnfs2 处理节点 CRUD 时经 pymsg/TCP 调 db2 持久化，新增节点前调 ai_review 审核。
各服务经 log_client.py 异步批量推送日志到 db2 的 Logs 表（fail-safe）。

2.5 端口一览

端口	服务	绑定	说明
80	redirect80	0.0.0.0	HTTP→HTTPS 重定向
443	waf	0.0.0.0	HTTPS 对外入口（TLS + coraza）
8443	ca	127.0.0.1	中央认证（内部 HTTP）
8445	gateway	127.0.0.1	纯转发反代（loopback）
5200	core	127.0.0.1	PMC HTTP 管理接口
8010	core（内嵌 confs）	127.0.0.1	统一配置（pymsg/TCP，仅 gateway.ini）
9200	fsys	127.0.0.1	前端托管（经 gateway 代理）
8006	dnfs2	127.0.0.1	树状菜单（经 gateway 代理）
8005	db2	127.0.0.1	数据库服务（pymsg/TCP）
8007	ai_review	127.0.0.1	AI 审核（仅内部调用）
8009	captcha2	127.0.0.1	验证码（经 ca 代理）
8008	smtp	127.0.0.1	邮件服务（仅内部调用）
8765	aibox	127.0.0.1	AI 智能体（WebSocket，独立产品）

3. 模块清单（按职责分组）

3.1 核心与编排

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

核心设计：systemd 常驻、root 运行（见第 5 章风险）、Pipe/Mq 进程通信、无内置看门狗（崩溃自愈依赖 systemd）。

3.2 入口与网关层

模块	语言	端口	职责
redirect80	Python	80	HTTP→HTTPS 重定向（GET/HEAD 301 / 其余 308），纯标准库
waf	Go	443	唯一对外入口，终止 TLS + coraza 规则匹配（SecLang）+ 反代到 ca；`kill -HUP` 热加载；规则库 `waf/rules/`
ca	C++20	8443	中央认证服务（v1.0.0，内部 HTTP），注册/登录鉴权、Token 签发校验、身份头注入后前置转发到 gateway
gateway	C++20	8445	应用层网关（v0.9.0，仅 loopback），纯转发反代，不验签（认证已迁至 ca）

ca 关键设计：PBKDF2-HMAC-SHA256（10 万轮 + 16 字节盐）、常数时间比较防 timing attack；Token 为 Base64(payload)+"_"+RSA-Sign(payload)，默认 1 小时过期，RSA 密钥启动时内存生成（重启即失效）；HttpOnly+Secure+SameSite=Lax 的 q4_token Cookie；登录 5 次/5 分钟、注册 3 次/10 分钟速率限制；首位注册者即管理员（无默认管理员账号）。

gateway 关键点：纯转发，存在性不变量——显式 Target-Url 请求必须携带 ca 注入的 X-Auth-User，缺失一律 401；Target-Url 必须在 Proxy.opened 白名单。

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

模块	语言	端口	职责
fsys	C++20	9200	前端托管：社区首页/静态页/媒体流/文件浏览；static 的 C++ 重写（legacy `static/` 目录保留，不再部署）
dnfs	Python/Flask	8006	树状菜单（Dendrachy Network File-System），基于 pid 的节点树 CRUD，新增节点前调 ai_review 审核（遗留，已由 dnfs2 平替）
dnfs2	C++20	8006	dnfs 的 C++20 重实现（libhttp + libmsg），接口完全兼容，修复 P0/P1（fail-closed 验签/所有权校验/脱敏）；支持 js/file/style/theme 特殊节点
ai_review	Python/Flask	8007	AI 内容审核，DeepSeek + ChromaDB RAG（色情/违禁药/赌博/诈骗/仇恨暴力），fail-closed 宁可误拦

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

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

3.5 AI 智能体与前端

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

3.6 机器人硬件与嵌入式

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

3.7 共享基础库

库	语言	说明
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++	内存数据库（internal 组件，未在主 README 模块表列出）

3.8 测试与文档

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

4. 通信协议：pymsg / libmsg

这是 Blackbird 异构架构的通信基石。

帧结构：[4 字节大端长度][UTF-8 JSON]，单帧上限 64 MiB。
跨语言一致：Python pymsg 与 C++ libmsg 字节级兼容，是 v1/v2 双栈迁移的关键支撑。
资源防护：慢连接总 deadline 防护 + 有界线程池，控制资源耗尽类风险。
错误脱敏：_sanitize_error 以正则替换绝对路径，降低信息泄露面。
安全现状（重要）：协议无握手、无鉴权、明文无 TLS，安全性完全依赖 127.0.0.1 主机隔离。一旦内网隔离被突破（同机多租户或某内部服务失陷），所有跨进程调用即暴露。详见第 5 章与加固计划。

5. 安全体系

5.1 边界鉴权优势（已达 A-）

gateway（及 ca）的边界鉴权设计扎实，安全评级由 B+ 提升至 A-（Gateway v0.8.0 修复 P0：错误消息脱敏、SIGTERM 退出、doAccept 无限递归、8 秒关闭超时）：

口令：PBKDF2-HMAC-SHA256（10 万轮 + 16 字节盐），常数时间比较防时序攻击。
Token：RSA-2048 + PKCS#1 v1.5 签名，双轨吊销（jti 黑名单 + 用户版本号）。
多层防护：CAPTCHA 一次性、登录 5/300s、注册 3/600s、邮箱级双窗口限流。
Cookie：HttpOnly;Secure;SameSite=Lax。
管理面 fail-closed：core HTTP 接口绑 127.0.0.1 且 verify_admin_token。

5.2 已核实缺口（来自 2026-08-08 研究报告的审计结论）

以下结论基于研究报告对当时代码快照的核实，整理时（2026-08-10）部分项已在 ca 引入、C++ 重写潮与加固计划中进入整改。具体是否已在最新提交修复，需逐文件人工复核，状态标记为 human_review_pending。

级别	缺口	说明	关联整改
高危 1	WAF 规则失效	`waf/rules/local/custom.conf` 的 6 条 SecRule 全部被注释，无 `crs/` 目录 → WAF 仅做 TLS 终止 + 响应头，不拦截 SQLi/XSS/命令注入	加固计划阶段一目标；待启用规则
高危 2	core MQ 未鉴权即 exec	`parse_data_from_mq` 对 list/kill/exec 未鉴权即经 `/bin/sh -c` 执行；core 以 root 运行 → 本地 root RCE	加固计划阶段二核心项
高危 3	内部服务零信任缺失	pymsg 无认证；db 的 `execute` 路由接受任意 action/table/where，仅依赖 127.0.0.1 隔离 → 边界失守后可免认证读写全库	加固计划阶段三（AES-GCM）
中危 1	ai_review 未鉴权 + 提示注入	`/review` 仅 per-IP 限流、无鉴权；用户输入直接拼入系统提示词 → 审核绕过 + 开放 LLM 端点	aibox_open_dev_plan 跟踪
中危 2	密钥配置缺陷	`.env.example` 写 `OPENAI_API_KEY` 而代码读 `DEEPSEEK_API_KEY` → 变量名不一致的静默失效 bug	待对齐

5.3 安全加固计划（三层防线）

docs/security/SECURITY_HARDENING_PLAN_20260803.md 定义了"隔离层 + 认证层 + 加密层"三阶段目标：

阶段一（隔离加固，P0）：所有内部服务绑 127.0.0.1（✅ 已实现 db/confs/captcha/gateway/static/smtp/dnfs）；防火墙仅放行 443、外网端口扫描验证仍 [ ] 待办。
阶段二（core 密钥注入，P1）：core 启动时生成进程组密钥，经 execve 的 envp 注入 MICROSERV_KEY，子进程 fail-fast 读取——仍 [ ] 待办。
阶段三（AES-GCM 通信加密，P1）：编写 microcrypt 库，接入 pymsg 帧与 HTTP 调用，防篡改/重放——仍 [ ] 待办。

5.4 安全审计覆盖（`docs/security/`，41+ 篇）

包含全局审计（DEPLOY / DEPS / SECURITY_HARDENING_PLAN）与逐模块审计报告（waf、gateway×3、core、db、db2、pymsg、dnfs、dnfs2、static/fsys、ai_review、smtp、smtp3、captcha、captcha2、confs、libmsg、libhttp、libsqlite3、libth、aibox、BotOps、actpred）。docs/reviews/ 另有 4 篇代码审查日志。可审计性远超多数同类项目，是风险闭环的基底。

6. 部署与运维

6.1 依赖

系统级：g++（C++20）、make、libboost-all-dev、libcurl4-gnutls-dev、libssl-dev、libsqlite3-dev、python3 + venv + pip、patchelf、golang-go（Go 1.22+，用于 waf）、-ljpeg -lpng（lci）。
Python：Flask、Flask-CORS、Flask-SQLAlchemy、SQLAlchemy、waitress、openai、chromadb、python-dotenv、nuitka。
Go：corazawaf/coraza v3.3.0、gopkg.in/yaml.v3。

6.2 安装链（一键脚本）

# 1. 系统依赖
bash _setup.deb.sh        # Debian/Ubuntu
# 或
bash _setup.rhel.sh       # RHEL/CentOS/Rocky/Fedora

# 2. 依次构建安装（库先行，core 最后）
bash _inst.sh

单独安装某服务：bash _set.sh（构建+安装）、bash _run.sh（运行）。部署路径约定 /opt/micro_servers/。

6.3 运行

services.yaml 自启动顺序重要（db2 → ai_review → dnfs2 → smtp → fsys → waf → ca → gateway → captcha2 → aibox → redirect80）。启动 core：

systemctl start Nidus      # 或 bash core/_run.sh

对外入口：https://<host>:443（waf 终止 TLS 后转发到 ca）。

6.4 WAF 与 ca 协作

启用 WAF 后证书从 gateway 迁到 waf：cp gateway/full_chain.crt gateway/server.key waf/certs/。ca 改内部 HTTP 模式（core/services.yaml 中 --host 127.0.0.1、--port 8443）。独立部署（不用 WAF）时把 waf 从 services.yaml 移除、ca 的 --port 设为 443。

6.5 容器化现状

docker-compose.yml 的 services 块仅纳入 db / ai_review / dnfs 三个服务（另含 networks 与 volumes），core/waf/ca/gateway/fsys/captcha2/smtp 未纳入 → 编排不完整。生产部署当前以 systemd 链路为准。

7. 测试与质量

黑盒测试：tests/blackbox/ 约 8 个集成测试，覆盖 db / dnfs / gateway / waf / static / captcha / smtp / ai_review；无单元测试、无 CI（仓库无 .github/workflows）。
文档/审计完备度：docs/security/ 24+ 份逐模块审计 + docs/reviews/ 评审日志，可审计性极高。
双实现（v1/v2）重构负担：db↔db2、dnfs↔dnfs2、pymsg↔libmsg、libtry↔libth、lci↔bot4cj 并存，正以「C++ 重写 Python 微服务」为目标迁移。任一逻辑修正需两语言同步，存在语义漂移风险——建议重构收口时优先合并单轨。

8. 开发路线图与近期重点（2026-08）

8.1 C++ 重写潮（2026-08-09 引入）

新增/重写模块	说明
ca	中央认证服务（C++ 2463 行），认证独立化，接管原 gateway 端口前置鉴权
captcha2	C++ 重写 captcha（含 stb_image_write），修复 P0 大小写缺陷
confs2	C++ 重写 confs（libmsg RpcServer 替代 pymsg），协议兼容零改动
smtp3	C++ 重写 smtp（1013 行，SMTP_SSL 手写），审计 7 项遗留一并修复
core ConfsTask	C++ 内嵌配置任务（557 行）
gateway 精简	`src/main.cpp` 大幅精简（-1980 行），认证逻辑下沉至 ca

8.2 认证独立化（auth_service_plan）

waf → ca → gateway 前置拓扑：ca 统一鉴权并前置转发，gateway 退化为纯转发（仅 loopback），下游 / WAF / 前端零改动。对应开发文档见 docs/reports/auth_service_plan.md。

8.3 关键 dev docs 索引（`docs/reports/`）

core_service_registry_dev_doc（注册中心）、auth_service_plan（CA 模块）、aibox_open_dev_plan / aibox_file_network_cli_refactor（aibox 安全沙箱与 CLI 化）、libcrypt_CBC_deprecation_dev_doc（AES-GCM 迁移）、libhttp_remote_addr_dev_doc（X-Remote-Addr 透传）、captcha_cpp_rewrite / smtp_cpp_rewrite / confs2_cpp_rewrite（C++ 重写方案）、actpred_pretrain_test（预训练与推理测试）。

8.4 安全评级演进

Gateway v0.8.0 修复 P0 后，安全评级 B+ → A-；随 ca 引入与 C++ 重写潮加固，整体向"端到端一致鉴权"收敛（详见第 5 章待办）。

9. 许可证与推广

许可证：各模块 MIT。
价值主张摘要（详见 docs/blackbird_promo_pack.md）：
- "微服务的好处，Kubernetes 的麻烦，二选一？Blackbird 说：都要，但只留好处。"
- "你的数据、你的服务、你的规则——一台机器，全部自己说了算。"
- Slogan 候选：轻装微服务，主权握手中；一台服务器，一座可控的城；微服务的纯粹主义。

10. 风险与待办（收口）

风险 / 待办	级别	状态	来源
WAF 检测规则未启用	高危	`human_review_pending`（计划阶段一目标）	研究报告 / 加固计划
core MQ 未鉴权 RCE（root 运行）	高危	`human_review_pending`（计划阶段二）	研究报告 / 加固计划
内部 pymsg/db 零信任缺失	高危	`human_review_pending`（计划阶段三）	研究报告 / 加固计划
ai_review 未鉴权 + 提示注入	中危	`human_review_pending`	研究报告 / aibox_open_dev_plan
密钥变量名不一致（DEEPSEEK/OPENAI）	中危	`advisory`（待对齐）	研究报告
docker-compose 仅 3 服务，不完整	P2	`advisory`	研究报告
无单元测试 / 无 CI	P2	`advisory`	研究报告
v1/v2 双实现维护成本	结构性	`advisory`（建议收口合并）	研究报告
文档口径差异（MODULES 记 gateway:8443）	低	✅ 已同步（2026-08-10 统一为 ca:8443 → gateway:8445）	本文档核实

建议交付清单

启用 WAF 规则并补建 crs/（直击高危 1）
为 core MQ 通道落地 verify_admin_token 并降权运行（直击高危 2）
内部服务加调用方鉴权 / pymsg 上 mTLS 或 Unix socket（直击高危 3）
ai_review /review 加鉴权 + 结构化提示词拼接
统一 DEEPSEEK_API_KEY 与 .env.example
补全 compose 或文档声明 systemd 为唯一受支持链路
引入单元测试与 CI，降低双实现回归风险

续接胶囊

文档类型：项目综合资料长文档（Blackbird / micro_servers）
目标读者：开发者、维护者、安全审计者、潜在贡献者
核心目标：将分散在 40+ 篇仓库文档中的架构、模块、协议、安全、部署、路线图整合为单一可查阅手册
已完成章节：第 0–10 章（概述、架构、模块清单、pymsg 协议、安全体系、部署运维、测试质量、路线图、许可证、风险收口）
已确认事实：主 README 拓扑（waf:443→ca:8443→gateway:8445）；ca 为 C++ 认证前置模块；C++ 重写潮（ca/captcha2/confs2/smtp3/gateway 精简/core ConfsTask）；安全评级 B+→A-；MIT 许可
待核验事项：3 项高危 + 2 项中危是否已在最新提交修复（研究报基于 2026-08-08 快照）；docker-compose 补全状态；MODULES.md 端口口径同步
下一节唯一目标：（可选）补充"各模块 API 速查表"或"从零部署实战 walkthrough"
续写口令：继续编辑 docs/blackbird_project_profile.md，当前停于第 10 章风险收口；已含架构/模块/协议/安全/部署/路线图；约束：以主 README 拓扑为准、高危缺口标注 human_review_pending、不虚构修复状态；下一目标：补模块 API 速查表或部署实战。

27 KiB Raw Blame History Unescape Escape