qing/blackbird
3
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- profile/evaluation/promo_pack 移入 docs/reports/（按文档管理约定），内部引用同步
- 补建 captcha2/README.md、smtp3/README.md（主 README 曾引用但缺失）
- 重写 README 测试章节（实际为 tests/blackbox/，纯标准库零依赖）
- 清除全部 docs/INDEX.md 残留引用；legacy README 中已删除 ini 的失效链接改文字
- 全仓库链接检查 0 broken
This commit is contained in:
qing committed 2026-08-10 12:45:26 +00:00
1 parent 2817dbbab2
commit 30e064996c
16 files changed
+159 -25
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/MODULES.md
+1 -1
View File
@@ -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/blackbird_project_evaluation.md → docs/reports/blackbird_project_evaluation.md
View File
File renamed without changes.
docs/blackbird_project_profile.md → docs/reports/blackbird_project_profile.md
+4 -4
View File
@@ -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/blackbird_promo_pack.md → docs/reports/blackbird_promo_pack.md
View File
File renamed without changes.
docs/reports/blackbird_research_report.md
+2 -2
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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”等标记内联于对应代码）。本文档仅保留**开放项、历史追溯与上线检查清单**，避免陈旧信息。