qing/micro_servers
1
3 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新文档

Browse Source
This commit is contained in:
qing committed 2026-07-25 02:11:28 +08:00
1 parent c5fc6f1076
commit fcf3084d0f
2 files changed
+283 -39
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+71 -34
View File
@@ -1,7 +1,7 @@
# micro_servers
一套 DIY 的轻量级微服务架构（UniServe Framework），由 C++ 与 Python 混合实现。
`core` 作为进程托管服务负责拉起并守护各业务子进程，`gateway` 作为应用层网关统一鉴权与反向代理，`db` 提供通用数据库访问，`ai_review` 提供 AI 内容审核，`static` 与 `dnfs` 作为业务服务对外提供能力。
一套 DIY 的轻量级微服务架构（UniServe Framework），由 C++、Python 与 Go 混合实现。
`core` 作为进程托管服务负责拉起并守护各业务子进程，`waf` 作为前置 WAF 网关终止 TLS 并做规则匹配，`gateway` 作为应用层网关统一鉴权与反向代理，`db` 提供通用数据库访问，`ai_review` 提供 AI 内容审核，`static` 与 `dnfs` 作为业务服务对外提供能力。
## 架构总览
@@ -12,33 +12,36 @@
│ 读取 init.txt 拉起并守护下列子进程 │
└───────────────┬──────────────────────────────┘
│ 启动 / 守护
┌──────────────────┬───────────┼───────────┬──────────────────┐
▼ ▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌────────┐ ┌──────────────┐ ┌──────────────┐
│ gateway │ │ static │ │ dnfs │ │ db │ │ ai_review │
│ 应用层网关 │ │ 前端托管服务 │ │树状菜单│ │ 通用数据库 │ │ AI内容审核 │
│ :443 (入口) │ │ :9200 │ │ :8006 │ │ :8005 │ │ :8007 │
│ 鉴权 + 反代 │ │ 静态/媒体 │ │节点CRUD│ │ SQL-over-HTTP│ │ DeepSeek+RAG │
└──────┬───────┘ └──────────────┘ └───┬────┘ └──────────────┘ └──────────────┘
│ 反向代理 │ 调用
├────────────────► static:9200 ├──────────► db:8005
└────────────────► dnfs:8006 └──────────► ai_review:8007
┌──────────────────┬───────────┼───────────┬──────────────────┬──────────────┐
▼ ▼ ▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ waf │ │ gateway │ │ static │ │ dnfs │ │ db │ │ ai_review │
│ WAF 网关 │ │ 应用层网关 │ │前端托管│ │ 树状菜单 │ │ 通用数据库 │ │ AI内容审核 │
│ :443 (入口) │ │ :8443 (内部) │ │ :9200 │ │ :8006 │ │ :8005 │ │ :8007 │
│ coraza+反代 │ │ 鉴权 + 反代 │ │静态/媒体│ │ 节点CRUD │ │ SQL-over-HTTP│ │ DeepSeek+RAG │
└──────┬───────┘ └──────┬───────┘ └────────┘ └──────┬───────┘ └──────────────┘ └──────────────┘
│ HTTPS终止 │ 反向代理 │ 调用
└──────────────────►│ ├──────────► db:8005
├────────────────► static:9200
└────────────────► dnfs:8006 ──► ai_review:8007
```
### 请求链路
1. 客户端所有请求统一打到 `gateway:443`（HTTPS）。
2. `gateway` 对 `/login`、`/register` 做账号鉴权（SQLite + SHA256 + RSA 签名 Token）。
3. 其余请求携带 Token，经 `gateway` 校验后反向代理到 `Proxy.opened` 中放开的内部服务（`static:9200` / `dnfs:8006`）。
4. `db:8005` 与 `ai_review:8007` 在 `Proxy.closed` 中，仅允许内部服务间调用，不对外暴露。
5. `dnfs` 处理节点增删改查时，通过 HTTP 调用 `db` 服务完成数据持久化，新增节点前调用 `ai_review` 进行内容审核。
1. 客户端所有请求先打到 `waf:443`（HTTPS），WAF 终止 TLS、运行 coraza 规则匹配，命中则直接返回 403。
2. 未命中规则的请求由 WAF 以明文 HTTP 转发到 `gateway:8443`，并设置 `X-Forwarded-For` / `X-Forwarded-Proto` 头。
3. `gateway` 对 `/login`、`/register` 做账号鉴权（SQLite + PBKDF2 密码哈希 + RSA 签名 Token + 可选 CAPTCHA + 速率限制）。
4. 其余请求携带 Token，经 `gateway` 校验后反向代理到 `Proxy.opened` 中放开的内部服务（`static:9200` / `dnfs:8006`）。
5. `db:8005` 与 `ai_review:8007` 在 `Proxy.closed` 中，仅允许内部服务间调用，不对外暴露。
6. `dnfs` 处理节点增删改查时，通过 HTTP 调用 `db` 服务完成数据持久化，新增节点前调用 `ai_review` 进行内容审核。
## 各服务说明
| 服务 | 语言 | 端口 | 职责 |
|------|------|------|------|
| [core](core/) | C++20 | 5200 | 进程托管服务（PMC），创建/列举/杀死/执行子进程，读取自启动列表守护业务进程，提供 HTTP 管理接口 |
| [gateway](gateway/) | C++20 | 443 | 应用层网关（入口），用户注册/登录鉴权、Token 签发与校验、反向代理到内部服务 |
| [waf](waf/) | Go | 443 | WAF 网关（入口），终止 TLS、coraza 规则匹配（SecLang）、反向代理到 gateway，支持 SIGHUP 热加载规则 |
| [gateway](gateway/) | C++20 | 8443 | 应用层网关（内部 HTTP），用户注册/登录鉴权、Token 签发与校验、反向代理到内部服务 |
| [static](static/) | Python(Flask) | 9200 | 前端托管服务，社区首页、静态页面与文件浏览、视频/音频流媒体播放、路径遍历防护 |
| [dnfs](dnfs/) | Python(Flask) | 8006 | 树状网络文件系统（Dendrachy Network File-System），基于父子 pid 的节点树增删改查，集成 AI 内容审核 |
| [db](db/) | Python(Flask) | 8005 | 通用数据库服务，基于 SQLAlchemy Core 的 SQL-over-HTTP，支持 select/insert/update/delete，参数化查询防注入 |
@@ -49,15 +52,28 @@
- 可执行文件 `nidus.out`，作为 systemd 服务（`Nidus.service`）常驻运行。
- 支持两种工作模式：命令行子系统调用（`--send/--exec/--list/--kill`）与 HTTP 伺服器模式（`--serve <port>`）。
- 通过命名管道（Pipe）与消息队列（Mq）实现进程间通信。
- 读取 `init.txt` 自启动列表，按行拉起各业务服务（ai_review / db / dnfs / static / gateway）。
- 读取 `init.txt` 自启动列表，按行拉起各业务服务（ai_review / db / dnfs / static / waf / gateway / captcha）。
### gateway（应用层网关）
### waf（WAF 网关）
- 唯一对外入口，承载 HTTPS（`full_chain.crt` / `server.key`），默认监听 443 端口。
- 用户表 `Users`（email + SHA256 密码哈希），登录成功后用 RSA 私钥签发 `Base64(payload)_signature` 形式的 Token。
- 反向代理时校验 Token 签名与过期时间，仅放行 `Proxy.opened` 中配置的内部地址。
- `Proxy.closed` 配置内部专用服务（db:8005 / ai_review:8007），禁止外部直接访问。
- 配置示例见 [gateway/example.ini](gateway/example.ini)。
- 唯一对外入口，终止 TLS（`certs/full_chain.crt` / `certs/server.key`），监听 443 端口。
- 基于 [coraza](https://github.com/corazawaf/coraza) v3.3.0（ModSecurity SecLang 的 Go 实现），规则匹配命中后返回 403。
- 未命中规则的请求以明文 HTTP 反向代理到 `gateway:8443`，透传 `X-Forwarded-For` / `X-Forwarded-Proto`。
- 规则库位于 [waf/rules/](waf/rules/)，分两段：本地自定义（ID 100000-199999）与 OWASP CRS（ID 900000-999999，可选）。
- 极客操作：`kill -HUP <pid>` 热加载规则；`waf -list` 列规则；`waf -test <file>` 校验语法；`waf -check "<input>"` 测试单条输入。
- 配置见 [waf/config.yaml](waf/config.yaml)，详见 [waf/README.md](waf/README.md)。
### gateway（应用层网关 · v0.3.0-security）
- 内部 HTTP 服务，默认监听 127.0.0.1:8443，不再承载 TLS（TLS 已由 WAF 终止）。
- 通过 `Server.tls = on/off` 配置切换 HTTPS/HTTP 模式（[example.ini](gateway/example.ini)），独立部署时仍可启用 TLS。
- **密码安全**：PBKDF2-HMAC-SHA256（10 万轮 + 16 字节随机盐），密码强度校验（8+ 字符、4 类中至少 3 类），登录时自动迁移旧 SHA256 哈希，常数时间比较防 timing attack。
- **Token 机制**：`Base64(payload) + "_" + RSA-Sign(payload)`，默认 1 小时过期，验签通过才放行。
- **CAPTCHA**：`/captcha` 接口生成验证码（5 分钟过期、一次性使用），登录与注册均可选启用。
- **速率限制**：登录 5 次/5 分钟、注册 3 次/10 分钟，按 `X-Forwarded-For`（WAF 注入）客户端 IP 计数。
- **反向代理**：`Target-Url` 必须在 `Proxy.opened` 白名单中（`closed` 仅记录用途，实际隔离靠"不在 opened 中即拒绝"），缺省走 `Proxy.default`（不需 Token，服务前端静态资源）。
- **自动建表**：启动时若 `Users` 表不存在则自动创建，首位注册者即为管理员。
- 详见 [gateway/README.md](gateway/README.md)。
### static（前端托管服务）
@@ -104,17 +120,20 @@
| 端口 | 服务 | 绑定地址 | 说明 |
|------|------|----------|------|
| 443 | gateway | 0.0.0.0 | HTTPS 对外入口 |
| 443 | waf | 0.0.0.0 | HTTPS 对外入口（终止 TLS + coraza 规则匹配） |
| 8443 | gateway | 127.0.0.1 | 应用层网关（内部 HTTP，由 waf 转发） |
| 5200 | core | — | PMC HTTP 管理接口 |
| 9200 | static | 127.0.0.1 | 前端托管（经 gateway 代理） |
| 8006 | dnfs | 127.0.0.1 | 树状菜单（经 gateway 代理） |
| 8005 | db | 127.0.0.1 | 数据库服务（仅内部调用） |
| 8007 | ai_review | 127.0.0.1 | AI 审核（仅内部调用） |
| 8009 | captcha | 127.0.0.1 | 验证码服务（独立组件） |
## 依赖
- **系统级**：`g++`（C++20）、`make`、`libboost-all-dev`、`libcurl4-gnutls-dev`、`libssl-dev`、`libsqlite3-dev`、`python3`、`python3-venv`、`python3-pip`、`patchelf`
- **系统级**：`g++`（C++20）、`make`、`libboost-all-dev`、`libcurl4-gnutls-dev`、`libssl-dev`、`libsqlite3-dev`、`python3`、`python3-venv`、`python3-pip`、`patchelf`、`golang-go`（Go 1.22+，用于 waf）
- **Python**：Flask、Flask-CORS、Flask-SQLAlchemy、SQLAlchemy、waitress、openai、chromadb、python-dotenv、nuitka（详见各服务 `requirements.txt`）
- **Go**：corazawaf/coraza v3.3.0、gopkg.in/yaml.v3（详见 [waf/go.mod](waf/go.mod)）
## 安装
@@ -141,16 +160,20 @@ bash _run.sh # 运行
> **注意**：`ai_review` 未包含在 `_inst.sh` 中，需单独进入 `ai_review/` 目录执行 `_set.sh` 安装，并配置 `.env` 文件（DeepSeek API 密钥等）。
> **注意**：waf 首次编译需联网下载 Go 依赖，[waf/_set.sh](waf/_set.sh) 会自动调用 [waf/_goproxy.sh](waf/_goproxy.sh) 设置 GOPROXY 国内镜像。如需手动设置：`go env -w GOPROXY=https://goproxy.cn,direct`。
## 运行
由 `core` 守护的子进程通过 `init.txt` 自启动：
由 `core` 守护的子进程通过 `init.txt` 自启动（顺序很重要，waf 必须先于 gateway）：
```
bash /opt/micro_servers/ai_review/_run.sh
bash /opt/micro_servers/db/_run.sh
bash /opt/micro_servers/dnfs/_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
```
启动 `core`（需 root 或 systemd）：
@@ -159,20 +182,34 @@ bash /opt/micro_servers/gateway/_run.sh
systemctl start Nidus # 或 bash core/_run.sh
```
对外访问入口：`https://<host>:443`。
对外访问入口：`https://<host>:443`（由 waf 终止 TLS 后转发到 gateway）。
### WAF 与 gateway 的协作
WAF 启用后，证书从 gateway 迁移到 waf：
```bash
mkdir -p /opt/micro_servers/waf/certs
cp /opt/micro_servers/gateway/full_chain.crt /opt/micro_servers/gateway/server.key /opt/micro_servers/waf/certs/
```
gateway 改为内部 HTTP 模式（[example.ini](gateway/example.ini) 中 `tls = off`、`address = 127.0.0.1`、`port = 8443`）。
如需独立部署（不使用 WAF），把 gateway 的 `tls = on`、`port = 443`、`address = 0.0.0.0`，证书留在 gateway 目录即可。
## 关于架构定位
本项目具备微服务架构的核心特征，是一种**进程托管式轻量微服务**：
- **服务按业务能力拆分**：网关、前端托管、节点树、数据库、内容审核各自独立、独立端口、独立数据存储。
- **API 网关模式**：`gateway` 统一入口，承担鉴权与反向代理，内部服务通过 `closed` 列表隔离。
- **服务按业务能力拆分**：WAF 网关、应用网关、前端托管、节点树、数据库、内容审核各自独立、独立端口、独立数据存储。
- **API 网关模式**：`waf` 作为边缘网关统一入口，`gateway` 承担鉴权与反向代理，内部服务通过 `closed` 列表隔离。
- **进程编排/守护**：`core` 作为服务管理器拉起并守护子进程，类似简易版 supervisor。
- **多语言异构**：C++（core / gateway）与 Python（static / dnfs / db / ai_review）混合，通过 HTTP 通信。
- **多语言异构**：C++（core / gateway）、Python（static / dnfs / db / ai_review）、Go（waf）混合，通过 HTTP 通信。
- **数据访问层解耦**：`db` 服务将数据库操作收敛为统一的 HTTP 接口，业务服务无需直连数据库。
- **AI 能力集成**：`ai_review` 以 RAG 增强的 LLM 审核为业务层提供内容安全能力，支持人工反馈闭环。
- **安全分层**：`waf` 在边缘做规则匹配（OWASP CRS / 自定义 SecLang 规则），`gateway` 在应用层做鉴权，`db` 仅监听本机，多层防护。
与云原生微服务的差异：未引入服务注册发现、容器编排、消息总线，服务地址在 `gateway/example.ini` 中静态配置。对于个人/中小规模的 DIY 场景，这种取舍在简洁性与可控性上是合理的。
与云原生微服务的差异：未引入服务注册发现、容器编排、消息总线，服务地址在 `waf/config.yaml` 与 `gateway/example.ini` 中静态配置。对于个人/中小规模的 DIY 场景，这种取舍在简洁性与可控性上是合理的。
## 许可证
gateway/README.md
+212 -5
View File
@@ -1,7 +1,214 @@
# UniServe_gateway2
US Framework gateway C++ version
# gateway
# Dependancy
UniServe Framework 的应用层网关，C++20 实现。
libboost
libcurl
在引入 [waf](../waf/) 模块后，gateway 退化为内部 HTTP 服务：TLS 由 WAF 终止，gateway 专注做账号鉴权与反向代理。通过 `Server.tls` 配置可一键切换独立部署（HTTPS）或与 WAF 协作（HTTP）两种模式。
## 职责
- **账号鉴权**：`/register` 注册、`/login` 登录，签发 RSA 签名的 Token。
- **反向代理**：携带 Token 的请求校验后转发到 `Proxy.opened` 中放开的内部服务。
- **CAPTCHA 接口**：`/captcha` 生成验证码 token + 文本（内存存储，5 分钟过期，一次性使用）。
- **速率限制**：登录 5 次/5 分钟、注册 3 次/10 分钟，按 `X-Forwarded-For` 客户端 IP 计数（由 WAF 注入）。
- **OPTIONS 预检**：通配 `*` 返回 CORS 头，允许跨域。
## 安全特性
| 特性 | 实现 |
|------|------|
| 密码哈希 | PBKDF2-HMAC-SHA256，100000 轮，16 字节随机盐，32 字节哈希 |
| 密码强度校验 | 至少 8 字符；大写/小写/数字/特殊字符中至少 3 类 |
| 邮箱格式校验 | 正则匹配 `^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$` |
| 旧哈希自动迁移 | 登录时若发现 SHA256 旧哈希，验证通过后自动迁移为 PBKDF2 |
| Token 机制 | `Base64(payload) + "_" + RSA-Sign(payload)`，验签 + 过期校验（默认 1 小时） |
| 常数时间比较 | PBKDF2 验证用 `diff |= hash[i] ^ expected[i]` 防 timing attack |
| CAPTCHA | 一次性、5 分钟过期，登录与注册均可选启用 |
| 速率限制 | 内存计数器，自动清理超过 1 万条的老条目 |
| TLS 可选 | `Server.tls = off` 时纯 HTTP（配合 WAF），`on` 时用 `full_chain.crt` / `server.key` |
## 接口
### `POST /captcha`
生成验证码。返回：
```json
{
"token": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"text": "Ab3xy"
}
```
### `POST /login`
请求体：
```json
{
"username": "user@example.com",
"password": "P@ssw0rd",
"captcha_token": "a1b2c3d4...", // 可选
"captcha_answer": "Ab3xy" // 可选
}
```
成功响应：
```json
{
"success": true,
"data": { "token": "<base64_payload>_<rsa_sign>" }
}
```
失败响应：
```json
{ "success": false, "message": "Invalid Username or Password" }
```
错误码：`400`（参数/CAPTCHA 错误）、`401`（账号/密码错或 Token 过期）、`429`（速率超限）。
### `POST /register`
请求体与 `/login` 相同。先做密码强度校验、邮箱格式校验、CAPTCHA 校验，再写入 `Users` 表。
错误码：`400`（密码/邮箱/CAPTCHA 不合规）、`429`（速率超限）、`500`（数据库异常）。
### `GET/POST *`（反向代理）
携带 header：
```
Authorization: Bearer <base64_payload>_<rsa_sign>
Target-Url: http://127.0.0.1:9200 // 可选，缺省取 Proxy.default
```
- `Target-Url` 缺省时走 `Proxy.default`（不需 Token）。
- 自定义 `Target-Url` 必须在 `Proxy.opened` 白名单中，否则返回 403。
- 验签通过且未过期（默认 1 小时）才转发，否则返回 401。
- `Proxy.closed`（如 db:8005、ai_review:8007）不在 `opened` 中，外部无法直访。
### `OPTIONS *`
返回 CORS 预检响应：`Access-Control-Allow-Origin: *`、`Allow-Methods: GET, POST, OPTIONS`、`Max-Age: 86400`。
## 数据库
SQLite3，表 `Users`：
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER PK AUTOINCREMENT | |
| email | TEXT UNIQUE NOT NULL | 登录账号 |
| password_hash | TEXT NOT NULL | `pbkdf2:100000:<salt_hex>:<hash_hex>` |
| create_at | DATETIME DEFAULT CURRENT_TIMESTAMP | |
| last_login | DATETIME | 每次登录更新 |
| is_active | BOOLEAN DEFAULT 1 | |
启动时若 `Users` 表不存在则自动建表（含 `idx_users_email` 索引），无默认管理员账号——首位注册者即为管理员。
## 配置
[example.ini](example.ini)：
```ini
[Server]
# tls = off HTTP 模式（配合 waf 模块）
# tls = on HTTPS 模式（独立部署，证书为 full_chain.crt / server.key）
address = 127.0.0.1
port = 8443
tls = off
[Proxy]
default = http://127.0.0.1:9200
closed = http://127.0.0.1:8005;http://127.0.0.1:8007;
opened = http://127.0.0.1:9200;http://127.0.0.1:8006;
[Database]
path = sqlite3.db
```
- `Proxy.default`：未带 `Target-Url` header 时的默认转发地址（不需 Token，主要服务前端静态资源）。
- `Proxy.opened`：允许外部带 Token 访问的内部服务白名单（分号分隔）。
- `Proxy.closed`：仅记录用途，实际靠"不在 opened 中即拒绝"实现隔离。
## 部署模式
### 模式 A：与 WAF 协作（推荐）
```
客户端 ──HTTPS──▶ waf:443 (终止 TLS + coraza 规则) ──HTTP──▶ gateway:8443
```
```ini
address = 127.0.0.1
port = 8443
tls = off
```
证书放在 `waf/certs/`。RateLimiter 从 WAF 注入的 `X-Forwarded-For` 取真实客户端 IP。
### 模式 B：独立部署
```
客户端 ──HTTPS──▶ gateway:443 (终止 TLS + 鉴权 + 反代)
```
```ini
address = 0.0.0.0
port = 443
tls = on
```
证书 `full_chain.crt` / `server.key` 放在 gateway 目录。RateLimiter 取不到 `X-Forwarded-For`，所有请求记为 `"direct"`。
## 编译与运行
依赖系统库（由根目录 [_setup.deb.sh](../_setup.deb.sh) 或 [_setup.rhel.sh](../_setup.rhel.sh) 安装）：
- `libboost_json`、`libboost_program_options`
- `libcurl`
- `libssl` / `libcrypto`（OpenSSL，PBKDF2 + RSA + RAND_bytes）
- `libsqlite3`
- 项目内库：`libus_http`、`libus_crypt`（由 [libhttp](../libhttp/)、[libcrypt](../libcrypt/) 编译安装）
```bash
bash _set.sh # make clear && make
bash _run.sh # ./build/gateway.out -i example.ini
```
`gateway.out` 需以 `-i <ini>` 传配置文件路径。其他参数：`-h/--help`、`-v/--version`。
## 目录结构
```
gateway/
├── src/
│ └── main.cpp # 全部实现：PBKDF2 / PasswordValidator / RateLimiter / 路由 / handler
├── inc/
│ ├── Conf.hpp # ConfIni：基于 boost::property_tree 的 ini 解析
│ ├── ExpBase.hpp # 异常基类（带 source_location）
│ └── LocalTime.hpp # 本地时间工具（getCurrent / parse）
├── Makefile
├── example.ini
├── _set.sh / _run.sh
└── README.md
```
## 版本
`0.3.0-security`（见 [src/main.cpp:27](src/main.cpp#L27)）。启动时打印：
```
Gateway 0.3.0-security started (PBKDF2 + CAPTCHA + RateLimit)
```
## 依赖
- C++20（`g++`）
- Boost：`boost::json`、`boost::program_options`、`boost::property_tree`
- OpenSSL：PBKDF2-HMAC-SHA256、RSA 签名/验签、`RAND_bytes`
- libcurl（反向代理出站请求）
- libsqlite3（用户表存储）
- 项目库：[libhttp](../libhttp/)（HttpServer/HttpClient）、[libcrypt](../libcrypt/)（MyRSA/Base64/SHA256）、[libsqlite3](../libsqlite3/)