qing/blackbird
3
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2817dbbab236e18ced409f23c0ebbab5763811dd
blackbird/docs/blackbird_project_profile.md
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

375 lines
27 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 步）
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/ 分析、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 安装链（一键脚本）
```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/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 速查表或部署实战。`
Reference in new issue View Git Blame Copy Permalink