backend: 接入 SQLite 数据库 + 开单后台按功能重写
- store.py(新):卡密 / 订单信息 / 爱发电账本 / 呼叫记录 / 小块状态进 <DATA_DIR>/ys.db; 第一次启动自动建库并导入旧 JSON(旧文件不动),admin.py db check/backup/export - server.py / admin.py 存取换到库上,路由与接口字段不变;calls.jsonl 照旧追加 - 管理接口新增 calls / call-done / retry,codes 支持 q 搜索 - ys_admin.py 页面重写:待处理 / 订单 / 卡密 / 福利券 / 呼叫·反馈 / 开单工具 - tests/数据库测试.py(37 条,假数据);回归 27 条照旧全过 - 交接说明(数据库一节、面板一节)、回执第二轮、交付清单更新 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -36,7 +36,7 @@
|
||||
| 进程 | 单进程,由 systemd 托管;内存上限被 cgroup 卡住(小机器上防它吃爆) |
|
||||
| 监听 | **只绑回环**,公网由 nginx 反代过去(后端自己不对外开端口) |
|
||||
| 账号 | 跑在专用非 root 用户下 |
|
||||
| 数据 | 全在本地文件 + 一个 SQLite(无外部服务) |
|
||||
| 数据 | **SQLite**(`<DATA_DIR>/ys.db`,标准库自带 `sqlite3`,无外部服务)+ 皮肤 / 成品图片文件。2026-10-05 接入,见第五节 |
|
||||
| 规模 | 单机单进程,日单量个位数到几十 |
|
||||
|
||||
**为什么不用框架**:这台机器很小(1G 多内存),装一个 Web 框架 + 一堆传递依赖不划算,
|
||||
@@ -51,8 +51,11 @@
|
||||
| `server.py` | ~3100 | **全部服务端逻辑**:路由、订单状态机、卡密生命周期、限流、PNG 结构核验的调用方、爱发电回调、打包下载、小票生成 |
|
||||
| `admin.py` | ~540 | 命令行管理工具:发卡密 / 看队列 / 重渲 / 清过期 / 审计被拦记录 |
|
||||
| `pngcheck.py` | ~130 | PNG **结构**核验(不解码像素):防「夹带私货」——尾部塞字节、未知关键块、APNG |
|
||||
| `store.py` | ~400 | **数据层**(2026-10-05 新增):SQLite 建库 / 第一次启动自动导入旧 JSON / 存取 / 导出回旧格式 / 体检 / 热备份 |
|
||||
| `tests/回执复现测试.py` | ~280 | 回归 + 漏洞复现(27 条,HTTP 层打接口) |
|
||||
| `tests/数据库测试.py` | ~290 | 数据库专项(37 条:全新安装、迁移、回退、事务、并发、规模),数据全是现编的 |
|
||||
|
||||
> 这三个文件是**自足**的:没有 import 本项目之外的模块。
|
||||
> 这几个文件是**自足**的:没有 import 本项目之外的模块。**部署时 `store.py` 必须和 `server.py` 放在同一个目录**(`server.py` 直接 `import store`)。
|
||||
|
||||
---
|
||||
|
||||
@@ -81,6 +84,15 @@
|
||||
| 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`:按卡密 / 订单号 / 批次 / 平台模糊搜;不传和以前一样 |
|
||||
|
||||
### 支付回调的处理顺序(这段是重点,欢迎挑刺)
|
||||
|
||||
```
|
||||
@@ -96,18 +108,96 @@
|
||||
|
||||
---
|
||||
|
||||
## 五、数据形状(都是文件/JSON,没有数据库表)
|
||||
## 五、数据(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 所在目录> # 37 条:数据库专项
|
||||
python3 tests/回执复现测试.py <server.py 所在目录> # 27 条:回归 + 漏洞复现(现在跑在数据库上)
|
||||
```
|
||||
|
||||
- 数据全是测试脚本**现编的**(假卡密、假订单、假呼叫,包括一行写坏的 `calls.jsonl`),建在系统临时目录,不碰 `<DATA_DIR>`。
|
||||
- 交付副本里三个 URL 格式串被脱敏弄坏了(`http<WIN-PATH>`),要起服务器的那几节跑之前先换成能格式化的占位;线上原版直接跑。
|
||||
- 2026-10-05 结果:**64 条全过**。另外用假数据把服务器 + 后台面板 + 浏览器整条链路点了一遍(见 `backend-tools/交接说明.md`)。
|
||||
|
||||
### 5.7 文件 / 目录(库以外的)
|
||||
|
||||
| 路径 | 内容 |
|
||||
|---|---|
|
||||
| `<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>/ys.db`(+ `-wal` / `-shm`) | 上面那个库(640 权限) |
|
||||
| `<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>/calls.jsonl` | 呼叫记录的**副本**(给手机通知读,正本在库里) |
|
||||
| `<DATA_DIR>/upload.log` 等 | 审计留痕 |
|
||||
| `<DATA_DIR>/codes.json`、`orders/*/meta.json` … | **旧数据**:导入之后就不再读写,留着当回退的底 |
|
||||
|
||||
### 卡密生命周期(**激活 ≠ 核销**,这是刻意分开的)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user