Files
jinzuanwork/backend/backend-site/交接说明.md
T
ywsandClaude Opus 5.5 51212a07c0 backend: 接入 SQLite 数据库 + 开单后台按功能重写
- store.py(新):卡密 / 订单信息 / 爱发电账本 / 呼叫记录 / 小块状态进 <DATA_DIR>/ys.db;
  第一次启动自动建库并导入旧 JSON(旧文件不动),admin.py db check/backup/export
- server.py / admin.py 存取换到库上,路由与接口字段不变;calls.jsonl 照旧追加
- 管理接口新增 calls / call-done / retry,codes 支持 q 搜索
- ys_admin.py 页面重写:待处理 / 订单 / 卡密 / 福利券 / 呼叫·反馈 / 开单工具
- tests/数据库测试.py(37 条,假数据);回归 27 条照旧全过
- 交接说明(数据库一节、面板一节)、回执第二轮、交付清单更新

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 16:20:45 +00:00

340 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 交接说明 · 网站后端(卡密 / 自助渲染下单)
> **交付方**:苏达(网站运维与技术提供)
> **收件方**:外部协作者
> **日期**:2026-10-05
> **一句话**:这是一个**零依赖单进程**的下单/卡密/队列后端,跑在一台小机器上。
> 请你重点看**安全与并发**,并给我们**问题分析 + 改正意见**(见最后一节)。
---
## 一、这一份是什么
「自助模板渲染」的**服务端**:买家在网页挑模板、传皮肤、填卡密下单;
服务器登记订单、排队;家里那台渲染机上线后自动领单、出图、回传;
买家再回来下载。**目标是无人值守** —— 不用人 24 小时盯着。
```
买家 → 网页(本地质检→选模板→填卡密→核对)→ POST /api/submit
↓ 核销卡密 + 落盘订单目录
服务器 → 队列(订单 meta 里的一个 state 字段:waiting/working/done/failed)
渲染机 → 每 20s:POST /hb → POST /claim → GET /skin/<单号>
→ Blender 渲染 → POST /progress(进度)→ POST /finish(一张一次)
买家 → GET /api/order/<单号>?t=<口令> → 下载 /api/dl/<单号>/<i>?t=<口令>
```
**为什么"渲染机是主动出站"**:家里那台机器没有公网入口,所以**服务器从不连它**,
全靠它自己定时来拉。心跳超过阈值没更新 → 页面显示「渲染机离线」。
---
## 二、技术栈与运行方式
| 项 | 值 |
|---|---|
| 语言 / 依赖 | **Python 3,纯标准库,零第三方依赖**(连 Web 框架都没用,`BaseHTTPRequestHandler`) |
| 进程 | 单进程,由 systemd 托管;内存上限被 cgroup 卡住(小机器上防它吃爆) |
| 监听 | **只绑回环**,公网由 nginx 反代过去(后端自己不对外开端口) |
| 账号 | 跑在专用非 root 用户下 |
| 数据 | **SQLite**(`<DATA_DIR>/ys.db`,标准库自带 `sqlite3`,无外部服务)+ 皮肤 / 成品图片文件。2026-10-05 接入,见第五节 |
| 规模 | 单机单进程,日单量个位数到几十 |
**为什么不用框架**:这台机器很小(1G 多内存),装一个 Web 框架 + 一堆传递依赖不划算,
而且这台机器**不允许跑重活**(视频转码这类会把它拖死)。纯标准库启动快、内存稳。
---
## 三、文件清单
| 文件 | 行数 | 干什么 |
|---|---|---|
| `server.py` | ~3100 | **全部服务端逻辑**:路由、订单状态机、卡密生命周期、限流、PNG 结构核验的调用方、爱发电回调、打包下载、小票生成 |
| `admin.py` | ~540 | 命令行管理工具:发卡密 / 看队列 / 重渲 / 清过期 / 审计被拦记录 |
| `pngcheck.py` | ~130 | PNG **结构**核验(不解码像素):防「夹带私货」——尾部塞字节、未知关键块、APNG |
| `store.py` | ~400 | **数据层**(2026-10-05 新增):SQLite 建库 / 第一次启动自动导入旧 JSON / 存取 / 导出回旧格式 / 体检 / 热备份 |
| `tests/回执复现测试.py` | ~280 | 回归 + 漏洞复现(27 条,HTTP 层打接口) |
| `tests/数据库测试.py` | ~290 | 数据库专项(37 条:全新安装、迁移、回退、事务、并发、规模),数据全是现编的 |
> 这几个文件是**自足**的:没有 import 本项目之外的模块。**部署时 `store.py` 必须和 `server.py` 放在同一个目录**(`server.py` 直接 `import store`)。
---
## 四、对外接口
全部挂在 `/order/api/` 下(nginx 反代);下面路径已按脱敏规则替换过前缀,**看形状别看字面**。
| 方法 | 路径 | 谁用 | 说明 |
|---|---|---|---|
| GET | `/api/status` | 页面轮询 | 渲染机在线?队列长度 |
| POST | `/api/submit` | 页面 | 皮肤(base64) + 模板数组 + 卡密数组 + 臂型 → 返回 `{order, token}` |
| POST | `/api/add-skin` | 页面 | 追补一张皮肤(多皮肤单) |
| POST | `/api/set-templates` | 页面 | 改/补模板(可只改某一张皮肤的) |
| GET | `/api/order/<单号>?t=<口令>` | 页面 | 状态 + 可下载文件清单 + 进度 + 预计耗时 |
| GET | `/api/dl/<单号>/<i>?t=<口令>` | 买家 | 下载成品(未收货只能拿预览) |
| GET | `/api/zip/<单号>?t=` | 买家 | 整单原图打 zip(先落临时文件再边读边发) |
| GET | `/api/receipt/<单号>?t=` | 买家 | 小票纯文本(`&dl=1` 变附件) |
| POST | `/api/accept` | 买家 | 确认收货 → 才放原图 |
| POST | `/api/paid` | 买家 | 「我付好了」 |
| POST | `/api/activate` | 买家 | 用卡密**激活自己那一单**(码认单,不开新单) |
| POST | `/api/redo` | 买家 | 重渲(支持只重出勾中的那几张) |
| POST | `/api/call` | 页面 | 呼叫店主(同 IP 限次) |
| POST | `/api/feedback` | 页面 | 反馈(落盘 + 通知) |
| GET | `/api/payinfo` | 页面 | 付款方式(链接/收款码) |
| POST | `/api/payplatform-hook` | 支付平台回调 | **不验签,改成拿开放接口反查这笔单**(见下) |
| POST | `/api/hb` `/api/claim` `/api/skin/<单号>` `/api/progress` `/api/finish` `/api/fail` | **渲染机** | 都要请求头里的 worker token |
| GET/POST | `/api/admin/*` | **本机后台面板** | 头里带 admin token **且**来源 IP 必须是家里出口 IP |
**2026-10-05 管理接口新增四个**(都在上面那两道门后面;**老接口的路径和字段一个没动**):
| 方法 | 路径 | 干什么 |
|---|---|---|
| GET | `/api/admin/calls?limit=` | 「呼叫店主」/ 反馈 / 部分失败 记录,新的在前;`open` = 还没处理的条数 |
| POST | `/api/admin/call-done` | `{id, undo?}` 把一条呼叫标成「处理过了」(只加 `handled` 字段,不碰 `notified`) |
| POST | `/api/admin/retry` | `{oid}` 渲染失败的单退回队列(等于 `admin.py retry`,只收 `failed` 状态的单) |
| GET | `/api/admin/codes?q=` | 原有接口**加了一个可选参数** `q`:按卡密 / 订单号 / 批次 / 平台模糊搜;不传和以前一样 |
### 支付回调的处理顺序(这段是重点,欢迎挑刺)
```
① 标题含"测试" → 只记账
② 幂等:同一平台单号重推 → 回同一张卡密
③ 反查不到 / 未付款 → 只记账 + 标 need_human,**绝不发卡密**
④ 金额比对:
少付(paid + 0.005 < need)→ **闸门拦死**,不激活不发码,记 need_human
多付 → 照样激活出图,但记 over 待人工看一眼
⑤ 认单优先级:自定义订单号 > 留言里的卡密 > 留言里的订单号 > 「只有一笔待付款单金额对得上」
(两笔及以上一律人工,绝不乱认)
```
---
## 五、数据(2026-10-05 起:SQLite)
> ⚠️ **数据格式变了,按第八节的规矩单独标出来**:卡密 / 订单信息 / 爱发电账本 / 呼叫记录 / 几块小状态
> 从 JSON 文件挪进了 `<DATA_DIR>/ys.db`。**接口路径、请求 / 响应字段都没变**,渲染机那份代码**不用动**。
### 5.1 装上就能用
1. 把 `store.py` 放到 `server.py` 旁边,照常重启服务。**什么都不用配、不用装**(`sqlite3` 是 Python 自带的)。
2. 第一次启动时自动:建库 → 如果 `<DATA_DIR>` 里有旧的 `codes.json` / `orders/*/meta.json` / 账本等,**一次性导进来**。
- 导入是一个事务:中途出错就整体回滚,下次启动再试。
- **旧文件原样留着,一个字节都不改**(测试里逐字节比对过)。
- 只导一次:库里记了「导过了」,以后重启不会重复导。
3. 自检:`python3 admin.py db check`,看到「完整性:ok」和每张表的行数就对了。
⚠️ 跑 `admin.py` 的账号要对 `<DATA_DIR>` **目录**有写权限(不只是对 `ys.db`):SQLite 的 WAL 模式会在旁边建 `ys.db-wal` / `ys.db-shm` 两个文件。
以前 `admin.py` 就要写 `codes.json`、`.lock`,权限照以前那样给就行。
### 5.2 库里有什么
| 表 | 原来在哪 | 一行是什么 | 能按什么查(有索引) |
|---|---|---|---|
| `codes` | `codes.json` | 一张卡密 | 状态、订单号、批次、平台、福利券批次 |
| `orders` | `orders/<单号>/meta.json` | 一单的信息 | 状态(只算没清理的单) |
| `pay_orders` | `payplatform-orders.json` | 一笔爱发电成交(按平台单号幂等) | 平台单号 |
| `calls` | `calls.jsonl` | 一条呼叫 / 反馈 / 部分失败 | 来源 IP + 时间(限频用) |
| `kv` | `gifts.json` / `heartbeat.json` / `home_ips.json` / `tpl_times.json` | 一块小状态 | 键名 |
每张表都是「几个能查的列 + 一列 `data`(整条记录的 JSON)」。上层代码拿到的**还是原来那个 dict**,加字段不用改表。
**还是文件、没进库的**:皮肤和成品图片(`orders/<单号>/` 目录还在)、`feedback/` 里的反馈图、
两把令牌、人手改的配置(`payplatform.json`、`payplatform-map.json`、`prices.json`、`payinfo.json`)、各种 `.log`。
**`calls.jsonl` 还会继续追加**:库是正本,但「呼叫店主」的手机通知是盯这个文件的(那段不在这份代码里),所以每条记录**同时**照旧写一行进去,通知不会断。
**清理过期订单**(`admin.py sweep`):文件照旧删掉;库里那一行**留着做账**,但之后对外当它不存在(`read_meta` 返回空),单号也不会再被发出去。
### 5.3 为什么换、换了有什么用
上一轮回执里修的竞态(一码两单、CLI 和服务器互相覆盖、账本丢记录、半截 JSON),根子都是「拿 JSON 文件当数据库」。换成 SQLite 之后:
| | 以前(JSON 文件) | 现在(SQLite) |
|---|---|---|
| 断电 / 进程被杀 | 可能留下半截或 0 字节的 `codes.json`(后来加了 fsync 才堵上) | 事务要么全写进去、要么全没写 |
| 改一张码 | 整个 `codes.json` 重写一遍 | 一个事务里只改有变化的那几行 |
| 列出排队的单 | 把每一单的 `meta.json` 都读一遍 | 走索引:2000 单时 **38 ms,以前 1238 ms**(测试第 11 节实测) |
| 两个进程同时写 | 靠 `.lock` 文件锁 | `.lock` 照旧保留,库本身再兜一层(WAL + 等锁 30 秒,不会报 locked) |
| 查账 / 统计 | 只能自己写脚本扫文件 | 直接 SQL;`admin.py db check` 按状态出数 |
| 备份 | 拷整个目录(拷的时候可能有半截写入) | `admin.py db backup` 在线热备份,服务不用停 |
代价:多一个 `store.py`;库文件不能直接用记事本改(要改用 `sqlite3` 命令行,或者先导出成 JSON 改完再导回)。
### 5.4 运维命令
| 命令 | 干什么 |
|---|---|
| `python3 admin.py db check` | 完整性检查 + 每张表几行 + 订单 / 卡密按状态的数 + 当初导入了多少 |
| `python3 admin.py db backup` | 在线热备份到 `<DATA_DIR>/backup/ys-<时间>.db`(600 权限) |
| `python3 admin.py db export [目录]` | 把库导回**旧版 JSON 格式**;不写目录 = 写回 `<DATA_DIR>`(会覆盖那几个旧文件) |
| `python3 store.py check / backup / export` | 同上(不用 `admin.py` 也能跑,要先设 `YS_ROOT`) |
### 5.5 回退到旧版
1. 停服务 → `python3 admin.py db export`(把库里的最新数据写回 `codes.json` / `meta.json` / 账本 …)
2. 换回旧版 `server.py` / `admin.py` → 启动。旧版只认 JSON 文件,`ys.db` 放着不碰也没关系。
3. 以后要再切回来:先删掉(或挪走)`ys.db`,新版启动时会从 JSON 重新导入。
测试第 7 节验证过:导出 → 再导入,卡密 / 订单 / 账本 / 呼叫 / 小状态**一模一样**。
### 5.6 测试
```
python3 tests/数据库测试.py <server.py 所在目录> # 37 条:数据库专项
python3 tests/回执复现测试.py <server.py 所在目录> # 27 条:回归 + 漏洞复现(现在跑在数据库上)
```
- 数据全是测试脚本**现编的**(假卡密、假订单、假呼叫,包括一行写坏的 `calls.jsonl`),建在系统临时目录,不碰 `<DATA_DIR>`。
- 交付副本里三个 URL 格式串被脱敏弄坏了(`http<WIN-PATH>`),要起服务器的那几节跑之前先换成能格式化的占位;线上原版直接跑。
- 2026-10-05 结果:**64 条全过**。另外用假数据把服务器 + 后台面板 + 浏览器整条链路点了一遍(见 `backend-tools/交接说明.md`)。
### 5.7 文件 / 目录(库以外的)
| 路径 | 内容 |
|---|---|
| `<DATA_DIR>/ys.db`(+ `-wal` / `-shm`) | 上面那个库(640 权限) |
| `<DATA_DIR>/orders/<单号>/skins/` | 买家皮肤原图(落盘前已过 PNG 结构核验并剥掉元数据块) |
| `<DATA_DIR>/orders/<单号>/out/` | 成品(标准压缩 + 无压缩 两个版本/张) |
| `<DATA_DIR>/worker_token`、`admin_token` | 两把**互不通用**的令牌(文件权限 600) |
| `<DATA_DIR>/calls.jsonl` | 呼叫记录的**副本**(给手机通知读,正本在库里) |
| `<DATA_DIR>/upload.log` 等 | 审计留痕 |
| `<DATA_DIR>/codes.json`、`orders/*/meta.json` … | **旧数据**:导入之后就不再读写,留着当回退的底 |
### 卡密生命周期(**激活 ≠ 核销**,这是刻意分开的)
```
active 可用
↓ 买家点提交
bound **已激活** —— 被这一单占住,不能用于别的单;但还没核销
↓ 成品开放下载满 72 小时(或直发单从渲完起算)
used **已核销** —— 终态
inactive 停用(网页单等付款 / 手动停用)
```
⚠️ 触发核销的只有两处,**删文件之前必须先核销**,否则文件没了码还挂在"已激活"。
---
## 六、已经做了的防护(请你对着挑漏)
| 防护 | 做法 |
|---|---|
| 卡密暴力破解 | 31 字符取 12 位 ≈ 7.9e17 组合;**单 IP 连错 15 次 → 冷却 15 分钟** |
| 灌单 | 单 IP 10 分钟最多开 6 单;提交接口在 nginx 上单独限流 |
| 探测 | **「订单不存在」与「口令错」返回同一个 404**(不承认站上有这单) |
| 占盘 | 磁盘剩余低于阈值**停止收单** |
| 夹带私货 | PNG 结构核验:拒尾部追加 / 未知关键块 / APNG;剥掉文本与 EXIF 类元数据块 |
| 取皮肤 | 必须带 worker token |
| 管理接口 | **两道门**:token + 来源 IP 必须是家里出口 IP(公网别处扫到也是 403) |
| 路径穿越 | slug 白名单 + realpath 前缀校验 |
---
## 七、⚠️ 脱敏说明(**重要:这份代码不能直接跑**)
按我们的出站纪律,**所有指向真实环境的值都换成了占位**:
| 类别 | 替换成 |
|---|---|
| 站点域名 / 支付平台域名 | `shop.example.com` / `pay-platform.example` |
| 监听端口、面板端口 | 中性数字(`8080`/`8081`/`8082`…)—— **不是真值** |
| 数据 / 程序 / 工作目录 | `<DATA_DIR>` / `<APP_DIR>` / `<WORKER_DIR>` |
| Windows 盘符路径 | `<WIN-PATH>` / `<ARCHIVE_DIR>` / `<TOOLS_DIR>` |
| 家里出口 IP / 局域网 IP | `<HOME-LAN-IP>` / `<LOCAL-IP>` |
| 通配绑定地址 | `<ALL-INTERFACES>` |
| 密钥 / 令牌**值** | 本来就没有硬编码——全走文件与环境变量,所以代码里是干净的 |
**保留未换的**:`localhost`(回环,通用值)、渲染分辨率 `1000/1024/2048/4096`(业务常量)、
以及**品牌笔名**(属公开署名)。
**包里没有的**(⚠️ 别去找,是刻意不给):
- 任何真实卡密、订单、买家皮肤与成品图
- 两把令牌、任何密钥、任何账号凭据
- 数据库/运行数据、备份
- 私有仓库地址、内部文档
---
## 八、⭐ 我们要你交给我们的东西(**这一份的主要目的**)
请你读完之后**回一份文档**(放在同一个仓库里就行,文件名 `回执-<你的名字>.md`),至少包含三部分:
> 📋 **格式不用自己起** —— 仓库根目录有一份 `回执模板.md`,照着填就行。
1. **问题分析** —— 你看到的问题、风险、坏味道。分个轻重(会导致丢钱/丢数据/被人打的,排前面)。
请**尽量指到具体函数/行**,并说清**触发条件**(什么输入、什么并发时序会踩到)。
2. **改正意见** —— 每条给**你建议怎么改**(不一定要写代码,说清思路和代价也行)。
如果有**更简单的整体方案**(比如"这段根本该换个做法"),也请直说,别客气。
3. **你改了什么** —— 如果你直接动手改了,请逐条列:
```
文件 / 函数:
为什么改:
改成什么(一句话说清):
有没有动到接口路径、请求/响应字段、数据格式(**这三样动了我们必须知道**):
你怎么验证的(跑过什么、看到什么):
```
⚠️ **改了接口/数据格式一定要单独标出来** —— 渲染机那边是另一台机器上的另一份代码,
两边不同步会**静默出不来图**。
**另外请你顺手回答两个具体问题**(我们自己拿不准):
- 爱发电那条线**"不验签、改成拿开放接口反查"**,你认为够不够硬?有没有更好的做法?
- 订单状态机(`unpaid → paid → waiting → working → done/failed`)在**部分失败**时
(比如 3 张图渲出 2 张)你建议怎么收口?
---
## 九、我们的思路与方法(**请你连这套做法一起评**)
代码能看出的是一部分;**为什么这么做、踩过什么坑**,在代码里看不到。这一节补上,
**并且希望你连"做法"本身一起挑** —— 如果我们整套思路就是错的,那比某个函数写错更要紧。
### 9.1 我们给自己定的几条硬规矩
| 规矩 | 为什么 |
|---|---|
| **无人值守优先**:机器的活不该让人 24 小时待命 | 这行的买家半夜下单是常态,靠人盯必然漏 |
| **正常用户一步都不多加**:每加一道防探测,先问"正常买家会不会被误伤" | 防的是坏人,误伤的是给你钱的人。两者冲突时**先保买家** |
| **收钱的数字一律以服务器订单为准**,本地状态只能当兜底 | 踩过:恢复订单时本地状态是空的,按本地算出错的金额去拼付款链接 → 买家少付 → 闸门拦死。**同一行显示两个来源的数,必然自相矛盾** |
| **状态话术不许骗人** | 踩过:没付款的单子被兜底文案说成"正在排队"。宁可说"没取到订单信息",也不给假安心 |
| **出错要说清是什么、下一步怎么办**,不引导用户猜 | 报错是给人看的,不是给日志看的 |
| **同一件事的逻辑只写一处** | "CLI 一套、后台面板一套"必然漂移 —— 出现过面板和命令行生成出两种卡密 |
### 9.2 我们干活的方法(改这块代码时照着来)
1. **改一处 → 顺着所有调用点核一遍**。可见性逻辑被好几个入口调用,改了一处、
别的入口还传旧参数 → 出现"导航正常、首页却说没有可见内容"这种**看着像站坏了**的现象。
2. **同一个东西存在两处时,先问"读取方是按哪个字段找的"**。改写入方不改读取方 =
写进去了、读的还是旧的(踩过:换了皮肤文件、但路径字段没跟着改,买家看到"重渲了还是旧图")。
3. **前端必须真的在浏览器里点一遍**。有一批 bug 在 API 层**根本测不出来**
(页面上某个渲染函数调了不存在的名字 → 每次进第 2 步就抛异常 → 页面看着"就是没反应")。
4. **部署完要核对"跑的是不是新代码"**,不是"部署脚本说成功了"。
踩过:脚本全程报成功、功能静默缺失 —— 旧进程还活着,计划任务的"运行"不会替换它。
5. **自测的每一个负例各用一份新数据**。复用同一份的话,第一条成功就把它消耗了,
后面几条测的其实是"已经用过了"—— **全绿,但什么都没测到**。
6. **测完必须清场**。测试产生的记录不许留在管理员看得见的列表里。
### 9.3 我们付过学费的坑(这些是"不要重复踩"清单)
- **静默失败最贵**:不报错、不崩,就是没效果 —— 比抛异常难查十倍。
所以我们宁可让它**响亮地失败**(比如离线就不显示预计时间、宁可说"没取到")。
- **显示层会骗人**:订单本身算对了,但界面从另一个来源取数 → 用户看到的是错的。
**凡是"从 A 推导出 B"的函数,在别处读 B 之前都要先调一次它**。
- **文件重复投递**:渲染机与服务器之间"一张图一次"回传,是因为一次全传会撞体积上限。
- **重试要有上限也能收敛**:部分失败必须显式收尾,否则订单会永远停在"渲染中"、被反复重渲。
### 9.4 我们最想要你评的三件"做法"
1. **"不验签、改成拿开放接口反查"**这个取舍,你认同吗?(我们手头没有对方的公钥,与其猜算法不如反查)
2. **订单状态机在部分失败时怎么收口**(3 张渲出 2 张)—— 我们现在靠"显式收尾",你觉得够不够。
3. **这套"单文件纯标准库"的写法**:好处是零依赖零安装、小机器跑得动;
代价是路由/校验/序列化全得自己写。**换你,你会不会上框架?** 请直说。
---
## 十、边界
- 这份是**私有交付**,**请勿外传 / 勿镜像 / 勿公开**(含截图、片段)。
- 里面是**占位值**,请不要替换成任何真实地址再提交回来。
- 有看不懂的先问,别猜着改 —— 猜错了我们这边会静默坏掉。
- 你可以自由重构,但**动了接口/数据格式要按第 8 节单独标出来**。