Files
ywsandClaude Opus 5.5 74bf490baa 全量细审修复:部署漏配防清空、scrypt 并发闸、发布冲突可解、价格文件只在改了才写、排位扩容
- cms.py:没设 YS_PORTAL_DIR / YS_ORDER_DIR 或缺 content/site.json 时拒绝工作(不建空的第一版,免得一发布清空网站);
  同时最多 2 个 scrypt(内存上限 256M);登录冷却记录定期清理;价格 / 付款只在这次发布真改了才写回
  (不覆盖 admin.py price 的改动)
- 后台页面:发布冲突二选一(丢掉我的草稿 / 确认后覆盖发布);草稿没存上、还有图在上传时不让发布
- layout.js:中圈排满后分档到外圈空槽之间找位置,40 条世界线也不重叠;去掉慢的 Math.hypot
- config.js:后台把世界线删光也照实显示;门户删掉旧启动仪式留下的死数据;版本号 v=3
- 测试:内容后台 78 / 回归 27 / 数据库 38 全过;端到端浏览器 36 全过
- 文档同步(交接文档、内容后台设计「实现对照」、后端交接说明、交付清单)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 21:55:13 +00:00

22 KiB
Raw Permalink Blame History

交接说明 · 网站后端(卡密 / 自助渲染下单)

交付方:苏达(网站运维与技术提供) 收件方:外部协作者 日期: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
cms.py ~900 内容后台(2026-10-05 晚):账号 / 会话 / 草稿 / 发布 / 回滚 / 传图;server.py 把 /api/cms/* 交给它。见仓库根目录 内容后台设计.md
store.py ~400 数据层(2026-10-05 新增):SQLite 建库 / 第一次启动自动导入旧 JSON / 存取 / 导出回旧格式 / 体检 / 热备份
tests/回执复现测试.py ~280 回归 + 漏洞复现(27 条,HTTP 层打接口)
tests/内容后台测试.py ~360 内容后台专项(78 条:强制改密、无明文、Cookie、https / CSRF / 来源 / 冷却、校验、发布、回滚、传图、会话、命令行)
tests/数据库测试.py ~290 数据库专项(38 条:全新安装、迁移、回退、事务、并发、规模),数据全是现编的

这几个文件是自足的:没有 import 本项目之外的模块。部署时 store.py、cms.py 必须和 server.py 放在同一个目录(server.py 直接 import store / import cms)。 内容后台还要两个环境变量 YS_PORTAL_DIR / YS_ORDER_DIR、nginx 一节配置、首次部署马上改初始密码 —— 见 交接文档-2026-10.md 7.1b。


四、对外接口

全部挂在 /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 所在目录>     # 38 条:数据库专项
python3 tests/回执复现测试.py <server.py 所在目录>     # 27 条:回归 + 漏洞复现(现在跑在数据库上)
  • 数据全是测试脚本现编的(假卡密、假订单、假呼叫,包括一行写坏的 calls.jsonl),建在系统临时目录,不碰 <DATA_DIR>。
  • 交付副本里三个 URL 格式串被脱敏弄坏了(http<WIN-PATH>),要起服务器的那几节跑之前先换成能格式化的占位;线上原版直接跑。
  • 2026-10-05 结果:65 条全过。另外用假数据把服务器 + 后台面板 + 浏览器整条链路点了一遍(见 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 节单独标出来。