docs(confs): update README for P1 fixes and clarify RpcClient usage
- Update title/description: pymsg RpcServer/TCP instead of plain pymsg/TCP
- Add new feature entries: cache copy return, list symlink guard, strict
param validation, ConfigParser interpolation=None, Slowloris protection
- Fix Python call examples: RpcClient.call() returns data directly, not
wrapped in {'success':..., 'data':...}; add RpcError try/except example
- Clarify reload semantics: empty string/non-string name returns error;
only omitted name or explicit null triggers full cache clear
- Add parameter validation rules for get (name/key type checks) and reload
- Document INI % literal behavior (interpolation disabled)
- Add '返回值隔离' to cache mechanism section
- Expand security mechanism table: cache anti-tamper, list symlink guard,
strict param validation, INI safe parsing
- Add docs/ directory and audit report reference to project structure
- Add notes about correct reload usage, INI % handling, and return copy
- Add audit report cross-reference in 注意事项
This commit is contained in:
qing committed
1 parent
2f3e63e499
commit
53ce69c8dd
1 file changed
+105
-63
+105
-63
@@ -1,6 +1,6 @@
|
||||
# confs 统一配置服务（pymsg/TCP）
|
||||
# confs 统一配置服务（pymsg RpcServer/TCP）
|
||||
|
||||
集中存放各微服务的配置文件，通过 pymsg 协议分发给内部服务，替代各服务本地散落的 ini/json/yaml 配置，实现配置的统一管理与下发。
|
||||
集中存放各微服务的配置文件，通过 pymsg RPC 协议分发给内部服务，替代各服务本地散落的 ini/json/yaml 配置，实现配置的统一管理与下发。
|
||||
|
||||
服务由 `core`（PMC）的 `init.txt` 拉起，监听 `127.0.0.1:8010`（TCP），仅允许本机调用。
|
||||
|
||||
@@ -11,13 +11,20 @@
|
||||
- **内存缓存 + 自动重载**：文件 mtime 变化时自动重新读取，无需重启服务
|
||||
- **按键取值**：ini/conf/cfg 支持 `Section.option` 取单键，json 支持点号路径（含数字下标）
|
||||
- **路径遍历防护**：basename 校验 + realpath 前缀校验 + 扩展名白名单
|
||||
- **TOCTOU 防护**：所有文件系统操作（realpath → stat → open）在锁内原子完成，防止符号链接替换竞态
|
||||
- **缓存防污染**：`get()` 返回缓存条目的浅拷贝，调用方修改返回值不会影响内部缓存
|
||||
- **list 符号链接防护**：列出配置时同样解析 realpath 校验前缀，逃逸符号链接不会泄露外部文件元信息
|
||||
- **严格参数校验**：`name`/`key` 参数必须为字符串，空字符串/空白字符串/非字符串类型明确返回错误，不会产生误行为
|
||||
- **INI 安全解析**：禁用 ConfigParser 的 `%(key)s` 插值功能，配置值中包含裸 `%` 字符不会触发解析错误
|
||||
- **文件大小限制**：单配置文件上限 1 MiB，防止超大文件导致 OOM
|
||||
- **线程安全**：所有公开方法持锁，保证 `workers>0` 并发回调下的缓存一致性
|
||||
- **仅监听本机**：默认 `127.0.0.1:8010`，不对外暴露
|
||||
- **Slowloris 防护**：pymsg MsgServer 默认设置 10 秒接收超时，慢速半开连接自动断开
|
||||
|
||||
## 技术栈
|
||||
|
||||
- Python 3
|
||||
- [pymsg](../pymsg/) —— TCP 长度前缀帧协议（`[4字节大端长度][UTF-8 JSON]`）
|
||||
- [pymsg](../pymsg/) —— TCP 长度前缀帧协议（`[4字节大端长度][UTF-8 JSON]`），上层提供 `RpcServer`/`RpcClient` 高层 JSON RPC 封装
|
||||
|
||||
## 安装
|
||||
|
||||
@@ -40,143 +47,168 @@ python3 confs.py --addr 127.0.0.1 --port 8010 --workers 4 --dir configs/
|
||||
|
||||
## 协议与路由
|
||||
|
||||
服务基于 pymsg 协议：每条消息为完整 JSON，`_route` 字段指定路由。响应格式与 db / smtp / captcha 一致：
|
||||
服务基于 pymsg RPC 协议：客户端使用 `RpcClient.call(route, payload)` 传 dict，无需手动拼 `_route` 或手动 JSON 序列化/反序列化。响应格式与 db / smtp / captcha 一致：
|
||||
|
||||
```json
|
||||
{"success": true, "data": {...}}
|
||||
{"success": false, "error": "..."}
|
||||
```
|
||||
|
||||
| _route | 说明 |
|
||||
| -------- | ------------------------------------------ |
|
||||
`RpcClient.call()` 成功时直接返回 `data` 字段的值（dict/str/None 等），失败时抛出 `RpcError`。
|
||||
|
||||
| 路由 | 说明 |
|
||||
| ------ | ------------------------------------------ |
|
||||
| `get` | 取配置文件全文；带 `key` 时返回单键值（仅 ini/json） |
|
||||
| `list` | 列出配置目录下全部配置文件及其元信息 |
|
||||
| `reload` | 重载指定配置；缺省 `name` 时清空全部缓存 |
|
||||
| `reload` | 重载指定配置；省略 `name`（或传 `null`）时清空全部缓存 |
|
||||
| `health` | 健康检查 |
|
||||
|
||||
### 1. get — 取配置
|
||||
|
||||
**请求**（取全文）：
|
||||
|
||||
```json
|
||||
{"_route": "get", "name": "example.ini"}
|
||||
```python
|
||||
c.call("get", {"name": "example.ini"})
|
||||
```
|
||||
|
||||
**响应**：
|
||||
**返回**（data 字段）：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"name": "example.ini",
|
||||
"content": "[Server]\naddress = 127.0.0.1\nport = 8010\n",
|
||||
"size": 45,
|
||||
"mtime": "2026-08-01T10:00:00+00:00"
|
||||
}
|
||||
"name": "example.ini",
|
||||
"content": "[server]\nhost = 127.0.0.1\nport = 8010\nratio = 80%\n",
|
||||
"size": 60,
|
||||
"mtime": "2026-08-01T10:00:00+00:00"
|
||||
}
|
||||
```
|
||||
|
||||
**请求**（按键取值，仅 ini/conf/cfg 与 json 支持）：
|
||||
|
||||
```json
|
||||
{"_route": "get", "name": "example.ini", "key": "Server.port"}
|
||||
```python
|
||||
c.call("get", {"name": "example.ini", "key": "server.port"})
|
||||
```
|
||||
|
||||
**响应**：
|
||||
**返回**：
|
||||
|
||||
```json
|
||||
{"success": true, "data": {"name": "example.ini", "key": "Server.port", "value": "8010"}}
|
||||
{"name": "example.ini", "key": "server.port", "value": "8010"}
|
||||
```
|
||||
|
||||
> - ini/conf/cfg：键格式为 `Section.option`，返回字符串值
|
||||
参数校验：
|
||||
- `name` 必填，必须为非空字符串；非字符串/空字符串返回 `ConfigError`
|
||||
- `key` 可选；若提供必须为非空字符串，非字符串/空字符串返回 `ConfigError`
|
||||
|
||||
> - ini/conf/cfg：键格式为 `Section.option`，返回字符串值；插值已禁用，`%` 字符原样返回
|
||||
> - json：键格式为点号路径（如 `server.port`），列表可用数字下标（如 `servers.0.host`），返回原始 JSON 值
|
||||
> - 其他类型（yaml/yml/toml/txt）不支持按键查询，需取全文后自行解析
|
||||
|
||||
### 2. list — 列出配置
|
||||
|
||||
**请求**：`{"_route": "list"}`
|
||||
**请求**：
|
||||
|
||||
**响应**：
|
||||
```python
|
||||
c.call("list", {})
|
||||
```
|
||||
|
||||
**返回**：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"config_dir": "/opt/micro_servers/confs/configs",
|
||||
"configs": [
|
||||
{"name": "example.ini", "size": 45, "mtime": "2026-08-01T10:00:00+00:00", "cached": true}
|
||||
]
|
||||
}
|
||||
"config_dir": "/opt/micro_servers/confs/configs",
|
||||
"configs": [
|
||||
{"name": "example.ini", "size": 60, "mtime": "2026-08-01T10:00:00+00:00", "cached": true}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
> 逃逸到 `configs/` 目录外的符号链接不会出现在列表中。
|
||||
|
||||
### 3. reload — 重载配置
|
||||
|
||||
**请求**（重载指定配置）：
|
||||
**重载指定配置**（立即重新读取文件）：
|
||||
|
||||
```json
|
||||
{"_route": "reload", "name": "example.ini"}
|
||||
```python
|
||||
c.call("reload", {"name": "example.ini"})
|
||||
```
|
||||
|
||||
**请求**（清空全部缓存，下次访问惰性重载）：
|
||||
**清空全部缓存**（下次访问惰性重载）：
|
||||
|
||||
```json
|
||||
{"_route": "reload"}
|
||||
```python
|
||||
c.call("reload", {}) # 省略 name 字段
|
||||
# 或
|
||||
c.call("reload", {"name": None})
|
||||
```
|
||||
|
||||
**响应**：
|
||||
**返回**：
|
||||
|
||||
```json
|
||||
{"success": true, "data": {"reloaded": ["example.ini"]}}
|
||||
{"reloaded": ["example.ini"]}
|
||||
```
|
||||
|
||||
> 指定 `name` 时立即重新读取并返回受影响列表；缺省时仅清空缓存（返回被清除的配置名列表），实际重载发生在下次访问。
|
||||
参数校验：
|
||||
- 省略 `name` 或 `name` 为 `null`：清空全部缓存，返回被清除的配置名列表
|
||||
- `name` 为非字符串（数字、布尔、列表等）：返回 `ConfigError("name 字段必须是字符串")`
|
||||
- `name` 为空字符串或纯空白：返回 `ConfigError("name 字段不能为空（要清空全部缓存请省略 name 字段）")`
|
||||
- 指定合法 `name`：立即重新读取该配置并返回受影响列表
|
||||
|
||||
### 4. health — 健康检查
|
||||
|
||||
**请求**：`{"_route": "health"}`
|
||||
**请求**：
|
||||
|
||||
**响应**：
|
||||
```python
|
||||
c.call("health", {})
|
||||
```
|
||||
|
||||
**返回**：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"status": "ok",
|
||||
"service": "confs",
|
||||
"config_dir": "/opt/micro_servers/confs/configs",
|
||||
"cached": 1,
|
||||
"uptime": 3600
|
||||
}
|
||||
"status": "ok",
|
||||
"service": "confs",
|
||||
"config_dir": "/opt/micro_servers/confs/configs",
|
||||
"cached": 1,
|
||||
"uptime": 3600
|
||||
}
|
||||
```
|
||||
|
||||
### 调用示例（Python）
|
||||
|
||||
```python
|
||||
from pymsg import RpcClient
|
||||
from pymsg import RpcClient, RpcError
|
||||
|
||||
c = RpcClient("127.0.0.1", 8010, "my-service")
|
||||
|
||||
# 取配置全文（dict 直接传入，RpcClient 自动序列化/反序列化）
|
||||
resp = c.call("get", {"name": "example.ini"}, timeout=5)
|
||||
content = resp["data"]["content"]
|
||||
try:
|
||||
# 取配置全文（c.call() 直接返回 data 字段，无需 resp["data"]）
|
||||
entry = c.call("get", {"name": "static.ini"}, timeout=5)
|
||||
content = entry["content"]
|
||||
print(f"static.ini size={entry['size']}")
|
||||
|
||||
# 按键取值
|
||||
resp = c.call("get", {"name": "example.ini", "key": "server.port"}, timeout=5)
|
||||
port = resp["data"]["value"]
|
||||
# 按键取值
|
||||
port = c.call("get", {"name": "static.ini", "key": "server.port"}, timeout=5)
|
||||
print(f"static server.port = {port}")
|
||||
|
||||
# 列出所有配置
|
||||
resp = c.call("list", {}, timeout=5)
|
||||
for cfg in resp["data"]["configs"]:
|
||||
print(cfg["name"], cfg["size"])
|
||||
# 列出所有配置
|
||||
lst = c.call("list", {}, timeout=5)
|
||||
for cfg in lst["configs"]:
|
||||
print(cfg["name"], cfg["size"])
|
||||
|
||||
# 重载指定配置
|
||||
c.call("reload", {"name": "static.ini"})
|
||||
|
||||
# 清空全部缓存
|
||||
c.call("reload", {})
|
||||
|
||||
except RpcError as e:
|
||||
print(f"confs 调用失败: {e}")
|
||||
```
|
||||
|
||||
## 缓存机制
|
||||
|
||||
- **内存缓存**：每个配置首次读取后缓存于 `ConfigStore._cache`，结构为 `{name: {content, mtime, size}}`
|
||||
- **自动重载**：每次 `get` 时比对文件 mtime，变化则重新读取并更新缓存
|
||||
- **自动重载**：每次 `get` 时在锁内比对文件 mtime（通过 `os.stat()`），变化则重新读取并更新缓存
|
||||
- **手动重载**：`reload` 路由可指定单个配置立即重读，或清空全部缓存（下次访问惰性重载）
|
||||
- **返回值隔离**：`get()` 返回缓存条目的**浅拷贝**，调用方对返回 dict 的修改不会污染内部缓存
|
||||
- **线程安全**：所有缓存操作持 `threading.Lock`，并发安全
|
||||
|
||||
## 安全机制
|
||||
@@ -186,13 +218,17 @@ for cfg in resp["data"]["configs"]:
|
||||
- **TOCTOU 防护**：所有文件系统操作（`realpath` → `stat` → `open`）均在持锁状态下原子完成，不存在"先校验后打开"的时间窗口，防止符号链接替换攻击
|
||||
- **文件大小限制**：单配置文件上限 1 MiB（`MAX_CONFIG_SIZE`），超过则拒绝读取并返回错误，防止超大文件导致内存溢出
|
||||
- **Slowloris 防护**：pymsg `MsgServer` 默认设置 10 秒接收超时，慢速发送的半开连接会被自动断开
|
||||
- **缓存防污染**：`get()` 返回浅拷贝，调用方无法通过修改返回值污染内部缓存
|
||||
- **list 符号链接防护**：列出配置时对每个文件做 realpath 前缀校验，逃逸到目录外的符号链接被跳过，不泄露外部文件元信息（大小/mtime）
|
||||
- **严格参数校验**：`name`/`key` 参数必须为非空字符串，类型错误或空值明确返回 `ConfigError`，不产生误行为（如空字符串误清空全部缓存）
|
||||
- **INI 安全解析**：使用 `ConfigParser(interpolation=None)` 禁用 `%(key)s` 插值，配置值中裸 `%` 字符不会触发 `InterpolationError`
|
||||
- **仅监听本机**：默认 `127.0.0.1`，不对外暴露，仅供内部服务调用
|
||||
- **无鉴权**：当前无身份校验，依赖"仅本机 + 内部网络"的信任边界；如需承载敏感配置（如 API 密钥），应额外评估鉴权方案
|
||||
|
||||
## 集成关系
|
||||
|
||||
- 由 `core`（`PMC`）通过 `init.txt` 中的 `bash /opt/micro_servers/confs/_run.sh` 拉起并守护（在 db 之后、ai_review 之前启动）
|
||||
- 各内部服务通过 pymsg 调 `get` 路由按需获取配置，替代本地散落的 ini/json/yaml
|
||||
- 各内部服务通过 pymsg `RpcClient` 调 `get` 路由按需获取配置，替代本地散落的 ini/json/yaml
|
||||
- 自身日志通过 `log_client.py` 异步推送至 `db:8005` 的 Logs 表（与其他服务一致）
|
||||
|
||||
### 已接入的服务
|
||||
@@ -218,6 +254,8 @@ confs/
|
||||
├── configs/ # 配置文件存放目录（被分发对象）
|
||||
│ ├── example.ini # 示例配置
|
||||
│ └── static.ini # static 服务配置（已接入分发）
|
||||
├── docs/
|
||||
│ └── SECURITY_AUDIT_20260801.md # 安全审计报告
|
||||
├── _set.sh # 初始化脚本（建 venv + 安装依赖）
|
||||
├── _run.sh # 启动脚本（venv 中 exec python3 confs.py）
|
||||
├── requirements.txt # Python 依赖（本地 ../pymsg + nuitka）
|
||||
@@ -231,4 +269,8 @@ confs/
|
||||
- 配置名区分大小写（与文件系统一致）
|
||||
- 单配置文件大小上限为 1 MiB（`MAX_CONFIG_SIZE`），超过此限制会返回 `配置文件过大` 错误，防止超大文件读入内存导致 OOM
|
||||
- 缓存基于文件 mtime 判断变化，若同秒内修改且 mtime 精度不足（如某些 FAT 文件系统），可能无法及时重载——可手动调 `reload` 路由强制刷新
|
||||
- `reload` 清空全部缓存的正确方式是**省略 `name` 字段**或传 `{"name": null}`；传空字符串 `""` 会返回错误而非清空缓存（防误操作）
|
||||
- INI 配置文件中 `%(xxx)s` 语法**不会**被当作插值引用，而是作为字面字符串返回；如需插值请在业务层自行处理
|
||||
- 调用方拿到 `get()` 返回的 dict 可以自由修改（如 `entry["content"] = "x"`），不会影响 confs 内部缓存
|
||||
- 当前接入情况见上文"集成关系 → 已接入的服务"；新服务接入可参考 static 的三层 fail-safe 模式（内置默认 → confs 优先 → 本地回退）
|
||||
- 安全审计报告详见 [docs/SECURITY_AUDIT_20260801.md](docs/SECURITY_AUDIT_20260801.md)
|
||||
Reference in new issue
Block a user