Files
jinzuanwork/交接文档-2026-10.md
T
ywsandClaude Opus 5.5 cb7cd3649b 安全审计与加固:爱发电回调防投毒、回调日志封顶、令牌定长比较、转义补全;nginx 安全头 / 挡备份与原始内容文件(片段 + 文档)
- 没验证过的爱发电回调不再写进账本 pay_orders,只进 50 条封顶的待核对清单;回调日志只记关键头 + 正文 4KB、5MB 轮转(测试 +2)
- 福利券领取令牌定长比较;ys_admin.py 转义补上引号;星门格子提示转义;首页价格改读公开接口
- nginx 片段:安全头(HSTS/nosniff/XFO/Referrer/Permissions/CSP)、挡备份 / 预览稿 / 隐藏文件 / 原始内容 json、回调单独限流、server_tokens off
- 交接文档 2.9 安全加固 + 维护页挂法更新

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 12:52:16 +00:00

42 KiB
Raw Blame History

金钻客栈 · 2026-10 总交接文档(前端 + 后端)

这一份把 2026-10-05 这一轮前后端所有改动、功能增删、设计规范、业务逻辑和部署运维写在一处。 细节文档还在各自目录里(位置见第 1 节),这份是总目录 + 总说明。

占位值一律保持原样:example.com / shop.example.com、123456789、备案号(已移除)、(本机路径)、<DATA_DIR> / <APP_DIR> / <WORKER_DIR> / <WIN-PATH> 等。 署名不动(「苏达 · 大肥鱼」)。本文不含任何密钥、真实地址或截图。


目录

  1. 仓库里有什么
  2. 变更清单(按提交)
  3. 功能增加 / 删除一览
  4. ⚠️ 接口与数据格式变更(单独列)
  5. 设计规范
  6. 业务逻辑
  7. 部署与运维
  8. 测试与验证
  9. 已知未验证 / 待确认
  10. 内容后台(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 条)。

2.8 2026-10-06 晚 · 五个修复 + 点击光效回归 + 手机深色模式 + 维护页

  • 下单页模板样图按原图 1:1 显示。
  • 全景 / 动态壁纸:拖着拖出画框外松手,不会再被当成「点空白处」把大图关掉(按下和松手都在空白处才关)。
  • 画展长图(宽高比 0.45 那种)在大图里整张放得下(按视口高度限,网格行高 auto 时百分比 max-height 不生效);列表缩略图还没下完时大图先铺缩略图。
  • 点击光效:门户各页不加点击光效;下单页用它原来那套(按下发光、面板染色、邻按钮照亮)。(10-06 晚加过一版全站「彩虹边缘光段 + Q 弹」fx.js,店主看了说不要,已删。)
  • 手机深色模式:系统设成深色时,手机宽度(≤760px)整站换夜间版(门户六页、画展大图、宇宙页、加载动画、下单页、流动背景着色器 uDark);电脑宽度保持浅色。要让电脑也跟随,把 site.css / 下单页 jz-site 里那段媒体查询的 (max-width:760px) and 去掉,site.js 里 mqDark 同步改。
  • 维护页 portal/maintenance.html:「钻石在打磨中」—— 钻石镐用 Minecraft 原版 16×16 物品图(portal/assets/diamond-pickaxe.png,取自 Minecraft Wiki,版权归 Mojang;本站是非官方粉丝向站点,别拿它做商品图),平时就是原版图标的样子(0°、3px 一格),挥的时候抡起、镐尖敲钻石、钻石一扁一弹、光谱像素火花、白光扫过;MC 方块进度条每敲一下亮一格、满了闪光谱色重来;点钻石也会敲一下。上维护:服务器上 cp /var/www/jinzuan/index.html /var/backups/jinzuan/index.html.<日期> 备份,再 cp /var/www/jinzuan/maintenance.html /var/www/jinzuan/index.html;撤维护:把备份拷回来。别把备份留在网站目录里(见 2.9)。

2.9 2026-10-06 · 安全审计与加固

  • 爱发电回调防投毒:这个地址谁都能 POST。没经开放接口验证的报文(没付款 / 查不到)不再写进账本 pay_orders,只进 kv hook_unverified(最近 50 条、字段截断)供人工核对;回调日志只记关键头 + 正文前 4KB,5MB 轮转。nginx 给两个回调地址单独限流(20 次/分)+ 报文上限 64KB。测试 +2。
  • 福利券领取令牌改成定长比较;本机开单后台 ys_admin.py 的转义连引号一起转;星门格子提示文字转义;首页价格改读公开接口 /order/api/payinfo。
  • nginx(/etc/nginx/sites-available/family-todo,备份 .bak-20261006-pre-security):
    • 安全头:snippets/jz-sec-base.conf(HSTS / nosniff / X-Frame-Options / Referrer-Policy / Permissions-Policy,全站含待会儿办、隧道入口)、snippets/jz-sec-csp.conf(CSP,只给门户 / 下单页 / 内容后台)。⚠️ nginx 的 add_header 不继承:新加的 location 只要写了 add_header,就要在里面再 include 这两个(隧道 / 待会儿办只 include base)。
    • 挡掉:*.bak* *.maint* *.old* *.v3-live-* 之类备份、preview-*.html、隐藏文件(.well-known 照常)、内容后台原始文件 content/site.json / order/content/order.json(含「隐藏」的作品、付款设置;页面读的是 site.js / order.js)。
    • server_tokens off(不再暴露 nginx 版本)。
  • 网站目录里的 35 个备份 / 旧版 / 预览稿挪到 /var/backups/jinzuan/webroot-old-20261006/(没删)。以后备份一律放 /var/backups/jinzuan/。
  • 复查过没问题的:SQL 全参数化;订单号路由 [A-Z0-9]+ 且先查库再拼路径;渲染机回传文件名过滤;下单 / 反馈 / 呼叫限频 + 长度上限 + 磁盘水位;内容后台 https-only、Cookie HttpOnly; SameSite=Strict; Secure、CSRF + 同源、首次强制改密、服务端校验所有字段;公网只开 22 / 80 / 443(阿里云安全组);SSH 只认密钥 + fail2ban;数据目录 750。
  • 待定:内容后台还是初始 admin/admin(尽快改);主机防火墙没开(8018 待会儿办、1Panel、docker 等监听 0.0.0.0,只靠安全组挡)。

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 常用字里)才要重做子集,否则那几个字会掉回正文字体:
    # 文本 = 旧子集里已有的字 ∪ 页面 + 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
    
    源字体从 fusion-pixel-font 的 release 取(12px proportional zh_hans)。

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 内容后台首次部署(⚠️ 照顺序做)

  1. nginx 按 deploy/nginx-片段.md 第 ④ 节加配置(必须带 X-Forwarded-Proto,整站 http → https)。没配好证书之前不要开放:后端会拒绝所有非 https 请求。
  2. 放好 cms.py、设好两个环境变量、给 content/ uploads/ 写权限,重启服务。第一次启动会自动建初始账号 admin / admin,日志里有一句提示。
  3. 马上打开 https://<站点>/admin/,用 admin / admin 登录 → 强制改密(至少 8 位、不能是 admin / 常见密码)→ 用新密码重新登录。 在改密之前,服务端只放行改密码和退出,其它接口一律 403;但这段空档里谁先登进去谁就能改密 —— 所以越快越好。
  4. 第一次打开内容页时,后台把网站现有的 content/ 文件当成第 1 版。
  5. 账号管理(服务器上):
    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 次开始冷却(账号那档放宽,免得别人故意输错把店主锁在门外)。
  • 内容后台碰不到卡密 / 订单。