This website requires JavaScript.
0
Issues
Pull Requests
Milestones
Explore
0
Create…
New Repository
New Migration
New Organization
public
Signed in as
public
Profile
Starred
Subscriptions
Settings
Help
Sign Out
public
/
jinzuanwork
Unwatch
1
Star
0
Fork
0
Code
Issues
Pull Requests
Actions
Packages
Projects
Releases
Wiki
Activity
Settings
Files
jinzuanwork
/
or
Cancel
Edit File
Preview
Preview Changes
Spaces
Tabs
2
4
8
Wrap
No wrap
# 金钻客栈 · 2026-10 总交接文档(前端 + 后端) > 这一份把 2026-10-05 这一轮**前后端所有改动**、**功能增删**、**设计规范**、**业务逻辑**和**部署运维**写在一处。 > 细节文档还在各自目录里(位置见第 1 节),这份是总目录 + 总说明。 > > 占位值一律保持原样:`example.com` / `shop.example.com`、`123456789`、`备案号(已移除)`、`(本机路径)`、`<DATA_DIR>` / `<APP_DIR>` / `<WORKER_DIR>` / `<WIN-PATH>` 等。 > 署名不动(「苏达 · 大肥鱼」)。本文不含任何密钥、真实地址或截图。 --- ## 目录 1. [仓库里有什么](#1-仓库里有什么) 2. [变更清单(按提交)](#2-变更清单按提交) 3. [功能增加 / 删除一览](#3-功能增加--删除一览) 4. [⚠️ 接口与数据格式变更(单独列)](#4-️-接口与数据格式变更单独列) 5. [设计规范](#5-设计规范) 6. [业务逻辑](#6-业务逻辑) 7. [部署与运维](#7-部署与运维) 8. [测试与验证](#8-测试与验证) 9. [已知未验证 / 待确认](#9-已知未验证--待确认) 10. [内容后台(2026-10-05 晚实现)](#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 次开始冷却(账号那档放宽,免得别人故意输错把店主锁在门外)。 - 内容后台碰不到卡密 / 订单。
Commit Changes
Add a Signed-off-by trailer by the committer at the end of the commit log message.
Commit directly to the
main
branch.
Create a
new branch
for this commit and start a pull request.
Commit Changes
Cancel