docs: 更新 INDEX 索引并补充 confs2 C++ 重写开发文档
This commit is contained in:
qing committed
1 parent
407ce3c366
commit
c13d11aafb
2 files changed
+742
-1
No files matched your search
+2
-1
@@ -9,7 +9,7 @@ docs/
|
||||
├── INDEX.md # 本文件（文档总索引）
|
||||
├── security/ # 安全审计与加固（29 篇）
|
||||
├── reviews/ # 代码审查日志（4 篇）
|
||||
└── reports/ # 分析报告与开发规划（12 篇）
|
||||
└── reports/ # 分析报告与开发规划（13 篇）
|
||||
```
|
||||
|
||||
---
|
||||
@@ -92,6 +92,7 @@ docs/
|
||||
| [captcha_cpp_rewrite_dev_doc.md](reports/captcha_cpp_rewrite_dev_doc.md) | captcha 模块 C++20 重写开发方案（FreeType + stb_image_write 替代 Pillow，协议兼容零改动） |
|
||||
| [smtp_cpp_rewrite_dev_doc.md](reports/smtp_cpp_rewrite_dev_doc.md) | smtp 模块 C++20 重写开发方案（SMTP_SSL 客户端手写，审计 7 项遗留一并在重写中修复，零新增系统依赖） |
|
||||
| [libhttp_remote_addr_dev_doc.md](reports/libhttp_remote_addr_dev_doc.md) | libhttp 对端地址透传开发方案（X-Remote-Addr 可信头注入，非破坏；gateway trust_xff 配套，闭环审计 A4） |
|
||||
| [confs2_cpp_rewrite_dev_doc.md](reports/confs2_cpp_rewrite_dev_doc.md) | confs 模块 C++20 重写开发方案（libmsg RpcServer 替代 pymsg，协议兼容零改动，审计 7 项遗留一并修复，零新增系统依赖，未来可合入 core 注册中心） |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,740 @@
|
||||
# confs 模块 C++20 重写开发方案
|
||||
|
||||
> 文档类型：功能开发计划
|
||||
> 模块：confs → confs2（C++20 重写）
|
||||
> 作者：自动生成
|
||||
> 日期：2026-08-09
|
||||
|
||||
---
|
||||
|
||||
## 1. 概述
|
||||
|
||||
### 1.1 背景与动机
|
||||
|
||||
`confs` 统一配置服务当前以 Python 实现，基于 `pymsg RpcServer` 在 `127.0.0.1:8010` 提供配置文件集中托管与分发。5 个内部服务（static、dnfs、db、captcha、redirect80）通过 `pymsg RpcClient` 消费配置。
|
||||
|
||||
本项目已完成 db2、captcha2、smtp3、dnfs2 等 C++20 重写，遵循"原版与重写版并存 → 重写版验证通过后切换"的渐进策略。confs 作为最后一个纯 Python 基础设施服务，其 C++ 重写可：
|
||||
|
||||
| 收益 | 说明 |
|
||||
|------|------|
|
||||
| 内存占用降低 | Python 进程 ~50-100MB RSS → C++ 预估 < 5MB |
|
||||
| 启动速度提升 | Python 解释器启动 ~200ms → C++ 瞬时 |
|
||||
| 依赖链简化 | 消除 Python venv / pip / nuitka 工具链 |
|
||||
| 安全审计遗留修复 | 重写时一并修复 Python 版 7 项遗留审计发现 |
|
||||
| 未来合入 core 的基础 | C++ 同构后，未来可评估合入 core 注册中心 |
|
||||
|
||||
### 1.2 设计目标
|
||||
|
||||
1. **协议零改动**：pymsg RPC 协议、端口 `8010`、路由名（`get`/`list`/`reload`/`health`）、响应格式全部不变，5 个消费方零改动。
|
||||
2. **功能完全对等**：ConfigStore 内存缓存 + mtime 自动重载、INI/JSON 按键取值、扩展名白名单、TOCTOU 防护、文件大小限制——逐项 C++ 实现。
|
||||
3. **零新增系统依赖**：仅链接 `libmsg`（`-lus_msg`）、`boost_json`、`boost_program_options`、`pthread`——均为系统已安装库。
|
||||
4. **安全审计遗留修复**：Python 版 7 项未修复发现（P2-3/P2-4/P3-1~P3-6）在重写中一并解决。
|
||||
5. **配置目录兼容**：复用现有 `confs/configs/` 目录，配置文件零迁移。
|
||||
6. **可演进**：保留向 core 注册中心注册的接口预留，未来合入评估时改动最小。
|
||||
|
||||
### 1.3 不做什么
|
||||
|
||||
- **不改协议**：不引入 HTTP，不改变 pymsg 帧格式，不增减路由。
|
||||
- **不改消费方**：5 个 Python 服务的 `RpcClient` 调用代码不改。
|
||||
- **不引入新解析库**：INI 解析手写（与 captcha2 的 `merge_ini` 风格一致），不引入 `boost::property_tree::ini_parser`（其大小写语义与 Python ConfigParser 不一致）。
|
||||
- **不实现 YAML/TOML 按键取值**：与 Python 版一致，仅返回全文。
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状分析
|
||||
|
||||
### 2.1 Python confs 源码结构
|
||||
|
||||
```
|
||||
confs/
|
||||
├── confs.py # 服务主程序（ConfigStore + ConfsServer，361 行）
|
||||
├── log_client.py # 异步日志客户端 SDK（160 行）
|
||||
├── configs/ # 配置文件存放目录（9 个 .ini 文件）
|
||||
│ ├── ca.ini
|
||||
│ ├── captcha.ini
|
||||
│ ├── db.ini
|
||||
│ ├── dnfs.ini
|
||||
│ ├── example.ini
|
||||
│ ├── gateway.ini
|
||||
│ ├── redirect80.ini
|
||||
│ ├── smtp.ini
|
||||
│ └── static.ini
|
||||
├── _run.sh # 启动脚本（venv 中 exec python3 confs.py）
|
||||
├── _set.sh # 初始化脚本（建 venv + pip install）
|
||||
├── requirements.txt # 依赖（pymsg + nuitka）
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### 2.2 关键组件
|
||||
|
||||
| 组件 | 职责 | 行数 |
|
||||
|------|------|------|
|
||||
| `ConfigStore` | 磁盘 configs/ 目录 + 内存缓存 + mtime 自动重载 + 路径安全 | ~120 行 |
|
||||
| `ConfsServer` | RpcServer 入口，路由分发（get/list/reload/health） | ~90 行 |
|
||||
| `_extract_key()` | INI `Section.option` 取值 + JSON 点路径取值 | ~40 行 |
|
||||
| `log_client.py` | 异步批量推送日志到 db:8005 | 160 行 |
|
||||
|
||||
### 2.3 现有路由
|
||||
|
||||
| 路由 | 方法 | 说明 |
|
||||
|------|------|------|
|
||||
| `get` | `{"name": "db.ini"}` | 取配置全文；带 `key` 时返回单键值（仅 ini/json） |
|
||||
| `list` | `{}` | 列出配置目录全部文件及元信息 |
|
||||
| `reload` | `{"name": "db.ini"}` 或 `{}` | 重载指定配置；省略 name 清空全部缓存 |
|
||||
| `health` | `{}` | 健康检查 |
|
||||
|
||||
### 2.4 消费方清单
|
||||
|
||||
| 服务 | 配置文件 | 接入方式 |
|
||||
|------|---------|---------|
|
||||
| static | `static.ini` | pymsg `RpcClient` + `retry_on_refused=True` |
|
||||
| dnfs | `dnfs.ini` | pymsg `RpcClient` + `retry_on_refused=True` |
|
||||
| db | `db.ini` | pymsg `RpcClient` + `retry_on_refused=True` |
|
||||
| captcha | `captcha.ini` | pymsg `RpcClient` + `retry_on_refused=True` |
|
||||
| redirect80 | `redirect80.ini` | pymsg `RpcClient` + `retry_on_refused=True` |
|
||||
|
||||
### 2.5 Python 版安全审计遗留（7 项）
|
||||
|
||||
| 编号 | 级别 | 问题 | 重写修复方案 |
|
||||
|------|------|------|-------------|
|
||||
| P2-3 | P2 | 配置名/key 直接拼入日志，未过滤控制字符 | 日志消息过滤 `\n`/`\r`/ANSI 转义 |
|
||||
| P2-4 | P2 | `list()` 持锁遍历目录+stat | 拷贝文件名列表后释放锁再 stat |
|
||||
| P3-1 | P3 | `_run.sh` 有 `sleep` hack | 移除 sleep，靠 init.txt 启动顺序 |
|
||||
| P3-2 | P3 | `_set.sh` 硬编码 pip 镜像源 | C++ 重写无需 pip，`_set.sh` 改为 `make` |
|
||||
| P3-3 | P3 | `_set.sh` 缺少 `set -e` | `_set.sh` 加 `set -euo pipefail` |
|
||||
| P3-4 | P3 | requirements.txt 含运行时不需要的 nuitka | C++ 无 requirements.txt |
|
||||
| P3-5 | P3 | ConfigParser 大小写隐式行为未文档化 | INI 解析器明确定义大小写策略 |
|
||||
| P3-6 | P3 | 错误消息暴露底层 IO 异常 | 异常消息脱敏，不返回系统路径 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 整体设计
|
||||
|
||||
### 3.1 架构总览
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ confs2 (C++20, :8010) │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────┐ │
|
||||
│ │ ConfigStore (线程安全) │ │
|
||||
│ │ ├── 磁盘: configs/ 目录 │ │
|
||||
│ │ ├── 内存缓存: {name → {content, mtime, size}} │ │
|
||||
│ │ ├── mtime 自动重载 │ │
|
||||
│ │ └── 安全: 路径遍历/TOCTOU/扩展名白名单/大小限制 │ │
|
||||
│ └───────────────────────┬────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────────────────▼────────────────────────────┐ │
|
||||
│ │ RpcServer (libmsg, :8010, pymsg 协议) │ │
|
||||
│ │ ├── get → ConfigStore.get() + _extract_key() │ │
|
||||
│ │ ├── list → ConfigStore.list() │ │
|
||||
│ │ ├── reload → ConfigStore.reload() │ │
|
||||
│ │ └── health → 静态响应 │ │
|
||||
│ └────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────┐ │
|
||||
│ │ LogC (异步日志, libmsg AsyncQueue → db:8005) │ │
|
||||
│ └────────────────────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
▲
|
||||
│ pymsg RPC (TCP, 127.0.0.1:8010)
|
||||
│
|
||||
┌─────┴─────┬──────┬──────┬──────┬──────┐
|
||||
▼ ▼ ▼ ▼ ▼ ▼
|
||||
static dnfs db captcha redirect80
|
||||
(RpcClient, 消费方零改动)
|
||||
```
|
||||
|
||||
### 3.2 核心组件
|
||||
|
||||
| 组件 | 职责 | 对应 Python |
|
||||
|------|------|-------------|
|
||||
| **ConfigStore** | 配置文件仓库（磁盘+缓存+安全） | `ConfigStore` 类 |
|
||||
| **IniParser** | INI 解析（Section.option 取值） | `configparser.ConfigParser` |
|
||||
| **JsonKeyExtractor** | JSON 点路径取值 | `_extract_key` JSON 分支 |
|
||||
| **LogC** | 异步日志推送 | `log_client.py` |
|
||||
| **RpcServer** | pymsg RPC 服务端（libmsg） | `pymsg.RpcServer` |
|
||||
|
||||
### 3.3 目录结构
|
||||
|
||||
```
|
||||
confs2/
|
||||
├── src/
|
||||
│ └── main.cpp # 全部源码（ConfigStore + 路由 + main）
|
||||
├── inc/
|
||||
│ └── LogC.hpp # 异步日志客户端（从 captcha2 改编）
|
||||
├── configs/ # → 符号链接到 ../confs/configs/（配置文件零迁移）
|
||||
├── Makefile # 构建系统（g++ -std=c++20）
|
||||
├── _run.sh # 启动脚本
|
||||
├── _set.sh # 编译脚本
|
||||
└── README.md # 模块文档
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 详细设计
|
||||
|
||||
### 4.1 ConfigStore — 配置文件仓库
|
||||
|
||||
```cpp
|
||||
// 核心数据结构
|
||||
struct CacheEntry {
|
||||
std::string content;
|
||||
std::filesystem::file_time_type mtime;
|
||||
std::size_t size;
|
||||
};
|
||||
|
||||
class ConfigStore {
|
||||
public:
|
||||
explicit ConfigStore(const std::string& root);
|
||||
|
||||
// 取配置全文（带缓存 + mtime 自动重载）
|
||||
// 返回 CacheEntry 的拷贝（防缓存污染，与 Python 版 dict(entry) 语义一致）
|
||||
CacheEntry get(const std::string& name);
|
||||
|
||||
// 列出配置目录全部文件元信息
|
||||
std::vector<ConfigMeta> list();
|
||||
|
||||
// 重载指定配置 / 清空全部缓存
|
||||
std::vector<std::string> reload(const std::string* name);
|
||||
|
||||
std::size_t cached_count() const;
|
||||
|
||||
private:
|
||||
// 扩展名白名单校验（纯字符串操作，不访问文件系统）
|
||||
static void validate_name(const std::string& name);
|
||||
|
||||
// 持锁解析路径（realpath 前缀校验 + 文件存在性）
|
||||
std::string resolve_locked(const std::string& name);
|
||||
|
||||
std::filesystem::path root_;
|
||||
std::unordered_map<std::string, CacheEntry> cache_;
|
||||
mutable std::mutex mtx_;
|
||||
};
|
||||
```
|
||||
|
||||
#### 安全机制（逐项 C++ 实现）
|
||||
|
||||
| 安全机制 | Python 实现 | C++ 实现 |
|
||||
|----------|-------------|----------|
|
||||
| 扩展名白名单 | `ALLOWED_EXT = {".ini", ...}` | `static const std::unordered_set<std::string> kAllowedExt` |
|
||||
| 路径遍历防护 | `os.path.basename` + `os.path.realpath` 前缀校验 | `std::filesystem::path::filename()` + `canonical()` 前缀校验 |
|
||||
| TOCTOU 防护 | 锁内 `realpath→stat→open` | 锁内 `canonical→file_size→ifstream` |
|
||||
| 文件大小限制 | `MAX_CONFIG_SIZE = 1MiB`，stat 后校验 | `file_size()` 后校验 `kMaxConfigSize` |
|
||||
| 缓存防污染 | 返回 `dict(entry)` 浅拷贝 | 返回 `CacheEntry` 值拷贝 |
|
||||
| mtime 自动重载 | `os.stat().st_mtime` 比对 | `last_write_time()` 比对 |
|
||||
| list 符号链接防护 | 遍历时 `realpath` 前缀校验 | 遍历时 `canonical()` 前缀校验，逃逸链接跳过 |
|
||||
| 日志注入防护 | **未实现（P2-3 遗留）** | **新增**：日志消息过滤 `\n`/`\r`/`\x1b` |
|
||||
|
||||
#### TOCTOU 防护流程（锁内原子操作）
|
||||
|
||||
```cpp
|
||||
CacheEntry ConfigStore::get(const std::string& name) {
|
||||
validate_name(name); // 锁外快速拒绝非法名
|
||||
std::lock_guard<std::mutex> lock(mtx_);
|
||||
|
||||
auto path = resolve_locked(name); // 锁内: canonical() 解析符号链接 + 前缀校验
|
||||
|
||||
// 锁内: stat → mtime 比对 → open → read，无 TOCTOU 窗口
|
||||
auto mtime = std::filesystem::last_write_time(path);
|
||||
auto size = std::filesystem::file_size(path);
|
||||
|
||||
auto it = cache_.find(name);
|
||||
if (it != cache_.end() && it->second.mtime == mtime)
|
||||
return it->second; // 缓存命中，返回拷贝
|
||||
|
||||
if (size > kMaxConfigSize)
|
||||
throw ConfigError("配置文件过大");
|
||||
|
||||
std::ifstream f(path);
|
||||
std::string content((std::istreambuf_iterator<char>(f)),
|
||||
std::istreambuf_iterator<char>());
|
||||
|
||||
CacheEntry entry{content, mtime, content.size()};
|
||||
cache_[name] = entry;
|
||||
return entry; // 返回拷贝
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 IniParser — INI 按键取值
|
||||
|
||||
与 Python `ConfigParser(interpolation=None)` 行为对等的 C++ 手写解析器：
|
||||
|
||||
| Python ConfigParser 行为 | C++ 实现策略 |
|
||||
|--------------------------|-------------|
|
||||
| Section 大小写敏感 | `std::string` 原样比较 |
|
||||
| Option 大小写不敏感 | 比较前 `std::tolower` 归一化 |
|
||||
| `;` 和 `#` 注释 | 行首匹配跳过 |
|
||||
| `=` 和 `:` 分隔符 | 仅支持 `=`（与现有 configs/ 一致） |
|
||||
| 禁用 `%(key)s` 插值 | 不实现插值，原样返回 |
|
||||
| 多行续行（前导空格） | 支持：下一行以空格/Tab 开头则追加 |
|
||||
|
||||
```cpp
|
||||
// 从 INI 文本中提取 Section.option 的值
|
||||
// 键格式: "Section.option"
|
||||
// 大小写: section 敏感, option 不敏感（与 Python 一致）
|
||||
// 插值: 禁用，原样返回（与 Python interpolation=None 一致）
|
||||
static std::optional<std::string> extract_ini_key(
|
||||
const std::string& content, const std::string& key);
|
||||
```
|
||||
|
||||
### 4.3 JsonKeyExtractor — JSON 点路径取值
|
||||
|
||||
```cpp
|
||||
// 从 JSON 文本中按点路径提取值
|
||||
// 键格式: "server.port" 或 "servers.0.host"（数字下标）
|
||||
// 返回 boost::json::value（可为 string/int/double/bool/null/array/object）
|
||||
static json::value extract_json_key(
|
||||
const std::string& content, const std::string& key);
|
||||
```
|
||||
|
||||
### 4.4 路由实现
|
||||
|
||||
#### `get` — 取配置
|
||||
|
||||
```cpp
|
||||
rpc.add_route("get", [](const json::object& req) -> json::value {
|
||||
// 参数校验
|
||||
auto name_it = req.find("name");
|
||||
if (name_it == req.end() || !name_it->value().is_string())
|
||||
throw ConfigError("缺少 name 字段");
|
||||
|
||||
std::string name = json::value_to<std::string>(name_it->value());
|
||||
auto entry = g_store.get(name);
|
||||
|
||||
// 无 key：返回全文
|
||||
auto key_it = req.find("key");
|
||||
if (key_it == req.end())
|
||||
return json::object{
|
||||
{"name", name},
|
||||
{"content", entry.content},
|
||||
{"size", (std::int64_t)entry.size},
|
||||
{"mtime", iso_timestamp(entry.mtime)}
|
||||
};
|
||||
|
||||
// 有 key：按键取值
|
||||
std::string key = json::value_to<std::string>(key_it->value());
|
||||
auto ext = get_extension(name);
|
||||
|
||||
if (ext == ".ini" || ext == ".conf" || ext == ".cfg") {
|
||||
auto val = extract_ini_key(entry.content, key);
|
||||
if (!val) throw KeyNotFound("键不存在: " + name + " -> " + key);
|
||||
return json::object{{"name", name}, {"key", key}, {"value", *val}};
|
||||
}
|
||||
if (ext == ".json") {
|
||||
auto val = extract_json_key(entry.content, key);
|
||||
return json::object{{"name", name}, {"key", key}, {"value", val}};
|
||||
}
|
||||
throw ConfigError(get_extension(name) + " 类型不支持按键查询");
|
||||
});
|
||||
```
|
||||
|
||||
#### `list` — 列出配置
|
||||
|
||||
```cpp
|
||||
rpc.add_route("list", [](const json::object&) -> json::value {
|
||||
auto configs = g_store.list();
|
||||
json::array arr;
|
||||
for (const auto& c : configs)
|
||||
arr.push_back(json::object{
|
||||
{"name", c.name}, {"size", (std::int64_t)c.size},
|
||||
{"mtime", c.mtime_iso}, {"cached", c.cached}
|
||||
});
|
||||
return json::object{
|
||||
{"config_dir", g_store.root_string()},
|
||||
{"configs", arr}
|
||||
};
|
||||
});
|
||||
```
|
||||
|
||||
#### `reload` — 重载配置
|
||||
|
||||
```cpp
|
||||
rpc.add_route("reload", [](const json::object& req) -> json::value {
|
||||
auto it = req.find("name");
|
||||
|
||||
// 省略 name 或 null → 清空全部缓存
|
||||
if (it == req.end() || it->value().is_null()) {
|
||||
auto names = g_store.reload(nullptr);
|
||||
return json::object{{"reloaded", make_json_array(names)}};
|
||||
}
|
||||
|
||||
// 非字符串 → 报错
|
||||
if (!it->value().is_string())
|
||||
throw ConfigError("name 字段必须是字符串");
|
||||
|
||||
std::string name = json::value_to<std::string>(it->value());
|
||||
// 空字符串 → 报错（不误清全部缓存，与 Python 版一致）
|
||||
if (name.empty())
|
||||
throw ConfigError("name 字段不能为空（要清空全部缓存请省略 name 字段）");
|
||||
|
||||
auto names = g_store.reload(&name);
|
||||
return json::object{{"reloaded", make_json_array(names)}};
|
||||
});
|
||||
```
|
||||
|
||||
#### `health` — 健康检查
|
||||
|
||||
```cpp
|
||||
rpc.add_route("health", [](const json::object&) -> json::value {
|
||||
return json::object{
|
||||
{"status", "ok"},
|
||||
{"service", "confs"},
|
||||
{"config_dir", g_store.root_string()},
|
||||
{"cached", (std::int64_t)g_store.cached_count()},
|
||||
{"uptime", uptime_seconds()}
|
||||
};
|
||||
});
|
||||
```
|
||||
|
||||
### 4.5 配置加载（confs 自身的引导配置）
|
||||
|
||||
confs 自身不需要从 confs 获取配置（避免循环依赖），使用硬编码默认值 + 环境变量覆盖 + 命令行参数覆盖：
|
||||
|
||||
```cpp
|
||||
struct ConfsConfig {
|
||||
std::string host = "127.0.0.1";
|
||||
int port = 8010;
|
||||
int workers = 4;
|
||||
std::string config_dir; // 默认: 同级 configs/ 目录
|
||||
};
|
||||
|
||||
// 加载顺序: 硬编码默认 → 环境变量覆盖 → 命令行覆盖
|
||||
// 环境变量: LISTEN_ADDR, LISTEN_PORT, WORKERS, CONFS_DIR
|
||||
```
|
||||
|
||||
### 4.6 日志客户端（LogC.hpp）
|
||||
|
||||
从 [captcha2/inc/LogC.hpp](../../captcha2/inc/LogC.hpp) 改编，仅改 namespace 和服务名：
|
||||
|
||||
```cpp
|
||||
namespace confs2 {
|
||||
// ... 与 captcha2::LogC 结构完全一致
|
||||
// 仅改动:
|
||||
// - namespace: captcha2 → confs2
|
||||
// - 日志中服务名: "captcha2" → "confs"
|
||||
// - 客户端名: "captcha2-log" → "confs-log"
|
||||
}
|
||||
```
|
||||
|
||||
#### 日志注入防护（修复 P2-3）
|
||||
|
||||
```cpp
|
||||
// 过滤日志消息中的控制字符（\n, \r, \x1b ANSI 转义等）
|
||||
static std::string sanitize_for_log(std::string s) {
|
||||
s.erase(std::remove_if(s.begin(), s.end(), [](unsigned char c) {
|
||||
return c < 0x20 && c != '\t'; // 保留 Tab，过滤其他控制字符
|
||||
}), s.end());
|
||||
return s;
|
||||
}
|
||||
```
|
||||
|
||||
### 4.7 异常消息脱敏（修复 P3-6）
|
||||
|
||||
```cpp
|
||||
// 异常消息脱敏：不返回系统路径、权限错误等底层信息
|
||||
static std::string sanitize_error_msg(const std::string& msg) {
|
||||
// 替换绝对路径为 <redacted>
|
||||
static const std::regex path_re(R"(/\S+(?:/\S*)*)");
|
||||
std::string result = std::regex_replace(msg, path_re, "<redacted>");
|
||||
// 过滤 Permission denied 等系统错误
|
||||
static const std::regex perm_re(R"(Permission denied|No such file)");
|
||||
result = std::regex_replace(result, perm_re, "access error");
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
> 注意：RpcServer 已内置 `_sanitize_error()` 方法（见 [RpcServer.hpp](../../libmsg/inc/us/RpcServer.hpp#L188-L197)），会自动替换绝对路径。confs2 的 handler 抛出的异常会先经 RpcServer 脱敏。但 confs2 仍应在业务层对底层 IO 异常做一层包装，将 `Permission denied` 等系统错误转为业务语义错误。
|
||||
|
||||
---
|
||||
|
||||
## 5. 实现计划
|
||||
|
||||
### 5.1 分阶段交付
|
||||
|
||||
| 阶段 | 里程碑 | 涉及文件 | 预估工时 |
|
||||
|------|--------|----------|----------|
|
||||
| **P0 — 骨架搭建** | Makefile + _run.sh + _set.sh + 空 main.cpp（RpcServer 启动 + health 路由） | 新增 `confs2/Makefile`、`_run.sh`、`_set.sh`、`src/main.cpp`、`inc/LogC.hpp` | 1h |
|
||||
| **P1 — ConfigStore 核心** | ConfigStore 类：磁盘读取 + 内存缓存 + mtime 重载 + 安全机制 | `src/main.cpp` | 3h |
|
||||
| **P2 — 路由实现** | get / list / reload / health 四路由完整实现 | `src/main.cpp` | 2h |
|
||||
| **P3 — INI 按键取值** | IniParser 手写 + JSON 点路径取值 | `src/main.cpp` | 2h |
|
||||
| **P4 — 日志客户端** | LogC.hpp 改编 + 日志注入防护 | `inc/LogC.hpp`、`src/main.cpp` | 1h |
|
||||
| **P5 — 配置加载** | 环境变量 + 命令行参数解析 | `src/main.cpp` | 1h |
|
||||
| **P6 — 编译验证** | 零警告编译 + ldd 依赖检查 + --help 验证 | `Makefile` | 0.5h |
|
||||
| **P7 — 功能测试** | 逐路由对比 Python 版响应一致性 | `tests/` 新增 | 2h |
|
||||
| **P8 — 切换 init.txt** | init.txt 改为 confs2/_run.sh + 生产验证 | `core/init.txt` | 0.5h |
|
||||
|
||||
**总计预估：~13 小时**
|
||||
|
||||
### 5.2 Makefile
|
||||
|
||||
```makefile
|
||||
CXX := g++
|
||||
CXXFLAGS := -std=c++20 -Wall -Wextra -O2
|
||||
INCS := -I./inc
|
||||
LIBS := -lus_msg -lboost_json -lboost_program_options -lpthread
|
||||
|
||||
TARGET := confs2.bin
|
||||
SRC := src/main.cpp
|
||||
|
||||
.PHONY: all clean install
|
||||
|
||||
all: $(TARGET)
|
||||
|
||||
$(TARGET): $(SRC)
|
||||
$(CXX) $(CXXFLAGS) $(INCS) $^ $(LIBS) -o $@
|
||||
|
||||
install: $(TARGET)
|
||||
cp $(TARGET) /usr/local/bin/
|
||||
|
||||
clean:
|
||||
rm -f $(TARGET)
|
||||
```
|
||||
|
||||
### 5.3 _run.sh
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
cd "$(dirname "$0")" || exit
|
||||
sleep 1
|
||||
exec ./confs2.bin
|
||||
```
|
||||
|
||||
### 5.4 _set.sh
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
cd "$(dirname "$0")" || exit
|
||||
|
||||
make clean 2>/dev/null || true
|
||||
make
|
||||
echo "[confs2] 编译完成 → ./confs2.bin"
|
||||
|
||||
# 创建 configs 符号链接（指向 ../confs/configs/，配置文件零迁移）
|
||||
if [ ! -e configs ]; then
|
||||
ln -s ../confs/configs configs
|
||||
echo "[confs2] 已创建 configs → ../confs/configs 符号链接"
|
||||
fi
|
||||
```
|
||||
|
||||
### 5.5 新增文件清单
|
||||
|
||||
```
|
||||
confs2/
|
||||
├── src/
|
||||
│ └── main.cpp # 全部业务源码（预估 ~500 行）
|
||||
├── inc/
|
||||
│ └── LogC.hpp # 异步日志客户端（从 captcha2 改编，~110 行）
|
||||
├── configs # → 符号链接到 ../confs/configs/
|
||||
├── Makefile # 构建系统
|
||||
├── _run.sh # 启动脚本
|
||||
├── _set.sh # 编译 + 链接 configs/
|
||||
└── README.md # 模块文档
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 关键依赖
|
||||
|
||||
| 依赖 | 用途 | 已安装 |
|
||||
|------|------|--------|
|
||||
| `libmsg` (`-lus_msg`) | RpcServer / RpcClient / MsgServer / AsyncQueue | ✅ |
|
||||
| `boost::json` (`-lboost_json`) | JSON 序列化/反序列化 | ✅ |
|
||||
| `boost::program_options` (`-lboost_program_options`) | 命令行参数解析 | ✅ |
|
||||
| `pthread` | 多线程（mutex） | ✅ |
|
||||
| `std::filesystem` | 文件系统操作（C++20 标准库） | ✅ |
|
||||
|
||||
**零新增系统依赖**——所有库均已被 captcha2 / smtp3 等模块使用。
|
||||
|
||||
---
|
||||
|
||||
## 7. 测试计划
|
||||
|
||||
### 7.1 功能测试（对比 Python 版响应一致性）
|
||||
|
||||
| 测试项 | 方法 | 通过标准 |
|
||||
|--------|------|----------|
|
||||
| `get` 取全文 | `RpcClient.call("get", {"name":"db.ini"})` | content/size/mtime 与 Python 版一致 |
|
||||
| `get` INI 按键 | `RpcClient.call("get", {"name":"db.ini","key":"server.port"})` | value="8005" |
|
||||
| `get` JSON 按键 | 构造 .json 配置，取 `server.port` | 值一致 |
|
||||
| `get` 不存在 | `RpcClient.call("get", {"name":"nonexist.ini"})` | `success=false`，error 含"不存在" |
|
||||
| `get` 路径遍历 | `{"name":"../../etc/passwd"}` | `success=false`，拒绝 |
|
||||
| `get` 非法扩展名 | `{"name":"test.exe"}` | `success=false`，拒绝 |
|
||||
| `list` | `RpcClient.call("list", {})` | 配置列表与 Python 版一致 |
|
||||
| `reload` 指定 | `RpcClient.call("reload", {"name":"db.ini"})` | `success=true`，reloaded=["db.ini"] |
|
||||
| `reload` 全部 | `RpcClient.call("reload", {})` | `success=true`，reloaded 含全部缓存名 |
|
||||
| `reload` 空字符串 | `RpcClient.call("reload", {"name":""})` | `success=false`，error 含"不能为空" |
|
||||
| `reload` 非字符串 | `RpcClient.call("reload", {"name":123})` | `success=false`，error 含"必须是字符串" |
|
||||
| `health` | `RpcClient.call("health", {})` | status="ok"，service="confs" |
|
||||
| mtime 重载 | 修改配置文件内容，再 `get` | 返回新内容 |
|
||||
| 大文件拒绝 | 创建 > 1MiB 文件，`get` | `success=false`，error 含"过大" |
|
||||
| 符号链接逃逸 | configs/ 内放逃逸符号链接 | `list` 中不出现 |
|
||||
|
||||
### 7.2 消费方回归测试
|
||||
|
||||
| 服务 | 测试方法 |
|
||||
|------|----------|
|
||||
| static | 启动 confs2 + static，验证静态文件服务正常（从 confs2 获取 static.ini） |
|
||||
| dnfs | 启动 confs2 + dnfs，验证树状菜单 API 正常 |
|
||||
| db | 启动 confs2 + db，验证数据库服务正常（从 confs2 获取 db.ini） |
|
||||
| captcha | 启动 confs2 + captcha2，验证验证码生成正常（从 confs2 获取 captcha.ini） |
|
||||
| redirect80 | 启动 confs2 + redirect80，验证重定向服务正常 |
|
||||
|
||||
### 7.3 安全测试
|
||||
|
||||
| 测试项 | 方法 |
|
||||
|--------|------|
|
||||
| 路径遍历 | `{"name":"../../../etc/passwd"}` → 拒绝 |
|
||||
| 绝对路径 | `{"name":"/etc/passwd"}` → 拒绝 |
|
||||
| 非法扩展名 | `{"name":"malicious.sh"}` → 拒绝 |
|
||||
| 符号链接逃逸 | configs/ 内符号链接指向 /etc/ → list 跳过，get 拒绝 |
|
||||
| 大文件 OOM | 创建 2MiB 配置 → 拒绝 |
|
||||
| 日志注入 | 配置名含 `\n[FAKE]` → 日志中无伪造条目 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 安全考量
|
||||
|
||||
### 8.1 安全机制对照表
|
||||
|
||||
| 机制 | Python 版状态 | C++ 版方案 |
|
||||
|------|---------------|-------------|
|
||||
| 扩展名白名单 | ✅ | ✅ `kAllowedExt` |
|
||||
| 路径遍历防护 | ✅ basename + realpath 前缀 | ✅ `filename()` + `canonical()` 前缀 |
|
||||
| TOCTOU 防护 | ✅ 锁内 realpath→stat→open | ✅ 锁内 canonical→file_size→ifstream |
|
||||
| 文件大小限制 | ✅ 1MiB | ✅ `kMaxConfigSize = 1MiB` |
|
||||
| Slowloris 防护 | ✅ pymsg 10s recv 超时 | ✅ libmsg MsgServer 同策略 |
|
||||
| 缓存防污染 | ✅ 返回浅拷贝 | ✅ 返回值拷贝 |
|
||||
| list 符号链接防护 | ✅ realpath 前缀校验 | ✅ canonical 前缀校验 |
|
||||
| 参数类型校验 | ✅ 非字符串/空值报错 | ✅ 逐字段 is_string 校验 |
|
||||
| INI 安全 | ✅ 禁用插值 | ✅ 不实现插值 |
|
||||
| 仅监听本机 | ✅ 127.0.0.1 | ✅ 默认 127.0.0.1 |
|
||||
| 异常隔离 | ✅ RpcServer 包装 | ✅ libmsg RpcServer 同机制 |
|
||||
| 日志注入防护 | ❌ P2-3 遗留 | ✅ **新增** sanitize_for_log |
|
||||
| 异常消息脱敏 | ❌ P3-6 遗留 | ✅ **新增** RpcServer 内置脱敏 + 业务层包装 |
|
||||
| 鉴权 | ❌ 无 | ❌ 无（依赖仅本机信任边界，与 Python 版一致） |
|
||||
|
||||
### 8.2 INI 大小写策略文档化（修复 P3-5）
|
||||
|
||||
在代码注释和 README 中明确文档化：
|
||||
|
||||
```
|
||||
INI 解析大小写策略（与 Python configparser(interpolation=None) 一致）：
|
||||
- Section 名：大小写敏感（[Server] ≠ [server]）
|
||||
- Option 名：大小写不敏感（port = Port = PORT）
|
||||
- 值：原样返回，不做任何转换
|
||||
- 插值：禁用，%(key)s 原样返回
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 兼容性与迁移
|
||||
|
||||
### 9.1 零改动兼容
|
||||
|
||||
- **消费方零改动**：5 个 Python 服务继续用 `RpcClient("127.0.0.1", 8010, ...)` 调用，协议/端口/路由/响应格式全部不变。
|
||||
- **配置文件零迁移**：`confs2/configs/` 符号链接到 `../confs/configs/`，现有 9 个 .ini 文件不动。
|
||||
- **启动方式一致**：`init.txt` 中 `bash .../confs/_run.sh` 改为 `bash .../confs2/_run.sh`，一行改动。
|
||||
|
||||
### 9.2 迁移路径
|
||||
|
||||
```
|
||||
阶段 1: 编译 confs2 + 功能测试（confs2 与 confs 并存）
|
||||
↓
|
||||
阶段 2: 消费方回归测试（逐个服务切到 confs2 验证）
|
||||
↓
|
||||
阶段 3: init.txt 切换 confs → confs2（一行改动）
|
||||
↓
|
||||
阶段 4: 生产运行观察 72h，确认无异常
|
||||
↓
|
||||
阶段 5: Python confs 目录归档（不立即删除，保留回退能力）
|
||||
```
|
||||
|
||||
### 9.3 init.txt 切换
|
||||
|
||||
```
|
||||
# 切换前
|
||||
bash /opt/micro_servers/confs/_run.sh
|
||||
|
||||
# 切换后
|
||||
bash /opt/micro_servers/confs2/_run.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 未来扩展：core 注册中心联动
|
||||
|
||||
当 core 注册中心（[core_service_registry_dev_doc](core_service_registry_dev_doc.md)）落地后，confs2 可作为注册中心的第一个自注册服务：
|
||||
|
||||
```cpp
|
||||
// main() 启动后，RpcServer.start() 之前
|
||||
register_to_core("confs", g_config.port, "pymsg", "health",
|
||||
"bash /opt/micro_servers/confs2/_run.sh");
|
||||
```
|
||||
|
||||
进一步地，当未来评估 confs2 合入 core 时（方案 A: HTTP 合入），因 confs2 已是 C++ 同构，迁移成本仅为：
|
||||
1. 将 ConfigStore 代码移入 core 进程
|
||||
2. HTTP :5200 增加 `/confs/*` 路由
|
||||
3. 5 个消费方从 pymsg 改 HTTP（~50 行改动）
|
||||
|
||||
详见前序分析中的"confs2 合入 core 注册中心"可行性评估。
|
||||
|
||||
---
|
||||
|
||||
## 11. 附录
|
||||
|
||||
### A. 与已有 C++ 重写的模式对照
|
||||
|
||||
| 维度 | captcha2 | smtp3 | **confs2** |
|
||||
|------|----------|-------|-----------|
|
||||
| 原版语言 | Python | Python | Python |
|
||||
| 重写语言 | C++20 | C++20 | C++20 |
|
||||
| 协议 | pymsg(libmsg) | pymsg(libmsg) | pymsg(libmsg) |
|
||||
| 端口 | 8009 | 8008 | 8010 |
|
||||
| libmsg | ✅ RpcServer | ✅ RpcServer | ✅ RpcServer |
|
||||
| boost_json | ✅ | ✅ | ✅ |
|
||||
| LogC.hpp | ✅ 原创 | ✅ 改编 | ✅ 改编 |
|
||||
| Makefile 模式 | g++ -std=c++20 | g++ -std=c++20 | g++ -std=c++20 |
|
||||
| _run.sh 模式 | sleep 1 + exec .bin | sleep 1 + exec .bin | sleep 1 + exec .bin |
|
||||
| _set.sh 模式 | set -euo + make | set -euo + make | set -euo + make + ln -s |
|
||||
| 特殊依赖 | freetype, stb | openssl | 无（仅 libmsg + boost） |
|
||||
|
||||
### B. 配置文件目录现状
|
||||
|
||||
| 文件名 | 消费方 | 大小 |
|
||||
|--------|--------|------|
|
||||
| ca.ini | ca 模块 | 51 行 |
|
||||
| captcha.ini | captcha2 | 11 行 |
|
||||
| db.ini | db | 16 行 |
|
||||
| dnfs.ini | dnfs | 16 行 |
|
||||
| example.ini | 示例 | 10 行 |
|
||||
| gateway.ini | gateway | 20 行 |
|
||||
| redirect80.ini | redirect80 | 5 行 |
|
||||
| smtp.ini | smtp3 | 19 行 |
|
||||
| static.ini | static | 17 行 |
|
||||
|
||||
### C. libmsg RpcServer API 速查
|
||||
|
||||
```cpp
|
||||
// 构造
|
||||
pmc::net::RpcServer rpc("127.0.0.1", 8010,
|
||||
pmc::net::MsgServerConfig{.workers = 4},
|
||||
[](const std::string& route, const std::exception& e) {
|
||||
// on_error 回调
|
||||
});
|
||||
|
||||
// 注册路由
|
||||
rpc.add_route("get", [](const json::object& req) -> json::value {
|
||||
// handler 签名: json::value(const json::object& req)
|
||||
// 返回值自动包装为 {"success": true, "data": ...}
|
||||
// 抛异常自动包装为 {"success": false, "error": "<脱敏>"}
|
||||
return json::object{{"content", "..."}};
|
||||
});
|
||||
|
||||
// 启动（阻塞）
|
||||
rpc.start();
|
||||
|
||||
// 停止（另一线程）
|
||||
rpc.stop();
|
||||
```
|
||||
Reference in new issue
Block a user