qing
30e064996c
- profile/evaluation/promo_pack 移入 docs/reports/（按文档管理约定），内部引用同步 - 补建 captcha2/README.md、smtp3/README.md（主 README 曾引用但缺失） - 重写 README 测试章节（实际为 tests/blackbox/，纯标准库零依赖） - 清除全部 docs/INDEX.md 残留引用；legacy README 中已删除 ini 的失效链接改文字 - 全仓库链接检查 0 broken
70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# smtp3 — C++20 邮箱验证码服务
|
||
|
||
smtp 的 C++20 重实现，接口与 Python 版完全兼容（pymsg 路由 send_email/verify_email/health），修复审计发现的安全项（弱随机、日志明文验证码、now 遮蔽等）。基于 libmsg + boost::json + OpenSSL。
|
||
|
||
## 架构
|
||
|
||
```
|
||
ca :8443 (注册流程经 pymsg 调用)
|
||
│ pymsg TCP
|
||
▼
|
||
smtp3 :8008 (RpcServer)
|
||
│ SMTP_SSL (OpenSSL)
|
||
▼
|
||
外部 SMTP 服务器 (163/QQ 等)
|
||
```
|
||
|
||
- **服务框架**: libmsg `RpcServer`（pymsg 协议，4B 大端长度前缀 + UTF-8 JSON）
|
||
- **SMTP 会话**: 直接控制 OpenSSL 会话发送，更精细的超时/错误处理
|
||
- **安全**: `std::random_device` 安全随机、常数时间比较、日志脱敏、冷却/限流/熔断
|
||
- **异步日志**: libmsg `AsyncQueue` → db2 Logs 表
|
||
|
||
## 接口
|
||
|
||
| pymsg 路由 | 说明 |
|
||
|-----------|------|
|
||
| `send_email` | 生成 6 位验证码并经 SMTP_SSL 发送，10 分钟有效；同一邮箱 60s 冷却，发送失败不计入冷却 |
|
||
| `verify_email` | 校验，通过即一次性消费防重放；连续失败 5 次自动作废并返回 `invalidated` |
|
||
| `health` | 健康检查 |
|
||
|
||
请求/响应 JSON 格式与 Python smtp 完全一致，ca 零改动。
|
||
|
||
## 配置
|
||
|
||
纯 CLI + 环境变量 + 默认值，不依赖 confs。
|
||
|
||
| 配置项 | CLI 参数 | 默认值 |
|
||
|--------|---------|--------|
|
||
| 绑定地址 | `--addr` / `-a` | 127.0.0.1 |
|
||
| 监听端口 | `--port` / `-p` | 8008 |
|
||
| SMTP 服务器端口 | `--smtp-port` | 465（SSL） |
|
||
| 验证码长度 | `--code-len` | 6（4~10） |
|
||
| 验证码有效期 | `--code-ttl` | 600s |
|
||
| 发送冷却 | `--send-interval` | 60s |
|
||
| 最大校验失败次数 | `--max-verify-attempts` | 5 |
|
||
| 单邮箱限流 | `--email-hourly-limit` / `--email-daily-limit` | 3 / 10 |
|
||
| 全局熔断 | `--smtp-hourly-limit` | 100 |
|
||
| 邮件标题/正文上限 | `--max-subject-len` / `--max-content-len` | 256 / 4096 |
|
||
| 实例名 / 日志级别 | `--instance` / `--log-level` | smtp / info |
|
||
|
||
SMTP 账号凭据经 `.env` 注入（`SMTP_SERVER` / `SMTP_USER` / `__PASSWORD`）。优先级: CLI > 环境变量 > 默认值。
|
||
|
||
## 构建与运行
|
||
|
||
```bash
|
||
./_set.sh # 编译
|
||
./_run.sh # 运行
|
||
```
|
||
|
||
依赖: libmsg, boost::json, OpenSSL（libssl-dev）
|
||
|
||
## 状态
|
||
|
||
- **待上线**：代码就绪并通过安全审计，`core/services.yaml` 仍拉起 Python 版 `smtp`，尚未平替
|
||
- 开发文档见 [docs/reports/smtp_cpp_rewrite_dev_doc.md](../docs/reports/smtp_cpp_rewrite_dev_doc.md)
|
||
- 安全审计见 [docs/security/smtp3_SECURITY_AUDIT_20260809.md](../docs/security/smtp3_SECURITY_AUDIT_20260809.md)
|
||
|
||
## 许可证
|
||
|
||
MIT License
|