docs: 整理文档——分析类归位 reports/、补 captcha2/smtp3 README、修复全部失效链接

- profile/evaluation/promo_pack 移入 docs/reports/（按文档管理约定），内部引用同步 - 补建 captcha2/README.md、smtp3/README.md（主 README 曾引用但缺失） - 重写 README 测试章节（实际为 tests/blackbox/，纯标准库零依赖） - 清除全部 docs/INDEX.md 残留引用；legacy README 中已删除 ini 的失效链接改文字 - 全仓库链接检查 0 broken
2026-08-10 12:45:26 +00:00
1 parent 2817dbbab2
commit 30e064996c
@@ -0,0 +1,37 @@
+# Blackbird / micro_servers 项目红队评估
+
+> 评估对象：`docs/blackbird_project_profile.md`（2026-08-10 advisory 整合稿）
+> 评估视角：材料红队（事实 / 推断 / 未知 + 矛盾与缺证）
+> 评估时间：2026-08-10
+
+## 一句话结论
+架构主张清晰、文档可审计性极高的自托管轻量微服务框架；但"安全评级 A-"缺乏代码级实证，3 项高危整改全部处于 `human_review_pending`，当前不适合暴露于多租户或不可信内网。
+
+## 优势（已确认事实）
+- **定位成立**：砍掉 K8s 的服务注册/编排/消息总线，保留微服务拆分与统一入口收益，自托管 + MIT，价值主张自洽。
+- **可审计性远超同类个人项目**：41+ 篇安全/分析文档 + 24 篇逐模块审计报告，风险闭环有基底。
+- **协议基石扎实**：pymsg/libmsg 字节级兼容的 `[4B 长度][UTF-8 JSON]` 帧，支撑 v1/v2 双栈平滑迁移。
+- **认证设计不弱**：PBKDF2 10 万轮、常数时间比较、RSA 签名 Token、Cookie 安全属性、fail-closed 边界。
+
+## 关键风险（矛盾与缺证）
+1. **评级名实不符**：称"B+→A-"，但 3 高危（WAF 失效 / core root RCE / 内部零信任缺失）均未核实修复。A- 更像目标而非现状。
+2. **WAF 实际不拦截**：定位"唯一对外入口 + coraza"，但 `waf/rules/local/custom.conf` 的 6 条 SecRule 全被注释、无 `crs/` 目录 → 实际仅 TLS 终止 + 响应头，SQLi/XSS/命令注入零防护。
+3. **core 本地 root RCE**：`parse_data_from_mq` 对 list/kill/exec 未鉴权即经 `/bin/sh -c` 执行，且 core 以 root 运行。这是致命项却被标 `human_review_pending`。
+4. **内部零信任缺失**：pymsg 无握手/无鉴权/明文无 TLS，db `execute` 接受任意 action/table/where，完全依赖 127.0.0.1 隔离。
+5. ~~**端口口径漂移**：MODULES.md 记 gateway:8443，README 记 8445，未同步~~ → ✅ 2026-08-10 已统一（ca:8443 → gateway:8445，含 MODULES.md/ARCHITECTURE.md/各模块 README）。
+6. **密钥变量静默失效**：`.env.example` 写 `OPENAI_API_KEY`，代码读 `DEEPSEEK_API_KEY`。
+7. **质量债**：v1/v2 双实现（db/db2、dnfs/dnfs2、pymsg/libmsg…）并存，无单元测试、无 CI（无 `.github/workflows`），回归与语义漂移风险高。
+8. **部署半成品**：docker-compose 仅纳 3 服务，生产以 systemd 为准——容器化链路不完整。
+
+## 缺证项（需人工复核）
+- 3 高危是否在 2026-08-08 之后的提交中已修复（研究报告基于快照，文档未给代码证据）。
+- docker-compose 补全状态；~~MODULES.md 端口同步状态~~（✅ 2026-08-10 已同步）。
+
+## 优先级建议（收口路径）
+- P0：启用 WAF 规则 + 补 `crs/`（直击高危 1）。
+- P0：core MQ 落地 `verify_admin_token` 并降权运行（直击高危 2）。
+- P1：内部服务加调用方鉴权 / pymsg 上 mTLS 或 Unix socket（直击高危 3）。
+- P2：ai_review `/review` 加鉴权 + 结构化提示词；统一 `DEEPSEEK_API_KEY`；引入单元测试与 CI；双实现收口单轨。
+
+## 成熟度判定
+**个人/小团队可信内网自用 = 可用；暴露公网或多租户 = 不建议。** 文档完备度是亮点，代码整改完成度与测试覆盖是短板。
@@ -0,0 +1,374 @@
+# Blackbird / micro_servers 项目资料长文档
+
+> 文档类型：项目资料 / 综合参考手册（面向开发者、维护者、审计者与潜在贡献者）
+> 资料来源：仓库主 `README.md`、各模块 `README.md`、`docs/MODULES.md`、`docs/security/*`、`docs/reviews/*`、`docs/reports/blackbird_research_report.md`、`docs/security/SECURITY_HARDENING_PLAN_20260803.md`、`docs/reports/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 步）
+
+1. 客户端以 HTTP 访问 `:80`，由 `redirect80` 重定向到 HTTPS `:443`（GET/HEAD 301，其余 308 保留 body）。
+2. 所有请求先打到 `waf:443`，终止 TLS、运行 coraza 规则，命中即 403。
+3. 未命中请求以明文 HTTP 转发到 `ca:8443`，透传 `X-Forwarded-For` / `X-Forwarded-Proto`。
+4. `ca` 对 `/login`、`/register` 做账号鉴权（PBKDF2 + RSA Token + 可选 CAPTCHA + 速率限制；注册经 pymsg/TCP 调 `smtp:8008` 发码），用户数据走 `db2:8005`。
+5. 其余请求携带 Token，经 `ca` 验签后注入 `X-Auth-User` 转发到 `gateway:8445`（仅 loopback，仅做存在性检查），再由 gateway 反代到 `Proxy.opened` 放开的内部服务（`fsys:9200` / `dnfs2:8006`）。
+6. `db2:8005` 与 `ai_review:8007` 在 `Proxy.closed` 中，仅允许内部调用。
+7. `dnfs2` 处理节点 CRUD 时经 pymsg/TCP 调 `db2` 持久化，新增节点前调 `ai_review` 审核。
+8. 各服务经 `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/ 分析），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 安装链（一键脚本）
+
+```bash
+# 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：
+
+```bash
+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/reports/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/reports/blackbird_project_profile.md，当前停于第 10 章风险收口；已含架构/模块/协议/安全/部署/路线图；约束：以主 README 拓扑为准、高危缺口标注 human_review_pending、不虚构修复状态；下一目标：补模块 API 速查表或部署实战。`
@@ -0,0 +1,142 @@
+# Blackbird 推广文案包
+
+> 项目定位：一套 DIY 的轻量级微服务架构（UniServe Framework），用 C++ / Python / Go / 仓颉混合实现，让个人和中小团队用极简方式拥有**自托管、可控、安全**的服务平台，免去 Kubernetes 等重型基础设施的复杂度。
+> 许可证：各模块均为 MIT 开源。
+
+---
+
+## 一、主推长文（适合技术社区 / 博客 / 公众号）
+
+### 标题备选
+1. **不想被云厂商绑架？一台服务器，自己搭出一座"微型城市"**
+2. **告别 Kubernetes 的笨重，Blackbird 让微服务回到纯粹的快乐**
+3. **Blackbird：给独立开发者的"乐高底座"，拼出你自己的服务平台**
+4. **你的数据你做主：这套开源框架，把云的能力装进一台机器**
+
+### 正文
+
+**你有没有过这种纠结？**
+
+想做一个属于自己的小产品——一个笔记应用、一个内部工具、一个带 AI 审核的社区。可一查部署，满屏都是 Kubernetes、Service Mesh、云厂商控制台……光是看懂账单和术语，热情就凉了一半。
+
+要是有一套东西，能像搭积木一样，让你用**一台服务器**就拥有"安全入口 + 统一鉴权 + 数据库 + AI 审核 + 业务功能"的完整能力，而且**完全自己掌控、代码开源、零云厂商绑架**——你会心动吗？
+
+这就是 **Blackbird（UniServe Framework）** 想做的事。
+
+---
+
+### 它是什么？一台服务器里的"微型城市"
+
+想象你拥有一座小城市。城市的每个功能，都由一个个**专注的小部门**负责，彼此之间通过内部街道高效协作，而整座城只有**一个安检门**对外营业：
+
+- 🛡️ **WAF 网关**——城市的安检门。统一终止 HTTPS、挡掉恶意流量（内置 OWASP 防护规则），外面的风雨进不来。
+- 🔑 **应用网关**——门内的派出所。负责统一鉴权和反向代理，确保每个请求都"验明正身"才放行。
+- 🗄️ **数据库服务**——城市的档案局。所有业务的数据读写都从这里过，集中、统一、本机隔离，安全又省心。
+- 🤖 **AI 内容审核**——城市的审查员。基于 RAG + 大模型自动把关内容安全，还能吸收人工反馈越用越聪明。
+- ⚙️ **进程守护核心（core）**——城市的市长。负责把各个"部门"拉起来、盯好它们别"罢工"，挂了自动重启。
+- 🌳 **树状笔记（dnfs）**、🤖 **AI 智能体（aibox）**、🦾 **硬件控制模块（bot4cj）**——城市里真正对外提供服务的"营业厅"和"工厂"，甚至可以控制树莓派的舵机做实体机器人。
+
+它不是某个单一应用，而是一套**可以长出各种应用的底座**。
+
+---
+
+### 为什么是 Blackbird，而不是"上云"？
+
+| 传统云原生 | Blackbird |
+|---|---|
+| 要学 K8s、运维集群、看云账单 | 一台机器 + 一个一键脚本搞定 |
+| 数据散落在厂商手里 | 数据完全自托管，你说了算 |
+| 出事要提工单等回复 | 代码开源（MIT），问题自己就能改 |
+| 技术栈绑定某家云 | C++/Python/Go/仓颉多语言自由组合 |
+
+Blackbird 不追求"承载百万 QPS 的巨型帝国"，它专注把**微服务真正有用的那部分收益**——能力拆分、统一入口、安全分层、可观测——用**最轻的量**交到你手里。
+
+---
+
+### 上手有多简单？
+
+仓库里准备好了安装脚本：
+
+```bash
+# Debian/Ubuntu
+./_setup.deb.sh
+# 或 RHEL 系
+./_setup.rhel.sh
+```
+
+然后 `systemctl start Nidus`，核心会按配置自动拉起所有服务。从外部访问，你只需要记住一个地址——`https://你的域名`，安全、鉴权、转发全在背后默默处理好。
+
+---
+
+### 它适合谁？
+
+- 🧑‍💻 **独立开发者 / 个人站长**：想拥有自己的服务平台，又不想被运维压垮。
+- 🏢 **中小团队**：需要一个可控、低成本的内部中台，不依赖外部 SaaS。
+- 🔐 **注重数据主权的人**：数据必须握在自己手里。
+- 🤖 **AI / 硬件爱好者**：想玩转 AI 智能体、嵌入式舵机，又想要一个稳的底座。
+
+---
+
+### 最后说一句
+
+Blackbird 不是要取代云，而是给你**另一种选择**：当世界都在把你推向更复杂的系统时，它轻声说——"其实，简单一点也挺好。"
+
+代码已开源，MIT 许可，欢迎来仓库看看、提 Issue、一起把这座城市建得更漂亮。
+
+👉 **项目地址：https://git.cancerai.top/qing/blackbird**
+
+---
+
+## 二、短平快版本（适合朋友圈 / V2EX / 掘金 / Reddit 等社区发布）
+
+### 版本 A（社区首发自荐）
+> 做了个东西想分享一下：**Blackbird**——一套自托管的轻量微服务框架。
+>
+> 痛点大家都懂：想自己搞个带登录、带数据库、带安全防线的应用，一上来就是 K8s 劝退三连。Blackbird 的思路是"进程托管式微服务"：一个 WAF 门口挡坏人，一个网关管鉴权，一个 core 当保姆盯着所有服务别挂，底下还能挂 AI 审核、树状笔记、甚至树莓派舵机。
+>
+> C++ / Python / Go / 仓颉混编，MIT 开源，一键脚本装好。适合不想被云厂商绑架、又想要微服务那点好处的个人和中小团队。
+>
+> 仓库在这 👉 https://git.cancerai.top/qing/blackbird ，求 Star、求拍砖。
+
+### 版本 B（更"人话"、带情绪钩子）
+> 被云厂商的复杂度和账单搞烦了？我给自己搭了个"微型操作系统"——Blackbird。
+>
+> 一台服务器，一个 HTTPS 入口，背后自动帮你：拦黑客（WAF）、验身份（网关）、存数据（数据库服务）、审内容（AI）、看门狗（进程守护）。还能顺手长出笔记应用、AI 机器人、甚至控制实体舵机。
+>
+> 不玩虚的，代码全开源（MIT），装起来就一个脚本。数据主权这事儿，自己握着才踏实。🔗 https://git.cancerai.top/qing/blackbird
+
+### 版本 C（极简推文风，限字数场景）
+> 🐦 Blackbird：把"云"塞进一台机器。
+> 自托管微服务底座 · WAF+网关+DB+AI审核一应俱全 · C++/Py/Go/仓颉混编 · 一键安装 · MIT 开源。
+> 不想被 K8s 和云账单绑架的独立开发者，来看看 👉 https://git.cancerai.top/qing/blackbird
+
+---
+
+## 三、标题 & Slogan 弹药库
+
+**一句话卖点（可根据场景选用）**
+- "微服务的好处，Kubernetes 的麻烦，二选一？Blackbird 说：都要，但只留好处。"
+- "你的数据、你的服务、你的规则——一台机器，全部自己说了算。"
+- "给独立开发者的一座城：一个门、一套规则、无限可能。"
+
+**Slogan 候选**
+1. Blackbird —— 轻装微服务，主权握手中。
+2. Blackbird —— 一台服务器，一座可控的城。
+3. Blackbird —— 把云的能力，装进自己的机器。
+4. Blackbird —— 微服务的纯粹主义。
+
+**社区讨论钩子（引发互动用）**
+- "你们个人项目都怎么部署的？我最近把整套微服务收进了 Blackbird，一台机器搞定，聊聊？"
+- "K8s 对个人项目是不是杀鸡用牛刀？分享一个轻量替代思路。"
+
+---
+
+## 四、配图 / 可视化建议（如需进一步增强传播）
+
+- **架构一图流**：画一座"城市"，城门标 WAF，城内分派出所（gateway）、档案局（db）、审查员（ai_review）、市长（core），街道连向各营业厅（dnfs/aibox/bot4cj）。比纯 ASCII 架构图更亲民。
+- **对比图**：左"传统云原生=重型城堡"，右"Blackbird=精致小院"，视觉化"轻量可控"。
+- **一键安装 GIF**：录一段从 clone 到 `systemctl start` 到打开 https 的全过程，15 秒讲清"简单"。
+
+---
+
+*文案由 Content Creator 基于项目 README 与代码结构整理撰写，可自由用于推广。如需针对特定平台（如小红书、B站 视频脚本、官网 Landing Page）做深度定制，告诉我目标受众和调性即可。*
@@ -115,7 +115,7 @@ blackbird 是由个人开发者「qing」维护的轻量级多语言微服务框

 **论据（带引用）**：
 - 代码显示，`tests/blackbox/` 仅 8 个黑盒集成测试，覆盖 db/dnfs/gateway/waf/static/captcha/smtp/ai_review；无单元测试、无 CI（仓库无 `.github/workflows` / `gitlab-ci.yml`）。
- 文档完备度极高：`docs/security/` 含 24+ 份逐模块审计（自 2026-08-01 起，含 gateway(db2/dnfs2 多轮)、SECURITY_HARDENING_PLAN_20260803）；`docs/reviews/` 为代码评审日志；`docs/INDEX.md` 提供索引。
+- 文档完备度极高：`docs/security/` 含 24+ 份逐模块审计（自 2026-08-01 起，含 gateway(db2/dnfs2 多轮)、SECURITY_HARDENING_PLAN_20260803）；`docs/reviews/` 为代码评审日志；`docs/` 根目录提供全局文档。
 - 双实现并存：db（dbv2.py）vs db2（db2.cpp）、dnfs vs dnfs2、pymsg vs libmsg、libtry vs libth、lci vs bot4cj → 正以「C++ 重写 Python 微服务」为目标迁移（v1/v2 双轨）。
 - 模块 LOC 显示同一能力在两语言重复承载：db2 1007 行与 db 1301 行、pymsg 1490 行与 libmsg 1972 行（cloc 口径，含注释）。

@@ -123,7 +123,7 @@ blackbird 是由个人开发者「qing」维护的轻量级多语言微服务框

 **小结**：blackbird 以极高文档/审计完备度弥补了测试与 CI 短板；但 v1/v2 双实现带来的重复与维护成本，是质量与效率层面的核心结构性风险，建议在重构收口时优先合并单轨。

-**本章引用文件**：tests/blackbox/、docs/security/、docs/reviews/、docs/INDEX.md、db/dbv2.py、db2/src/db2.cpp、pymsg/pymsg/__init__.py、libmsg/inc/us/Msg_Basic.hpp
+**本章引用文件**：tests/blackbox/、docs/security/、docs/reviews/、db/dbv2.py、db2/src/db2.cpp、pymsg/pymsg/__init__.py、libmsg/inc/us/Msg_Basic.hpp

 ---

@@ -405,7 +405,7 @@ struct ConfsConfig {

 ### 4.6 日志客户端（LogC.hpp）

-从 [captcha2/inc/LogC.hpp](../../captcha2/inc/LogC.hpp) 改编，仅改 namespace 和服务名：
+从 [liblogc/inc/us/LogC.hpp](../../liblogc/inc/us/LogC.hpp)（原 captcha2/inc/LogC.hpp，后独立为 liblogc 模块）改编，仅改 namespace 和服务名：

 ```cpp
 namespace confs2 {
@@ -346,7 +346,7 @@ AAD 允许对**不加密但需认证**的数据做完整性校验。建议在以
 完成开发后需同步更新：

 - [ ] `libcrypt/README.md` — 新增 AES_GCM 章节，标注 AES_CBC 废弃
- [ ] `docs/INDEX.md` — 注册本文档
+- [ ] `docs/` 根目录或 `docs/reports/` 中登记本文档
 - [ ] `libcrypt/Makefile` — install/uninstall 新增 AES_GCM.hpp

 ---
@@ -625,7 +625,7 @@ smtp2/
 |------|----------|
 | `confs/configs/smtp.ini` | **新增**，smtp 统一配置文件 |
 | `core/init.txt` | `smtp/_run.sh` → `smtp2/_run.sh` |
-| `docs/INDEX.md` | 添加本文件的索引条目 |
+| `docs/` 根目录 | 登记本文件条目 |

 ### 零改动