Files
ywsandClaude Opus 5.5 09b229deee portal: 金钻宇宙换成星系图(three.js 懒加载)+ 推送前审查 + 总交接文档
- 门户「金钻宇宙」:删掉启动仪式 / 宇宙首屏晶体 / 盘符机架 / 读盘舱及其 CSS、图标;
  换成星系图(portal/assets/universe/,three.js r170 自托管于 assets/vendor/,第一次打开板块才下载)
  + 窗下世界线卡片;#0001 深链飞到对应世界线;世界线数据只留 config.js 一份
- 像素字子集重做(旧字全保留 + 新字);其余板块与改动前逐像素一致
- 后端审查:add_call 写库失败不再打断渲染机回传;多进程同时首启只导入一次(+1 条测试,共 38);
  撤销「处理过了」清掉 handled_at
- 交接文档-2026-10.md:变更清单 / 功能增删 / 接口与数据格式变更 / 设计规范 / 业务逻辑 / 部署运维
- 交付清单哈希重算;README、旧交接说明指路

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 17:31:36 +00:00

385 lines
37 KiB
Markdown
Raw Permalink 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.
# 回执 · Claude(受 ywsabc2 委托)· 2026-10-05
> 范围:`backend-site/`(server.py / admin.py / pngcheck.py)+ `deploy/nginx-片段.md`,以及它和前端 `order/index.html` 的对接。
> 渲染机 / 本机工具那边单独一份:`backend-tools/回执-Claude.md`。
> 行号一律指**交付时的原版**(提交 `c6034e9`)。
> 我改过的地方都在 `server.py` / `admin.py` 里标了「2026-10-05(外部复查)」,搜这几个字就能全部找到。
---
## 0. 一句话总结
整体思路是对的(无人值守、渲染机只出站、收钱以服务器为准、话术不骗人),工程习惯也好(决定留痕、踩坑写进注释)。
**最该先修的是「钱」和「数据」上的并发 / 信任问题**:一码两单、前端报的张数被直接信、支付回调重放白送码、
CLI 和服务器互相覆盖 `codes.json`、`sweep` 会删掉还在排队的已付款单。
这些我**都已经改了,并且写了复现测试**:同一套 27 条用例,原版失败 13 条、改后全部通过(见第 3 节末尾)。
**接口路径一条没动**;接口字段只**新增**了一个(`/claim` 返回里的 `terms_v`),渲染机那边不用改代码。
---
## 1. 问题分析
> 🔴 = 会丢钱 / 丢数据 / 能被人利用;🟡 = 静默失败、显示骗人、能把机器拖死;🟢 = 小问题 / 坏味道。
> 「已修」= 这次直接改了;「建议」= 只给意见没动(多半是要你们拍板,或者动的是部署层)。
| # | 严重度 | 位置(原版) | 问题是什么 | 触发条件 | 影响 | 状态 |
|---|---|---|---|---|---|---|
| 1 | 🔴 | server.py `submit` 1626 查码 → 1741 绑码 | 「查码」和「绑码」在**两次加锁**里,中间隔着 base64 解码、PNG 核验、落盘 | 同一张码**同时**提交两次(连点、两个标签页、脚本) | **一码两单**。实测:并发 6 次成了 2 单 | 已修 |
| 2 | 🔴 | server.py `submit` 1635-1637 | 卡密规则用的张数 / 模板并集是**前端报的** `nTotal` / `tplUnion`,真提交的 `templates` 不受它约束 | 「固定 1 张」的码 + `templates` 塞 7 个 + `nTotal=1`;锁模板的码 + `tplUnion=锁定那组` + `templates=别的` | **花 1 张的钱出 7 张**;锁模板(试玩券)形同虚设。实测两条都能过 | 已修 |
| 3 | 🔴 | server.py `payplatform_hook` 2014 | 幂等只认「发过码」。「对上网页单并激活」那条路记的是 `code=None` | 同一笔单再推一次:爱发电自己会重试;这个地址又是公开的,谁都能把报文原样再 POST 一次 | 第二次激活失败(单子已在排队)→ 掉进「按买码处理」→ **白送一张码,还写在返回体里**。实测:重放一次多出 1 张码 | 已修 |
| 4 | 🔴 | server.py `LOCK = threading.Lock()` 151;admin.py 各命令 | 锁只管**本进程**的线程。admin.py 是另一个进程,同样读-改-写 `codes.json` / `meta.json` | CLI 发码 / 改码 / retry 的同时,网页上有人下单 | 互相覆盖。**实测:CLI 发 200 张,最后文件里只剩 15 张;还有已下单的码被改回「可用」** | 已修 |
| 5 | 🔴 | admin.py `cmd_sweep` 279 + server.py `expire_at` | 没开放下载的单,到期按「创建 + 72h」算,**不看状态** | 渲染机关了三天(出差、断网、坏了),或者买家报了付款、金钻还没确认 | 排队中 / 待确认的单被**整目录删掉**,码还被记成「已核销」:钱收了、皮肤没了、图也没出。实测:5 天前的排队单被删 | 已修(只跳过 waiting/working/paid,见第 2 节 #5 的取舍) |
| 6 | 🔴 | server.py `new_oid` 713 / `new_owner_token` / `gen_codes` 742 / 批次号 / 反馈号 | 卡密、订单号、**取件码**都用 `random`(梅森旋转,不是密码学随机) | 攻击者攒够输出(反复领福利券、反复下网页单都会拿到码和取件码)就能还原内部状态 | 能**预测之后要生成的卡密和别人的取件码**。7.9e17 的码空间只防「盲猜」,防不住「预测」 | 已修(换 `secrets`,格式不变) |
| 7 | 🔴 | server.py `redo` 2340 | 重渲换皮肤:只 base64 解一下、看大小就落盘,**没走 PNG 结构核验** | 任何拿着自己取件码的人 | 「夹带私货」防护整个绕过,而且这个文件会直接发到家里那台电脑上给 Blender 读。实测:尾部夹带 18 字节照样落盘 | 已修 |
| 8 | 🟡 | server.py `feedback` 2413 | 不限频、不看磁盘;每条能存一张 4MB 的「图」(不校验是不是图),还往 calls.jsonl 写一条「呼叫」 | 写个循环 | 把盘写满(盘满后所有 `jsave` 都会失败);金钻手机通知被刷爆 | 已修 |
| 9 | 🟡 | server.py `download` 2559 | 下载原图是 `f.read()` 整张读进内存 | 4096 的无压缩 16bit 一张几十 MB,几个人同时下 | 服务 `MemoryMax=256M`,会被 OOM **整个杀掉**(你们说这是最值得报的一类) | 已修(边读边发,和 zip 一样) |
| 10 | 🟡 | server.py `class H` 里的 `def finish` 2694 | 和 socketserver 的 `StreamRequestHandler.finish()` **重名**。框架在**每个请求**处理完都调一次 `self.finish()` | 任何请求 | 每个请求结束后都把「回传成品」再跑一遍:多写一个 403;带渲染机令牌的请求还会再去读一次请求体(读到连接关闭才返回)。日志里大量「Exception occurred during processing of request … in finish」就是它(测试里原版一轮 32 条,改后 0 条) | 已修(方法改名,路径不变) |
| 11 | 🟡 | server.py `finish` 2754 / 2764;`order_detail` 1802-1808 | 渲染机收单(`close`)**不带 total**,服务器退回按「模板数」算;渲染机的 total 是按**文件数**(每模板 2 张)报的。另外部分失败照样标「已完成」,原因只写进 note,而 done 状态的页面文案会把 note 盖掉 | 有模板渲失败、或回传失败(见渲染机回执里的 16MB 上限问题) | **静默少交货**:买家看到「渲染完成」,金钻也收不到任何提醒 | 已修(见第 3 节) |
| 12 | 🟡 | server.py `activate` 2229-2282 | 同 #1:查码和绑码不在同一把锁里;而且输错码**不计数** | 同一张码同时激活两张网页单;拿这个接口试码不触发冷却 | 一码两单;试码没有冷却 | 已修 |
| 13 | 🟡 | server.py `edit_code` 1253(锁外读、锁里写)、`gift_batch_add` 464-467(锁外读写) | 读-改-写不在同一把锁里 | 面板改码 / 补福利券的同时有人下单或领券 | 存回去的旧快照把别人刚改的码冲掉(码被改回「可用」= 一码两用) | 已修 |
| 14 | 🟡 | server.py `jsave` 655 | 临时文件名固定是 `path + ".tmp"`;写完不 fsync | 两个线程 / 进程同时写同一个文件;或者写完马上断电 | 互相截断出半截 JSON;断电后可能留一个 0 字节的 `codes.json`(`jload` 读坏了会**静默**当成空字典 → 整个码池「消失」) | 已修 |
| 15 | 🟡 | deploy/nginx-片段.md | `/order/api/submit` 的 `client_max_body_size 4m`,但后端和页面都说皮肤最大 10MB(base64 后约 13.4MB);`add-skin` / `redo` / `feedback` 走通用 location,**没配大小 = nginx 默认 1MB** | 买家传一张 3MB 以上的皮肤;追补 / 重渲换一张 700KB 以上的皮肤;反馈带一张截图 | nginx 直接回 413 的 HTML,前端 `r.json()` 解析失败 → 买家只看到一句笼统的失败,不知道是图太大 | **建议**(部署层,见第 2 节;如果你们线上的值和片段一样的话) |
| 16 | 🟡 | server.py `ip_of` + `admin_ip_ok` 708 | 管理接口的 IP 门靠 `X-Real-IP`;取不到就用连接来源 —— 经过 nginx 时连接来源**永远是回环**,而回环在白名单里。原版白名单里还有 `"?"` | 哪天某条 location 漏配 `proxy_set_header X-Real-IP` | 来源变成回环 → IP 这道门对公网失效,只剩令牌一道 | `"?"` 已去掉;其余**建议**(第 2 节) |
| 17 | 🟡 | server.py `order_detail` 1793 | 文案里写了 Markdown 的 `**已经付过款,不用再付款**`,页面当纯文本显示 | 每一张卡密单 | 买家看到两对星号(我在浏览器里端到端点了一遍看到的) | 已修 |
| 18 | 🟡 | `order/index.html` 条款全文 vs server.py `TERMS_VERSION` | 页面上条款全文标的是「版本 2026-10-01.1」,提交时记进订单的是 `2026-10-04.1` | 每一单 | 「订单里记版本号,日后争议时证明买家当时同意的是哪一版」—— 现在记的版本和买家看到的那份**对不上** | **没动**:不知道是只改了版本号、还是条款内容也改了,要你们定 |
| 19 | 🟡 | server.py `claim` 2606 + ys_worker.py 26 / 438 | 派单不带订单的条款版本,渲染机留档时只能用自己写死的 `2026-10-01.1` | 每一单 | 永久留档里的「条款版本」全是错的 | 已修(`/claim` 新增 `terms_v`,渲染机本来就先读它,不用改) |
| 20 | 🟡 | server.py `download_zip` 2879 | PNG 再 `ZIP_DEFLATED` 一遍几乎不变小、白烧 CPU;**不限并发**,每个包最大 600MB 临时文件 | 同一个取件码连点 / 并发几次 | 盘和 CPU 一起被占满 | 已修(成品 STORED + 同时只打一个包) |
| 21 | 🟢 | server.py `my_coupons` 2462 / `coupon_status` | 一次查 60 张券 = 读 60 遍 `codes.json`;不限频 | 刷这个接口 | CPU;另外它和 `/api/code/<码>` 都能当「码是否存在」的查询口子,不计输错 | 读文件次数已修;查询口子在换成 `secrets` 之后风险可以忽略 |
| 22 | 🟢 | server.py `activate_payplatform` 2176 | 按「订单号**后缀**匹配」(≥10 位)+ 输错不计数;账本读写不在锁里 | 猜别人订单号的后 10 位 | 理论上能把别人付的款激活到自己单上(概率很低);账本和回调同时写会丢记录 | 计数 + 加锁已修;后缀匹配**建议**改成全号匹配(要你们看买家实际怎么复制) |
| 23 | 🟢 | server.py `ThreadingHTTPServer` | 线程数不设上限 | 慢请求堆积(ffmpeg 预览、打包、大下载) | 小机器上线程 + 内存一起涨 | **建议**:重活加信号量(zip 已加),或 nginx `limit_conn` |
| 24 | 🟢 | server.py `queue_pos` 1169 / `heartbeat` 1230 / `claim` | 每次都把 `orders/` 下所有 `meta.json` 读一遍 | 订单目录攒多了(sweep 不常跑的话) | 现在几十单无所谓;几千单就慢 | **建议**:现在不用动 |
| 25 | 🟢 | 脱敏误伤:server.py 53、2095、2150 | 脱敏把带 `%s` 的 URL 格式串整个换成了 `"http<WIN-PATH>"`,格式化时会 `TypeError` | 只影响你们给出来的这份 | 不是线上问题,但说明**脱敏规则会吃掉 URL 里的 `%s`**,下次出站可以留意 | 没动(占位值按要求保持原样) |
| 26 | 🟢 | 前端没在用的接口 | 交给我的这份 `order/index.html` 里**没有调用** `/api/activate`、`/api/activate-payplatform`、`/api/set-templates` | — | 要么是死接口(多一份攻击面),要么是前端副本比线上旧 | **问你们**:线上页面还调不调这三个? |
| 27 | 🟢 | 其它小问题 | `order_detail` 返回体里 `"amount"` 写了两遍;`IP_FAILS` 等计数字典对「只来一次的 IP」永不清理;`call()` 每次读整个 calls.jsonl;pngcheck 不检查 IHDR 长度 / 取值、IDAT 里 zlib 流结束后的多余字节 | — | 都很轻 | 没动 |
**我怀疑但没验证的**(没有真实环境):
- **ffmpeg 生成 4096 预览的内存**:解一张 4096×4096 的 8bit RGBA 要约 64MB,加上缩放缓冲,和 Python 进程本身共用 256M 的 cgroup。正常应该过得去,但几单同时完成时可能顶到。建议实测一次 4096 单的峰值内存。
- **2048 / 4096 的无压缩 16bit 回传会超过 16MB 上限**:详见渲染机那份回执第 1 条。如果成立,这些单会静默少一张无压缩版。#11 的修改至少能让它**不再静默**。
---
## 2. 改正意见(只列我没改、或者改了但你们要知道取舍的)
| 对应 # | 建议改法 | 代价 / 风险 | 优先级 |
|---|---|---|---|
| 5 | 我只让 sweep **跳过** `waiting / working / paid`(还在流水线上的)。`unpaid`(一直没付款)和 `done` 还没收货的,照旧 72h 后清。**另外建议**:`done` 但没确认收货的单,到期从**完成时间**算,而不是创建时间 —— 不然渲染机晚上线两天,买家只剩一天能收货 | 一行,改 `expire_at`;这是业务口径,你们定 | 中 |
| 15 | nginx:`/order/api/submit` 的 `client_max_body_size` 改成 **15m**(和后端 `MAX_BODY` 一致);给 `add-skin`、`redo` 单独配 15m,`feedback` 配 6m。再给它们加 `error_page 413 = @json413;` 回一段 `{"ok":false,"error":"图片太大"}`,前端不用改就能显示人话 | 改配置 + reload,不停机 | **高**(直接影响买家能不能下单) |
| 16 | 最稳:管理接口单独监听一个端口(或者单独一条 nginx location 带 `allow <家里 IP>; deny all;`);后端看到「来源是回环但没带 X-Real-IP」就当成**未知**而不是**本机**。至少在 nginx 每条 location 都确认带了 `proxy_set_header X-Real-IP $remote_addr;`(片段里 `/finish` 那条被省略了,看不出有没有) | 小 | 中 |
| 18 | 条款版本号和全文**放一处**(比如后端 `/api/payinfo` 顺带返回 `terms_v` + 全文,页面照着显示),改一处两边一起变 | 改前端要走前端那边的流程 | 中 |
| 22 | 爱发电订单号改成**全号匹配**(或至少 ≥ 20 位);买家复制时多出的空格 / 换行前端已经洗掉了 | 一行 | 低 |
| 23 | `submit` / `add-skin` 收的请求体一个约 15MB,解码 + 清洗 + 原串一共约 4~5 份拷贝 → 单个请求峰值 ~50MB;**5 个并发就顶到 256M**。建议 nginx `limit_conn`(每 IP 2 个)+ 应用层给「收图」接口加一个 `BoundedSemaphore(2)` | 小 | 中 |
| 新 | **取件码在 URL 的 query 里**(`?t=`),所以它会进 nginx access log、浏览器历史,订单页上点外链时还会带进 `Referer`。建议:订单页加 `Referrer-Policy: no-referrer`;nginx 的 access log 用不带 `$args` 的 log_format(或把 `t=` map 掉);`payplatform-hook.log` 现在是**整包 headers 落盘**,注意别把平台带过来的鉴权头长期留着 | 改配置 | 中 |
| 新 | **下载不留痕**:买家说「我的图被别人下了」,现在没法自证。建议 `/dl` `/zip` 各记一行审计(时间、单号、第几张、IP、UA,**不记取件码**) | 小 | 中 |
| 中期 | `codes.json` + 各种 jsonl / 账本 → **SQLite**(标准库自带 `sqlite3`,零依赖)。这次修的竞态(#1 #4 #12 #13 #14 + 账本)本质都是「文件当数据库用」:拿事务一把就全解决了,不用到处想锁。交接说明里写了「数据全在本地文件 + 一个 SQLite」,但代码里没看到 SQLite —— 是不是另有东西没给? | 一次迁移脚本 + 改数据层;接口不用动 | 中(不急,锁已经补上了) |
---
## 3. 你改了什么
> 所有改动都在 `backend-site/server.py`、`backend-site/admin.py`(+ 渲染机那份回执里的 `backend-tools/ys_local.py`)。
> **接口路径:一条都没动。** 下面每条都单独标了「接口路径 / 请求响应字段 / 数据格式」三样。
### 改动 1 · 校验 + 绑码同锁(一码两单)
```
文件 / 函数:server.py 新增 redeem_bind() / unbind_codes() / _redeem_check();submit()、activate() 改用 redeem_bind()
为什么改:问题 #1、#12
改成什么:查码和绑码放进同一把锁;绑不上(被别的提交抢先了)就整单不收、删掉刚建的目录;
订单写盘失败就把码放回 active。redeem() 保留,只查不占码,判断逻辑和 redeem_bind 共用一份。
⚠️ 有没有动:接口路径 [否] 请求响应字段 [否] 数据格式 [否]
(并发冲突时多一种报错文案,和原来「这张卡密已经用来下过单了」是同一句)
怎么验证的:同一张码并发提交 6 次 → 原版成 2 单,改后成 1 单;正常卡密单、网页单 + 卡密激活回归通过
有没有引入新的依赖:没有
```
### 改动 2 · 卡密规则不再只信前端报的张数
```
文件 / 函数:server.py submit()
为什么改:问题 #2
改成什么:张数取 max(前端报的 nTotal, 这次真提交的模板数);模板取两者并集;不认识的模板 key 提交时直接拒
⚠️ 有没有动:接口路径 [否] 请求响应字段 [否] 数据格式 [否]
正常页面报的 nTotal 本来就 ≥ 第一张皮肤的模板数,对正常买家没有变化
怎么验证的:「固定 1 张」+7 模板+nTotal=1 → 拒;锁模板 + 伪造 tplUnion → 拒;
多皮肤单(第 1 张 2 个模板、整单报 3 张)照常能交
有没有引入新的依赖:没有
```
### 改动 3 · 支付回调幂等 + 串行
```
文件 / 函数:server.py payplatform_hook() → 拆成外层 + _payplatform_hook_locked();activate_payplatform() 同理;新增 HOOK_LOCK
为什么改:问题 #3、#22(账本读写不在锁里)
改成什么:同一个 out_trade_no「发过码」或「激活过单」都算处理过,再推一律原样回上次的 content;
回调和「用爱发电订单号激活」共用一把锁,账本不会被同时写坏;后者输错计入冷却
⚠️ 有没有动:接口路径 [否] 请求响应字段 [否] 数据格式 [否](账本结构不变)
怎么验证的:用假的反查结果模拟一笔 ¥6 付款:首次对上网页单并激活 ✔;原样重放 → 码数不变、返回同一段内容 ✔
(原版:重放一次多出 1 张码,返回体里写着「这是你的卡密」)
有没有引入新的依赖:没有
```
### 改动 4 · 跨进程锁 + 原子写加固
```
文件 / 函数:server.py LOCK 换成 _DataLock(线程锁 + <DATA_DIR>/.lock 上的 flock);jsave();admin.py cmd_retry 加锁
为什么改:问题 #4、#14
改成什么:用法不变(还是 with LOCK:),admin.py import server 后自动用同一把文件锁;
jsave 的临时文件名每次唯一 + 写完 fsync + 权限沿用原文件;拿不到文件锁就退回只用线程锁并打一行日志
⚠️ 有没有动:接口路径 [否] 请求响应字段 [否] 数据格式 [否]
⚠️ 但:<DATA_DIR> 下会多一个空文件 .lock;临时文件名从 xxx.tmp 变成 xxx.<随机>.tmp
(如果你们有脚本按 *.tmp 清理或备份,留意一下)
怎么验证的:另起一个进程连续发 200 张码,同时 HTTP 下 30 单 → 原版文件里只剩 15 张、还有 1 张已下单的码被改回可用;
改后 200 张一张不少、30 张码全部是「已激活」
有没有引入新的依赖:没有(fcntl 是标准库;Windows 上不会 import 到这里)
```
### 改动 5 · sweep 不删流水线上的单
```
文件 / 函数:admin.py cmd_sweep()
为什么改:问题 #5
改成什么:state 是 waiting / working / paid 的单跳过,不删、不核销;其它状态口径不变
⚠️ 有没有动:接口路径 [否] 请求响应字段 [否] 数据格式 [否]
怎么验证的:造一张 5 天前创建、还在排队的单,跑 admin.py sweep → 原版删掉并核销了码,改后保留
有没有引入新的依赖:没有
```
### 改动 6 · 卡密 / 订单号 / 取件码用 secrets
```
文件 / 函数:server.py new_oid() / new_owner_token() / gen_codes() / gift_batch_new() / gift_claim() / feedback()
为什么改:问题 #6
改成什么:random.choice → secrets.choice,字符表、长度、格式一个没变
⚠️ 有没有动:接口路径 [否] 请求响应字段 [否] 数据格式 [否]
怎么验证的:回归里所有生成的码都过 CODE_RE;订单号 / 取件码格式不变
有没有引入新的依赖:没有
```
### 改动 7 · 重渲换皮肤走 PNG 核验
```
文件 / 函数:server.py redo()
为什么改:问题 #7
改成什么:换皮肤改用 _read_skin()(和下单、追补皮肤同一个:尺寸 + 结构核验 + 剥元数据),落盘的是清洗后的字节
⚠️ 有没有动:接口路径 [否] 请求响应字段 [否] 数据格式 [否](不合格时多一种报错文案)
怎么验证的:尾部夹带 18 字节 → 拒、不落盘;正常皮肤换图照常可以
有没有引入新的依赖:没有
```
### 改动 8 · 反馈限频 + 磁盘闸 + 只收图片
```
文件 / 函数:server.py feedback();新增 feedback_allowed() / note_feedback() / _img_ext()
为什么改:问题 #8
改成什么:每 IP 10 分钟 5 条(超了回 429);磁盘不够回 503;「图片」只认 png/jpg/webp/gif 文件头
⚠️ 有没有动:接口路径 [否] 请求响应字段 [否]
数据格式 [是,很小]:反馈图片的文件扩展名按真实格式存(原来一律 .png),feedback/<id>.json 的 image 字段跟着变
怎么验证的:同 IP 连发 7 条 → 第 6、7 条 429;伪装成 PNG 的 exe 头不落盘
有没有引入新的依赖:没有
```
### 改动 9 · 下载 / 取皮肤边读边发
```
文件 / 函数:server.py 新增 H._send_file();download()、skin() 改用它
为什么改:问题 #9
改成什么:64KB 一块往外写,不整张进内存;响应头(Content-Type / Content-Length / no-store / Content-Disposition)完全不变
⚠️ 有没有动:接口路径 [否] 请求响应字段 [否] 数据格式 [否]
怎么验证的:下载原图字节一致、带附件头;渲染机取皮肤内容一致、Content-Length 一致;端到端下单后订单页正常
有没有引入新的依赖:没有
```
### 改动 10 · finish 方法改名(框架重名)
```
文件 / 函数:server.py H.finish → H.finish_upload(路由 /api/finish 指过去)
为什么改:问题 #10
改成什么:只是改名,逻辑见改动 11
⚠️ 有没有动:接口路径 [否](还是 /api/finish) 请求响应字段 [否] 数据格式 [否]
怎么验证的:同一套测试,原版一轮 32 条「Exception occurred during processing of request」,改后 0 条
有没有引入新的依赖:没有
```
### 改动 11 · 部分失败要响亮
```
文件 / 函数:server.py finish_upload()、claim()、order_detail()
为什么改:问题 #11(以及回执模板 Q2)
改成什么:记住渲染机报过的 total(meta.plan_total),收单时按它判断收没收满;
没收满 → meta.partial = {got, want, why, at} + 往 calls.jsonl 写一条(走「呼叫金钻」同一套通知)+ 页面文案直说「有 N 个文件没渲出来」;
状态仍是 done(已经出好的部分照常能看、能收货);领单时清掉上一轮的 plan_total / partial
⚠️ 有没有动:接口路径 [否] 请求响应字段 [否](note 文案多一句)
数据格式 [是,只增]:订单 meta.json 新增 plan_total、partial 两个字段;calls.jsonl 多一种 kind="部分失败"
—— 如果你们的通知脚本按 kind 过滤,记得把它加进去
怎么验证的:计划 4 个文件只交回 1 个 → 页面「有 3 个文件没渲出来,已经自动通知金钻补」,calls.jsonl 里有这一单
有没有引入新的依赖:没有
```
### 改动 12 · 派单带上条款版本
```
文件 / 函数:server.py claim()
为什么改:问题 #19
改成什么:/claim 返回的 order 里多一个 terms_v(订单真实同意的版本)
⚠️ 有没有动:接口路径 [否] 请求响应字段 [是,只增]:/api/claim 响应的 order 新增 terms_v 数据格式 [否]
渲染机 ys_worker.py 本来就是 order_meta.get("terms_v") or TERMS_VERSION,所以**渲染机不用改**:
老渲染机连新服务器 → 留档写对;新服务器配老渲染机也完全兼容
怎么验证的:领单返回里 terms_v = 2026-10-04.1
有没有引入新的依赖:没有
```
### 改动 13 · 其它几处小改
```
文件 / 函数:server.py edit_code()(拆出 _edit_code_locked,整段进锁)、gift_batch_new/add/off(写文件进锁)、
my_coupons()/coupon_status()(一次只读一遍 codes.json)、admin_ip_ok()(去掉 "?")、
download_zip()(成品 STORED、同时只打一个包,忙时回 503「稍等一分钟再点」)、
order_detail()(去掉文案里的 ** 星号)
⚠️ 有没有动:接口路径 [否] 请求响应字段 [否](打包忙时多一种 503) 数据格式 [否](zip 还是标准 zip,只是成品不再二次压缩)
怎么验证的:打包下载 zip 内容完整(小票 + 两张图,字节一致);其余随回归一起跑
有没有引入新的依赖:没有
```
### 验证方式汇总
- 测试脚本放在 `backend-site/tests/回执复现测试.py`:在临时目录起一份 server、从 HTTP 层打接口,**全部用脚本现画的假皮肤**,每条用例各用一份新数据。
用法:`python3 tests/回执复现测试.py <server.py 所在目录>`。对原版跑能看到哪些洞真实存在。
(你们给的这份因为脱敏弄坏了三个 URL 格式串跑不起来,我是在一份只替换了那三处的副本上跑的;线上原版可以直接跑。)
- 结果:**原版 27 条失败 13 条,改后 27 条全部通过**。
- 端到端:在测试机上用无头浏览器打开真实的 `order/index.html`,接到改过的后端,按买家的路径点了一遍:
卡密下单 → 填码(`/code` ✔ 识别有效)→ 勾条款、传皮肤(本地质检 ✔)→ 选模板 → 提交(`/submit` ✔)→ 结果页显示订单号,
`/status`、`/order`、`/tick` 都是 200,页面 0 个 JS 报错。上面 #17 的星号就是这时候看到的。
---
## 4. 我们这边拿不准的,请你表态
**Q1. 支付回调「不验签、改成拿开放接口反查」这个取舍,你认同吗?**
认同。反查比「拿不到公钥去猜签名」硬得多 —— 前提是**反查结果是唯一可信来源**,推送报文只当一条「单号 X 有动静,去查一下」的通知。现在有两处还在信报文:
- 幂等只认「发过码」(#3,已修);
- `custom_order_id` 在反查结果里没有时,会退回用**推送报文里的**(2049 行)。幂等修好之后这个口子拿不到好处了(同一笔钱只能处理一次),但更干净的做法是金额、状态、订单号、留言**全部只从反查结果取**。
另外两点:反查只翻前 3 页,单子多了会查不到(会落进 need_human,不丢钱,但要人工);据我所知爱发电的 `query-order` 支持按 `out_trade_no` 精确查,请你们核对一下文档,能精确查就别翻页。
如果哪天拿到平台公钥:**验签 + 反查两道都做**最好;拿不到的话,反查加上「每个单号只处理一次」已经够用。
**Q2. 订单状态机在「部分失败」时怎么收口?**
「渲染机显式收尾」这个方向是对的:没有它就只能靠超时,会无限重渲。但原版收得**太安静**,而且收单时张数口径不一致(#11)。我改成:服务器记住计划张数,收单缺张就记 `partial` + 通知金钻 + 页面说实话,已经出好的部分照常能收货、能下载。
再往前一步(没做,要你们定):缺的那几张**自动补渲一次**(上限 1 次),还不行再转人工;页面上把缺的是哪几张列出来。
**Q3. 「改完不生效」除了「先杀旧进程再起新的」,有没有更稳的机制?**
有:**让进程自己报版本**。部署时把代码的 git 提交号或文件 sha256 写进一个常量;渲染机心跳里带上它,服务器存进 heartbeat.json、在 `/status` 和面板上显示;部署脚本**比对「期望版本 == 心跳报上来的版本」才算成功**。这样旧进程还活着会立刻看出来,不用猜。服务器那边同理:systemd 的 `ExecStartPost` 或部署脚本打一下 `/api/status` 看版本号。
Windows 那边:用 NSSM / WinSW 把渲染机装成**服务**,「重启」的语义是确定的(停、等退出、再起),比计划任务的「运行」可靠。
**Q4. 单机多单:如果要同时渲多单,怎么才不会把机器顶满?**
我会先**不加并发、先加吞吐**:现在每张图都要冷启动一次 Blender、加载一次工程,固定开销不小。同一个模板的多张皮肤放进**同一个 Blender 进程**里连着渲(换贴图、再渲),通常比开两个进程更快、峰值还更低。
真要并发的话:瓶颈是**显存**不是 CPU。按模板估一个显存占用,用一个「显存预算」信号量决定同时开几个;Blender 进程设成低于正常优先级、限定 Cycles 线程数;白天只开一个槽,夜里再开第二个。服务器 `/claim` 不用改,渲染机开两个消费线程各领各的就行(领单本身是原子的)。
**Q5. 技术栈:换你会不会上框架?**
不会换 Web 框架。这个规模下纯标准库完全够,换框架解决不了这次发现的任何一个问题。
真正缺的是**数据层**:这次的大部分问题(一码两单、CLI 和服务器互相覆盖、账本丢记录、半截 JSON)本质都是「拿 JSON 文件当数据库」。标准库自带的 `sqlite3` 一个事务就全解决了,零依赖、零安装,小机器也跑得动。路由和校验可以保持现在这样。
**Q6. 前后端共用一个质检脚本,值不值?**
值。前端拦是给人看的体验,后端剥是安全边界,规则来自同一份就不会出现「网页说能传、后端说不行」。
但这次也说明了:**比「两边一致」更要紧的是「每个收皮肤的入口都过后端核验」** —— 重渲换皮肤那条路就漏了(#7)。现在所有入口都收敛到 `_read_skin()` 一个函数,以后新加入口也请走它。
另外 `pngcheck.py` 里提到的 `tests/png_struct_test.py`(共享用例)这次没带过来,有的话请补一份,它是「两边一致」唯一的保证。
---
## 5. 苏达(运维)另外想知道的
- **3100 行的单文件该不该拆、先拆哪块?**
该拆,但不急。先拆**数据层**(codes / orders / 账本的读写 + 锁,约 300 行)—— 这次的 bug 一大半在这里,拆出来才好单测;再拆**支付回调**(钱相关,最需要单测)。HTTP 路由放最后,它最不容易出事。
- **卡密和订单用 JSON 文件存,并发写和「写到一半崩了」风险多大?**
实测给你一个数:CLI 一边发码、服务器一边下单,**原版 200 张码丢了 185 张**。这次的低成本加固已经做了(跨进程 flock + 唯一临时文件 + fsync),改后 0 丢失。中期还是建议换 SQLite(见 Q5)。
- **限流放两处(nginx + 应用),是重复还是互补?会不会打架?**
互补:nginx 按**请求速率**挡刷接口,应用按**业务语义**挡(同 IP 开单数、输错冷却)。
打架的地方有两个:① 请求体大小 nginx 4m / 1m 对上应用的 10MB(#15);② nginx 回 429 / 413 时给的是 **HTML**,前端按 JSON 解析会失败,买家只看到一句笼统的错。建议 nginx 的 413 / 429 都回一段 JSON(`error_page` + 一个返回 JSON 的 location)。
- **内存受限的前提下,还有哪些地方可能爆?**
① 下载整张读进内存(已改);② 收图接口单个请求峰值约 50MB,5 个并发就到 256M(建议见第 2 节 #23);③ ffmpeg 做 4096 预览(未验证,建议实测);④ 线程不设上限。
- **日志与审计够不够追责?**
不够自证「我的图被别人下了」:**下载根本不留记录**(建议见第 2 节)。反过来,有些地方又记得**太多**:nginx access log 里有取件码(URL 的 `?t=`),`payplatform-hook.log` 整包 headers 落盘。建议审计记「谁、什么时候、哪一单、哪一张」,但**不记凭证本身**。
- **有没有「完全没想到」的角度?**
- **取件码放在 URL 里**:会进浏览器历史、服务器日志,订单页上点外链还会通过 `Referer` 带出去。订单页加 `Referrer-Policy: no-referrer` 成本最低。
- **随机数**(#6):「码空间够大,暴力猜不中」这个论证只防盲猜,防不住预测。
- **框架方法重名**(#10):继承标准库的类时,自己的方法名别和父类撞,`finish` / `handle` / `setup` 都是保留的。
- **买家数据的保留期**:渲染机那边永久留档了买家皮肤和成品(你们已知缺口 2)。从隐私角度,建议给留档也定一个保留期,至少能按订单号删。
---
## 6. 你没验证的部分
- 真实 nginx 配置(只看了片段;`/finish` 那条省略了 headers,看不出有没有带 X-Real-IP)。
- 爱发电真实的反查返回结构(`custom_order_id` 到底在不在反查结果里)—— 我是拿假的反查结果测的。
- ffmpeg 预览:测试机没有水印字体,预览那一步我用「直接拷一份」顶替了,水印本身没测。
- 2048 / 4096 的真实成品大小、ffmpeg 峰值内存(没有渲染机、没有真实成品)。
- systemd / cgroup 配置、定时任务(sweep 多久跑一次)都没看到。
## 7. 你还需要什么材料
- 线上 nginx 里 `/order/` 相关的完整配置(脱敏)。
- 一份 4096 单的成品文件大小(标准版 + 无压缩各多大)。
- 爱发电 `query-order` 返回的一条样例(脱敏)。
- `tests/png_struct_test.py`。
- systemd unit(`MemoryMax` 等)和跑 `admin.py sweep` 的定时任务。
---
*以上改动都还只在工作区,等你们(和 ywsabc2)看过再决定要不要合。*
---
# 第二轮(2026-10-05 晚)· 接入数据库 + 管理接口补齐
> 上一轮第 2 节「中期:换 SQLite」这次做了。你们没给真实数据,所以测试全用现编的假数据;
> 设计目标是**换上就能用**:放好 `store.py` 重启即可,第一次启动自动建库并导入旧 JSON。
> 怎么装、怎么回退、怎么测,都写进了 `交接说明.md` 第五节。
### 改动 14 · 数据层换成 SQLite
```
文件 / 函数:新增 store.py;server.py 的 load_codes / save_codes(新)/ read_meta / write_meta / list_orders /
drop_order(新)/ purge_order(新)/ add_call(新)/ note_tpl_time / tpl_eta_sec / gift_batches /
heartbeat / hb / call / feedback / finish_upload 里写呼叫的地方 / 爱发电账本读写;
admin.py 的 calls / sweep,新增 db 子命令
为什么改:上一轮修的竞态根子都是「拿 JSON 文件当数据库」;锁补上了,但断电半截、整文件重写、
列队列要读遍所有 meta.json 这些还在
改成什么:卡密 / 订单信息 / 爱发电账本 / 呼叫记录 / 小块状态进 <DATA_DIR>/ys.db;
上层还是拿到原来的 dict,路由逻辑一行没动,原来的 LOCK 也照旧保留
⚠️ 有没有动接口路径 / 请求响应字段 / 数据格式:
接口路径、请求 / 响应字段:没动。
数据格式:**动了**(存储从 JSON 文件换成 SQLite)。第一次启动自动导入、旧文件不动,
`admin.py db export` 能原样导回旧格式。calls.jsonl 照旧追加(手机通知要读)。渲染机不用动。
你怎么验证的:tests/数据库测试.py 38 条(全新安装 / 迁移 / 重启不重导 / 多进程同时首启只导一次 / 只改变化的行 / 清理 / 回滚 /
导出再导入一致 / 热备份 / 服务器跑在迁移来的数据上 / 8 线程 + 2 进程并发 / 5000 码 2000 单规模);
tests/回执复现测试.py 27 条照旧全过(现在跑在库上)
```
### 改动 15 · 管理接口补四个(给新面板用)
```
文件 / 函数:server.py 的 admin_calls / admin_call_done / admin_retry(新);admin_codes 加可选参数 q
为什么改:面板上「渲染失败」只能写「喊苏达用 admin.py retry」;呼叫记录只能 ssh 上去看
改成什么:GET /api/admin/calls、POST /api/admin/call-done、POST /api/admin/retry(只收 failed 的单)、
GET /api/admin/codes?q=(不传 q 和以前一样)
⚠️ 有没有动接口:**新增**四个,老的路径 / 字段没改;都在原来的两道门(令牌 + 家里 IP)后面
你怎么验证的:假数据起真服务器 + 真面板逐个打:退回重渲成功、对非 failed 单拒绝;
不带令牌直接打 → 403;面板不带 PIN → 401
```
### 这轮没验证的
- 没在你们的真机器(1.6G 内存 + systemd MemoryMax)上跑过;库很小(几千行级别),按测试的内存占用不会有压力,但请部署后跑一次 `admin.py db check`。
- `admin.py` 用别的账号跑时的目录权限(WAL 要在 `<DATA_DIR>` 里建两个小文件),见交接说明 5.1。
### 第二轮自查修掉的三处(推送前审查)
- `add_call`:渲染机回传(`finish_upload`)的「部分失败」也调它;写库出错原来会把异常抛到回传接口 → 改成只记日志、`calls.jsonl` 照写。
- `store.import_legacy`:服务器和 `admin.py` 同时第一次启动会各导一遍(呼叫记录翻倍)→ 在写事务里再判一次「导过没有」。测试加了一条(三个进程同时首启)。
- `admin_call_done`:撤销「处理过了」时 `handled_at` 没清 → 一起清掉。