- 他应该知道的.md:生意背景/机器约束/数据边界/术语表/我们的纪律 - 回执模板.md:照着填即可(问题分析+改正意见+你改了什么+我方问题+运维个人想问的) - 两份交接说明里指向回执模板;仓库根 README 标出两批交付
188 lines
11 KiB
Markdown
188 lines
11 KiB
Markdown
# 交接说明 · 工具后端(渲染机 + 本机开单工具 + 开单后台)
|
||
|
||
> **交付方**:苏达(网站运维与技术提供)
|
||
> **收件方**:外部协作者
|
||
> **日期**: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 节单独标出来** ——
|
||
这套工具跟服务器那份代码是**两台机器上各一份**,不同步会静默坏掉。
|
||
- 有看不懂的先问再改,别猜。
|