From da8ebbf9e67139b6b67c94bce732c54ead20de5f Mon Sep 17 00:00:00 2001 From: qing <1776177662@qq.com> Date: Mon, 10 Aug 2026 15:55:43 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=A0=94=E7=A9=B6=E6=95=B4=E7=90=86?= =?UTF-8?q?=E2=80=94=E2=80=94=E5=90=8C=E6=AD=A5=E8=AE=A4=E8=AF=81=E8=BF=81?= =?UTF-8?q?=E8=87=B3=20ca=20=E5=90=8E=E7=9A=84=E8=BF=87=E6=97=B6=E6=8F=8F?= =?UTF-8?q?=E8=BF=B0=E3=80=81=E8=A1=A5=20liblogc=20=E4=B8=8E=E6=B5=8B?= =?UTF-8?q?=E8=AF=95=E6=B8=85=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ARCHITECTURE/MODULES：ca 版本 v1.1.0、共享基础库补 liblogc、tests 描述与实际 9 个文件对齐、docs 篇数 57 - core README/报告/HttpTask 注释：管理员鉴权由"gateway 唯一权威"更正为 ca（v0.9.0 认证迁址后描述滞后） - ca/gateway README 架构图 static:9200 → fsys:9200、db:8005 → db2:8005 - 主 README 与 blackbox README 补 test_core_confs.py，test_gateway 文档更新为 ca:8443 契约 --- README.md | 1 + ca/README.md | 2 +- core/README.md | 2 +- core/src/main/HttpTask.cpp | 16 ++++++++-------- docs/ARCHITECTURE.md | 3 ++- docs/MODULES.md | 5 +++-- docs/reports/core_module_overview.md | 4 ++-- gateway/README.md | 4 ++-- tests/blackbox/README.md | 5 +++-- tests/blackbox/test_gateway.py | 8 ++++---- 10 files changed, 27 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index d729377..1f01871 100755 --- a/README.md +++ b/README.md @@ -307,6 +307,7 @@ | `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 | 验证码一次性消费、邮件验证码、内容审核纠偏、文件浏览与视频流 | +| `test_core_confs.py` | core（内嵌 confs） | confs get/list/reload/health 与 Python 版基线行为对比 | - 默认使用 `tests/blackbox/config.py` 中的生产地址（127.0.0.1，条目名映射见该文件），运行方式见 [tests/blackbox/README.md](tests/blackbox/README.md)。 - 注册测试会创建真实数据库记录，测试完成后可手动清理。 diff --git a/ca/README.md b/ca/README.md index 88b622b..599c224 100644 --- a/ca/README.md +++ b/ca/README.md @@ -5,7 +5,7 @@ UniServe Framework 的中央认证服务（Central Auth），C++20 实现，v1.0 ## 拓扑定位（waf → ca → gateway 前置拓扑） ``` -客户端 ──HTTPS──▶ waf:443 (终止 TLS + coraza 规则) ──HTTP──▶ ca:8443 (认证+前置转发) ──HTTP──▶ gateway:8445 (纯转发) ──▶ static:9200 / dnfs2:8006 / core:5200 +客户端 ──HTTPS──▶ waf:443 (终止 TLS + coraza 规则) ──HTTP──▶ ca:8443 (认证+前置转发) ──HTTP──▶ gateway:8445 (纯转发) ──▶ fsys:9200 / dnfs2:8006 / core:5200 ``` - CA 接管原 gateway 的 **8443** 端口，WAF upstream 配置不变（`waf/config.yaml` 仍指向 8443）。 diff --git a/core/README.md b/core/README.md index 841b0d4..8249025 100644 --- a/core/README.md +++ b/core/README.md @@ -111,7 +111,7 @@ PMC 把所有常驻能力抽象为 `ITask`，用 `libth` 的 `Thread`（带 `sto - 仅监听 `127.0.0.1:5200`，纯 HTTP（WAF 已终止 TLS，无证书）。 - 三个 POST 路由：`/list` `/exec` `/kill`，返回 `{"success", "message", "data"}`。 -- **管理员鉴权**（`verify_admin_token`）：每个操作都先调 `gateway /admin/verify`（gateway 是 Token 签发/验签唯一权威，RSA 验签 + is_admin + 过期检查），`Authorization` 头优先、回退 `q4_token` Cookie；gateway 地址由 `GATEWAY_HOST`/`GATEWAY_PORT` 配置（默认 `127.0.0.1:8443`）。gateway 不可用或异常一律 `fail-closed` 返回 401。 +- **管理员鉴权**（`verify_admin_token`）：每个操作都先调 `ca /admin/verify`（认证 v0.9.0 起由 gateway 迁至 ca，RSA 验签 + is_admin + 过期检查），`Authorization` 头优先、回退 `q4_token` Cookie；ca 地址由 `GATEWAY_HOST`/`GATEWAY_PORT` 环境变量配置（沿用旧名，默认 `127.0.0.1:8443`）。ca 不可用或异常一律 `fail-closed` 返回 401。 - 命令执行（`exec`）与 pid 解析同时支持 query 参数与 JSON body。 ## 内嵌 confs 配置服务（v0.1.0 起） diff --git a/core/src/main/HttpTask.cpp b/core/src/main/HttpTask.cpp index 148c7e8..752a3ae 100644 --- a/core/src/main/HttpTask.cpp +++ b/core/src/main/HttpTask.cpp @@ -152,10 +152,10 @@ namespace process_http_server { return ""; } - /* 管理员验证：调用 gateway 的 /admin/verify 验签端点，验证请求携带的 Token 是否为有效管理员。 - * gateway 是 Token 签发与验证的唯一权威（RSA 验签 + is_admin + 过期检查）。 - * gateway 地址由环境变量 GATEWAY_HOST/GATEWAY_PORT 配置，默认 127.0.0.1:8443。 - * gateway 不可用或响应异常一律视为未授权（fail-closed）。 */ + /* 管理员验证：调用 ca 的 /admin/verify 验签端点，验证请求携带的 Token 是否为有效管理员。 + * ca 是 Token 签发与验证的唯一权威（RSA 验签 + is_admin + 过期检查，v0.9.0 起由 gateway 迁至 ca）。 + * ca 地址由环境变量 GATEWAY_HOST/GATEWAY_PORT 配置（沿用旧名），默认 127.0.0.1:8443。 + * ca 不可用或响应异常一律视为未授权（fail-closed）。 */ static bool verify_admin_token(const http::request& req) { try { /* 提取 Token：Authorization 头优先，回退 Cookie */ @@ -173,7 +173,7 @@ namespace process_http_server { } if (raw.empty() || raw.substr(0, 7) != "Bearer ") return false; - /* gateway 地址 */ + /* ca 地址 */ std::string host = "127.0.0.1"; int port = 8443; if (const char* h = std::getenv("GATEWAY_HOST")) host = h; @@ -276,7 +276,7 @@ namespace process_http_server { res.version(req.version()); res.set(http::field::content_type, "application/json"); - /* 管理员认证：调用 gateway 验签，未授权直接拒绝 */ + /* 管理员认证：调用 ca 验签，未授权直接拒绝 */ if (!verify_admin_token(req)) { res.result(http::status::unauthorized); res.body() = buildJsonResponse(false, "Unauthorized: admin token required"); @@ -311,7 +311,7 @@ namespace process_http_server { res.version(req.version()); res.set(http::field::content_type, "application/json"); - /* 管理员认证：调用 gateway 验签，未授权直接拒绝 */ + /* 管理员认证：调用 ca 验签，未授权直接拒绝 */ if (!verify_admin_token(req)) { res.result(http::status::unauthorized); res.body() = buildJsonResponse(false, "Unauthorized: admin token required"); @@ -364,7 +364,7 @@ namespace process_http_server { res.version(req.version()); res.set(http::field::content_type, "application/json"); - /* 管理员认证：调用 gateway 验签，未授权直接拒绝 */ + /* 管理员认证：调用 ca 验签，未授权直接拒绝 */ if (!verify_admin_token(req)) { res.result(http::status::unauthorized); res.body() = buildJsonResponse(false, "Unauthorized: admin token required"); diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 1f56a65..fa2dbd3 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -133,7 +133,7 @@ Blackbird 是一套 **进程托管式轻量微服务** 系统（自研 UniServe | **core** | C++20 | 5200 / 8010 | 5200 管理 / 8010 loopback | 进程托管(PMC) + 内嵌 confs 配置服务 | 生产 | | **redirect80** | Python | 80 | 0.0.0.0 | HTTP→HTTPS 重定向 | 生产 | | **waf** | Go | 443 | 0.0.0.0 | 边缘网关：TLS 终止 + coraza WAF | 生产 | -| **ca** | C++20 | 8443 | 127.0.0.1 | 中央认证 + 身份头注入 + 前置转发 | 生产 (v1.0.0) | +| **ca** | C++20 | 8443 | 127.0.0.1 | 中央认证 + 身份头注入 + 前置转发 | 生产 (v1.1.0) | | **gateway** | C++20 | 8445 | 127.0.0.1 | 纯转发反向代理（loopback 强制自检） | 生产 (v0.9.0) | | **fsys** | C++20 | 9200 | 127.0.0.1 | 前端托管 + dnfs 代理（static 的 C++ 重写） | 生产 | | **dnfs2** | C++20 | 8006 | 127.0.0.1 | 树状笔记 CRUD | 生产（dnfs 的 C++ 重写） | @@ -170,6 +170,7 @@ Blackbird 是一套 **进程托管式轻量微服务** 系统（自研 UniServe | libcrypt | C++20 | AES_CBC / RSA / SHA256 / Base64 | | libsqlite3 | C++20 | SQLite3 header-only 封装 | | libmsg | C++20 | pymsg 协议 C++ 实现（4B 大端长度前缀 + UTF-8 JSON），与 Python pymsg 字节级兼容，提供 RpcClient/RpcServer/AsyncQueue | +| liblogc | C++20 | 统一集中式日志客户端（`us/LogC.hpp`，对应 Python `log_client.py`）：pymsg/TCP 异步批量写 db2 Logs 表，队列上限 1 万条 + 级别过滤 + fail-safe，C++ 服务共用 | | libtry | C | 嵌入式脚本解释器（递归下降，中文标识符） | | pymsg | Python | 自研 RPC 基础库（`[4B 大端长度][UTF-8 JSON]`），Python 侧 db/log_client 依赖 | diff --git a/docs/MODULES.md b/docs/MODULES.md index 9976479..6db8d08 100644 --- a/docs/MODULES.md +++ b/docs/MODULES.md @@ -64,6 +64,7 @@ | 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 字节级兼容 | +| liblogc | C++ | 统一集中式日志客户端（`us/LogC.hpp`，对应 Python `log_client.py`）：pymsg/TCP 异步批量写 db2 Logs 表，队列上限 1 万条 + 级别过滤 + fail-safe，ca/core/gateway/captcha2/smtp3 等 C++ 服务共用 | | libtry | C | 嵌入式脚本解释器（~741 行），手写递归下降，支持中文标识符，用于嵌入式操作界面 shell | | pymsg | Python | 自研 RPC 基础库（`[4B 长度][UTF-8 JSON]`），db 服务端与各 `log_client.py` 的基础依赖（setuptools 包） | | memdb | C++ | 内存数据库（include/src），内部组件，未在主 README 模块表列出 | @@ -72,8 +73,8 @@ | 模块 | 说明 | |------|------| -| tests | 黑盒测试套件（`test_db_*`/`test_gateway_*`/`test_waf_*`/`test_dnfs_*`），子进程 + HTTP 验证，前后自动备份恢复 db | -| docs | 文档聚合（security/ 审计、reviews/ 审查、reports/ 分析），41+ 篇 md | +| tests | 黑盒测试套件（`test_db.py`/`test_gateway.py`/`test_waf.py`/`test_dnfs.py`/`test_captcha.py`/`test_smtp.py`/`test_ai_review.py`/`test_static.py`/`test_core_confs.py`），纯标准库 HTTP/TCP 用户旅程模拟，经 `test_runner.py` 统一调度（详见 [tests/blackbox/README.md](../tests/blackbox/README.md)） | +| docs | 文档聚合（security/ 审计、reviews/ 审查、reports/ 分析），57 篇 md | ## 九、根级构建与部署脚本 diff --git a/docs/reports/core_module_overview.md b/docs/reports/core_module_overview.md index a6f1d63..d6cfee9 100644 --- a/docs/reports/core_module_overview.md +++ b/docs/reports/core_module_overview.md @@ -71,7 +71,7 @@ core 把所有常驻能力抽象为 `ITask`，用 `libth` 的 `Thread`（带 `st - 仅监听 `127.0.0.1:5200`，纯 HTTP（WAF 已终止 TLS，无证书）。 - 三个 POST 路由：`/list` `/exec` `/kill`，返回 `{"success", "message", "data"}`。 -- **管理员鉴权**（`verify_admin_token`）：每个操作都先调 `gateway /admin/verify`（gateway 是 Token 签发/验签唯一权威，RSA 验签 + is_admin + 过期检查），Authorization 头优先、回退 `q4_token` Cookie；gateway 地址由 `GATEWAY_HOST`/`GATEWAY_PORT` 配置（默认 `127.0.0.1:8443`）。gateway 不可用或异常一律 `fail-closed` 返回 401。 +- **管理员鉴权**（`verify_admin_token`）：每个操作都先调 `ca /admin/verify`（认证 v0.9.0 起由 gateway 迁至 ca，RSA 验签 + is_admin + 过期检查），Authorization 头优先、回退 `q4_token` Cookie；ca 地址由 `GATEWAY_HOST`/`GATEWAY_PORT` 环境变量配置（沿用旧名，默认 `127.0.0.1:8443`）。ca 不可用或异常一律 `fail-closed` 返回 401。 - 命令执行（`exec`）与 pid 解析同时支持 query 参数与 JSON body。 ## 7. 内嵌配置服务（`ConfsTask` + `ConfigStore`） @@ -98,7 +98,7 @@ core 把所有常驻能力抽象为 `ITask`，用 `libth` 的 `Thread`（带 `st 2. **`PPool` 用下标而非 pid 索引**：`kill(idx)` 语义不自然，FIXME 仍在。 3. **内存泄漏 TODO**：`HttpTask`/`ConfsTask` 的 `start()` 获取资源后未确认释放（代码注释标注）。 4. **`/tmp/pst-*` FIFO 残留**：`subsys_call` 异常路径可能留下管道文件。 -5. **管理接口强依赖 gateway**：`/admin/verify` 不可用时所有管理操作 fail-closed 拒绝（安全优先，但运维注意 gateway 必须在线）。 +5. **管理接口强依赖 ca**：`/admin/verify` 不可用时所有管理操作 fail-closed 拒绝（安全优先，但运维注意 ca 必须在线）。 6. **`exec` 命令注入面**：`pmc_mtd::exec` 直接 `boost::process::child(cmd)` 以 shell 执行，仅在已通过管理员鉴权后可用——务必保证鉴权不被绕过。 ## 10. 上手要点 diff --git a/gateway/README.md b/gateway/README.md index 0cd9673..170e8c9 100644 --- a/gateway/README.md +++ b/gateway/README.md @@ -14,13 +14,13 @@ UniServe Framework 的应用层网关，C++20 实现。 ## 信任模型 ``` -waf:443 ──HTTP──▶ ca:8443 ──(注入 X-Auth-User)──▶ gateway:8445 ──▶ static:9200 / dnfs2:8006 / core:5200 +waf:443 ──HTTP──▶ ca:8443 ──(注入 X-Auth-User)──▶ gateway:8445 ──▶ fsys:9200 / dnfs2:8006 / core:5200 ▲ 安全边界 ▲ 仅 loopback ``` - gateway 不持有 RSA 密钥、不验签；身份完全信任 ca 注入的头。 - 因此 **启动强制 loopback 自检**：`Server.address` 非 `127.0.0.1`/`::1`/`localhost` 时拒绝启动（防止误配导致外部直连伪造身份）。 -- `db:8005` 的 `execute` 路由本就无认证，loopback 信任模型与既有基线一致。 +- `db2:8005` 的 `execute` 路由本就无认证，loopback 信任模型与既有基线一致。 ## 接口 diff --git a/tests/blackbox/README.md b/tests/blackbox/README.md index 14ec214..99ded77 100644 --- a/tests/blackbox/README.md +++ b/tests/blackbox/README.md @@ -17,14 +17,15 @@ tests/blackbox/ ├── config.py # 服务地址与端口映射 ├── helpers.py # HTTP/TCP 请求封装 + 断言工具 + 计数器 ├── test_runner.py # 统一入口，--url 自动识别目标服务 -├── test_gateway.py # 输入校验/Token契约/代理路径安全/限流/CORS（v0.8.0 契约，认证链路待测试钩子） +├── test_gateway.py # 输入校验/Token契约/代理路径安全/限流/CORS（目标 ca:8443，认证 happy path 待测试钩子） ├── test_captcha.py # 获取验证码 → 校验 → 一次性消费 ├── test_smtp.py # 发送邮箱验证码 → 校验 ├── test_dnfs.py # 创建笔记 → 查询 → 更新 → 删除（含内容审核） ├── test_db.py # 日志写入 → 查询 → 统计 → 清理 ├── test_ai_review.py # 内容审核 → 人工反馈纠正 ├── test_static.py # 首页加载 → 文件浏览 → 视频流 → 路径遍历防护 -└── test_waf.py # 正常请求通行 → SQLi/XSS/命令注入/路径遍历/扫描器拦截 +├── test_waf.py # 正常请求通行 → SQLi/XSS/命令注入/路径遍历/扫描器拦截 +└── test_core_confs.py # core 内嵌 confs（与 Python confs 基线行为对比） ``` ## 覆盖的用户旅程 diff --git a/tests/blackbox/test_gateway.py b/tests/blackbox/test_gateway.py index 7e00b7d..1ee0bea 100644 --- a/tests/blackbox/test_gateway.py +++ b/tests/blackbox/test_gateway.py @@ -1,5 +1,5 @@ """ -gateway 黑盒用户模拟测试（v2 — 对齐 gateway v0.8.0 契约） +认证/网关黑盒用户模拟测试（v2 — 目标 ca:8443，原 gateway 认证契约随 v0.9.0 迁至 ca） 覆盖范围（P0，无需测试钩子）: A. 输入校验与错误语义（v0.8.0 新契约：/login 强制 CAPTCHA、/register 强制 email_code） @@ -9,7 +9,7 @@ gateway 黑盒用户模拟测试（v2 — 对齐 gateway v0.8.0 契约） E. 速率限制（随机 XFF 隔离限流桶，避免用例互斥） F. CORS 预检现状固化 + 错误响应脱敏回归（P0-2/P0-3） -已知待修复缺陷（断言目标行为，gateway 修复前会 FAIL）: +已知待修复缺陷（断言目标行为，ca 修复前会 FAIL）: - A3: 缺失 JSON 字段 → 当前 500，应为 400（场景 A5/A8） - A2: 白名单外 Target-Url → 当前 500，应为 403（需有效 Token 才能触达，待测试钩子） @@ -17,9 +17,9 @@ gateway 黑盒用户模拟测试（v2 — 对齐 gateway v0.8.0 契约） captcha2/smtp 测试模式（固定验证码答案钩子），落地前黑盒无法覆盖（P1 清单）。 依赖说明: - - gateway 必须运行，否则全部 SKIP + - ca (:8443) 必须运行，否则全部 SKIP - captcha2 (pymsg:8009) 不在线时 C/E5 段 SKIP（其余用例不受影响） - - static (:9200) 不在线时 D3 段 SKIP + - fsys (:9200) 不在线时 D3 段 SKIP - smtp 不在线不影响本文件（相关用例均为 fail-closed 400 路径） """