refactor(ca): v1.1.0 配置体系重构为纯 CLI 传递

- 移除 confs 依赖：删 Conf.hpp 与 confs/configs/ca.ini，配置加载改为 CLI > 环境变量 > 默认值三层（与 dnfs2 同模式） - 新增 16 个配置选项，env 以 CA_* 为主并兼容旧名（LISTEN_ADDR/UPSTREAM_GATEWAY/DB_* 等），启动时配置完整性校验 - 原 ca.ini 配置值迁入 core/services.yaml ca 条目 args - 修复伪造 Token 触发 500：verify_token 统一捕获 RSA 验签异常，按验签失败返回 401（符合黑盒 B3/B4 契约） - 同步更新 ca/README.md 与根 README.md
2026-08-10 06:13:43 +00:00
1 parent 8b6eb47c80
commit 9d548c064f
@@ -21,7 +21,7 @@ UniServe Framework 的中央认证服务（Central Auth），C++20 实现，v1.0
  - 无 `Target-Url` 头 = 公开请求：剥离伪造身份头（`X-Auth-User`/`X-Auth-Admin`）后直转。
  - 有 `Target-Url` 头 = 受保护请求：本地验签（RSA + 过期 + jti 黑名单 + 用户版本号），通过后注入 `X-Auth-User`（管理员追加 `X-Auth-Admin: 1`）与 `Authorization: Bearer` 再转发。
  - 上游不可达/超时统一返回 `502 Bad Gateway`（区别于 CA 自身故障的 500）。
- **WebSocket 反向代理（仅管理员）**：`[WsProxy]` 段配置的路径在 HTTP Upgrade 握手时校验 Token（`is_admin=true`），通过后透明桥接到后端 ws:// 或 wss:// 服务。
+- **WebSocket 反向代理（仅管理员）**：`--ws-proxy-routes` 配置的路径在 HTTP Upgrade 握手时校验 Token（`is_admin=true`），通过后透明桥接到后端 ws:// 或 wss:// 服务。
 - **CAPTCHA 代理**：`GET /captcha/image` 代理 captcha2 签发图形验证码（PNG + `X-Captcha-Token` 响应头，10 次/分钟/IP，禁缓存）。
 - **邮箱验证码**：`/register/send_code`、`/reset/send_code` 发送 6 位验证码邮件（10 分钟有效）；`/reset_password` 重置密码（防枚举恒成功 + 改密后版本号吊销全端 Token）。
 - **速率限制**：登录 5 次/5 分钟、注册 3 次/10 分钟、发验证码 5 次/10 分钟（IP 级）+ 3 次/小时/10 次/天（邮箱级），按 `X-Forwarded-For` 客户端 IP 计数（由 WAF 注入），超限一律返回 429。
@@ -48,8 +48,8 @@ gateway 侧仅做**存在性不变量**检查（显式 `Target-Url` 请求必须
 | 常数时间比较 | PBKDF2 验证用 `diff |= hash[i] ^ expected[i]` 防 timing attack |
 | 防用户枚举 | 登录对不存在用户执行 dummy PBKDF2 拉平时序；重置密码恒返回成功 |
 | CAPTCHA | 统一走 captcha2 远端校验（Token 一次性消费）；`/login` 强制 |
-| TLS 可选 | `Server.tls = off` 时纯 HTTP（配合 WAF），`on` 时用 `full_chain.crt` / `server.key` |
-| 下游容错 | pymsg 客户端 `retry_on_refused`：db/confs 未就绪时阻塞等待；日志客户端 fail-safe 静默丢弃 |
+| TLS 可选 | 缺省（不传 `--tls`）纯 HTTP（配合 WAF），`--tls` 时用 `full_chain.crt` / `server.key` |
+| 下游容错 | pymsg 客户端 `retry_on_refused`：db 未就绪时阻塞等待；日志客户端 fail-safe 静默丢弃 |

 ## 接口

@@ -93,32 +93,46 @@ Target-Url: http://127.0.0.1:8006                   // 可选；携带即视为
 - 有 `Target-Url`：验签通过后注入身份头转发；`Target-Url` 白名单由 gateway 侧 `Proxy.opened` 裁决（403）。
 - 上游故障：`502 {"success": false, "message": "Bad Gateway"}`。

-### WebSocket 代理（`[WsProxy]` 配置的路径）
+### WebSocket 代理（`--ws-proxy-routes` 配置的路径）

 握手阶段从 `Authorization: Bearer` / `Cookie: q4_token` 提取 Token，验签且 `is_admin=true` 才升级连接并桥接后端；否则拒绝。路由精确匹配，优先级高于 HTTP 通配 `*`。

 ## 配置

-两层加载：**confs 统一配置服务**（启动时 pymsg `get` 拉取 `ca.ini`，`retry_on_refused=true`）→ **环境变量覆盖**（最高优先级）。
+v1.1.0 起配置**全部经 CLI 传递**，不再依赖 confs 统一配置服务（与 dnfs2 同模式）。三层优先级：**CLI 参数 > 环境变量 > 代码默认值**；部署侧由 [`core/services.yaml`](../core/services.yaml) 的 `args` 声明完整传入。

-配置文件：[confs/configs/ca.ini](../confs/configs/ca.ini)。
+| CLI 选项 | 环境变量（CA_ 前缀优先，兼容旧名） | 默认值 |
+|----------|-----------------------------------|--------|
+| `--host` | `CA_HOST` / `LISTEN_ADDR` | `127.0.0.1` |
+| `--port` | `CA_PORT` / `LISTEN_PORT` | `8443` |
+| `--tls` | `CA_TLS=on` | 关（纯 HTTP） |
+| `--upstream-gateway` | `CA_UPSTREAM_GATEWAY` / `UPSTREAM_GATEWAY` | `http://127.0.0.1:8445` |
+| `--token-keep-time` | `CA_TOKEN_KEEP_TIME` | `3600` |
+| `--token-refresh-grace-multiplier` | `CA_TOKEN_REFRESH_GRACE_MULTIPLIER` | `2` |
+| `--token-max-refresh` | `CA_TOKEN_MAX_REFRESH` | `10` |
+| `--cors-origins` | `CA_CORS_ORIGINS` | 空 |
+| `--admin-users` | `CA_ADMIN_USERS` | 空 |
+| `--ws-proxy-routes` | `CA_WS_PROXY_ROUTES` | 空 |
+| `--db-host` / `--db-port` | `CA_DB_HOST`/`DB_HOST` / `CA_DB_PORT`/`DB_PORT` | `127.0.0.1:8005` |
+| `--captcha-host` / `--captcha-port` | `CA_CAPTCHA_HOST`/`CAPTCHA_HOST` / `CA_CAPTCHA_PORT`/`CAPTCHA_PORT` | `127.0.0.1:8009` |
+| `--smtp-host` / `--smtp-port` | `CA_SMTP_HOST`/`SMTP_HOST` / `CA_SMTP_PORT`/`SMTP_PORT` | `127.0.0.1:8008` |
+| `--instance` | — | `ca` |
+| `--log-level` | — | `info` |

- `Server.address`/`port`/`tls`：监听地址/端口/TLS（默认 `127.0.0.1:8443`，env `LISTEN_ADDR`/`LISTEN_PORT`）。
- `Upstream.gateway`：唯一上游 gateway 地址（默认 `http://127.0.0.1:8445`，env `UPSTREAM_GATEWAY`）。
- `Token.*`：`keep_time` / `refresh_grace_multiplier` / `max_refresh`。
- `Admin.users`：管理员白名单（分号分隔邮箱），登录命中时 Token payload 写入 `is_admin=true`。
- `CORS.allowed_origins`：已读取但尚未用于预检响应（见 [`ca_SECURITY_AUDIT.md`](../docs/security/ca_SECURITY_AUDIT.md) P2-3）。
- `WsProxy.routes`：`/path=ws://host:port/target`，分号分隔。
- `Downstream.*`：db/captcha/smtp 地址（env `DB_*`/`CAPTCHA_*`/`SMTP_*`/`CONFS_*`）。
+- `--admin-users`：管理员白名单（分号分隔邮箱），登录命中时 Token payload 写入 `is_admin=true`。
+- `--cors-origins`：已读取但尚未用于预检响应（见 [`ca_SECURITY_AUDIT.md`](../docs/security/ca_SECURITY_AUDIT.md) P2-3）。
+- `--ws-proxy-routes`：`/path=ws://host:port/target`，分号分隔多条。
+- 旧环境变量名（`LISTEN_ADDR` 等）保留兼容，供 Docker 部署用服务名覆盖 `127.0.0.1`。
+- 启动时做配置完整性校验：监听地址/端口、上游 gateway、db 地址非法则启动失败。

 ## 编译与运行

 ```bash
 bash _set.sh   # make clean && make
-bash _run.sh   # 从 confs 拉取配置启动（先 sleep 2 等待 confs/db）
+bash _run.sh   # 纯 CLI 配置启动（"$@" 透传，可临时覆盖任意配置项）
 ```

-命令行参数：`-h/--help`、`-v/--version`。日志经 LogC 异步批量推送 db:8005 `Logs` 表（service 名 `ca`）。
+命令行参数：完整选项见 `--help`（见上表）；`-h/--help`、`-v/--version`。日志经 LogC 异步批量推送 db:8005 `Logs` 表（service 名 `ca`）。

 ## 目录结构

@@ -129,7 +143,6 @@ ca/
 ├── inc/
 │   ├── DbC.hpp           # db 服务客户端（pymsg，retry_on_refused=true；client 名 "ca"）
 │   ├── LogC.hpp          # 统一日志客户端（异步批量，fail-safe；client 名 "ca-log"）
-│   ├── Conf.hpp          # ConfIni：ini 解析 + env 覆盖
 │   ├── ExpBase.hpp       # 异常基类（带 source_location）
 │   └── LocalTime.hpp     # 本地时间工具
 ├── Makefile
@@ -139,4 +152,6 @@ ca/

 ## 版本

+`1.1.0`：配置体系重构——彻底移除 confs 依赖（删 `Conf.hpp` 与 `confs/configs/ca.ini`），配置全部经 CLI 传递（CLI > 环境变量 > 默认值三层），原 ca.ini 配置值迁入 `core/services.yaml` 的 ca 条目 args；修复伪造 Token 触发 500（RSA 验签异常未捕获，现统一返回 401，符合黑盒测试 B3/B4 契约）。
+
 `1.0.0`：认证独立化首发——自 gateway v0.8.0 整体搬迁全部认证资产（逐字保留实现），新增前置转发层（固定上游 + strip-then-set 身份头契约 + 上游 502 语义）。原 gateway 同步瘦身为 v0.9.0 纯转发服务。