Files

15 KiB
Raw Permalink Blame History

交接说明 · 工具后端(渲染机 + 本机开单工具 + 开单后台)

交付方:苏达(网站运维与技术提供) 收件方:外部协作者 日期: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,局域网)

2026-10-05 页面重写:样子跟 2026 版网站统一(白光 + 毛玻璃卡片 + MC 方块按钮),按「要干的事」分页:

页 干什么 新增 / 变化
待处理(默认打开) 渲染机在不在、队列、待激活、卡密数一眼看完;下面是要你动手的:买家说付好了的单(排最前)、渲染失败的单、没处理的呼叫 失败的单有「退回重渲」按钮(以前只能写「喊苏达用 admin.py」);呼叫直接在这里看、点「处理过了」
订单 全部订单,按状态筛 + 搜索(单号 / 卡密 / 模板 / 备注) 每单能写备注(服务器早有接口,以前面板上没按钮)
卡密 左:生成(设置下面实时出一句「会生成什么」);右:卡密库,按状态筛 + 搜索(码 / 订单号 / 批次 / 平台) 能停用 / 启用、改张数(服务器早有 code-edit,以前面板上没按钮)
福利券 左:开一批;右:已开的批次(复制券码 / 补货 / 收摊 / 领取情况) 只改了排版
呼叫·反馈 买家「呼叫金钻」、反馈、渲染机报的「部分失败」 新页:以前只能 ssh 上去 admin.py calls 看
开单工具 本机开单工具(iframe,第一次点开才加载) 不变
  • 手机上导航放到底部;电脑上在左边。顶栏的状态、导航上的角标每 30 秒自动刷新(页面藏在后台时不刷)。
  • 自带 PIN 锁:首次打开自己设 4~12 位数字,存加盐 sha256(不是明文),12 小时免输;校验在服务端,直接打接口也会 401。
  • 面板新增的本机接口(都要 PIN,都是原样转给服务器 /api/admin/*): GET /api/codes、GET /api/calls、POST /api/retry、POST /api/note、POST /api/code-edit、POST /api/call-done。 老接口(/api/state、/api/gen、/api/activate、/api/void、/api/orders、/api/gifts、/api/gift/*、/api/savecsv、PIN 那三个)一个没动。
  • ⚠️ 用到了服务器这次新加的管理接口(calls / call-done / retry / codes?q=),所以服务器要先升级; 面板先升、服务器没升的话,这几个按钮会提示「服务器回 404」,别的照常能用。
  • 怎么验证的:用现编的假数据(10 单覆盖全部状态、30 多张卡密、3 条呼叫、1 批福利券)起一份真服务器 + 真面板, 浏览器里(电脑 1366 宽 + 手机 390 宽)把每一页点了一遍:生成卡密、搜订单、激活、退回重渲、停用卡密、标呼叫已处理都走通, 没有报错、没有横向滚动;不带 PIN 打面板接口 → 401,不带令牌直接打服务器管理接口 → 403。

③ 纯本机开单(ys_local.py + local.html,只监听回环)

给平台单(聊天里成交的买家)用:拖皮肤 → 同一套质检 → 勾模板 → 本机 Blender 出图 → 下载。 不联网、不上传、不要卡密,所以网站上根本没有入口(避免卡密被暴力试)。

2026-10-05 页面重写(local.html;ys_local.py 和本机接口一个没动):

  • 样子跟网站 / 开单后台统一;电脑上左边「① 皮肤 + 质检」、右边「② 模板 + 分辨率 + 备注 + 开始」,出图结果在下面整行;手机上从上往下排。
  • 补上了原来没写样式的两处:分辨率选择(原来 .seg / label.sel 没有 CSS,看着像一行纯文字)、「清空」「再开一单」按钮(原来用的 .ghost 没定义)。
  • 模板卡片:按勾的顺序标 1 / 2 / 3(出图就是这个顺序);每个模板一个颜色 + 小图标(还没有实拍预览图,以后有了把 thumb 里的 svg 换成 <img>)。
  • 「开始」上面实时一句话:出几张、哪几个模板、多大、大概多久;勾完、皮肤过了质检,步骤号变绿。
  • 「清空」现在真的会清皮肤(原来这个按钮没绑任何事件,点了没反应);「再开一单」照旧只清模板和备注、留着皮肤(同一个买家常常再加几张)。
  • 拖到页面别处也能收皮肤(原来拖偏了浏览器会直接打开那张图、把工具页换掉);买家说明多了一个「复制这段话」按钮。
  • 质检结果去掉了每行前面的小圆点,改成「通过 / 注意 / 不通过」色块。
  • 怎么验证的:写了一个假的本机服务(假装渲染,每张 1.4 秒),浏览器在电脑宽 / 手机宽各走一遍:选皮肤 → 勾 3 个模板 → 选 2048 → 渲染 → 出 3 张卡片各两个下载,无报错、无横向滚动。没在真 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 节单独标出来 —— 这套工具跟服务器那份代码是两台机器上各一份,不同步会静默坏掉。
  • 有看不懂的先问再改,别猜。