- 门户:单页改成 index / gallery / tools / universe / links / about 六页,标记 / 样式 / 交互照预览站;内容照旧读 content/site.js - 画展:预览站作品墙 + 原有全部功能(筛选、排序、看过的、高清、本站视频、B 站、全景、动态壁纸、观展统计、外链);按最矮列投放保证时间顺序 - 加载动画 boot.js:像素钻石垒成形 → 白光 → 店名逐字 → 进度条 → 幕布上收(每个标签页只放一次,减少动效时不放) - 金钻宇宙开场 gate.js:星门(钻石 + 光谱环 + 世界线格子逐个点亮),星系画好后炸开接镜头俯冲 - 下单页:全站顶栏 / 底栏 / 页脚、宽版面、落地「怎么下单?」两张路卡 + 下过单了 + 模板样图;下单逻辑和按钮 id 不动 - 站点固定信息(域名 / 群号 / 备案号 / 邮箱)只在 assets/site-info.js,仓库是占位,正式服务器只换这一个文件 - 像素字体换成常用 3755 字 + 全部内容的子集(门户和下单页共用);旧链接 /#/板块、/#0001 自动跳新页 - 交接文档 / 星系图说明 / nginx 片段同步更新 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
38 KiB
金钻客栈 · 2026-10 总交接文档(前端 + 后端)
这一份把 2026-10-05 这一轮前后端所有改动、功能增删、设计规范、业务逻辑和部署运维写在一处。 细节文档还在各自目录里(位置见第 1 节),这份是总目录 + 总说明。
占位值一律保持原样:
example.com/shop.example.com、123456789、备案号(已移除)、(本机路径)、<DATA_DIR>/<APP_DIR>/<WORKER_DIR>/<WIN-PATH>等。 署名不动(「苏达 · 大肥鱼」)。本文不含任何密钥、真实地址或截图。
目录
- 仓库里有什么
- 变更清单(按提交)
- 功能增加 / 删除一览
- ⚠️ 接口与数据格式变更(单独列)
- 设计规范
- 业务逻辑
- 部署与运维
- 测试与验证
- 已知未验证 / 待确认
- 内容后台(2026-10-05 晚实现)
1. 仓库里有什么
| 目录 / 文件 | 是什么 | 细节文档 |
|---|---|---|
portal/ |
门户(整个网站):index.html 首页、gallery.html 画展、tools.html 工具与开源、universe.html 金钻宇宙、links.html 平台入口、about.html 关于(2026-10-06 起是多页,样子以设计预览站为准)+ assets/ fonts/ content/ admin/ |
本文第 2.7、5、6 节;portal/assets/universe/交接说明.md(星系图) |
order/ |
自助模板渲染(下单页)index.html + skincheck.js |
本文第 6.2 节 |
backend/backend-site/ |
网站后端:server.py(全部服务端逻辑)、store.py(数据库)、admin.py(命令行管理)、pngcheck.py(PNG 结构核验)、tests/ |
backend/backend-site/交接说明.md、回执-Claude.md |
backend/backend-tools/ |
店主电脑上的一整套:渲染机 ys_worker.py、开单后台 ys_admin.py、本机开单 ys_local.py + local.html、Blender 出图脚本 make_order.py、各种启动脚本 |
backend/backend-tools/交接说明.md、回执-Claude.md |
backend/模板/ |
三个 Blender 模板工程(测试用) | backend/模板/说明.md |
backend/deploy/ |
反向代理路由与限流片段 | backend/deploy/nginx-片段.md |
backend/他应该知道的.md |
生意背景 / 机器约束 / 数据边界 / 术语表 | — |
交接说明.md(根目录) |
11eb16c 那一轮视觉改版的说明(部分已过时,以本文为准) |
— |
2. 变更清单(按提交)
时间顺序。哈希以 git log 为准。
2.1 11eb16c · 前端 2026 改版「白光藏色 × MC 方块」
- 删掉上一轮的暗色覆盖块
redesign-2026(反馈不好看)。 - 两页
</body>前新增<!-- jz-2026:start -->…<!-- jz-2026:end -->:手机底栏 HTML +<style id="jz-2026">+<script id="jz-2026-js">;下单页<body>开头另加一段跟门户一样的顶栏。 - 浅色配色、流动淡彩背景(WebGL,降级为静态渐变)、MC 方块按钮、像素标题字(缝合像素字体子集,OFL)。
- 门户顶栏加「自助渲染」入口;手机端底部物品栏导航 + 「更多」面板(像开关一样再点就收)。
- 下单页页头改版;四段进度条
.prog用 CSS 隐藏(DOM 和逻辑都还在)。 - 修了「工具与开源」卡片正文被挤成一指宽的问题。
- 这一轮没改任何原有
<script>/<style>块(逐块比对过)。详见根目录交接说明.md。
2.2 651d21d · 后端复查修复 + 回执
外部复查找到的问题,按会丢钱 / 丢数据的先修:
| 问题 | 改法 |
|---|---|
| 同一张码并发提交能成两单 | 查码和绑码放进同一把锁(redeem_bind) |
| 卡密规则只信前端报的张数 | 按 max(前端张数, 实际模板数) 和模板并集校验;不认识的模板 key 直接拒 |
| 爱发电回调重放 / 改单号能多发码、多激活 | 处理过的平台单号一律原样回;回调和账本读写串行(HOOK_LOCK) |
admin.py 和服务器同时改 codes.json 互相覆盖(实测 200 张丢 185 张) |
LOCK 加跨进程 flock;写文件用唯一临时名 + fsync |
sweep 会删掉还在排队 / 等确认的单 |
只清走完流程的单 |
卡密 / 单号 / 取件码用 random 生成(可预测) |
改 secrets |
| 重渲换皮肤不过 PNG 核验 | 走同一套核验 |
| 反馈接口能灌爆磁盘和通知 | 限频 + 磁盘闸 + 只收图片 |
| 下载整个读进内存 | 边读边发;zip 同一时间只打一个 |
| 部分失败静默标「已完成」 | 记 partial,通知店主,页面说实话 |
H.finish 和框架方法重名 |
改名 finish_upload(接口路径不变) |
| 本机开单工具接受任意来源的 POST | 只认本机页面(Host / Origin 校验) |
附 tests/回执复现测试.py(27 条;原版 13 条失败,改后全过)。
2.3 51212a0 · 接入 SQLite + 开单后台重写
- 新增
store.py:卡密 / 订单信息 / 爱发电账本 / 呼叫记录 / 小块状态进<DATA_DIR>/ys.db;第一次启动自动建库并导入旧 JSON(旧文件不动)。 server.py/admin.py的存取换到库上,路由逻辑不变;calls.jsonl照旧追加(手机通知读它)。- 管理接口新增
calls/call-done/retry,codes加q搜索。 admin.py db check / backup / export。ys_admin.py(开单后台)页面按功能重写:待处理 / 订单 / 卡密 / 福利券 / 呼叫·反馈 / 开单工具。- 新增
tests/数据库测试.py(现编假数据)。
2.4 3ae940d · 本机开单页面重写
backend-tools/local.html 换成跟网站 / 后台同一套样子;补上原来没写样式的分辨率选择、没绑事件的「清空」;整页接收拖拽;按勾选顺序标号;预计耗时。ys_local.py 没动。
2.5 09b229d · 金钻宇宙换成星系图 + 推送前审查
- 门户「金钻宇宙」板块:删掉启动仪式、宇宙首屏晶体、盘符机架、读盘舱;换成星系图(three.js,懒加载)+ 窗下世界线卡片。
- 世界线数据只剩一份:
portal/assets/universe/config.js(主脚本也读它)。 - 像素字子集按新文字重做(并保留了原来所有字)。
- 审查修掉的后端问题:
add_call写库失败会打断渲染机回传;多进程同时首启会重复导入呼叫记录;撤销「处理过了」没清时间。数据库测试加一条,共 38 条。 - 本文档。
2.6 内容后台 + 新世界线自动排位 + 星球预设
- 内容后台(第 10 节):网站上所有展示内容在网页后台里改 —— 账号密码登录(首次
admin/admin强制改密)、草稿自动保存、预览、发布、回滚、画展传图。 后端backend-site/cms.py(挂在server.py的/api/cms/*),页面portal/admin/,命令行admin.py user …。 - 门户 / 下单页改成读内容文件:
portal/content/site.js(window.JZ_CONTENT)、order/content/order.js(window.JZ_ORDER),后台发布时生成;代码里写死的数据降级为兜底。 - 门户顶栏最右边加内容后台入口:一个不带字的淡色铅笔图标(无边框,hover 稍亮)。
- 星系图排布
layout.js:新点亮的世界线自动排到中圈不挤的位置,补给线接到附近更靠里的星(不穿星);空槽按编号固定在外圈;新加一条,已有的星和线都不动。 - 星球预设从 7 种加到 18 种:类地(卡通地球)/ 海洋 / 丛林 / 荒漠 / 冻原 / 熔岩 / 毒雾 / 荒芜岩球 / 冰巨星 / 带环巨星(光环只有这个预设才有)。
- 星图名牌 / 档案卡的文字一律转义(内容来自后台,不能当 HTML 拼)。
- 新增
tests/内容后台测试.py(78 条);端到端浏览器流程 36 条(第 8 节)。 - 推送后全量细审又修了:部署漏配(没设
YS_PORTAL_DIR/ 缺content/site.json)时内容后台拒绝工作,不会建空的第一版、一发布清空网站;同时最多 2 个 scrypt 在算(内存上限 256M);登录冷却记录定期清理;发布冲突给「丢掉我的草稿 / 用我的覆盖」二选一(原来会卡死在冲突里);草稿没存上、还有图在上传时不让发布;价格 / 付款文件只在这次真改了才写(不覆盖admin.py price的改动);排位在世界线很多时分档放宽、40 条也不重叠;删掉门户里旧启动仪式留下的死数据。
2.7 2026-10-06 · 全站按设计预览站重做 + 加载动画 + 宇宙开场星门 + 内容后台接住真实画展
- 门户从单页(
#/板块切换)改成六个独立页面,标记、样式、交互全部照设计预览站(http://161.33.11.66/):index / gallery / tools / universe / links / about.html,共用assets/site.css(预览站原样式 + 末尾一段正式站补充)、assets/site.js(预览站原交互:流动背景、视差、卡片倾斜、滚动浮现、翻牌、手机「更多」)。 内容照旧全部读content/site.js(内容后台发布的),由assets/pages.js按预览站的标记填进去;画展的真功能在assets/gallery.js。 - 画展(
gallery.js):样子是预览站的作品墙 + 年份栏 + 白色毛玻璃大图层;原来的功能一样没少 —— 类型 / 谁做的 / 年份→月份筛选、最新 / 最早排序、看过的放前 / 放后 / 不显示、hd_cache 先轻后重的高清、本站 mp4(优先网页版副本)、B 站播放器、全景球面环视、动态壁纸时间轴、观展统计/hit+view_stats.json、作品外链。 作品墙改成 JS 按「最矮的一列」投放(预览站用 CSS 分栏,330 件时顺序会竖着走)。 - 旧地址兼容:
/#/gallery、/#/apps、/#/universe、/#0001等会自动跳到新页面(universe.html#0001打开就飞到那条世界线)。 - 加载动画(新)
assets/boot.js:像素钻石一块块从底往上垒成形 → 白光扫过 →「金钻客栈」逐字弹出 → 光谱进度条跟真实加载走 → 幕布上收。只在同一个标签页第一次打开时放、最少 1.25 秒、最多等 3 秒、点一下可跳过、「减少动效」时不放。 - 金钻宇宙开场(新)
assets/universe/gate.js:three.js 下载 / 星系生成期间,星图窗里是一道「星门」(钻石 + 三圈光谱环 + 一排世界线格子按编号点亮);星系第一帧画好就光环外炸、格子散开、淡出,接上星系图自己的镜头俯冲。打不开 3D 时停在说明文字上。 - 站点固定信息只放一处:
portal/assets/site-info.js(window.JZ_SITE:域名 / QQ 群号 / 群名 / 加群链接 / 备案号 / 反馈邮箱)。门户六页、下单页、关于页都读它。 仓库里是占位;正式服务器上只替换这一个文件(以前要在好几个页面里改,容易漏 —— 10-06 就漏过)。 - 下单页对齐预览站:全站同一个顶栏 / 底栏 / 页脚、宽版面、落地页改成「怎么下单?」两张路卡 + 「下过单了?」条 + 模板样图(用 400px 的 jpg)+ 分辨率;之后的步骤卡片照预览站的晶体面板。按钮 id、下单逻辑、接口一个没动(新样式在
<style id="jz-site">,放在 jz-2026 块后面)。 - 像素字体换成更全的子集
portal/fonts/fusion-pixel-12.woff2(114KB:ASCII + 常用 3755 字 + 当前全部内容;下单页也用这一份),删了旧的jz-pixel-12.woff2。 - 内容后台能原样接住真实画展(
cms.py):文件名带空格、本站 mp4 视频(不填 B 站链接)+web网页版副本、作品外链link/links、离线缩略图索引media、世界线tone/sector/media—— 以前校验时会报错或悄悄丢掉;site_payload把media一起写进site.js(以前一发布就丢缩略图,画展会直接拉几百张原图)。测试 +8(86 条)。
3. 功能增加 / 删除一览
增加
| 在哪 | 功能 |
|---|---|
| 门户 · 金钻宇宙 | 星系图:旋臂星系 + 星云 + 扇区 + 补给线;每条世界线一颗卡通星球(材质按设定:晶体 / 铅笔纸面 / 冰封 / 霓虹 / 善恶两半);点星系或下面卡片飞过去,档案卡和星球同时落定;五种运镜(推进 / 放大 / 升空俯冲 / 跃迁 / 绕行);全屏;#0001 深链可分享 |
| 门户 · 全站 | 「自助渲染」入口;手机底部物品栏 + 「更多」面板;流动淡彩背景 |
| 下单页 | 跟门户一致的顶栏 / 底栏 |
| 后端 | SQLite 数据库(自动建库、自动导入、导出回退、热备份、体检) |
| 后端 · 管理接口 | 呼叫记录列表、标「处理过了」、失败单退回重渲、卡密搜索 |
| 开单后台 | 待处理首页(要动手的事集中在一页)、订单搜索、卡密搜索 / 停用 / 启用 / 改张数、订单备注、呼叫·反馈页、失败单「退回重渲」按钮 |
| 本机开单 | 分辨率选择样式、清空、整页拖拽、出图顺序标号、预计耗时、复制买家说明 |
| 内容后台(新) | 账号密码登录、首次强制改密、草稿 / 预览 / 发布 / 回滚、发布记录、操作日志、登录设备管理;可改:首页文案与公告、板块说明、画展(含传图)、工具与开源、金钻宇宙(档案 + 外观)、平台入口、关于、下单页模板上下架 / 名字 / 说明、页头与公告、价格档位、付款方式 |
| 门户 / 下单页 | 读后台发布的内容;首页公告条(可设起止日期);?preview=1 预览草稿(只有登录的人看得到) |
| 金钻宇宙 | 新世界线自动排位与连线;星球预设 18 种 |
删除
| 在哪 | 删了什么 | 为什么 |
|---|---|---|
| 门户 · 金钻宇宙 | 启动仪式(逐字 / 权限扫描 / 欢迎)、宇宙首屏晶体线框(CrystalView)、盘符机架(抽插 / 拖拽 / 导轨)、读盘舱(特写弹窗 / 拆解 / 翻页)、两枚只给插卡用的图标(白标 --icd-logo、火柴人 --icd-people)、相关 CSS |
被星系图取代;店主说机架「丑死了」 |
| 门户 · 装饰 | 英文 kicker、遥测数字条、时钟、LINK // 已同步(CSS 隐藏,DOM 还在) |
文案要说人话 |
| 下单页 | 四段进度条(CSS 隐藏,逻辑还在) | 店主觉得难看 |
| 前端 | 上一轮暗色覆盖块 redesign-2026 |
不好看 |
保留:首页右侧晶钻徽记、#0001 / #rack 旧链接(分别飞到那条世界线 / 打开宇宙板块)。
4. ⚠️ 接口与数据格式变更(单独列)
规矩:动了接口路径、请求 / 响应字段、数据格式的,必须单独标出来 —— 渲染机是另一台机器上的另一份代码,两边对不上会静默出不来图。
| 类别 | 变更 | 影响谁 |
|---|---|---|
| 数据格式 | 卡密 / 订单信息 / 爱发电账本 / 呼叫记录 / 小块状态从 JSON 文件挪进 <DATA_DIR>/ys.db。第一次启动自动导入,旧文件原样留着;admin.py db export 能导回旧格式 |
服务器、admin.py。渲染机不受影响 |
| 新增接口 | GET /api/admin/calls、POST /api/admin/call-done、POST /api/admin/retry |
开单后台(新按钮要它们:服务器先升级) |
| 接口加参数 | GET /api/admin/codes?q=(可选,不传和以前一样) |
开单后台 |
| 新增字段 | /api/claim 回的订单里多一个 terms_v(只增不减) |
渲染机可以不理 |
| 开单后台本机接口 | 新增 /api/codes /api/calls /api/retry /api/note /api/code-edit /api/call-done(都要 PIN,原样转服务器) |
只有面板页面自己用 |
| 前端 | 门户的 #rack / #bay DOM 与 window.__icd.open/close/flip/tray 调试钩子删了;新增 window.__jzUniverse.show()/fly(no) |
只有页面自己和自动化脚本 |
| 新增接口 | /api/cms/*(登录 / 内容 / 草稿 / 发布 / 回滚 / 传图 / 预览),见 cms.py 开头;nginx 要加一节(deploy/nginx-片段.md ④) |
只有内容后台页面 |
| 数据格式 | 库里新增 cms_users / cms_sessions / cms_draft / cms_versions / cms_audit 五张表(启动时自动建);新增内容文件 portal/content/site.{json,js}、order/content/order.{json,js};画展上传的图在 portal/uploads/ |
服务器、门户、下单页 |
| 文件被谁写 | prices.json / payinfo.json 现在也由内容后台发布时写(格式不变,别的字段原样保留;只有这次发布真改了价格 / 付款才写)。admin.py price 还能用,但建议统一在后台改 |
服务器 |
| 前端 | 门户读 window.JZ_CONTENT、下单页读 window.JZ_ORDER(读不到用内置兜底);下单页 TEMPLATES 拆成 TEMPLATES_ALL(全部,用于显示老订单)和 TEMPLATES(上架的) |
页面自己 |
没变:所有买家接口、渲染机接口的路径和字段;本机开单的本机接口。
5. 设计规范
5.1 一句话
白光藏色 × Minecraft 方块:一眼看过去是白的,颜色藏在亮部和缓慢流动的淡彩光里;按钮是 MC Ore UI 那种方块按钮;标题用像素字;正文用 OPPO Sans。
5.2 颜色 token(门户 / 下单页写在 jz-2026 块的 :root;后台 / 本机开单各自复制一份)
| 用途 | 变量 | 值 |
|---|---|---|
| 页面底色 | --bg |
#F5F7FB |
| 正文墨色(深→浅) | --ink / --txt · --txt-2 · --txt-3 · --txt-4 |
#1E2440 · #454B6B · #676D8A · #858AA2 |
| 发丝线 | --line / --line-soft |
rgba(30,36,64,.12) / .08 |
| 主色(草方块绿) | --mc-green / -hi / -lo |
#3C8527 / #5BAA3C / #1D4D13 |
| 次按钮(石头白) | --stone / --stone-lo / --stone-edge |
#F3F4F6 / #B4B7BE / #9EA2AA |
| 面板 | --panel-shadow + 半透明白 |
inset 0 1px 0 #fff, 0 22px 44px -28px rgba(100,110,190,.38);底 rgba(255,255,255,.74~.9),2px 白边 |
| 警告 / 错误文字 | --warn-t / --bad-t |
#9A6A0C / #B33A2E |
| 首页板块卡的「矿石色」 | --zc |
画展金 #F2C14D、工具蓝 #4F86E8、宇宙紫 #9A6BE0、平台绿、关于红(只在悬停时从边缘亮出来) |
| 背景彩光 | body::before 四团 radial-gradient |
天蓝 / 粉 / 杏 / 薄荷,透明度 .22~.30;有 WebGL 时换成 #jzBg 流动彩光 |
| 星系图(唯一的深色区域) | config.js → GALAXY.colors |
深海军蓝 #070B1C + 蓝紫星云 + 一点青 + 暖金 #FFD36E(名牌 / 数字) |
5.3 字体
- 标题:缝合像素字体 12px(TakWolf,SIL OFL 1.1),子集
portal/fonts/fusion-pixel-12.woff2(门户和下单页共用;ASCII + GB2312 一级常用 3755 字 + 当前全部内容,114KB),协议原文portal/fonts/fusion-pixel-OFL.txt。12 的整数倍字号最清楚,-webkit-font-smoothing:none。 - 正文:OPPO Sans(可免费商用)。
- 常用字都在子集里,一般不用管;用到生僻字(不在 3755 常用字里)才要重做子集,否则那几个字会掉回正文字体:
源字体从 fusion-pixel-font 的 release 取(12px proportional zh_hans)。
# 文本 = 旧子集里已有的字 ∪ 页面 + config.js + galaxy.js 里所有字(只加不减) python3 -m fontTools.subset fusion-pixel-12px-proportional-zh_hans.otf.woff2 \ --text-file=字表.txt --flavor=woff2 --layout-features='*' --no-hinting --output-file=portal/fonts/fusion-pixel-12.woff2
5.4 组件
| 组件 | 规则 |
|---|---|
| 按钮 | 全站统一一种:MC 方块,border-radius:4px,2px 边,上亮下暗的内阴影;按下下沉 2px。绿 = 主操作,石头白 = 次操作,红字 = 危险操作(注销 / 停用 / 收摊) |
| 卡片 / 面板 | 半透明白 + 2px 白边 + --panel-shadow,圆角 8px(大块 12px)。只有吸顶顶栏用 backdrop-filter,面板不用(卡、而且显得死板) |
| 标签 / 状态 | 色块小标签(4px 圆角、浅底深字):绿 = 通过 / 已完成,黄 = 注意,红 = 失败,蓝 = 进行中,灰 = 停用 |
| 输入框 | 白底、2px 线、聚焦变绿 |
| 动效 | 只动 transform / opacity;缓动 cubic-bezier(.23,1,.32,1);尊重 prefers-reduced-motion 和页面上的「动效」开关 |
5.5 移动端规则
- 窄屏(≤760 / 860px):顶栏只留 logo 和开关;底部浮动物品栏(首页 / 画展 / 渲染〔中间钻石〕 / 宇宙 / 更多),「更多」从底栏上方弹出一排格子,再点同一个按钮 / 点空白 / 返回键 / Esc 收起。
- 左右边距 16px 左右;任何页面不许横向滚动(每次改完都要在 390 宽度下检查)。
- 星系图在手机上:星图里的手势全归星图(拖动转、双指缩放,页面不跟着滑),窗户只占屏幕约 64%,上下留出滑页面的地方;档案卡是窗里的底部抽屉,星球挪到上半个窗。
5.6 口味禁区(每条都是看过预览之后的直接反馈)
- 不要暗色面板、不要黑白强对比(星系图窗户是唯一例外);不要复古风。
- 文字 / 标题 / 名牌前面不要放小圆点、小方块色点。
- 不要按钮扫光动画;不要六边形「三棱镜」按钮;全站按钮一个样子。
- 星系图:不要星球光环、不要每颗星外面一层大气「罩子」、辉光不能过曝;颜色只用那一套(深蓝 + 蓝紫 + 金),不要彩虹;装饰星球不能互相重叠、卫星不能反着转;开场 / 飞行运镜要连贯,档案卡要跟星球落定同时出来。
- 流动大背景要平滑,不要像素化;像素风只留在字、按钮、粒子上。
- 文案说人话:不写「标签 · 解释」式的说明、不加英文小字装饰、不写解释界面怎么用的句子。
- 改一块就只动那一块,不要顺手改邻居(比如改顶栏时别动头图);小步改。
6. 业务逻辑
6.1 网站全貌
金钻客栈 = 一个线上「客栈」:画展、工具与开源、金钻宇宙、各平台入口都在里面;自助模板渲染只是其中一家店。
| 页面 | 内容 | 数据在哪 |
|---|---|---|
index.html 首页 |
首屏 +「都有些什么」五间屋(桌面)/ 金刚区 + 最新作品(手机)+ 自助渲染服务台(渲染机状态、价格实时读)+ 常用平台 | content/site.js(hero / boards / gallery / apps / universe / links / about) |
gallery.html 画展 |
图片 / 视频 / 全景 / 动态壁纸,按时间排、可筛选(脱敏版只有一张占位) | content/site.js 的 gallery + media,hd_cache/manifest.json,view_stats.json |
tools.html 工具与开源 |
开源 / 在线使用 / 闭源三行,按类型筛选 | apps |
universe.html 金钻宇宙 |
星门开场 → 星系图 + 世界线档案 | universe(兜底 assets/universe/config.js) |
links.html 平台入口 |
按分组列出,外链新窗口打开 | linkGroups + links |
about.html 关于 |
名字由来 + 署名卡片 | about |
各页之间是普通链接(整页跳转)。旧的单页地址 /#/板块、/#0001 会被首页自动跳到新页面。页脚、「更多」面板里的群号和备案号读 assets/site-info.js。
加一条世界线:config.js 里把空槽换成完整档案(no / name / kind / tag / tags / desc)+ 在 LOOKS 里给它一个外观(style / r / orbit / accent / moons / enter);名字里有新字记得重做像素字子集(5.3);改了 JS 要换版本号(7.2)。细节见 portal/assets/universe/交接说明.md。
6.2 下单页(order/)
两条路:
网页下单:传皮肤(本地质检)→ 选模板 / 分辨率 → 出订单号(待付款)→ 去爱发电付款
→ 爱发电回调确认 / 店主后台激活 → 排队 → 渲染机出图 → 买家看 512 预览 → 确认收货 → 下原图
卡密下单:传皮肤 → 填卡密(自动认模板 / 张数)→ 直接排队 → 出图 → 同上
凭票取图:拿单号 + 取件码(或卡密)回来看进度、下载
皮肤质检(skincheck.js,前端和本机开单共用):尺寸是否 64 网格的正方形、像素风检查、主体层完整、半透明、外层铺满、手臂粗细判定;PNG 结构核验防夹带(尾部追加 / 未知关键块 / APNG)。服务器落盘前还会再核一遍(pngcheck.py)并剥掉元数据块。
6.3 订单状态机
unpaid(待付款)──买家点「我付好了」──▶ paid(待激活)
│ │
└──── 爱发电回调确认 / 后台激活 / 买家用卡密激活 ───┘
▼
waiting(排队中)──渲染机 claim──▶ working(渲染中)
▲ │
后台「退回重渲」/ admin.py retry 一张一次 /finish 回传
│ ▼
failed(失败)◀── 水印没生成 ── done(已完成)
unpaid / paid ──后台注销──▶ void(已注销,不占卡密)
- 领单超过 45 分钟没交回 → 自动退回队列。4096 的「重单」高峰期给小单让路,最多让 30 分钟(防饿死)。
- 收满张数才算完成;渲染机显式收单但没收满 = 部分失败:记
partial、页面说实话、通知店主。 - 预览水印没做出来的不许标完成(标
failed,等退回重渲)。 - 成品保留 72 小时(从开放下载算);
admin.py sweep清理时先核销卡密再删文件,排队 / 渲染中 / 待激活的单绝不删。清理后库里那一行留着做账。
6.4 卡密生命周期(激活 ≠ 核销)
active(可用)──买家提交──▶ bound(已激活:被这一单占住,还没核销)──开放下载满 72 小时──▶ used(已核销,终态)
inactive(停用:网页单等付款 / 手动停用)
卡密种类:固定 N 张 / 最多 N 张 / 不限张数;可锁模板;「直发」= 店主自己发的码,不用等确认收货。 防暴破:码空间 31¹² ≈ 7.9e17;同 IP 连错 15 次冷却 15 分钟;单 IP 10 分钟最多开 6 单。
6.5 爱发电回调
不验签(没有对方公钥),改成拿开放接口反查这笔单。处理顺序: ① 标题含「测试」只记账 → ② 同一平台单号重推:原样回上次结果(幂等)→ ③ 反查不到 / 没付款:只记账、标人工,绝不发码 → ④ 金额:少付拦死、多付照常但记一笔 → ⑤ 认单:自定义订单号 > 留言里的卡密 > 留言里的单号 > 「只有一笔待付款单金额对得上」(两笔以上一律人工)。
6.6 渲染机(店主电脑,ys_worker.py)
只出站:定时 claim(领单)+ 独立线程 hb(心跳,默认 10 分钟一次,hb_every)→ 取皮肤 → Blender 后台渲染(同一时刻只允许一个 Blender)→ 中途 progress → 一张一次 finish 回传。心跳超过 1500 秒没更新 = 页面显示离线(所以 OFFLINE_AFTER 必须大于心跳间隔,两边一起改)。心跳顺带记下家里的出口 IP,管理接口只认这个 IP。
6.7 福利券
一批「免费、已激活」的码放在福利页让人自取:每台设备 + 每个网络各限领 1 张(服务器硬规则),领到后 N 天内要用;可锁模板、限张数、定种类(渲染图 / 立牌 / 钥匙扣 / 海报)、到期自动收摊;收摊后已领走的照常能用。
6.8 开单后台(ys_admin.py,店主电脑,局域网)
- PIN 锁(服务端校验,加盐 sha256,12 小时免输);调服务器管理接口要「令牌 + 家里出口 IP」两道门。
- 六页:待处理(买家说付好了的单、渲染失败的单、没处理的呼叫)/ 订单 / 卡密(生成 + 库)/ 福利券 / 呼叫·反馈 / 开单工具。
6.9 本机开单(ys_local.py + local.html)
给聊天里成交的平台单用:拖皮肤 → 同一套质检 → 勾模板 → 本机 Blender 出图 → 下载 / 打开留档文件夹。不联网、不上传、不要卡密,只监听本机,只认本机页面。
6.10 数据库
见 backend/backend-site/交接说明.md 第五节。要点:ys.db 里 5 张表(codes / orders / pay_orders / calls / kv),每张「能查的列 + 一列整条 JSON」;上层代码拿到的还是原来的 dict;.lock 文件锁照旧;WAL 模式。
7. 部署与运维
7.1 文件放哪
| 文件 | 放到 | 备注 |
|---|---|---|
portal/** |
网站根目录 | 星系图要 assets/universe/ 和 assets/vendor/ 一起上;assets/site-info.js 换成正式服务器那份(真实群号 / 备案号),别用仓库里的占位覆盖;content/ 是线上数据,别用仓库里的占位覆盖(内容后台管它) |
order/** |
网站 /order/ |
|
server.py + store.py + admin.py + pngcheck.py |
<APP_DIR>(同一目录) |
server.py 直接 import store,少了 store.py 服务起不来 |
backend-tools/* |
店主电脑 <WORKER_DIR> |
deploy.py 推送;面板新按钮依赖服务器新接口,先升服务器 |
cms.py |
<APP_DIR>(和 server.py 同一目录) |
server.py 直接 import cms |
portal/admin/ |
网站 /admin/ |
内容后台页面(静态) |
portal/content/、order/content/ |
随页面一起 | 后台发布时由服务器进程覆盖写:这两个目录和 portal/uploads/ 要给服务进程写权限 |
环境变量(systemd 单元里加):YS_PORTAL_DIR=<门户网站根目录>、YS_ORDER_DIR=<下单页目录>(内容后台写内容文件和上传图用;YS_ROOT 照旧)。
7.1b 内容后台首次部署(⚠️ 照顺序做)
- nginx 按
deploy/nginx-片段.md第 ④ 节加配置(必须带X-Forwarded-Proto,整站 http → https)。没配好证书之前不要开放:后端会拒绝所有非 https 请求。 - 放好
cms.py、设好两个环境变量、给content/uploads/写权限,重启服务。第一次启动会自动建初始账号admin / admin,日志里有一句提示。 - 马上打开
https://<站点>/admin/,用admin / admin登录 → 强制改密(至少 8 位、不能是 admin / 常见密码)→ 用新密码重新登录。 在改密之前,服务端只放行改密码和退出,其它接口一律 403;但这段空档里谁先登进去谁就能改密 —— 所以越快越好。 - 第一次打开内容页时,后台把网站现有的
content/文件当成第 1 版。 - 账号管理(服务器上):
python3 admin.py user list # 有哪些账号、最近登录 python3 admin.py user add <用户名> [--email 邮箱] [--temp] # 建账号(--temp 发一次性临时密码,首次登录必须改) python3 admin.py user passwd <账号> # 设新密码(所有会话作废) python3 admin.py user reset <账号> [--to-admin] # 忘了密码:会话全作废 → 临时密码(只打印在终端)→ 下次登录必须改 python3 admin.py user disable|enable <账号> python3 admin.py user sessions <账号> [--revoke-all]
7.2 缓存与版本号
- 门户各页引用
assets/*.js|css?v=1:改了哪个就把六个页面里它的?v=一起加 1。HTML 本身要no-cache(nginx 片段里给*.html加了)。 - 门户星系图:改了 JS / CSS 要换版本号,一起换:
portal/universe.html里universe-page.css?v=、config.js?v=、底部模块脚本里galaxy.js?v=,galaxy.js里import './planets.js?v='和'./layout.js?v=',以及portal/admin/index.html里planets.js?v=。踩过:坏文件被缓存住,修好了打开还是「加载不出来」。 - 内容文件
content/site.js/order.js文件名不变、内容会变:nginx 给/content//order/content/加Cache-Control: no-cache(片段里有)。 - 检查 ES 模块语法要拷成
.mjs再node --check(按普通脚本查会漏「重复声明」)。 - three.js 只在第一次打开「金钻宇宙」时下载(约 690KB,gzip 后约 170KB)。
7.3 数据库命令
python3 admin.py db check # 完整性 + 每张表几行 + 按状态计数
python3 admin.py db backup # 在线热备份到 <DATA_DIR>/backup/
python3 admin.py db export [目录] # 导回旧版 JSON(回退用)
回退:停服务 → db export → 换回旧版 server.py / admin.py → 启动。再切回来:挪走 ys.db,新版启动时从 JSON 重新导入。
权限:跑 admin.py 的账号要对 <DATA_DIR> 目录有写权限(WAL 会建 ys.db-wal / -shm)。
7.4 常用
python3 admin.py ls waiting # 看排队
python3 admin.py retry <单号> # 失败单退回(后台也有按钮)
python3 admin.py calls # 呼叫记录(后台也有页面)
python3 admin.py sweep # 清过期成品 + 核销(建议每天跑一次)
8. 测试与验证
| 测试 | 怎么跑 | 结果(2026-10-05) |
|---|---|---|
| 后端回归 + 漏洞复现 | python3 backend/backend-site/tests/回执复现测试.py <server.py 所在目录> |
27 / 27 |
| 数据库专项 | python3 backend/backend-site/tests/数据库测试.py <server.py 所在目录> |
38 / 38 |
| 开单后台 | 假数据起真服务器 + 真面板,headless 浏览器电脑宽 / 手机宽点全部页面 | 无报错、无横滚;无 PIN → 401、无令牌 → 403 |
| 本机开单 | 假本机服务(模拟渲染)+ headless 浏览器走完整流程 | 无报错、无横滚 |
| 门户 | headless 浏览器 1366 / 390:六个板块都切一遍;宇宙:星图就绪、点卡片飞过去出档案、#0002 深链、全屏开关、手机上拖星图页面不滚;首页不下载 three.js |
全过;除星系图板块外,其余板块和改动前逐像素一致 |
| 下单页 | 打开截图 | 正常(本轮没改) |
| 内容后台(后端) | python3 backend/backend-site/tests/内容后台测试.py <server.py 所在目录> <仓库根目录> |
78 / 78:部署漏配时拒绝工作、后台发布不覆盖命令行改过的价格、初始账号与强制改密(改密前 11 个接口全 403)、库里无明文、Cookie 属性、https / CSRF / 跨站来源 / 爆破冷却(按 IP 5 次、按账号合计 20 次)、内容校验、XSS 转义、发布写文件、冲突 409、回滚一致、预览要登录、传图核验与去元数据、会话撤销与过期、命令行、三进程同时首启只建一个账号 |
| 内容后台(端到端) | 迷你反代模拟 nginx + 真服务器 + headless 浏览器 1366 / 390 | 36 / 36:门户入口 → 登录 → 强制改密 → 改文案 / 传图 / 点亮新地球 / 加入口 / 下架模板 / 加档位 → 预览(未登录看不到草稿)→ 发布 → 门户 / 星系图 / 下单页都变了 → 回滚复原 → 退出;无新增报错(只有交付副本本来就缺的 view_stats.json 和模板缩略图 404) |
后端测试数据全是测试脚本现编的,建在系统临时目录。⚠️ 交付副本里三个 URL 格式串被脱敏成 http<WIN-PATH>,要起服务器的测试得先在测试副本里换成能格式化的占位(这三处分别吃 1 / 2 / 0 个参数);线上原版直接跑。
9. 已知未验证 / 待确认
- 星系图帧率没在真机上测过(只在无头浏览器的软件渲染里验证了画面和交互)。上线前用一台普通手机、一台集显笔记本各打开看一下;卡的话按
universe/交接说明.md第 8 节降粒子数。 - 数据库没在真机器上跑过(1.6G 内存 + systemd 内存上限)。部署后先跑一次
admin.py db check。 - 渲染机、真实 Blender、爱发电真实回调、手机通知脚本(读
calls.jsonl的那段不在仓库里)都没有端到端测过。 - 下单页里的链接是站点根路径(
/index.html、/order/、/assets/site-info.js、/fonts/…),本地要从portal/起服务、再把order/放到/order/才完整。 - 加载动画 / 宇宙星门只在无头浏览器里看过逐帧截图;真机(尤其低端安卓)上看一眼顺不顺。
- 署名按要求没改(「苏达 · 大肥鱼」)。
10. 内容后台(2026-10-05 晚实现)
网站前端所有展示内容在网页后台里改,不用再改代码。设计和每条安全规则的来由见根目录 内容后台设计.md;实现在:
| 部分 | 文件 |
|---|---|
| 服务端(账号 / 会话 / 草稿 / 发布 / 传图) | backend/backend-site/cms.py(server.py 把 /api/cms/* 交给它) |
| 后台页面 | portal/admin/index.html(入口:门户顶栏最右边的淡色铅笔) |
| 内容文件 | portal/content/site.{json,js}、order/content/order.{json,js}(发布时生成;.json 是正本,.js 给页面读) |
| 命令行 | admin.py user …(见 7.1b) |
| 测试 | tests/内容后台测试.py(75 条) |
要点(店主定的安全底线,别放松):
- 初始账号
admin / admin,首次登录强制改密;改密前服务端只放行改密码 / 退出,其它接口一律 403。 - 密码
hashlib.scrypt(没有就pbkdf2_hmac)加盐存哈希,任何地方都不存明文;至少 8 位。 - 会话是服务端令牌(库里只存哈希),「记住我」30 天滑动过期;退出 / 改密 / 命令行重置 / 停用都会当场作废。
- Cookie:HttpOnly + SameSite=Strict,https 下 Secure;修改类请求要带 CSRF 头;跨站来源拒绝。
- 只走 https(反代没说 https 就拒);登录冷却:同一 IP 错 5 次 / 同一账号合计错 20 次开始冷却(账号那档放宽,免得别人故意输错把店主锁在门外)。
- 内容后台碰不到卡密 / 订单。