docs: 同步文档至当前生产架构（ca:8443 → gateway:8445、C++20 重写版为主、confs 内嵌 core）

- README: 更新架构图/链路/服务表/端口表，static/dnfs/db/captcha/confs 标注遗留 - MODULES/ARCHITECTURE: 事实来源改为 services.yaml，配置链路收敛为仅 gateway.ini - fsys/dnfs2 README: 架构图改为 ca 验签与纯 CLI 配置
2026-08-10 12:31:35 +00:00
1 parent 77bc367d03
commit ad5d91c47a
@@ -1,6 +1,6 @@
 # Blackbird 架构文档（UniServe Framework）

-> 权威架构参考。本文以 `core/init.txt`（实际运行清单）与 `git HEAD` 为事实来源。
+> 权威架构参考。本文以 `core/services.yaml`（实际运行清单）与 `git HEAD` 为事实来源。
 > 与根目录 `README.md` 的偏差见文末「§10 与 README 的偏差」。
 > 最后核对于：2026-08-10。

@@ -52,7 +52,7 @@ Blackbird 是一套 **进程托管式轻量微服务** 系统（自研 UniServe
                          ┌──────────────────────────────────────────────────┐
                          │                core (PMC / Nidus)                 │
                          │  进程托管 :5200 (HTTP 管理)  +  内嵌 confs :8010   │
-                          │  读 init.txt 拉起并守护下列子进程                  │
+                          │  读 services.yaml 拉起并守护下列子进程           │
                          └───────────────────────┬──────────────────────────┘
                                                 │ 启动 / 守护
        ┌────────────────┬───────────────────────┼──────────────────┬─────────────────┐
@@ -92,10 +92,10 @@ Blackbird 是一套 **进程托管式轻量微服务** 系统（自研 UniServe
    actpred / memdb / libtry (实验 / 支撑库)

  日志链路: 各服务 log_client ──pymsg──► db2:8005 Logs 表 (fail-safe, db 不可用时静默丢弃)
-  配置链路: core 内嵌 confs :8010 ──pymsg get──► 各服务 (confs/configs/*.ini, mtime 自动重载)
+  配置链路: gateway ──pymsg get──► core 内嵌 confs :8010 (confs/configs/gateway.ini, mtime 自动重载；其余服务配置纯 CLI 传递)
 ```

-> 注：`core` 启动参数为 `./nidus.out -i init.txt --serve 5200 --confs 8010`，`--confs` 启用内嵌配置服务（由 confs2 合并而来，与 Python confs 协议兼容）。
+> 注：`core` 启动参数为 `./nidus.out -i . --serve 5200 --confs 8010`（`-i .` 指向 services.yaml 所在目录），`--confs` 启用内嵌配置服务（由 confs2 合并而来，与 Python confs 协议兼容）。

 ---

@@ -122,7 +122,7 @@ Blackbird 是一套 **进程托管式轻量微服务** 系统（自研 UniServe

 ### 4.4 日志 / 配置（横切）
 - 各服务内置 `log_client`（异步队列 + 后台批量 flush）→ pymsg 写 `db2:8005` 的 `Logs` 表；`db2` 自带 30 天/100 万条清理线程。
- 各服务启动时经 pymsg `get` 从 `core:8010` 拉取自身 `.ini`；`confs/configs/` 下 mtime 变化自动重载；环境变量覆盖；命令行参数最高优先级。
+- `gateway` 启动时经 pymsg `get` 从 `core:8010` 拉取 `gateway.ini`；`confs/configs/` 下 mtime 变化自动重载。其余服务配置纯 CLI 传递（CLI > 环境变量 > 默认值），不依赖 confs。

 ---

@@ -149,7 +149,7 @@ Blackbird 是一套 **进程托管式轻量微服务** 系统（自研 UniServe
 | **memdb** | C++20 | — | — | 内存数据库 | 实验/支撑 |
 | **libtry** | C | — | — | 嵌入式脚本解释器 | 支撑 |

-### 已被替代、不应再部署的遗留模块（不在 init.txt）
+### 已被替代、不应再部署的遗留模块（不在 services.yaml）
 | 遗留 | 替代 | 说明 |
 |------|------|------|
 | `static` (Python) | `fsys` | 前端托管已 C++ 重写 |
@@ -157,7 +157,7 @@ Blackbird 是一套 **进程托管式轻量微服务** 系统（自研 UniServe
 | `dnfs` (Python) | `dnfs2` | 笔记服务已 C++ 重写 |
 | `captcha` (Python) | `captcha2` | 验证码已 C++ 重写 |
 | `confs` (Python) | 并入 `core` | 配置服务内嵌进 core（ConfsTask） |
-| `smtp3` (C++) | （预备） | 代码就绪，init.txt 仍用 Python `smtp`，尚未平替 |
+| `smtp3` (C++) | （预备） | 代码就绪，services.yaml 仍用 Python `smtp`，尚未平替 |

 ---

@@ -226,22 +226,23 @@ Blackbird 是一套 **进程托管式轻量微服务** 系统（自研 UniServe
 ## 9. 演进策略与已知缺口

 - **无服务注册发现 / 容器编排**：服务地址在 `waf/config.yaml` 与 `gateway` 的 `Proxy.*` 中静态配置，由 `core` 进程托管。适合个人/中小规模 DIY，但扩展需手工。
- **smtp3 待上线**：C++ 重写已完成并通过安全审计，但 init.txt 仍指向 Python `smtp`，建议择机平替以消除最后一块 Python 有状态服务。
+- **smtp3 待上线**：C++ 重写已完成并通过安全审计，但 services.yaml 仍指向 Python `smtp`，建议择机平替以消除最后一块 Python 有状态服务。
 - **可观测性缺口**：缺 tracing/metrics/告警，建议后续引入轻量方案（或复用 db2 Logs + 定时聚合）。
 - **水平扩展限制**：smtp/captcha 内存态为单点，若需多实例需引入 Redis 等共享存储。

 ---

-## 10. 与 README.md 的偏差（待同步）
+## 10. 与 README.md 的偏差（已同步，2026-08-10）

-以下为本文相对于根 `README.md` 的纠正点，建议择机回填 README：
+以下为本文相对于根 `README.md` 的纠正点。2026-08-10 已按本清单回填 README 并同步 MODULES.md，状态如下：

-1. **端口**：README 端口表写 `gateway 8443`，实际 `ca:8443`、`gateway:8445`（v0.9.0 起）。README 正文已正确，仅端口表需改。
-2. **前端模块**：README 仍列 `static`（Python）为主，实际生产为 `fsys`（C++ 重写），`static` 已废弃。
-3. **C++ 重写版未进主表**：README 模块表仍以 `db`/`dnfs`/`captcha`/`confs` 为主，实际生产跑 `db2`/`dnfs2`/`captcha2`，`confs` 已并入 `core`。
-4. **init.txt 不含 confs**：独立 confs 服务已不用，配置由 `core --confs 8010` 内嵌提供。
-5. **fsys README 图示滞后**：`fsys/README.md` 架构图仍写 `gateway :8443`，应为 `ca:8443 → gateway:8445`。
-6. **工作记忆偏差**：项目记忆中的 `gateway:8443 → fsys / dnfs` 与 `confs:8010` 需更新为 `ca:8443 → gateway:8445`、`dnfs2`、confs 内嵌 core。
+1. **端口**：✅ 已修正。README 端口表原写 `gateway 8443`，现已改为 `ca:8443`、`gateway:8445`。
+2. **前端模块**：✅ 已修正。README 现以 `fsys`（C++ 重写）为主表，`static` 标注遗留。
+3. **C++ 重写版未进主表**：✅ 已修正。README 模块表现以 `db2`/`dnfs2`/`captcha2` 为主，`db`/`dnfs`/`captcha` 标注遗留，`confs` 标注已并入 `core`。
+4. **init.txt**：✅ 已同步。core 已于 2026-08 移除 init.txt 兼容，仅支持 `services.yaml`（提交 b0d71a4）；README/本文件均已更新为 `-i . --serve 5200 --confs 8010`。
+5. **fsys README 图示滞后**：✅ 已修正（2026-08-10）。`fsys/README.md` 架构图与配置章节已更新为 `ca:8443 → gateway:8445`、纯 CLI 配置。
+6. **工作记忆偏差**：✅ 已同步。`ca:8443 → gateway:8445`、`dnfs2`、confs 内嵌 core 均已写入各文档。
+7. **dnfs2 README 图示滞后**：✅ 已修正（2026-08-10）。`dnfs2/README.md` 架构图与验签描述已更新为 ca:8443（CLI 参数 `--gateway-url` 指向 ca）。

 ---

@@ -1,41 +1,43 @@
 # 模块清单（blackbird / micro_servers）

 > 一套 DIY 的轻量级「进程托管式微服务」（UniServe Framework）。
-> 混合语言：C++20（core/gateway/dnfs2/db2/lib*）、Python（fsys/dnfs/db/ai_review/smtp/captcha/confs/redirect80/BotOps/aibox/actpred/pymsg）、Go（waf）、仓颉/Cangjie（bot4cj）。
-> 由 `core` 读 `init.txt` 拉起并守护各子进程；`waf:443 → gateway:8443 → 业务服务` 为对外主链路。
+> 混合语言：C++20（core/gateway/ca/dnfs2/db2/fsys/captcha2/lib*）、Python（static/dnfs/db/ai_review/smtp/captcha/confs/redirect80/BotOps/aibox/actpred/pymsg，多为遗留）、Go（waf）、仓颉/Cangjie（bot4cj）。
+> 由 `core` 读 `services.yaml` 拉起并守护各子进程；`waf:443 → ca:8443 → gateway:8445 → 业务服务` 为对外主链路。

 ## 一、核心与编排

 | 模块 | 语言 | 端口 | 职责 |
 |------|------|------|------|
-| core | C++20 | 5200 | 进程托管服务 PMC / Nidus，读 `init.txt` 拉起守护子进程，提供 HTTP 管理接口（`--send/--exec/--list/--kill/--serve`） |
+| core | C++20 | 5200 / 8010 | 进程托管服务 PMC / Nidus，读 `services.yaml` 拉起守护子进程，提供 HTTP 管理接口（`--send/--exec/--list/--kill/--serve`），内嵌 confs 配置服务（`--confs 8010`） |

 ## 二、入口与网关层

 | 模块 | 语言 | 端口 | 职责 |
 |------|------|------|------|
 | redirect80 | Python | 80 | HTTP→HTTPS 重定向（GET/HEAD 301，其余 308 保留 body）；纯标准库 `http.server` |
-| waf | Go | 443 | 唯一对外入口，终止 TLS + coraza 规则匹配（SecLang）+ 反代到 gateway；`kill -HUP` 热加载；规则库 `waf/rules/` |
-| gateway | C++20 | 8443 | 应用层网关（内部 HTTP），注册/登录鉴权、PBKDF2 密码哈希、RSA Token 签发校验、Cookie 认证、速率限制、反向代理（`Proxy.opened` 白名单） |
+| waf | Go | 443 | 唯一对外入口，终止 TLS + coraza 规则匹配（SecLang）+ 反代到 ca；`kill -HUP` 热加载；规则库 `waf/rules/` |
+| ca | C++20 | 8443 | 中央认证服务（内部 HTTP），注册/登录鉴权、PBKDF2 密码哈希、RSA Token 签发校验、Cookie 认证、速率限制、身份头注入后前置转发到 gateway |
+| gateway | C++20 | 8445 | 应用层网关（仅 loopback 纯转发，v0.9.0 起认证迁至 ca），反向代理（`Proxy.opened` 白名单），不验签 |

 ## 三、业务服务（对外，经 gateway 代理）

 | 模块 | 语言 | 端口 | 职责 |
 |------|------|------|------|
-| fsys | Python/Flask | 9200 | 前端托管（社区首页/静态页面/媒体流/文件浏览）；**原为 static，2026-08 重命名为 fsys**（core/init.txt 已同步），过渡期仍保留 legacy `static/` 目录存放 `fsys.py` |
-| dnfs | Python/Flask | 8006 | 树状菜单（Dendrachy Network File-System），基于 pid 的节点树 CRUD，新增节点前调 ai_review 审核 |
-| dnfs2 | C++20 | 8006 | dnfs 的 C++20 重实现（libhttp + libmsg），接口兼容可平替，修复 P0/P1（fail-closed 验签/所有权校验/脱敏） |
+| fsys | C++20 | 9200 | 前端托管（社区首页/静态页面/媒体流/文件浏览）；Python/Flask `static` 的 C++ 重写（legacy `static/` 目录保留），代理 dnfs2 笔记请求 |
+| 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 宁可误拦 |

 ## 四、基础设施 / 支撑服务（仅内部调用）

 | 模块 | 语言 | 端口 | 职责 |
 |------|------|------|------|
-| db | Python/pymsg | 8005 | 通用数据库服务，SQL-over-TCP（SQLAlchemy Core 参数化防注入），内置集中式日志（Logs 表 + 自动清理） |
+| 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 | 统一配置分发，集中存放各服务配置（`confs/configs/`），内存缓存 + mtime 自动重载，路径遍历防护 |
-| smtp | Python/pymsg | 8008 | 邮件服务，注册邮箱验证码后端（路由 send_email/verify_email/health），6 位码内存存储、冷却/限流/熔断 |
-| captcha | Python/pymsg | 8009 | 验证码服务，图形验证码（一次性、5 分钟过期），经 gateway `GET /captcha/image` 代理给浏览器 |
+| 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 对齐 |

 ## 五、AI 智能体与前端

@@ -78,12 +80,12 @@
 - `_inst.sh`：一键按依赖顺序构建安装（库先行，core 最后）
 - `_setup.deb.sh` / `_setup.rhel.sh`：系统依赖安装（Debian/Ubuntu、RHEL 系）
 - `docker.sh` / `docker-compose.yml`：容器化部署
- 部署路径约定 `/opt/micro_servers/`，`core` 的 `init.txt` 即从该路径拉起其余服务
+- 部署路径约定 `/opt/micro_servers/`，`core` 的 `services.yaml` 即从该路径拉起其余服务

 ## 关键链路速记

- **请求主链路**：client → `redirect80`(:80→443) → `waf`(:443 TLS + WAF) → `gateway`(:8443 鉴权) → `fsys`(:9200) / `dnfs`(:8006)
- **日志链路**：各服务 `log_client.py`（异步批量）→ `db:8005` Logs 表（fail-safe，db 不可用时静默丢弃）
- **配置链路**：业务服务 → `confs:8010`（内存缓存 + mtime 重载，confs 不可用时回退本地配置）
- **数据/审核/邮件**：`dnfs` → `db:8005`（pymsg 持久化）；`dnfs` → `ai_review:8007`（审核）；注册邮件 `gateway` → `smtp:8008`
- **端口一览**：80 redirect80 · 443 waf · 8443 gateway · 5200 core · 9200 fsys · 8006 dnfs/dnfs2 · 8005 db/db2 · 8007 ai_review · 8009 captcha · 8008 smtp · 8010 confs · 8765 aibox
+- **请求主链路**：client → `redirect80`(:80→443) → `waf`(:443 TLS + WAF) → `ca`(:8443 认证+前置转发) → `gateway`(:8445 纯转发) → `fsys`(:9200) / `dnfs2`(:8006)
+- **日志链路**：各服务 `log_client.py`（异步批量）→ `db2:8005` Logs 表（fail-safe，db2 不可用时静默丢弃）
+- **配置链路**：`gateway` → `core` 内嵌 confs:8010（内存缓存 + mtime 重载，仅 gateway.ini）；其余服务配置纯 CLI 传递
+- **数据/审核/邮件**：`dnfs2` → `db2:8005`（pymsg 持久化）；`dnfs2` → `ai_review:8007`（审核）；注册邮件 `ca` → `smtp:8008`；登录验证码 `ca` → `captcha2:8009`
+- **端口一览**：80 redirect80 · 443 waf · 8443 ca · 8445 gateway · 5200/8010 core · 9200 fsys · 8006 dnfs2 · 8005 db2 · 8007 ai_review · 8009 captcha2 · 8008 smtp · 8765 aibox