- 他应该知道的.md:生意背景/机器约束/数据边界/术语表/我们的纪律 - 回执模板.md:照着填即可(问题分析+改正意见+你改了什么+我方问题+运维个人想问的) - 两份交接说明里指向回执模板;仓库根 README 标出两批交付
14 KiB
交接说明 · 网站后端(卡密 / 自助渲染下单)
交付方:苏达(网站运维与技术提供) 收件方:外部协作者 日期: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,照着填就行。
- 问题分析 —— 你看到的问题、风险、坏味道。分个轻重(会导致丢钱/丢数据/被人打的,排前面)。 请尽量指到具体函数/行,并说清触发条件(什么输入、什么并发时序会踩到)。
- 改正意见 —— 每条给你建议怎么改(不一定要写代码,说清思路和代价也行)。 如果有更简单的整体方案(比如"这段根本该换个做法"),也请直说,别客气。
- 你改了什么 —— 如果你直接动手改了,请逐条列:
⚠️ 改了接口/数据格式一定要单独标出来 —— 渲染机那边是另一台机器上的另一份代码, 两边不同步会静默出不来图。
文件 / 函数: 为什么改: 改成什么(一句话说清): 有没有动到接口路径、请求/响应字段、数据格式(**这三样动了我们必须知道**): 你怎么验证的(跑过什么、看到什么):
另外请你顺手回答两个具体问题(我们自己拿不准):
- 爱发电那条线**"不验签、改成拿开放接口反查"**,你认为够不够硬?有没有更好的做法?
- 订单状态机(
unpaid → paid → waiting → working → done/failed)在部分失败时 (比如 3 张图渲出 2 张)你建议怎么收口?
九、我们的思路与方法(请你连这套做法一起评)
代码能看出的是一部分;为什么这么做、踩过什么坑,在代码里看不到。这一节补上, 并且希望你连"做法"本身一起挑 —— 如果我们整套思路就是错的,那比某个函数写错更要紧。
9.1 我们给自己定的几条硬规矩
| 规矩 | 为什么 |
|---|---|
| 无人值守优先:机器的活不该让人 24 小时待命 | 这行的买家半夜下单是常态,靠人盯必然漏 |
| 正常用户一步都不多加:每加一道防探测,先问"正常买家会不会被误伤" | 防的是坏人,误伤的是给你钱的人。两者冲突时先保买家 |
| 收钱的数字一律以服务器订单为准,本地状态只能当兜底 | 踩过:恢复订单时本地状态是空的,按本地算出错的金额去拼付款链接 → 买家少付 → 闸门拦死。同一行显示两个来源的数,必然自相矛盾 |
| 状态话术不许骗人 | 踩过:没付款的单子被兜底文案说成"正在排队"。宁可说"没取到订单信息",也不给假安心 |
| 出错要说清是什么、下一步怎么办,不引导用户猜 | 报错是给人看的,不是给日志看的 |
| 同一件事的逻辑只写一处 | "CLI 一套、后台面板一套"必然漂移 —— 出现过面板和命令行生成出两种卡密 |
9.2 我们干活的方法(改这块代码时照着来)
- 改一处 → 顺着所有调用点核一遍。可见性逻辑被好几个入口调用,改了一处、 别的入口还传旧参数 → 出现"导航正常、首页却说没有可见内容"这种看着像站坏了的现象。
- 同一个东西存在两处时,先问"读取方是按哪个字段找的"。改写入方不改读取方 = 写进去了、读的还是旧的(踩过:换了皮肤文件、但路径字段没跟着改,买家看到"重渲了还是旧图")。
- 前端必须真的在浏览器里点一遍。有一批 bug 在 API 层根本测不出来 (页面上某个渲染函数调了不存在的名字 → 每次进第 2 步就抛异常 → 页面看着"就是没反应")。
- 部署完要核对"跑的是不是新代码",不是"部署脚本说成功了"。 踩过:脚本全程报成功、功能静默缺失 —— 旧进程还活着,计划任务的"运行"不会替换它。
- 自测的每一个负例各用一份新数据。复用同一份的话,第一条成功就把它消耗了, 后面几条测的其实是"已经用过了"—— 全绿,但什么都没测到。
- 测完必须清场。测试产生的记录不许留在管理员看得见的列表里。
9.3 我们付过学费的坑(这些是"不要重复踩"清单)
- 静默失败最贵:不报错、不崩,就是没效果 —— 比抛异常难查十倍。 所以我们宁可让它响亮地失败(比如离线就不显示预计时间、宁可说"没取到")。
- 显示层会骗人:订单本身算对了,但界面从另一个来源取数 → 用户看到的是错的。 凡是"从 A 推导出 B"的函数,在别处读 B 之前都要先调一次它。
- 文件重复投递:渲染机与服务器之间"一张图一次"回传,是因为一次全传会撞体积上限。
- 重试要有上限也能收敛:部分失败必须显式收尾,否则订单会永远停在"渲染中"、被反复重渲。
9.4 我们最想要你评的三件"做法"
- **"不验签、改成拿开放接口反查"**这个取舍,你认同吗?(我们手头没有对方的公钥,与其猜算法不如反查)
- 订单状态机在部分失败时怎么收口(3 张渲出 2 张)—— 我们现在靠"显式收尾",你觉得够不够。
- 这套"单文件纯标准库"的写法:好处是零依赖零安装、小机器跑得动; 代价是路由/校验/序列化全得自己写。换你,你会不会上框架? 请直说。
十、边界
- 这份是私有交付,请勿外传 / 勿镜像 / 勿公开(含截图、片段)。
- 里面是占位值,请不要替换成任何真实地址再提交回来。
- 有看不懂的先问,别猜着改 —— 猜错了我们这边会静默坏掉。
- 你可以自由重构,但动了接口/数据格式要按第 8 节单独标出来。