diff --git a/README.md b/README.md index c462d21..651a917 100755 --- a/README.md +++ b/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_gateway_*.py` | gateway | 用户注册/登录/Token 校验、速率限制、CAPTCHA 集成 | -| `test_waf_*.py` | waf | coraza 规则匹配与拦截、白名单放行 | -| `test_dnfs_*.py` | dnfs | 节点树 CRUD、AI 审核集成 | +| `test_db.py` | db2 | SQL-over-TCP 的日志写入/查询/统计/清理 | +| `test_gateway.py` | ca（认证） | 用户注册/登录/Token 校验、输入校验、代理路径安全、限流 | +| `test_waf.py` | waf | coraza 规则匹配与拦截（SQLi/XSS/命令注入/路径遍历/扫描器）、正常请求放行 | +| `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 数据，保证不污染线上数据。 -- 测试依赖 `pymsg`、`Flask`、`flask-cors`、`requests`、`Pillow`，详见 [tests/requirements-test.txt](tests/requirements-test.txt)。 +- 默认使用 `tests/blackbox/config.py` 中的生产地址（127.0.0.1，条目名映射见该文件），运行方式见 [tests/blackbox/README.md](tests/blackbox/README.md)。 +- 注册测试会创建真实数据库记录，测试完成后可手动清理。 ## 依赖 diff --git a/captcha2/README.md b/captcha2/README.md new file mode 100644 index 0000000..438c3dc --- /dev/null +++ b/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 diff --git a/confs/README.md b/confs/README.md index 6cc4c36..a271c05 100644 --- a/confs/README.md +++ b/confs/README.md @@ -237,8 +237,8 @@ except RpcError as e: | 服务 | 配置文件 | 接入方式 | |------|---------|---------| -| [static](../static/) | [static.ini](configs/static.ini) | confs 强依赖（pymsg 自动阻塞等待 confs 就绪）→ 环境变量覆盖（最高优先级，Docker 兼容） | -| [db](../db/) | [db.ini](configs/db.ini) | confs 强依赖（pymsg 自动阻塞等待 confs 就绪）→ 环境变量覆盖（最高优先级，Docker 兼容） | +| [static](../static/) | `static.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) diff --git a/db/README.md b/db/README.md index 5f64b0d..4654f95 100644 --- a/db/README.md +++ b/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`） diff --git a/dnfs/README.md b/dnfs/README.md index 63077d3..528923b 100644 --- a/dnfs/README.md +++ b/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 | 说明 | |---------|-----|------| diff --git a/docs/MODULES.md b/docs/MODULES.md index 36761ef..9976479 100644 --- a/docs/MODULES.md +++ b/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 | ## 九、根级构建与部署脚本 diff --git a/docs/blackbird_project_evaluation.md b/docs/reports/blackbird_project_evaluation.md similarity index 100% rename from docs/blackbird_project_evaluation.md rename to docs/reports/blackbird_project_evaluation.md diff --git a/docs/blackbird_project_profile.md b/docs/reports/blackbird_project_profile.md similarity index 97% rename from docs/blackbird_project_profile.md rename to docs/reports/blackbird_project_profile.md index 66dad66..a505ea6 100644 --- a/docs/blackbird_project_profile.md +++ b/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 速查表或部署实战。` diff --git a/docs/blackbird_promo_pack.md b/docs/reports/blackbird_promo_pack.md similarity index 100% rename from docs/blackbird_promo_pack.md rename to docs/reports/blackbird_promo_pack.md diff --git a/docs/reports/blackbird_research_report.md b/docs/reports/blackbird_research_report.md index f6f8a4e..1df2d36 100644 --- a/docs/reports/blackbird_research_report.md +++ b/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 --- diff --git a/docs/reports/confs2_cpp_rewrite_dev_doc.md b/docs/reports/confs2_cpp_rewrite_dev_doc.md index f6426ad..4377bc6 100644 --- a/docs/reports/confs2_cpp_rewrite_dev_doc.md +++ b/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 { diff --git a/docs/reports/libcrypt_CBC_deprecation_dev_doc.md b/docs/reports/libcrypt_CBC_deprecation_dev_doc.md index 21e36b5..a892462 100644 --- a/docs/reports/libcrypt_CBC_deprecation_dev_doc.md +++ b/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 --- diff --git a/docs/reports/smtp_cpp_rewrite_dev_doc.md b/docs/reports/smtp_cpp_rewrite_dev_doc.md index 044c7bd..341e9e5 100644 --- a/docs/reports/smtp_cpp_rewrite_dev_doc.md +++ b/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/` 根目录 | 登记本文件条目 | ### 零改动 diff --git a/docs/security/gateway_SECURITY_AUDIT.md b/docs/security/gateway_SECURITY_AUDIT.md index f0b7f4b..5ecfb70 100644 --- a/docs/security/gateway_SECURITY_AUDIT.md +++ b/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”等标记内联于对应代码）。本文档仅保留**开放项、历史追溯与上线检查清单**，避免陈旧信息。 diff --git a/smtp3/README.md b/smtp3/README.md new file mode 100644 index 0000000..6c58b54 --- /dev/null +++ b/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 diff --git a/static/README.md b/static/README.md index 40e9a8b..5f8bb4c 100644 --- a/static/README.md +++ b/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 | 说明 | |---------|-----|------|