docs: refine moderation and signup policy
This commit is contained in:
QiuSW
+18
-2
@@ -23,6 +23,7 @@
|
||||
- **API 层（DRF）**：对外生成接口、余额查询、支付回调接收、扫码下单。入口 `apps/api/`。生成/余额这类对外业务 API **只认 API Key，不接受 Web session**；充值下单/状态查询属于用户端流程，走 Web session + CSRF；支付回调走平台验签。
|
||||
- **计费层**：点数计算、原子扣减（锁 `UserWallet` 行）、退点、充值入账、流水记账。入口 `apps/billing/`。
|
||||
- **AI 调用层（Provider Adapter 架构）**：对外只暴露稳定能力，内部用「能力别名 → 具体供应商适配器」解耦。入口 `apps/ai/`，适配器在 `apps/ai/providers/`。
|
||||
- **内容安全层（本地敏感词 / 后续云审核）**：入口 `apps/moderation/`。T-604 只做 prompt 文本本地敏感词快筛，命中在扣点和调上游前返回 `content_blocked`；云内容安全、图片审核和输出审核保留扩展点，不在 T-604 范围。
|
||||
- **运营后台**：django-admin，注册各模型的 Admin。入口各 app 的 `admin.py`。T-401 已补齐用户、钱包、API Key（脱敏）、计费规则、汇率、充值订单、点数流水和调用记录的管理/检索；点数手工调整只能从钱包专用入口提交原因和非 0 变动，经计费层写 `adjust` 流水。
|
||||
- **外部服务**：上游 AI（vectorengine）、外部支付系统（跳转 + 回调）。
|
||||
- **数据库**：MySQL 8.4 LTS（cmhub **专用独立实例**，不复用 VPS 已有的 MySQL 5.7）；引擎必须 InnoDB、字符集 utf8mb4。开发与生产同用 MySQL，勿用 SQLite（SQLite 会静默忽略 `select_for_update`，测不出并发扣点）。
|
||||
@@ -68,6 +69,14 @@ T-306 已实现对外 API 安全加固：`download_image_input()` 在请求前
|
||||
- 输入：prompt、可选图片、能力别名、分辨率、`parameters` 安全子集；输出：文字或图片，或明确错误。`parameters` / `extra_body` 不得覆盖服务端固定的核心/计费字段（如 `model`、`n`、`size`、`resolution`、`messages`、`image*`）。
|
||||
- 处理超时、错误，向上层抛出可分类的异常（区分「上游失败」与「参数错误」）。不在本层写点数逻辑。
|
||||
|
||||
**内容安全层（`apps/moderation`）**
|
||||
|
||||
- T-604 的范围只包含输入 prompt 敏感词过滤；具体实施规则见 [`moderation.md`](moderation.md)。
|
||||
- 生成接口时序必须是 serializer 后先审 prompt，再读取 `image_base64` / 下载 `image_url`，最后才进入别名解析、计费和预扣。命中敏感词时不得下载图片、不得扣点、不得写调用/流水、不得调上游。
|
||||
- 本地词表只做免费快筛和运营自定义黑名单，不替代合规内容审核；云厂商内容安全、图片审核和输出审核后续用 provider 接口扩展。
|
||||
- 敏感词 matcher 必须缓存，禁止每请求重建；生产多 worker 下用共享 cache 的词库版本号触发各 worker 懒重建，不能只依赖当前进程的 Django signal。
|
||||
- 留痕只记录分类、命中词 ID、用户/API Key 关联和处理结果，不保存违规 prompt 原文。
|
||||
|
||||
**数据库 / 存储**
|
||||
|
||||
- 持久化：账号、API Key、点数余额、计费规则、汇率、充值订单、点数流水、调用记录、模型配置。
|
||||
@@ -87,6 +96,7 @@ T-306 已实现对外 API 安全加固：`download_image_input()` 在请求前
|
||||
| AiConfigAuditLog | 后台自动写入 | AiModel / ModelAlias / api_key 变更审计；记录 actor、action、target、changed_fields、changes、created_at；只读 |
|
||||
| PricingRule | 运营配置 | 操作类型 × **能力别名字符串**（+ 可选分辨率）→ 点数单价；不外键到具体 AiModel |
|
||||
| ExchangeRate | 运营配置 | 金额 → 点数 的汇率（如 1 元 = N 点），按 `currency + effective_from` 取当前有效值 |
|
||||
| SensitiveWord | 运营配置 | 本地敏感词快筛词库；word、normalized_word、category、action、is_active；T-604 MVP 仅支持 action=block |
|
||||
|
||||
关键事实：
|
||||
|
||||
@@ -102,6 +112,7 @@ T-306 已实现对外 API 安全加固：`download_image_input()` 在请求前
|
||||
- `AiConfigAuditLog` 只追加、不在后台编辑删除；密钥变更只记录 `api_key: empty/set` 状态变化，不记录明文 key 或 Fernet 密文。
|
||||
- 汇率在**充值下单创建订单时**锁定并记录到订单，同时计算预计到账点数；后续改汇率不影响已创建订单。支付回调入账时使用订单上的 `exchange_rate` / `points_granted`，不重新读取当前汇率。
|
||||
- Provider 适配器只允许白名单安全参数透传；外部调用方或后台 `extra_body` 传入核心字段时忽略，由服务端按别名解析和计费口径固定。
|
||||
- `SensitiveWord` 的 matcher 由 active 词库构建；词库变更后更新共享 cache 版本号，各 Gunicorn worker 在下一次请求检查版本并懒重建。
|
||||
|
||||
#### 配置表目标 schema
|
||||
|
||||
@@ -346,7 +357,7 @@ CREATE TABLE call_record (
|
||||
| 配置热生效 | 后台改模型/密钥后运行时仍用旧值 | 不在进程内长缓存；每次查库或保存时失效缓存 |
|
||||
| 配置变更审计 | 改密钥/模型/别名映射无痕 | `AiConfigAuditLog` 自动记录后台 create/update/delete；密钥只记录 empty/set 变化，日志只读 |
|
||||
| API Key 泄露 | 明文存库一旦泄露全泄 | Key **哈希存储**（sha256），明文只在创建时显示一次，库内存 `key_hash`+`key_prefix`，鉴权做哈希比对 |
|
||||
| 注册滥用 | 自助注册被批量刷 | 邮箱验证 + 生成接口限流（DRF throttle）；**注册不送点数**，无免费额度可薅 |
|
||||
| 注册滥用 | 自助注册被批量刷 | **免邮箱验证**（`ACCOUNT_EMAIL_VERIFICATION="none"`），防刷改由注册限流 / 图形验证码补位 + 生成接口限流（DRF throttle）；**注册不送点数**，无免费额度可薅 |
|
||||
| Web/API 抢 worker | 图片同步长请求占满 worker、拖慢用户端页面 | 单体下按路径把 `/api/v1/generate/*` 与用户端页面**分流到不同 gunicorn/worker 池**（见 5.1） |
|
||||
| 充错账户 | 扫码订单未绑定发起用户 | 订单创建即绑定 `user`；回调按 `order_no` 定位订单→其 user 入账 |
|
||||
| SSRF / 任意 URL 下载 | `image_url` 让服务端请求调用方指定地址 | 仅允许公网 http/https；请求前解析 IP 并拒绝内网/回环/链路本地/保留地址；重定向逐跳校验；流式读取并限制大小 |
|
||||
@@ -407,4 +418,9 @@ cmhub/
|
||||
- 点数余额存 `UserWallet`（与 auth `User` 表分离）；扣点锁 wallet 行，不与登录/资料更新抢锁。
|
||||
- **API Key 哈希存储**（sha256），明文只在创建时返回一次；库内存 `key_hash`+`key_prefix`，任何页面不回显明文。
|
||||
- **对外 API 只接受 API Key 认证，不挂 SessionAuthentication**，防止浏览器带 cookie 绕过 Key 与计费归属。
|
||||
- 用户端页面用 session + CSRF；自助注册须邮箱验证，生成接口须限流。
|
||||
- 用户端页面用 session + CSRF；自助注册**免邮箱验证**（邮箱仍必填且唯一），生成接口须限流。
|
||||
- **用户端与后台共用同一个 Django 会话（设计事实 + 账号分离约定）**：`/`（portal）、`/admin/`、`/api/`（session 部分）挂在同一域名/同一 Django 工程，用**同一个 `sessionid` cookie**；`/admin/` 不是「另一套登录」，只是在同一登录态上加一道 `is_staff=True` 门槛。因此：
|
||||
- 普通用户 `is_staff=False`，登 portal **进不了** `/admin/`（无越权、无泄露）；观察到的「用户端登录、后台跟着登」是因为用了 **staff/superuser 账号**同时登了 portal。
|
||||
- **解耦方案（采用方案 A·账号分离，零代码）**：终端用户一律 `is_staff=False`；运营用**专用 admin superuser** 只登 `/admin/`，不与 portal 账号混用。这样两个入口天然分开。
|
||||
- 不采用「同账号双会话」（需 admin 独立子域名/独立 cookie 或自定义中间件，成本高、MVP 不值）。
|
||||
- 相关加固（上线前，见 `deployment.md`）：`/admin/` 加访问保护（改路径 / IP 白名单 / 反代 basic auth / 2FA）；**永不给终端用户 `is_staff`**。
|
||||
|
||||
Reference in New Issue
Block a user