Files
jinzuanwork/backend/backend-tools/交接说明.md
T
Suda c6034e9acd backend: 补《他应该知道的》与《回执模板》,并指路
- 他应该知道的.md:生意背景/机器约束/数据边界/术语表/我们的纪律
- 回执模板.md:照着填即可(问题分析+改正意见+你改了什么+我方问题+运维个人想问的)
- 两份交接说明里指向回执模板;仓库根 README 标出两批交付
2026-10-05 18:55:16 +08:00

188 lines
11 KiB
Markdown
Raw 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.
# 交接说明 · 工具后端(渲染机 + 本机开单工具 + 开单后台)
> **交付方**:苏达(网站运维与技术提供)
> **收件方**:外部协作者
> **日期**:2026-10-05
> **一句话**:这是跑在**店主自己那台 Windows 电脑**上的一整套工具:渲染机、
> 局域网开单后台、纯本机开单工具。请你重点看**健壮性与"静默失败"**,
> 并给我们**问题分析 + 改正意见**(见最后一节)。
---
## 一、这一份是什么
跟「网站后端」配套的**本地侧**。因为店里那台电脑没有公网入口,所以它**只做出站**:
主动来服务器领单、渲染、回传。
```
<WORKER_DIR>\
├─ ys_worker.py 渲染机主程序(开机自启的计划任务;轮询领单 → 调 Blender → 回传)
├─ ys_admin.py 开单后台(局域网面板:发卡密 / 激活订单 / 免费码),自带 PIN 锁
├─ ys_local.py 纯本机开单工具(不联网、不上传、不要卡密;拖皮肤→勾模板→出图)
├─ local.html 本机开单工具的页面(ys_local.py 内嵌服务它)
├─ make_order.py Blender 出图脚本(渲染机调用它;改模板/分辨率/臂型都在这)
├─ install_worker.ps1 / chk_worker.ps1 / pack_archive.ps1
└─ run_*.bat / stop_*.bat / open_local.bat / show_log.bat
```
---
## 二、技术栈与运行方式
| 项 | 值 |
|---|---|
| 语言 / 依赖 | **Python 3,纯标准库**(`ys_admin.py` 连 HTML 都内嵌在单文件里) |
| 渲染 | Blender **命令行后台模式**(`-b --factory-startup --python make_order.py`) |
| 进程托管 | Windows 计划任务(**开机自启**);面板另有独立计划任务 |
| 网络 | **只做出站**(来服务器领单/回传);本机工具与面板只监听本机/局域网 |
| 关键约束 | ⚠️ **任何时刻只允许一个 Blender 在跑** —— 同时跑两个会把机器顶满(渲染队列是硬约束,不是优化) |
---
## 三、三条链路
### ① 渲染机(`ys_worker.py`)
```
每 20s POST /hb(心跳) ← 心跳在**独立线程**里,不然一渲染就发不出去被判离线
POST /claim(领单)
GET /api/skin/<单号> ← 取买家皮肤(必须带 worker token)
Blender 渲染(一张一次 POST /finish)
中途每 2s POST /progress ← 抠 Blender 输出的百分比
```
### ② 开单后台(`ys_admin.py`,局域网)
四块:① 生成卡密 ② 待激活订单(一键激活进队列)③ 最近卡密 ④ 免费码(福利券)批次管理。
**自带 PIN 锁**:首次打开自己设 4~12 位数字,存**加盐 sha256**(不是明文),12 小时免输;
校验在服务端,直接打接口也会 401。
### ③ 纯本机开单(`ys_local.py` + `local.html`,只监听回环)
给**平台单**(聊天里成交的买家)用:拖皮肤 → 同一套质检 → 勾模板 → 本机 Blender 出图 → 下载。
**不联网、不上传、不要卡密**,所以网站上根本没有入口(避免卡密被暴力试)。
---
## 四、几个刻意做出的设计(欢迎质疑)
| 设计 | 为什么 |
|---|---|
| 渲染串行(一个队列一个消费线程) | 两个 Blender 同时跑会把机器顶满 |
| Blender 超时 600s,卡住就**连整个进程组一起杀**再重跑 | 只杀父进程的话子进程还占着管道,`communicate()` 会白等 30 秒 |
| 命名逻辑**只写两处且必须一致**(`make_order.py` 与 `ys_worker.py`) | 散落硬编码过,判过一次 bug |
| 未压缩版**不重渲**:从已渲好的渲染结果直接另存 | 省一次完整渲染(一张约 37 秒);失败再回退重渲 |
| 质检代码只有一份(前后端共用同一个 js) | 两边判定一旦漂移,会出现「网页说能渲、本机渲不出来」这种最难查的 bug |
| 部署脚本**先显式杀旧进程再起新的** | 计划任务的"运行"对已在跑的实例不替换 → 新代码静默不生效 |
| 成品不保留 `.blend` 工程 | 太大,磁盘受不住;工程渲完立刻删 |
---
## 五、⚠️ 脱敏说明(**这份也不能直接跑**)
| 类别 | 替换成 |
|---|---|
| 站点域名 / 支付平台域名 | `shop.example.com` / `pay-platform.example` |
| 端口 | 中性数字(**不是真值**) |
| 程序 / 数据 / 工作目录 | `<WORKER_DIR>` / `<DATA_DIR>` / `<APP_DIR>` |
| Windows 盘符路径 | `<WIN-PATH>` / `<ARCHIVE_DIR>` / `<TOOLS_DIR>` / `<PROGRAM_DIR>` |
| 局域网与出口 IP | `<LOCAL-IP>` / `<HOME-LAN-IP>` |
| 通配绑定 | `<ALL-INTERFACES>` |
| 跳板与密钥文件名 | `<SSH-KEY>` / `<跳板>` |
**保留未换的**:`localhost`、分辨率常量 `1000/1024/2048/4096`、品牌笔名。
**包里没有的**:真实卡密/订单/皮肤/成品、两把令牌、模板工程(**模板单独给**,见包根目录说明)、
任何密钥凭据、私有仓库地址。
---
## 六、⚠️ 已知缺口(我们知道的,不用你重复发现)
1. **没有内容审核** —— 结构合法的 PNG 但内容违规照样能过(技术拦不住,靠人)。
2. **留档只增不减** —— 成品的永久留档目录会慢慢攒满盘。
3. **预览水印是"防君子"** —— 512 宽 + 平铺水印,拦不住认真截图去水印的人。
4. **渲染机真挂了,最长要 25 分钟才判定离线**(心跳周期 × 容错次数的代价)。
---
## 七、⭐ 我们要你交给我们的东西(**这一份的主要目的**)
同样请回一份 `回执-<你的名字>.md`,含三部分:
> 📋 **格式不用自己起** —— 仓库根目录有一份 `回执模板.md`,照着填就行。
1. **问题分析** —— 你看到的 bug、健壮性问题、坏味道。**特别欢迎**指这几类:
- **静默失败**:出错了但看着"一切正常"的地方(我们被这个坑过好几次)
- **状态不一致**:显示与真实不一致(比如界面说排队中、实际没领单)
- **部署/重启类**:改了不生效、旧进程没替换、两边版本漂移
- **并发/时序**:心跳与渲染抢资源、超时与重试互相打架
2. **改正意见** —— 每条说清**怎么改 + 代价**。
3. **你改了什么** —— 逐条列(同网站后端那份的格式):
```
文件 / 函数: 为什么改: 改成什么:
⚠️ 有没有动接口路径 / 请求响应字段 / 数据格式(动了必须单独标):
怎么验证的:
```
**另外请你顺手回答两个具体问题**:
- `ys_worker.py` 的**部署不生效**(旧进程还在跑)这类问题,除了"先杀再起",有没有更稳的办法?
- 渲染队列现在是**单线程串行**。如果要在一台机器上同时支持多单,
你觉得该怎么做才**不会把机器顶满**?(先说方案,不用实现)
---
## 八、我们的思路与方法(**请你连这套做法一起评**)
代码能看出一部分;**为什么这么做、踩过什么坑**,代码里看不到。这一节补上,
**希望你连"做法"本身一起挑** —— 整套思路要是错的,比某个函数写错更要紧。
### 8.1 我们给自己定的硬规矩
| 规矩 | 为什么 |
|---|---|
| **机器只做出站**:店里那台没有公网入口,所以服务器从不连它,全靠它自己定时来拉 | 不给家用网络开任何入站口子;代价是"渲染机真挂了,最长要过一会儿才判离线" |
| **任何时刻只允许一个渲染在跑** | 两个同时跑会把机器顶满 —— 这是**硬约束不是优化**,所以做成 FIFO 队列 |
| **渲染串行、队列单消费者** | 同上;宁可让买家多等,也不让机器崩 |
| **命名/路径这类"两边都要知道"的规则只写两处且必须一致** | 散落硬编码过一次,修的时候漏了地方 |
| **质检逻辑只有一份,前后端共用** | 两边判定一旦漂移,会出现"网页说能渲、本机渲不出来"这种最难查的 bug |
| **不保留巨大的中间产物** | 工程文件渲完立刻删(磁盘受不住);需要保留的从已渲结果直接另存,不重渲一遍 |
### 8.2 我们干活的方法(改这套工具时照着来)
1. **长驻进程必须交给任务计划/系统托管**,不能用"临时起一个"。
踩过:从远程会话里起的进程,**会话一断就被系统回收** —— 装完看着"已运行",
几十秒后就没了,订单干等在队列里没人领。表现是"看起来一切正常"。
2. **部署 = 先明确杀掉旧进程,再起新的**。多数"重启/运行"命令对**已在运行的实例不会替换**,
于是新代码静默不生效。部署后必须核对**进程的启动时间**,光看"在线"没用(旧进程也报在线)。
3. **判断"活没活"要看真实产物**,不看脚本自述。`Set-Content` 类写入要回读、看字节数;
端口要真连一次;图要真存在。
4. **卡死要连整个进程组一起杀**。只杀父进程的话子进程还占着输出管道,读取方会白等很久
(实测:只杀父 → 64 秒才返回;连组杀 → 4 秒)。
5. **进度要自己吐日志,并且按 `\r` 和 `\n` 都切**。渲染器的进度条是**原地回车刷新**的,
按 `\n` 逐行读会**一条都读不到**(看着像"没有进度",其实进度一直在刷)。
6. **每台机器的配置里不放凭据**,凭据由部署流程单独推(密钥与规则分离)。
7. **中文不要进 `.bat`**,中文一律放带 BOM 的 `.ps1` 里;编码错了会**连累后面的行**一起崩。
### 8.3 我们付过学费的坑("不要重复踩"清单)
- **"改完不生效"是这套系统最高频的坑**,而且从不报错:旧进程在跑、计划任务不替换、
两边版本漂移 —— 三种都会表现成"功能没反应"。
- **静默半死**:某一步抛异常 → 后面的渲染链全断 → 页面看着"就是没反应",
只有开发者控制台才有线索。所以我们加了"出错要能看到原因"的要求。
- **从 A 推导出 B 的函数,在别处读 B 之前必须先调一次**(同一个形状我们踩了两次)。
- **同名文件被覆盖 + 地址不变 = 用户以为没更新**(缓存/同名双杀)。
### 8.4 我们最想要你评的三件"做法"
1. **部署不生效**这类问题,除了"先杀再起",**有没有更稳的机制**?
2. **单机多单**:现在是严格串行。如果要在同一台机器上支持多单,你会怎么设计才**不会把机器顶满**?
3. **"纯标准库单文件"**这套(零依赖零安装、小机器跑得动)换你你会不会换技术栈?请直说。
---
## 九、边界
- **私有交付,请勿外传 / 勿公开 / 勿镜像**。
- 占位值保持原样,**不要**替换成真实地址再交回来。
- 你可以自由重构,但**动了接口/数据格式要按第 7 节单独标出来** ——
这套工具跟服务器那份代码是**两台机器上各一份**,不同步会静默坏掉。
- 有看不懂的先问再改,别猜。