This website requires JavaScript.
0
Issues
Pull Requests
Milestones
Explore
0
Create…
New Repository
New Migration
New Organization
public
Signed in as
public
Profile
Starred
Subscriptions
Settings
Help
Sign Out
public
/
jinzuanwork
Unwatch
1
Star
0
Fork
0
Code
Issues
Pull Requests
Actions
Packages
Projects
Releases
Wiki
Activity
Settings
Files
jinzuanwork
/
backend
/
backend-site
/
or
Cancel
Edit File
Preview
Preview Changes
Spaces
Tabs
2
4
8
Wrap
No wrap
# 交接说明 · 网站后端(卡密 / 自助渲染下单) > **交付方**:苏达(网站运维与技术提供) > **收件方**:外部协作者 > **日期**: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 节单独标出来**。
Commit Changes
Add a Signed-off-by trailer by the committer at the end of the commit log message.
Commit directly to the
main
branch.
Create a
new branch
for this commit and start a pull request.
Commit Changes
Cancel