Files
jinzuanwork/backend/backend-site/交接说明.md
T
Suda c6034e9acd backend: 补《他应该知道的》与《回执模板》,并指路
- 他应该知道的.md:生意背景/机器约束/数据边界/术语表/我们的纪律
- 回执模板.md:照着填即可(问题分析+改正意见+你改了什么+我方问题+运维个人想问的)
- 两份交接说明里指向回执模板;仓库根 README 标出两批交付
2026-10-05 18:55:16 +08:00

250 lines
14 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(无外部服务) |
| 规模 | 单机单进程,日单量个位数到几十 |
**为什么不用框架**:这台机器很小(1G 多内存),装一个 Web 框架 + 一堆传递依赖不划算,
而且这台机器**不允许跑重活**(视频转码这类会把它拖死)。纯标准库启动快、内存稳。
---
## 三、文件清单
| 文件 | 行数 | 干什么 |
|---|---|---|
| `server.py` | ~3100 | **全部服务端逻辑**:路由、订单状态机、卡密生命周期、限流、PNG 结构核验的调用方、爱发电回调、打包下载、小票生成 |
| `admin.py` | ~540 | 命令行管理工具:发卡密 / 看队列 / 重渲 / 清过期 / 审计被拦记录 |
| `pngcheck.py` | ~130 | PNG **结构**核验(不解码像素):防「夹带私货」——尾部塞字节、未知关键块、APNG |
> 这三个文件是**自足**的:没有 import 本项目之外的模块。
---
## 四、对外接口
全部挂在 `/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 |
### 支付回调的处理顺序(这段是重点,欢迎挑刺)
```
① 标题含"测试" → 只记账
② 幂等:同一平台单号重推 → 回同一张卡密
③ 反查不到 / 未付款 → 只记账 + 标 need_human,**绝不发卡密**
④ 金额比对:
少付(paid + 0.005 < need)→ **闸门拦死**,不激活不发码,记 need_human
多付 → 照样激活出图,但记 over 待人工看一眼
⑤ 认单优先级:自定义订单号 > 留言里的卡密 > 留言里的订单号 > 「只有一笔待付款单金额对得上」
(两笔及以上一律人工,绝不乱认)
```
---
## 五、数据形状(都是文件/JSON,没有数据库表)
| 路径 | 内容 |
|---|---|
| `<DATA_DIR>/codes.json` | 卡密池:`{码: {state, platform, tpl, n_fix, n_free, n_max, lock_tpl, oid, order, batch}}` |
| `<DATA_DIR>/orders/<单号>/meta.json` | 订单:状态、皮肤数组、模板、金额、时间、条款留证、进度 |
| `<DATA_DIR>/orders/<单号>/skins/` | 买家皮肤原图(落盘前已过 PNG 结构核验并剥掉元数据块) |
| `<DATA_DIR>/orders/<单号>/out/` | 成品(标准压缩 + 无压缩 两个版本/张) |
| `<DATA_DIR>/worker_token`、`admin_token` | 两把**互不通用**的令牌(文件权限 600) |
| `<DATA_DIR>/home_ips.json` | 渲染机心跳认出来的「家里的出口 IP」 |
| `<DATA_DIR>/calls.jsonl` | 「呼叫店主」记录 |
| `<DATA_DIR>/upload.log` 等 | 审计留痕 |
### 卡密生命周期(**激活 ≠ 核销**,这是刻意分开的)
```
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 节单独标出来**。