# 交接说明 · 工具后端(渲染机 + 本机开单工具 + 开单后台) > **交付方**:苏达(网站运维与技术提供) > **收件方**:外部协作者 > **日期**:2026-10-05 > **一句话**:这是跑在**店主自己那台 Windows 电脑**上的一整套工具:渲染机、 > 局域网开单后台、纯本机开单工具。请你重点看**健壮性与"静默失败"**, > 并给我们**问题分析 + 改正意见**(见最后一节)。 --- ## 一、这一份是什么 跟「网站后端」配套的**本地侧**。因为店里那台电脑没有公网入口,所以它**只做出站**: 主动来服务器领单、渲染、回传。 ``` \ ├─ 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` | | 端口 | 中性数字(**不是真值**) | | 程序 / 数据 / 工作目录 | `` / `` / `` | | Windows 盘符路径 | `` / `` / `` / `` | | 局域网与出口 IP | `` / `` | | 通配绑定 | `` | | 跳板与密钥文件名 | `` / `<跳板>` | **保留未换的**:`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 节单独标出来** —— 这套工具跟服务器那份代码是**两台机器上各一份**,不同步会静默坏掉。 - 有看不懂的先问再改,别猜。