docs: 整理文档模块——归位散落文件、修复双扩展名、补全 INDEX 索引
- 移动 docs/ 根目录散落文件到 reports/（auth_service_plan、aibox_file_network_cli_refactor、blackbird_promo_full） - 修复 blackbird_research_report.md.md 双扩展名 → blackbird_research_report.md - INDEX.md 补全缺失条目：dnfs2/fsys/libsqlite3/libth 安全审计，blackbird_research_report、aibox_open_dev_plan 等报告，dnfs2/fsys/libmsg/libtry README - 更新目录树结构（security 25 篇、reviews 3 篇、reports 8 篇） - 修正模块描述（BotOps、lci 说明更准确） - 收录此前未跟踪的 actpred_CODE_AUDIT_20260808.md
This commit is contained in:
qing committed
1 parent
0af9019af8
commit
1e34348d6c
6 files changed
+335
-7
No files matched your search
@@ -0,0 +1,183 @@
|
||||
# aibox 文件操作与网络操作命令行化 开发计划
|
||||
|
||||
## 目标
|
||||
|
||||
将 aibox 中所有 Python 原生实现的文件操作和网络操作改为通过系统命令行工具实现，统一工具执行模式，减少 Python 依赖。
|
||||
|
||||
## 涉及模块
|
||||
|
||||
| 现有类 | 作用 | 替换方案 |
|
||||
|--------|------|----------|
|
||||
| `FileToolBase` | 文件工具基类 | 简化为命令行工具基类 |
|
||||
| `ReadFileTool` | 读文件 | `cat` / `head` / `tail` / `wc` |
|
||||
| `WriteFileTool` | 写文件 | `mkdir -p` + shell 重定向 |
|
||||
| `ListFilesTool` | 列目录 | `ls` / `find` / `du` |
|
||||
| `SimpleWebClient` | HTTP 客户端 | `curl` |
|
||||
| `WebPage` | 网页解析对象 | 移除，curl + grep/sed 替代 |
|
||||
| `SimpleWebCrawlerTool` | 网页爬虫工具 | `curl` + 文本处理管道 |
|
||||
|
||||
## 阶段一：文件操作命令行化
|
||||
|
||||
> **实现说明（已落地）**：阶段一采用「工具返回 markdown 提示词」的方式而非工具内部调子进程。`read_file` / `write_file` / `list_files` 三个工具的 `execute()` 不再执行 Python 文件 I/O，而是返回一段 markdown 提示词，指导智能体改用 `run_command` 工具执行对应的命令行命令（`head`/`tail`/`sed`/`wc`/`file`/`cut`/`cat`/`ls`/`du`/`find`）。工具接口（名称与参数）保持不变，安全限制（500 行、10KB/行、10MB 文件、路径 `shlex.quote` 转义）在提示词中注明。
|
||||
|
||||
### 1.1 ReadFileTool 重构
|
||||
|
||||
用以下命令行工具替代 Python 文件 I/O：
|
||||
|
||||
| 原功能 | 命令行实现 |
|
||||
|--------|-----------|
|
||||
| `head=True` 读取开头 N 行 | `head -n N` |
|
||||
| `tail=True` 读取末尾 N 行 | `tail -n N` |
|
||||
| 指定行范围 `start_line ~ end_line` | `sed -n 'start,endp'` |
|
||||
| 统计行数 `_count_lines` | `wc -l` |
|
||||
| 文件编码检测 | `file -b --mime-encoding` |
|
||||
| 单行超长截断 | `cut -c 1-10000` |
|
||||
|
||||
保留的安全限制：
|
||||
- 文件大小限制 `MAX_FILE_SIZE`：通过 `wc -c` 或 `stat -f%z` 检查
|
||||
- 行数上限 500 行：`head -n 500` 作为最后一道防线
|
||||
- 单行 10KB 限制：`cut -c 1-10000`
|
||||
|
||||
### 1.2 WriteFileTool 重构
|
||||
|
||||
| 原功能 | 命令行实现 |
|
||||
|--------|-----------|
|
||||
| 创建目录 | `mkdir -p` |
|
||||
| 覆盖写入 `mode=w` | `content > filepath` |
|
||||
| 追加写入 `mode=a` | `content >> filepath` |
|
||||
| 检查文件大小 | `wc -c` 或 `stat -f%z` |
|
||||
| 路径安全检查 | `realpath` / `test -f` |
|
||||
|
||||
### 1.3 ListFilesTool 重构
|
||||
|
||||
| 原功能 | 命令行实现 |
|
||||
|--------|-----------|
|
||||
| 列出目录内容 | `ls -la` 或 `find . -maxdepth 1` |
|
||||
| 隐藏文件过滤 | `ls -la` 默认不显示 `.` 开头的隐藏文件（或 `find` 排除） |
|
||||
| 文件大小统计 | `du -sh *` 或 `ls -lh` |
|
||||
| 目录/文件区分 | `ls -F` 或 `find -type f/d` |
|
||||
|
||||
### 1.4 FileToolBase 简化
|
||||
|
||||
移除 `normalize_path()`、`check_path_safety()` 中 Python `os` 模块调用，改为：
|
||||
- 路径规范化：`realpath`
|
||||
- 文件存在性检查：`test -f` / `test -d`
|
||||
- 文件大小检查：`wc -c` 或 `stat`
|
||||
|
||||
### 1.5 安全边界保留
|
||||
|
||||
- `MAX_FILE_SIZE`（默认 10MB）：通过命令检查
|
||||
- 行数上限 500 行：`head -n 500` 兜底
|
||||
- 单行长度上限 10KB：`cut -c 1-10000` 兜底
|
||||
- 所有路径参数 `shlex.quote()` 转义
|
||||
|
||||
## 阶段二：网络操作命令行化
|
||||
|
||||
> **实现说明（已落地）**：阶段二沿用阶段一的方式，`web` 工具（`SimpleWebCrawlerTool`）的 `execute()` 不再使用 `requests`/`BeautifulSoup`，而是返回 markdown 提示词，指导智能体改用 `run_command` 执行 `curl` 命令完成各 action（`get`/`text`/`title`/`links`/`search`）。`WebPage`、`SimpleWebClient` 类已删除；`urljoin`/`urlparse`/`BeautifulSoup` 导入已清理。代理通过 `get_proxy()` 读取配置并拼出 `--socks5` 参数。注意 `requests` 仍在 `aibox.py` 其他位置（API 调用、DeepSeek 请求）使用，故保留其依赖。
|
||||
|
||||
### 2.1 SimpleWebClient → curl
|
||||
|
||||
| 原功能 | 命令行实现 |
|
||||
|--------|-----------|
|
||||
| HTTP GET 请求 | `curl -sL --max-time N` |
|
||||
| 自定义 User-Agent | `curl -A "..."` |
|
||||
| SOCKS5 代理 | `curl --socks5 host:port` 或环境变量 `ALL_PROXY` |
|
||||
| 请求间隔控制 | `SubprocessCommandExecutor` 层面控制 |
|
||||
| 响应状态码 | `curl -sL -o /dev/null -w '%{http_code}'` |
|
||||
| 下载大小限制 | `curl --max-filesize N` 或管道 `head -c N` |
|
||||
|
||||
### 2.2 WebPage 移除
|
||||
|
||||
`WebPage` 类不再需要，其功能由命令行管道实现：
|
||||
|
||||
| 原属性/方法 | 命令行实现 |
|
||||
|------------|-----------|
|
||||
| `title` | `curl -sL | grep -oP '<title>\K[^<]+'` |
|
||||
| `text` | `curl -sL | lynx -dump -stdin` 或 `html2text` |
|
||||
| `links` | `curl -sL | grep -oP 'href="[^"]*"'` |
|
||||
| `status_code` | `curl -sL -o /dev/null -w '%{http_code}'` |
|
||||
| `headers` | `curl -sL -I` |
|
||||
|
||||
### 2.3 SimpleWebCrawlerTool 重构
|
||||
|
||||
| action | 命令行实现 |
|
||||
|--------|-----------|
|
||||
| `get` | `curl -sL` 获取完整页面信息 |
|
||||
| `text` | `curl -sL | lynx -dump -stdin` 或 `html2text` |
|
||||
| `title` | `curl -sL | grep -oP '<title>\K[^<]+'` |
|
||||
| `links` | `curl -sL | grep -oP 'href="[^"]*"'` |
|
||||
| `search` | `curl -sL | grep -c 'keyword'` 或 `grep -q` |
|
||||
|
||||
### 2.4 下载大小限制
|
||||
|
||||
- 响应体：`curl --max-filesize` 或 `curl | head -c 100M` 管道限制
|
||||
- 配置项 `web.max_download_size`（默认 100MB）
|
||||
|
||||
## 阶段三：清理与收尾
|
||||
|
||||
> **实现说明（已落地）**：
|
||||
> - 3.1 `requirements.txt` 已移除 `beautifulsoup4`；**`requests` 保留**（仍在 `aibox.py` 的 DeepSeek API 调用 `ConversationCompressor` 与 `DeepSeekChat` 中使用，属核心功能，无法移除）。
|
||||
> - 3.2 已统一：文件/网页工具改为返回 markdown 提示词，实际 I/O 全部委托给 `run_command`（`SubprocessCommandExecutor`），天然复用其 1MB 输出上限、超时与中断取消。
|
||||
> - 3.3 中断支持已随 `SubprocessCommandExecutor.cancel()` 覆盖。
|
||||
> - 3.4 默认提示词 `3_file_operations.md`、`4_web_access.md` 已更新为命令行走指导（`head`/`sed`/`cat`/`ls`/`curl` 等）。
|
||||
> - 3.5 `README.md` 工具表与安全说明已更新。
|
||||
|
||||
### 3.1 移除 Python 依赖
|
||||
|
||||
从 `requirements.txt` 删除：
|
||||
|
||||
```diff
|
||||
- requests
|
||||
- beautifulsoup4
|
||||
```
|
||||
|
||||
### 3.2 统一使用 SubprocessCommandExecutor
|
||||
|
||||
所有新工具统一通过 `SubprocessCommandExecutor` 执行命令，与 `CommandLineTool` 保持一致：
|
||||
- 输出上限 1MB（超出自动终止进程并截断）
|
||||
- 超时控制
|
||||
- 中断取消（`cancel()` → `process.kill()`）
|
||||
|
||||
### 3.3 中断支持
|
||||
|
||||
- 利用已有的 `SubprocessCommandExecutor.cancel()` 机制
|
||||
- 确保 Ctrl+C 可终止长时间运行的 curl 下载或文件操作
|
||||
|
||||
### 3.4 更新提示词
|
||||
|
||||
`~/.aibox/prompts/` 中相关文件更新：
|
||||
|
||||
| 文件 | 更新内容 |
|
||||
|------|---------|
|
||||
| `3_file_operations.md` | 文件操作描述改为命令行方式 |
|
||||
| `4_web_access.md` | 网络访问描述改为 curl 方式 |
|
||||
|
||||
### 3.5 更新文档
|
||||
|
||||
- `SKILLS_FORMAT.md`：技能开发示例中文件/网络操作更新
|
||||
- `README.md`：更新依赖说明和架构图
|
||||
|
||||
## 不做的事
|
||||
|
||||
- **不改变工具接口**：`read_file`、`write_file`、`list_files`、`web` 四个工具名称和参数签名保持不变
|
||||
- **不改变 `CommandLineTool`（`run_command`）**：已有的命令执行工具不动
|
||||
- **不改变 `SubprocessCommandExecutor`**：已有安全限制（1MB 输出）保持不变
|
||||
- **不改变记忆/备忘录数据库**：`MemoryDatabase`、`MemoDatabase` 的 SQLite 操作保留
|
||||
|
||||
## 收益
|
||||
|
||||
- **减少依赖**：移除 `requests`、`beautifulsoup4` 两个 Python 库，降低供应链风险
|
||||
- **统一执行模式**：所有外部操作（文件、网络、命令）全部走 `SubprocessCommandExecutor`，统一超时控制、输出限制、中断取消
|
||||
- **更强的可审计性**：AI 操作日志中能看到完整的 `curl` / `cat` / `ls` 命令，更透明
|
||||
- **复用已有基础设施**：`CommandLineTool` 已有的安全防护直接复用
|
||||
|
||||
## 风险与注意事项
|
||||
|
||||
| 风险 | 缓解措施 |
|
||||
|------|----------|
|
||||
| `curl` 不存在 | 启动时检测 `curl` 可用性，缺失时尝试 `wget` 降级或报错 |
|
||||
| 跨平台 `sed`/`grep` 差异 | macOS (BSD) 和 Linux (GNU) 行为差异；使用 POSIX 兼容写法，必要时运行时检测 |
|
||||
| 网页解析精度下降 | `grep` 正则提取 HTML 不可靠；优先用 `lynx -dump` 或 `html2text` 替代 BeautifulSoup 解析 |
|
||||
| 命令注入风险 | 所有用户输入参数必须经过 `shlex.quote()` 转义 |
|
||||
| Proxy 配置 | `curl` 通过 `--socks5` 或 `ALL_PROXY` 环境变量传递，与现有 `set_proxy` 工具集成 |
|
||||
| 性能影响 | 文件操作每步 fork 新进程，但 aibox 不是高吞吐服务，IO 瓶颈远大于进程开销 |
|
||||
@@ -0,0 +1,373 @@
|
||||
# 权限系统独立化计划书
|
||||
|
||||
## 一、现状分析
|
||||
|
||||
### 1.1 当前架构
|
||||
|
||||
```
|
||||
客户端 ──HTTPS──▶ WAF:443 ──HTTP──▶ gateway:8443 ──HTTP──▶ 下游服务
|
||||
( auth + proxy + captcha + rate-limit + ws-proxy )
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
▼ ▼ ▼
|
||||
db:8005 captcha:8009 smtp:8008
|
||||
(Users表) (图形验证码) (邮件发送)
|
||||
|
||||
下游鉴权调用链:
|
||||
core:5200 ──HTTP POST──▶ gateway:/admin/verify (管理员验签)
|
||||
dnfs2:8006 ──HTTP POST──▶ gateway:/whoami (Token 验签)
|
||||
```
|
||||
|
||||
### 1.2 Gateway 职责清单（main.cpp 2508 行，单文件）
|
||||
|
||||
| 职责域 | 函数/组件 | 行数占比 |
|
||||
|--------|-----------|---------|
|
||||
| **用户认证** | handleLogin, handleRegister, handleLogout, handleResetPassword, handleSendEmailCode, handleResetSendCode, PBKDF2Hasher, PasswordValidator | ~40% |
|
||||
| **Token 管理** | verify_token, generate_jti, revoke_jti, revoke_all_user_tokens, handleRefreshToken, handleWhoami, handleAdminVerify, TokenInfo, JtiDenylist, UserVerMap | ~25% |
|
||||
| **CAPTCHA** | handleCaptcha, handleCaptchaImage, CaptchaEntry, generate_captcha_text, verify_captcha | ~8% |
|
||||
| **速率限制** | 8 个 RateLimiter 实例（login/register/email/refresh/reset 等） | ~5% |
|
||||
| **HTTP 反向代理** | handleProxy, is_special_header, is_safe_target | ~12% |
|
||||
| **WebSocket 代理** | verifyWsAdminToken, ws_proxy 路由注册 | ~5% |
|
||||
| **配置/基础设施** | main(), registerRoutes(), ConfIni, DbC, LogC, 信号处理 | ~5% |
|
||||
|
||||
### 1.3 核心问题
|
||||
|
||||
1. **职责严重耦合**：auth（~65%代码量）与 proxy（~17%）捆绑在同一进程，任一域的重构/扩展都影响全局
|
||||
2. **不可独立扩展**：认证密集型场景（批量登录/注册）和代理密集型场景（大文件传输）无法分别扩容
|
||||
3. **安全隔离缺失**：密码哈希、RSA 私钥、Token 黑名单等敏感数据与代理逻辑共存于同一进程内存空间
|
||||
4. **下游耦合 gateway**：core/dnfs2 通过 HTTP 回调 gateway 做验签，gateway 既是流量入口又是认证权威，形成环形依赖
|
||||
5. **单文件维护瓶颈**：2508 行 C++ 单文件，所有功能交叉耦合，测试和 code review 成本高
|
||||
6. **Token 状态纯内存**：jti 黑名单和版本号在 gateway 重启后丢失（虽然 RSA 密钥同步重建可兜底，但限制了多实例部署）
|
||||
|
||||
---
|
||||
|
||||
## 二、目标架构
|
||||
|
||||
```
|
||||
客户端 ──HTTPS──▶ WAF:443 ──HTTP──▶ gateway:8443 ──HTTP──▶ 下游服务
|
||||
( 纯反向代理 + Token 透传 )
|
||||
│
|
||||
▼
|
||||
auth:8444 (独立权限服务)
|
||||
┌────┼────┐
|
||||
▼ ▼ ▼
|
||||
db:8005 captcha smtp
|
||||
|
||||
下游鉴权调用链（改造后）:
|
||||
core:5200 ──pymsg──▶ auth:8444:/verify (管理员验签)
|
||||
dnfs2:8006 ──pymsg──▶ auth:8444:/whoami (Token 验签)
|
||||
gateway ──pymsg──▶ auth:8444:/verify (代理转发前的 Token 校验)
|
||||
```
|
||||
|
||||
### 2.1 职责划分
|
||||
|
||||
| 模块 | 改造后职责 |
|
||||
|------|-----------|
|
||||
| **auth（新）** | 用户注册/登录/注销、Token 签发/验签/刷新/吊销、CAPTCHA、密码重置、邮箱验证码、速率限制、管理员验证 |
|
||||
| **gateway（精简）** | HTTP/WebSocket 反向代理、Target-Url 白名单过滤、XFF 注入、CORS 预检；认证路由（/login, /register 等）作为代理目标指向 auth |
|
||||
| **core / dnfs2** | 验签调用目标由 gateway 改为 auth（pymsg 协议，消除 HTTP 回调） |
|
||||
|
||||
---
|
||||
|
||||
## 三、实施阶段
|
||||
|
||||
### 阶段一：auth 服务搭建（核心剥离）
|
||||
|
||||
**目标**：将认证逻辑整体迁入独立 C++ 服务
|
||||
|
||||
**新建目录结构**：
|
||||
```
|
||||
auth/
|
||||
├── src/
|
||||
│ └── main.cpp # 入口 + 路由注册
|
||||
├── inc/
|
||||
│ ├── AuthService.hpp # 核心认证逻辑（PBKDF2、Token 签发/验签/吊销）
|
||||
│ ├── RateLimiter.hpp # 速率限制器（从 gateway 迁移）
|
||||
│ ├── CaptchaService.hpp # CAPTCHA 生成/验证
|
||||
│ ├── DbC.hpp # 复用 gateway 的 DbC（提取为公共库或复制）
|
||||
│ ├── LogC.hpp # 复用 LogC
|
||||
│ ├── Conf.hpp # 复用 ConfIni
|
||||
│ ├── LocalTime.hpp # 复用
|
||||
│ └── ExpBase.hpp # 复用
|
||||
├── Makefile
|
||||
├── _run.sh
|
||||
├── _set.sh
|
||||
└── README.md
|
||||
```
|
||||
|
||||
**迁移清单**（从 gateway/src/main.cpp 提取）：
|
||||
|
||||
| 组件 | 源位置 | 目标文件 |
|
||||
|------|--------|---------|
|
||||
| PBKDF2Hasher | main.cpp L62-85 | AuthService.hpp |
|
||||
| PasswordValidator | main.cpp L87-160 | AuthService.hpp |
|
||||
| TokenInfo / generate_jti / verify_token / revoke_* | main.cpp L340-760 | AuthService.hpp |
|
||||
| handleLogin | main.cpp L1346-1525 | main.cpp (auth) |
|
||||
| handleRegister | main.cpp L1891-1981 | main.cpp (auth) |
|
||||
| handleLogout | main.cpp L1527-1554 | main.cpp (auth) |
|
||||
| handleWhoami | main.cpp L1556-1606 | main.cpp (auth) |
|
||||
| handleAdminVerify | main.cpp L1608-1657 | main.cpp (auth) |
|
||||
| handleRefreshToken | main.cpp L1672-1837 | main.cpp (auth) |
|
||||
| handleSendEmailCode | main.cpp ~L1983-2080 | main.cpp (auth) |
|
||||
| handleResetSendCode | main.cpp ~L2080-2170 | main.cpp (auth) |
|
||||
| handleResetPassword | main.cpp ~L2170-2308 | main.cpp (auth) |
|
||||
| handleCaptcha / handleCaptchaImage | main.cpp ~L1158,1845-1890 | CaptchaService.hpp |
|
||||
| RateLimiter 实例（8 个） | main.cpp L417-427 | RateLimiter.hpp |
|
||||
| CAPTCHA_STORE | main.cpp L438-499 | CaptchaService.hpp |
|
||||
| JTI_DENYLIST / USER_VER_MAP | main.cpp L447-465 | AuthService.hpp |
|
||||
|
||||
**新增配置**（`confs/configs/auth.ini`）：
|
||||
```ini
|
||||
[Server]
|
||||
address = 127.0.0.1
|
||||
port = 8444
|
||||
|
||||
[Token]
|
||||
keep_time = 3600
|
||||
refresh_grace_multiplier = 2
|
||||
max_refresh = 10
|
||||
|
||||
[Admin]
|
||||
users = 1776177662@qq.com;277665039@qq.com;
|
||||
|
||||
[Downstream]
|
||||
db_host = 127.0.0.1
|
||||
db_port = 8005
|
||||
captcha_host = 127.0.0.1
|
||||
captcha_port = 8009
|
||||
smtp_host = 127.0.0.1
|
||||
smtp_port = 8008
|
||||
```
|
||||
|
||||
**对外接口**（pymsg TCP 协议 + HTTP 双栈）：
|
||||
|
||||
| 路由 | 协议 | 说明 |
|
||||
|------|------|------|
|
||||
| POST /login | HTTP | 登录（兼容前端直访） |
|
||||
| POST /register | HTTP | 注册 |
|
||||
| POST /logout | HTTP | 注销 |
|
||||
| POST /refresh_token | HTTP | Token 刷新 |
|
||||
| POST /whoami | HTTP | 身份查询 |
|
||||
| POST /register/send_code | HTTP | 发送注册验证码 |
|
||||
| POST /reset/send_code | HTTP | 发送重置验证码 |
|
||||
| POST /reset_password | HTTP | 重置密码 |
|
||||
| POST /captcha | HTTP | 生成验证码 |
|
||||
| GET /captcha/image | HTTP | 验证码图片代理 |
|
||||
| verify | pymsg | 内部验签（替代 /admin/verify，供 core/dnfs2/gateway 调用） |
|
||||
| whoami | pymsg | 内部身份查询（供 dnfs2 调用） |
|
||||
|
||||
### 阶段二：gateway 瘦身
|
||||
|
||||
**目标**：gateway 仅保留反向代理 + WebSocket 代理
|
||||
|
||||
**保留内容**：
|
||||
- `handleProxy`（HTTP 反代 + Token 透传）
|
||||
- WebSocket 代理路由注册 + `verifyWsAdminToken`（改为调 auth 的 pymsg verify 接口）
|
||||
- `is_special_header` / `is_safe_target` / `get_cookie_value`
|
||||
- 配置加载、信号处理、LogC
|
||||
|
||||
**删除内容**：
|
||||
- 所有 auth handler（handleLogin ~ handleResetPassword）
|
||||
- PBKDF2Hasher / PasswordValidator / TokenInfo / JTI_DENYLIST / USER_VER_MAP
|
||||
- CAPTCHA 相关代码
|
||||
- 8 个 RateLimiter 实例（迁移到 auth，auth 路由不再经过 gateway 限流）
|
||||
- RSA 密钥对生成（`_KEYGEN`，迁移到 auth）
|
||||
|
||||
**gateway.ini 精简**：
|
||||
```ini
|
||||
[Server]
|
||||
address = 127.0.0.1
|
||||
port = 8443
|
||||
tls = off
|
||||
|
||||
[Proxy]
|
||||
default = http://127.0.0.1:9200
|
||||
opened = http://127.0.0.1:9200;http://127.0.0.1:8006;http://127.0.0.1:5200;
|
||||
|
||||
[Auth]
|
||||
host = 127.0.0.1
|
||||
port = 8444
|
||||
|
||||
[WsProxy]
|
||||
routes = /ws/aibox=ws://127.0.0.1:8765;
|
||||
|
||||
[CORS]
|
||||
allowed_origins = https://qsont.me;https://www.qsont.me
|
||||
```
|
||||
|
||||
**认证路由处理方案**（二选一）：
|
||||
|
||||
- **方案 A（推荐）：gateway 代理认证路由**
|
||||
- gateway 将 `/login`、`/register` 等路径加入代理白名单，Target-Url 自动指向 auth 服务
|
||||
- 前端请求路径不变：`POST /login` → WAF → gateway → auth
|
||||
- 优势：前端零改动，gateway 仍是唯一入口
|
||||
|
||||
- **方案 B：auth 直暴露**
|
||||
- WAF 配置分流规则，认证路径直接转发到 auth:8444
|
||||
- 需改动 WAF 配置，增加路由复杂度
|
||||
|
||||
### 阶段三：下游服务适配
|
||||
|
||||
**目标**：core 和 dnfs2 的验签调用目标从 gateway 切换为 auth
|
||||
|
||||
#### 3.1 core 适配
|
||||
|
||||
**当前**（`core/src/main/HttpTask.cpp` L155-204）：
|
||||
```cpp
|
||||
// HTTP POST → gateway:8443/admin/verify
|
||||
std::string url = "http://" + host + ":" + std::to_string(port) + "/admin/verify";
|
||||
pmc::net::HttpClient client;
|
||||
client.set_header("Authorization: " + raw);
|
||||
client.post_stream_sync(url, "", ...);
|
||||
```
|
||||
|
||||
**改造后**：
|
||||
```cpp
|
||||
// pymsg → auth:8444 verify 路由（消除 HTTP 回调，统一内部协议）
|
||||
pmc::net::MsgClient client(auth_host, auth_port, "core");
|
||||
json::value req = {{"_route", "verify"}, {"token", raw_token}};
|
||||
std::string resp = client.call(json::serialize(req), 5.0);
|
||||
```
|
||||
|
||||
#### 3.2 dnfs2 适配
|
||||
|
||||
**当前**（`dnfs2/src/dnfs2.cpp` L446-495）：
|
||||
```cpp
|
||||
// HTTP POST → gateway:8443/whoami
|
||||
http.post_stream_sync(_cfg.gateway_url, "{}", ...);
|
||||
```
|
||||
|
||||
**改造后**：
|
||||
```cpp
|
||||
// pymsg → auth:8444 whoami 路由
|
||||
RpcClient auth_client(_cfg.auth_host, _cfg.auth_port, "dnfs2", timeout);
|
||||
json::value result = auth_client.call("whoami", {{"token", token}});
|
||||
```
|
||||
|
||||
**配置文件变更**（`confs/configs/dnfs.ini`）：
|
||||
```ini
|
||||
[auth] # 新增，替代 [gateway]
|
||||
host = 127.0.0.1
|
||||
port = 8444
|
||||
timeout = 5
|
||||
```
|
||||
|
||||
### 阶段四：启动编排与部署
|
||||
|
||||
**core/init.txt 更新**：
|
||||
```
|
||||
bash /opt/micro_servers/db2/_run.sh
|
||||
bash /opt/micro_servers/confs/_run.sh
|
||||
bash /opt/micro_servers/auth/_run.sh # 新增，须在 gateway 之前启动
|
||||
bash /opt/micro_servers/ai_review/_run.sh
|
||||
bash /opt/micro_servers/dnfs2/_run.sh
|
||||
bash /opt/micro_servers/smtp/_run.sh
|
||||
bash /opt/micro_servers/static/_run.sh
|
||||
bash /opt/micro_servers/waf/_run.sh
|
||||
bash /opt/micro_servers/gateway/_run.sh
|
||||
bash /opt/micro_servers/captcha/_run.sh
|
||||
bash /opt/micro_servers/aibox/_run.sh
|
||||
bash /opt/micro_servers/redirect80/_run.sh
|
||||
```
|
||||
|
||||
**docker-compose.yml 新增 auth 服务**：
|
||||
```yaml
|
||||
auth:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: auth/Dockerfile
|
||||
container_name: micro-auth
|
||||
ports:
|
||||
- "127.0.0.1:8444:8444"
|
||||
environment:
|
||||
- LISTEN_ADDR=0.0.0.0
|
||||
- LISTEN_PORT=8444
|
||||
- DB_HOST=db
|
||||
- DB_PORT=8005
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、接口契约设计
|
||||
|
||||
### 4.1 auth 内部 pymsg 接口（供其他微服务调用）
|
||||
|
||||
#### verify 路由（替代 /admin/verify）
|
||||
```json
|
||||
// 请求
|
||||
{"_route": "verify", "token": "base64payload_signature", "require_admin": true}
|
||||
|
||||
// 响应（成功）
|
||||
{"success": true, "user": "admin@example.com", "is_admin": true}
|
||||
|
||||
// 响应（失败）
|
||||
{"success": false, "error": "token expired"}
|
||||
```
|
||||
|
||||
#### whoami 路由（替代 /whoami）
|
||||
```json
|
||||
// 请求
|
||||
{"_route": "whoami", "token": "base64payload_signature"}
|
||||
|
||||
// 响应（已登录）
|
||||
{"success": true, "login": true, "user": "user@example.com", "is_admin": false}
|
||||
|
||||
// 响应（未登录/Token 无效）
|
||||
{"success": true, "login": false}
|
||||
```
|
||||
|
||||
### 4.2 Token 格式不变
|
||||
|
||||
保持现有 `Base64(payload)_RSA-Sign(payload)` 格式，payload 字段不变：
|
||||
```json
|
||||
{
|
||||
"user": "email@example.com",
|
||||
"jti": "random_hex_32",
|
||||
"ver": 1,
|
||||
"iat": "2026-08-08 12:00:00",
|
||||
"created_at": "2026-08-08 12:00:00",
|
||||
"keep_time": 3600,
|
||||
"is_admin": true,
|
||||
"refresh_count": 0,
|
||||
"max_refresh": 10
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、风险评估与缓解
|
||||
|
||||
| 风险 | 影响 | 缓解措施 |
|
||||
|------|------|---------|
|
||||
| auth 服务不可用导致全系统鉴权失败 | 高 | auth 的 pymsg 客户端启用 `retry_on_refused`；gateway 对 auth 路由的代理失败返回 503（而非静默放行） |
|
||||
| 前端请求路径变化 | 中 | 采用方案 A（gateway 代理认证路由），前端零改动 |
|
||||
| Token 验签增加一跳网络延迟 | 低 | pymsg TCP 本机通信延迟 <1ms；gateway 代理层可增加 Token 缓存（TTL 60s） |
|
||||
| RSA 密钥迁移 | 中 | auth 启动时自生成密钥对（与当前 gateway 行为一致）；过渡期可共享密钥文件 |
|
||||
| 过渡期双系统并存 | 中 | 分阶段切换：先 auth 上线 → gateway 认证路由代理到 auth → 删除 gateway 内置 auth 代码 |
|
||||
| Token 黑名单持久化需求 | 低 | 初期保持纯内存方案（与现状一致）；后续可选 Redis 持久化 |
|
||||
|
||||
---
|
||||
|
||||
## 六、时间估算
|
||||
|
||||
| 阶段 | 工作量 | 说明 |
|
||||
|------|--------|------|
|
||||
| 阶段一：auth 服务搭建 | 2-3 天 | 代码迁移 + 新配置 + 测试 |
|
||||
| 阶段二：gateway 瘦身 | 1 天 | 删除代码 + 代理路由配置 + 回归测试 |
|
||||
| 阶段三：下游适配 | 1 天 | core/dnfs2 验签调用改造 + 集成测试 |
|
||||
| 阶段四：部署编排 | 0.5 天 | init.txt + docker-compose + 端到端测试 |
|
||||
| **合计** | **4.5-5.5 天** | 含测试缓冲 |
|
||||
|
||||
---
|
||||
|
||||
## 七、验收标准
|
||||
|
||||
1. auth 服务独立启动，通过 pymsg 和 HTTP 双栈提供全部认证接口
|
||||
2. gateway 代码量从 ~2500 行降至 ~800 行，仅含代理逻辑
|
||||
3. 前端所有认证操作（登录/注册/注销/刷新/重置密码）路径不变、行为不变
|
||||
4. core/dnfs2 通过 pymsg 调用 auth 验签，延迟 ≤ 5ms（本机）
|
||||
5. auth 服务重启不影响 gateway 代理转发（已认证请求在 Token 过期前仍有效）
|
||||
6. 所有现有安全特性（PBKDF2、RSA 签名、常数时间比较、jti 黑名单、版本号吊销）完整保留
|
||||
@@ -0,0 +1,139 @@
|
||||
# blackbird 项目「完整版」宣传文案
|
||||
|
||||
> 本文档为 blackbird（UniServe Framework / micro_servers）项目创作的**完整版**宣传文案，基于项目 Git 仓库调研结论提炼与合理延展，未虚构任何调研范围外的能力或数据。
|
||||
|
||||
---
|
||||
|
||||
## 一、项目定位 + 品牌一句话
|
||||
|
||||
**定位句**：blackbird 是一套 DIY 的轻量级微服务架构，由 C++20、Python、Go 与仓颉（Cangjie）混合实现，主打进程托管式微服务的轻量、自主可控与安全落地。
|
||||
|
||||
**品牌一句话（Slogan）**：**轻量微服务，自主可控更安全。**
|
||||
|
||||
**理念 / 愿景**：把微服务的控制权交还给开发者自己——不必被云原生的重基建绑架，用最少的依赖，跑起一套属于你自己的、安全可信的服务集群。
|
||||
|
||||
---
|
||||
|
||||
## 二、品牌故事 / 背景
|
||||
|
||||
我们见过太多团队想拥有自己的服务集群，却被 Kubernetes、服务注册发现、消息总线这一整套云原生重基建劝退。容器编排很强大，但代价是复杂度、学习成本与对外部平台的深度绑定。
|
||||
|
||||
blackbird 想回答一个更朴素的问题：如果我只想要"几个常驻进程、一套鉴权、一道防火墙、一份集中日志"，能不能用最轻的方式自己搞定？于是有了这套进程托管式的微服务框架——一个核心进程读着 `init.txt` 就把业务子进程都拉起来并守护好，模块各司其职、各司其语言。
|
||||
|
||||
从边缘私有化部署到自托管社区，从 AI 内容审核到机器人硬件联动，blackbird 把"自建可控"这件事压到了一条安装脚本的重量级。它不追求成为另一个云原生怪兽，而是成为你手里那把趁手的、可信的轻刀。
|
||||
|
||||
---
|
||||
|
||||
## 三、核心架构概览
|
||||
|
||||
blackbird 以 **`core` 进程托管核心**（C++20）为基石：它读取 `init.txt`，拉起并守护所有业务子进程，对外提供 `:5200` 的 HTTP 管理接口，并以 `Nidus.service` 身份常驻于 systemd。所有模块以独立进程形态运行，由 core 统一托管、统一看门。
|
||||
|
||||
**请求链路（8 步）**：
|
||||
客户端 → `redirect80:80`（HTTP→HTTPS 301/308 重定向）→ `waf:443`（HTTPS 终止 + coraza WAF 防护）→ `gateway:8443`（统一鉴权 + 反向代理白名单）→ `static:9200` / `dnfs:8006`（前端托管 / 树状菜单节点 CRUD）。其中 `db:8005` 与 `ai_review:8007` 仅内部调用；`dnfs` 在新增节点前会先调用 `ai_review` 完成内容审核，审核不通过则拒绝写入。
|
||||
|
||||
**旁路链路**：
|
||||
- **日志链路**：各业务服务经 `log_client` 将日志推送至 `db` 的 Logs 表，并支持自动清理，实现集中式日志收集。
|
||||
- **配置链路**：`confs` 配置中心通过 pymsg/TCP 向各模块分发统一配置并支持热重载。
|
||||
|
||||
模块地图一览：
|
||||
- **核心服务**：`core`（进程托管）· `redirect80`（HTTP→HTTPS 重定向）· `waf`（前置 WAF 网关）· `gateway`（应用层网关）· `static`/`dnfs`（前端托管 / 树状菜单）· `db`/`db2`（数据+日志，Python/C++ 双实现）· `ai_review`（AI 内容审核）· `confs`（统一配置）· `captcha`/`smtp`（验证码 / 邮件）。
|
||||
- **独立产品**：`aibox`（AI 智能体）· `BotOps`（aibox 终端前端）· `bot4cj`（机器人硬件控制）· `lci`（嵌入式帧缓冲图形界面）。
|
||||
- **共享基础库**：libhttp / libcrypt / libsqlite3 / libmsg / libth / libtry（C++ 基础库与嵌入式脚本引擎）· pymsg / log_client / security_middleware（Python 共享组件）。
|
||||
|
||||
---
|
||||
|
||||
## 四、功能特性详解
|
||||
|
||||
- **进程托管（core）**：C++20 核心读 `init.txt` 拉起并守护各业务子进程，HTTP 管理接口 `:5200`（`/list`、`/exec`、`/kill`，需管理员 Token 鉴权），systemd 常驻。
|
||||
- **HTTP→HTTPS 重定向（redirect80）**：极简 Python 标准库服务，监听 :80，GET/HEAD 返回 301、其余方法返回 308，无缝升级到 HTTPS。
|
||||
- **边缘安全 WAF（waf）**：Go 实现的前置网关，终止 TLS 并运行 coraza v3.3.0（OWASP CRS + 自定义规则），命中即返回 403。
|
||||
- **统一鉴权网关（gateway）**：C++20 应用层网关，统一鉴权（PBKDF2 + RSA Token + 验证码 + 速率限制）与反向代理白名单。
|
||||
- **数据库 + 集中日志（db / db2）**：Python/pymsg 与 C++20 双实现，通用数据库访问（SQL-over-TCP、参数化防注入）+ 内置 Logs 表与自动清理的集中式日志，接口完全兼容可平替。
|
||||
- **树状菜单（dnfs / dnfs2）**：Python 与 C++20 双实现，基于父子 pid 的节点树增删改查，新增节点前调用 AI 内容审核。
|
||||
- **AI 内容审核（ai_review）**：Python 基于 DeepSeek + RAG 实现，采用 fail-closed 设计，宁可拒绝也不放过风险内容。
|
||||
- **统一配置中心（confs）**：pymsg/TCP 配置中心，向各模块分发配置并支持热重载。
|
||||
- **AI 智能体（aibox）**：独立 Python 智能体，基于 DeepSeek + WebSocket 技能系统自主执行任务。
|
||||
- **机器人硬件控制（bot4cj）**：仓颉（Cangjie）实现的硬件控制，解析 `.mt` 脚本驱动舵机与陀螺仪。
|
||||
|
||||
---
|
||||
|
||||
## 五、技术亮点
|
||||
|
||||
- **多语言混编协同**：C++20 / Python / Go / 仓颉各取所长，核心性能与业务敏捷兼得，用最合适的语言写最合适的模块。
|
||||
- **自研 pymsg RPC**：协议为 `[4 字节大端长度][UTF-8 JSON]`，在 C++ 与 Python 间实现字节级兼容，轻量无外部依赖。
|
||||
- **开箱即用安全**：WAF（coraza）+ 网关多重鉴权 + AI 内容审核 + 集中日志四层叠加，多模块安全审计持续覆盖（gateway 评级 A-，dnfs2 评级 A，P0 严重问题已全部修复）。
|
||||
- **共享基础库**：libhttp / libcrypt / libsqlite3 / libmsg / libth / libtry 等 C++ 基础库，与 pymsg / log_client / security_middleware 等 Python 共享组件，避免重复造轮子。
|
||||
- **一键部署**：`_setup.deb.sh` / `_setup.rhel.sh` / `_inst.sh` 安装脚本 + systemd 守护，一条命令拉起整套集群。
|
||||
- **MIT 开源友好**：各模块均基于 MIT License，可自由使用、修改与再分发。
|
||||
|
||||
---
|
||||
|
||||
## 六、适用场景 / 谁该用
|
||||
|
||||
- **边缘 / 私有化部署**：不想依赖公云、需要在本地或边缘节点自托管服务集群的团队。
|
||||
- **自托管社区 / 论坛**：需要前端托管、树状菜单与集中日志的内容站点。
|
||||
- **需要 AI 审核的内容平台**：新增内容时自动合规审查，fail-closed 兜底风险。
|
||||
- **教学 / 实验微服务架构**：轻量、可读、多语言混编，是理解微服务与 RPC 的绝佳样本。
|
||||
- **硬件 + 服务联动**：通过 bot4cj 仓颉脚本驱动舵机/陀螺仪，做软硬一体项目。
|
||||
|
||||
---
|
||||
|
||||
## 七、快速上手（极简）
|
||||
|
||||
```bash
|
||||
# 1. 下载并执行对应发行版的一键安装脚本（Debian / RHEL 示例）
|
||||
curl -fsSL https://git.cancerai.top/qing/blackbird/-/raw/main/_setup.deb.sh | bash
|
||||
# 或 RHEL 系：_setup.rhel.sh ；通用：_inst.sh
|
||||
|
||||
# 2. 编辑 init.txt，声明需要托管的子进程模块（顺序很重要）
|
||||
# （db / confs / ai_review / dnfs / smtp / static /
|
||||
# redirect80 / waf / gateway / captcha / aibox）
|
||||
|
||||
# 3. 启动托管核心（注册为 systemd 服务 Nidus.service）
|
||||
systemctl enable --now Nidus.service
|
||||
|
||||
# 4. 访问 :443 即走完整安全链路（redirect80 → waf → gateway → 业务服务）
|
||||
# core 管理接口 :5200 提供 /list /exec /kill（需管理员 Token）
|
||||
curl -X POST http://localhost:5200/list \
|
||||
-H "Authorization: Bearer <your_admin_token>"
|
||||
```
|
||||
|
||||
> 注：具体脚本名与参数以仓库 `main` 分支最新文件为准；首次部署建议放行 `:80`、`:443` 端口（内部服务均绑 127.0.0.1，无需额外放行）。
|
||||
|
||||
---
|
||||
|
||||
## 八、多平台版本文案
|
||||
|
||||
### 8.1 GitHub / README 完整简介（约 150–220 字）
|
||||
|
||||
> **blackbird** 是一套 DIY 的轻量级微服务架构（别名 UniServe Framework / micro_servers），由 C++20、Python、Go 与仓颉混合实现。它以进程托管核心为核心，内置 WAF 网关、统一鉴权、AI 内容审核与集中日志，主打轻量、自主可控与安全。自研 pymsg RPC 实现跨语言字节级通信，共享基础库降低重复成本，一键安装脚本 + systemd 守护让整套集群开箱即用。各模块均基于 MIT License 开源。适合边缘私有化部署、自托管社区、AI 审核内容平台与软硬一体实验。把微服务的控制权，握回自己手里。
|
||||
|
||||
### 8.2 公众号长导语（约 200–300 字，故事感 + 号召）
|
||||
|
||||
你有没有想过，自己搭一套"能用的"微服务集群，到底要付出多大的代价？
|
||||
|
||||
许多人卡在第一步：Kubernetes、服务注册、消息总线……云原生很强大，却也把"自建可控"变成了高门槛的奢侈品。blackbird 想做的，是把这件事重新变轻——一个 C++20 核心读着一份 `init.txt`，就把 WAF、网关、数据库、AI 审核一个个进程稳稳托管起来，systemd 常驻，一条脚本装好。
|
||||
|
||||
它不追逐重基建，而是把轻量、自主可控、安全三件事做到位：Go 写的 WAF 在前端挡刀，C++ 网关做统一鉴权，Python 调 DeepSeek 做内容审核，仓颉脚本还能直接驱动机器人舵机。多语言混编，各司其职；MIT 开源，随心改造。
|
||||
|
||||
如果你也想把服务集群的控制权握回自己手里，不妨点开仓库，给它一颗 Star。轻量微服务，自主可控更安全——这一次，由你来定义。
|
||||
|
||||
### 8.3 技术社区 / 小红书短文案（约 80–120 字）
|
||||
|
||||
自己搭微服务一定要上 K8s 吗？blackbird 给你另一种答案：C++20/Python/Go/仓颉多语言混编的轻量进程托管微服务，自带 WAF + 统一鉴权 + AI 内容审核 + 集中日志，一条脚本开箱即用，MIT 开源。边缘私有化、自托管社区、软硬一体都能跑。把控制权握回自己手里，欢迎 Star & Fork 🌟
|
||||
|
||||
---
|
||||
|
||||
## 九、号召行动（CTA）+ 开源信息
|
||||
|
||||
**把微服务的控制权，握回自己手里。**
|
||||
|
||||
- ⭐ **Star** 项目，让更多人看到这套轻量自主可控的微服务框架：https://git.cancerai.top/qing/blackbird
|
||||
- 🍴 **Fork** 仓库，按你的场景裁剪模块、改写脚本、替换鉴权策略。
|
||||
- 💬 提交 Issue 与 PR，一起把安全评级推向更高。
|
||||
|
||||
**开源协议**：blackbird 各模块均基于 **MIT License** 发布，可自由使用、修改、再分发，仅需保留版权与许可声明。轻量、开放、自主可控——欢迎共建。
|
||||
|
||||
---
|
||||
|
||||
*文档由文案创作专家笔澜（Penn）基于项目调研结论创作，内容均源自仓库可验证信息，未作能力虚构。*
|
||||
File renamed without changes.
Reference in new issue
Block a user