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

README.md

@@ -297,17 +297,18 @@
 
 ## 测试
 
-[tests/](tests/) 包含一套黑盒测试套件，基于子进程调用与 HTTP 请求验证各微服务功能正确性：
+[tests/blackbox/](tests/blackbox/) 包含一套黑盒用户模拟测试套件，基于 HTTP/TCP 公开接口验证各微服务功能正确性（纯 Python 标准库，零第三方依赖）：
 
 | 测试文件 | 被测模块 | 说明 |
 |----------|----------|------|
-| `test_db_*.py` | db | SQL-over-TCP 的 select/insert/update/delete、日期哨兵、边界条件 |
+| `test_db.py` | db2 | SQL-over-TCP 的日志写入/查询/统计/清理 |
-| `test_gateway_*.py` | gateway | 用户注册/登录/Token 校验、速率限制、CAPTCHA 集成 |
+| `test_gateway.py` | ca（认证） | 用户注册/登录/Token 校验、输入校验、代理路径安全、限流 |
-| `test_waf_*.py` | waf | coraza 规则匹配与拦截、白名单放行 |
+| `test_waf.py` | waf | coraza 规则匹配与拦截（SQLi/XSS/命令注入/路径遍历/扫描器）、正常请求放行 |
-| `test_dnfs_*.py` | dnfs | 节点树 CRUD、AI 审核集成 |
+| `test_dnfs.py` | dnfs2 | 节点树 CRUD、AI 审核集成 |
+| `test_captcha.py` / `test_smtp.py` / `test_ai_review.py` / `test_static.py` | captcha2 / smtp / ai_review / fsys | 验证码一次性消费、邮件验证码、内容审核纠偏、文件浏览与视频流 |
 
-- 默认使用 `config.py` 中的生产地址（127.0.0.1），每个测试函数前后自动备份/恢复 db 数据，保证不污染线上数据。
+- 默认使用 `tests/blackbox/config.py` 中的生产地址（127.0.0.1，条目名映射见该文件），运行方式见 [tests/blackbox/README.md](tests/blackbox/README.md)。
-- 测试依赖 `pymsg`、`Flask`、`flask-cors`、`requests`、`Pillow`，详见 [tests/requirements-test.txt](tests/requirements-test.txt)。
+- 注册测试会创建真实数据库记录，测试完成后可手动清理。
 
 ## 依赖
 

captcha2/README.md

@@ -0,0 +1,64 @@
+# captcha2 — C++20 验证码服务
+
+captcha 的 C++20 重实现，接口与 Python 版完全兼容（pymsg 路由 image/verify/health），修复审计发现的安全项。基于 libmsg + boost::json + FreeType。
+
+## 架构
+
+```
+ca :8443 (GET /captcha/image 代理给浏览器)
+   │  pymsg TCP
+   ▼
+captcha2 :8009 (RpcServer)
+```
+
+- **服务框架**: libmsg `RpcServer`（pymsg 协议，4B 大端长度前缀 + UTF-8 JSON）
+- **图片生成**: FreeType 渲染旋转字符 + 干扰线 + 噪点，stb_image_write 输出 PNG
+- **安全**: `std::mt19937` + `random_device` 安全随机、答案 XOR 防时序比较、全局生成速率限制
+- **异步日志**: libmsg `AsyncQueue` → db2 Logs 表
+
+## 接口
+
+| pymsg 路由 | 说明 |
+|-----------|------|
+| `image` | 生成验证码，返回 `token` + base64 PNG |
+| `verify` | 校验，一次性消费；错误答案 `{valid:false}`、无效 Token 带 `error` |
+| `health` | 健康检查 |
+
+请求/响应 JSON 格式与 Python captcha 完全一致，ca 零改动。
+
+## 配置
+
+纯 CLI + 环境变量 + 默认值，不依赖 confs。
+
+| 配置项 | CLI 参数 | 默认值 |
+|--------|---------|--------|
+| 绑定地址 | `--addr` / `-a` | 127.0.0.1 |
+| 监听端口 | `--port` / `-p` | 8009 |
+| 工作线程 | `--workers` / `-w` | 4 |
+| 验证码长度 | `--len` | 4（2~8） |
+| 有效期 | `--ttl` | 300s |
+| 字体路径 | `--font-path` | /usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf |
+| 最大存储 | `--max-store` | 10000 |
+| 速率限制 | `--rate-limit` | 600 次/分钟 |
+| 实例名 / 日志级别 | `--instance` / `--log-level` | captcha2 / info |
+
+优先级: CLI > 环境变量 > 默认值；生产参数由 `core/services.yaml` 的 captcha2 条目 args 传入。
+
+## 构建与运行
+
+```bash
+./_set.sh    # 编译
+./_run.sh    # 运行
+```
+
+依赖: libmsg, boost::json, libfreetype, stb_image_write（单头文件，仓库内）
+
+## 状态
+
+- 生产运行中（services.yaml 拉起），Python captcha 已废弃
+- 开发文档见 [docs/reports/captcha_cpp_rewrite_dev_doc.md](../docs/reports/captcha_cpp_rewrite_dev_doc.md)
+- 安全审计见 [docs/security/captcha2_SECURITY_AUDIT_20260809.md](../docs/security/captcha2_SECURITY_AUDIT_20260809.md)
+
+## 许可证
+
+MIT License

confs/README.md

@@ -237,8 +237,8 @@ except RpcError as e:
 
 | 服务 | 配置文件 | 接入方式 |
 |------|---------|---------|
-| [static](../static/) | [static.ini](configs/static.ini) | confs 强依赖（pymsg 自动阻塞等待 confs 就绪）→ 环境变量覆盖（最高优先级，Docker 兼容） |
+| [static](../static/) | `static.ini` | confs 强依赖（pymsg 自动阻塞等待 confs 就绪）→ 环境变量覆盖（最高优先级，Docker 兼容） |
-| [db](../db/) | [db.ini](configs/db.ini) | confs 强依赖（pymsg 自动阻塞等待 confs 就绪）→ 环境变量覆盖（最高优先级，Docker 兼容） |
+| [db](../db/) | `db.ini` | confs 强依赖（pymsg 自动阻塞等待 confs 就绪）→ 环境变量覆盖（最高优先级，Docker 兼容） |
 
 static 的接入实现见 [static/fsys.py](../static/fsys.py)：
 - 两层加载顺序：confs（static.ini，强依赖）→ 环境变量覆盖（优先级最高）
@@ -288,4 +288,4 @@ confs/
 - INI 配置文件中 `%(xxx)s` 语法**不会**被当作插值引用，而是作为字面字符串返回；如需插值请在业务层自行处理
 - 调用方拿到 `get()` 返回的 dict 可以自由修改（如 `entry["content"] = "x"`），不会影响 confs 内部缓存
 - 当前接入情况见上文"集成关系 → 已接入的服务"；新服务接入可参考 static 的三层 fail-safe 模式（内置默认 → confs 优先 → 本地回退）
-- 安全审计报告详见 [docs/SECURITY_AUDIT_20260801.md](docs/SECURITY_AUDIT_20260801.md)
+- 安全审计报告详见 [confs_SECURITY_AUDIT_20260801.md](../docs/security/confs_SECURITY_AUDIT_20260801.md)

db/README.md

@@ -40,7 +40,7 @@ db 已接入 [confs](../confs/) 统一配置服务，confs 是 db 启动的**强
 
 ### confs 配置文件（db.ini）
 
-配置文件托管于 [confs/configs/db.ini](../confs/configs/db.ini)：
+配置文件托管于 `confs/configs/db.ini`（已删除，配置经 CLI 传递）：
 
 ```ini
 [server]
@@ -288,7 +288,7 @@ python3 _view_db.sqlite3.py -s "SELECT service, COUNT(*) FROM Logs GROUP BY serv
 
 ## 切换数据库
 
-推荐方式：修改 confs 的 [db.ini](../confs/configs/db.ini) 中 `[database] url`，然后通过 confs `reload` 路由重载（或重启 db）。也可通过环境变量 `DATABASE_URL` 覆盖（Docker 部署时常用）：
+推荐方式：修改 confs 的 `db.ini`（已删除，配置经 CLI 传递）中 `[database] url`，然后通过 confs `reload` 路由重载（或重启 db）。也可通过环境变量 `DATABASE_URL` 覆盖（Docker 部署时常用）：
 
 - SQLite（默认）：`sqlite:///database.db`（相对路径）或 `sqlite:////app/data/database.db`（绝对路径，Docker 中使用）
 - PostgreSQL：`postgresql://user:pass@localhost/dbname`（需 `pip install psycopg2-binary`）

dnfs/README.md

@@ -230,7 +230,7 @@ dnfs 已接入 confs 统一配置服务，confs 是 dnfs 启动的**强依赖**
 
 ### 配置文件
 
-集中托管在 [confs/configs/dnfs.ini](../confs/configs/dnfs.ini)，由 confs 服务分发：
+集中托管在 `confs/configs/dnfs.ini`（已删除，配置经 CLI 传递），由 confs 服务分发：
 
 | Section | Key | 说明 |
 |---------|-----|------|

docs/MODULES.md

@@ -73,7 +73,7 @@
 | 模块 | 说明 |
 |------|------|
 | tests | 黑盒测试套件（`test_db_*`/`test_gateway_*`/`test_waf_*`/`test_dnfs_*`），子进程 + HTTP 验证，前后自动备份恢复 db |
-| docs | 文档聚合（security/ 审计、reviews/ 审查、reports/ 分析、INDEX.md），41+ 篇 md |
+| docs | 文档聚合（security/ 审计、reviews/ 审查、reports/ 分析），41+ 篇 md |
 
 ## 九、根级构建与部署脚本
 

docs/reports/blackbird_project_profile.md

@@ -1,7 +1,7 @@
 # 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`
+> 资料来源：仓库主 `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`，需结合代码人工复核）
 
@@ -195,7 +195,7 @@ Blackbird 是一套 **DIY 的轻量级"进程托管式微服务"框架**，用 C
 | 项 | 说明 |
 |----|------|
 | **tests** | 黑盒测试套件（`test_db_*`/`test_gateway_*`/`test_waf_*`/`test_dnfs_*`），子进程 + HTTP 验证，前后自动备份恢复 db |
-| **docs** | 文档聚合（security/ 审计、reviews/ 审查、reports/ 分析、INDEX.md），41+ 篇 md |
+| **docs** | 文档聚合（security/ 审计、reviews/ 审查、reports/ 分析），41+ 篇 md |
 
 ---
 
@@ -329,7 +329,7 @@ Gateway v0.8.0 修复 P0 后，**安全评级 B+ → A-**；随 ca 引入与 C++
 ## 9. 许可证与推广
 
 - **许可证**：各模块 MIT。
-- **价值主张摘要**（详见 `docs/blackbird_promo_pack.md`）：
+- **价值主张摘要**（详见 `docs/reports/blackbird_promo_pack.md`）：
   - "微服务的好处，Kubernetes 的麻烦，二选一？Blackbird 说：都要，但只留好处。"
   - "你的数据、你的服务、你的规则——一台机器，全部自己说了算。"
   - Slogan 候选：*轻装微服务，主权握手中*；*一台服务器，一座可控的城*；*微服务的纯粹主义*。
@@ -371,4 +371,4 @@ Gateway v0.8.0 修复 P0 后，**安全评级 B+ → A-**；随 ca 引入与 C++
 - **已确认事实**：主 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 速查表或部署实战。`
+- **续写口令**：`继续编辑 docs/reports/blackbird_project_profile.md，当前停于第 10 章风险收口；已含架构/模块/协议/安全/部署/路线图；约束：以主 README 拓扑为准、高危缺口标注 human_review_pending、不虚构修复状态；下一目标：补模块 API 速查表或部署实战。`

docs/reports/blackbird_research_report.md

@@ -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
 
 ---
 

docs/reports/confs2_cpp_rewrite_dev_doc.md

@@ -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 {

docs/reports/libcrypt_CBC_deprecation_dev_doc.md

@@ -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
 
 ---

docs/reports/smtp_cpp_rewrite_dev_doc.md

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

docs/security/gateway_SECURITY_AUDIT.md

@@ -5,7 +5,7 @@
 > - **2026-08-07** 复审（P0 全部修复、进程退出 bug 修复）
 > - **2026-08-09** 增量复审（8 项新发现：优雅关闭崩溃、头名大小写、XFF 伪造绕过修复、黑盒测试重写落地）
 >
-> **架构变更（v0.9.0）**：gateway 已退化为**纯转发服务**（仅 loopback 监听，不验签），认证职责（Token 签发/验签、登录/注册/重置、限流、WS 代理鉴权、PBKDF2/RSA）整体迁移至 [ca](../ca/) 模块。
+> **架构变更（v0.9.0）**：gateway 已退化为**纯转发服务**（仅 loopback 监听，不验签），认证职责（Token 签发/验签、登录/注册/重置、限流、WS 代理鉴权、PBKDF2/RSA）整体迁移至 [ca](../../ca/README.md) 模块。
 >
 > 所有 ✅ 已修复项已作为代码注释合入 `gateway/src/main.cpp`（以“审计 A*”“P1-1”等标记内联于对应代码）。本文档仅保留**开放项、历史追溯与上线检查清单**，避免陈旧信息。
 

smtp3/README.md

@@ -0,0 +1,69 @@
+# smtp3 — C++20 邮箱验证码服务
+
+smtp 的 C++20 重实现，接口与 Python 版完全兼容（pymsg 路由 send_email/verify_email/health），修复审计发现的安全项（弱随机、日志明文验证码、now 遮蔽等）。基于 libmsg + boost::json + OpenSSL。
+
+## 架构
+
+```
+ca :8443 (注册流程经 pymsg 调用)
+   │  pymsg TCP
+   ▼
+smtp3 :8008 (RpcServer)
+   │  SMTP_SSL (OpenSSL)
+   ▼
+外部 SMTP 服务器 (163/QQ 等)
+```
+
+- **服务框架**: libmsg `RpcServer`（pymsg 协议，4B 大端长度前缀 + UTF-8 JSON）
+- **SMTP 会话**: 直接控制 OpenSSL 会话发送，更精细的超时/错误处理
+- **安全**: `std::random_device` 安全随机、常数时间比较、日志脱敏、冷却/限流/熔断
+- **异步日志**: libmsg `AsyncQueue` → db2 Logs 表
+
+## 接口
+
+| pymsg 路由 | 说明 |
+|-----------|------|
+| `send_email` | 生成 6 位验证码并经 SMTP_SSL 发送，10 分钟有效；同一邮箱 60s 冷却，发送失败不计入冷却 |
+| `verify_email` | 校验，通过即一次性消费防重放；连续失败 5 次自动作废并返回 `invalidated` |
+| `health` | 健康检查 |
+
+请求/响应 JSON 格式与 Python smtp 完全一致，ca 零改动。
+
+## 配置
+
+纯 CLI + 环境变量 + 默认值，不依赖 confs。
+
+| 配置项 | CLI 参数 | 默认值 |
+|--------|---------|--------|
+| 绑定地址 | `--addr` / `-a` | 127.0.0.1 |
+| 监听端口 | `--port` / `-p` | 8008 |
+| SMTP 服务器端口 | `--smtp-port` | 465（SSL） |
+| 验证码长度 | `--code-len` | 6（4~10） |
+| 验证码有效期 | `--code-ttl` | 600s |
+| 发送冷却 | `--send-interval` | 60s |
+| 最大校验失败次数 | `--max-verify-attempts` | 5 |
+| 单邮箱限流 | `--email-hourly-limit` / `--email-daily-limit` | 3 / 10 |
+| 全局熔断 | `--smtp-hourly-limit` | 100 |
+| 邮件标题/正文上限 | `--max-subject-len` / `--max-content-len` | 256 / 4096 |
+| 实例名 / 日志级别 | `--instance` / `--log-level` | smtp / info |
+
+SMTP 账号凭据经 `.env` 注入（`SMTP_SERVER` / `SMTP_USER` / `__PASSWORD`）。优先级: CLI > 环境变量 > 默认值。
+
+## 构建与运行
+
+```bash
+./_set.sh    # 编译
+./_run.sh    # 运行
+```
+
+依赖: libmsg, boost::json, OpenSSL（libssl-dev）
+
+## 状态
+
+- **待上线**：代码就绪并通过安全审计，`core/services.yaml` 仍拉起 Python 版 `smtp`，尚未平替
+- 开发文档见 [docs/reports/smtp_cpp_rewrite_dev_doc.md](../docs/reports/smtp_cpp_rewrite_dev_doc.md)
+- 安全审计见 [docs/security/smtp3_SECURITY_AUDIT_20260809.md](../docs/security/smtp3_SECURITY_AUDIT_20260809.md)
+
+## 许可证
+
+MIT License

static/README.md

@@ -95,7 +95,7 @@ static 已接入 confs 统一配置服务，confs 是 static 启动的**强依
 
 ### 配置文件
 
-集中托管在 [confs/configs/static.ini](../confs/configs/static.ini)，由 confs 服务分发：
+集中托管在 `confs/configs/static.ini`（已删除，配置经 CLI 传递），由 confs 服务分发：
 
 | Section | Key | 说明 |
 |---------|-----|------|