Files
jinzuanwork/内容后台设计.md
ywsandClaude Opus 5.5 74bf490baa 全量细审修复:部署漏配防清空、scrypt 并发闸、发布冲突可解、价格文件只在改了才写、排位扩容
- cms.py:没设 YS_PORTAL_DIR / YS_ORDER_DIR 或缺 content/site.json 时拒绝工作(不建空的第一版,免得一发布清空网站);
  同时最多 2 个 scrypt(内存上限 256M);登录冷却记录定期清理;价格 / 付款只在这次发布真改了才写回
  (不覆盖 admin.py price 的改动)
- 后台页面:发布冲突二选一(丢掉我的草稿 / 确认后覆盖发布);草稿没存上、还有图在上传时不让发布
- layout.js:中圈排满后分档到外圈空槽之间找位置,40 条世界线也不重叠;去掉慢的 Math.hypot
- config.js:后台把世界线删光也照实显示;门户删掉旧启动仪式留下的死数据;版本号 v=3
- 测试:内容后台 78 / 回归 27 / 数据库 38 全过;端到端浏览器 36 全过
- 文档同步(交接文档、内容后台设计「实现对照」、后端交接说明、交付清单)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 21:55:13 +00:00

177 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 内容后台 · 设计说明(2026-10-05 定稿,待实现)
> 目的:网站前端所有**展示内容**都能在网页后台里改,不用再改代码、再部署。
> 状态:**2026-10-05 晚已实现**(四步都做了)。实现:`backend/backend-site/cms.py`、`portal/admin/`、`admin.py user …`;部署步骤见 `交接文档-2026-10.md` 7.1b。
> 跟设计有出入的地方见文末「实现对照」。
---
## 1. 和现有两个后台的关系
| | **内容后台(本文)** | 开单后台(`backend-tools/ys_admin.py`) |
|---|---|---|
| 管什么 | 网站上所有展示内容 | 卡密、订单、福利券、激活:跟钱有关 |
| 跑在哪 | 服务器上(和 `server.py` 同一个进程) | 店主家里电脑 |
| 谁能打开 | 公网能打开登录页,**登录后才能进** | 只在家里局域网 |
| 怎么登录 | 账号(用户名或邮箱)+ 密码 | PIN(不变) |
| 入口 | 门户顶栏最右边一个**不带字的铅笔图标** | 家里电脑桌面 |
**内容账号碰不到卡密和订单**:内容后台的接口只读写「内容」那几张表,跟卡密 / 订单 / 账本是两套接口、两套权限。
内容账号就算被盗,最坏也就是网页内容被改,而且能一键回到上一版(第 5 节)。
---
## 2. 能改什么
| 页面 | 能改的 |
|---|---|
| 门户 · 首页 | 大标题下那句话、按钮文字、公告条(可开关、可设起止日期) |
| 门户 · 画展 | 增删改作品:标题、日期、类型(图片 / 视频 / 全景 / 动态壁纸)、归属(金钻 / 他人)、说明、排序、隐藏;**上传图片**(第 7 节);视频填 B 站链接 |
| 门户 · 工具与开源 | 增删改条目:名称、英文名、类型、开源 / 闭源、说明、版本、状态、链接、仓库 |
| 门户 · 金钻宇宙 | 世界线档案(名字、类型、一句话、简介、标签);外观用**下拉选**(星球风格、主色、入场运镜);空槽数量 |
| 门户 · 平台入口 | 分组、名称、说明、链接(只允许 `https://` 和 `mailto:`) |
| 门户 · 关于 | 名字的由来、署名卡片、鸣谢 |
| 下单页 | 模板的名称 / 说明 / 上下架 / 预览图;页面上的提示与说明文字;价格档位(原 `prices.json`);付款方式(原 `payinfo.json`) |
**刻意不放进来的**:
- **条款版本号**:服务器、下单页、渲染机三处必须同时改,放进后台容易只改一处、静默出错;继续手改,见交接文档。
- **`.blend` 模板文件本身**:继续在家里电脑上放。
- 模板 key(`stand`、`airship` …):渲染机认这个,后台只能改显示名,不能改 key。
---
## 3. 账号与密码
- 登录:**用户名或邮箱 + 密码**。**不开放注册**,账号只能在服务器上用命令行建。
- 存储:`hashlib.scrypt`(每个账号一份随机盐,≥16 字节),参数和盐一起存进 SQLite;
机器上的 Python 不带 scrypt 时自动改用 `pbkdf2_hmac`(sha256,≥60 万次迭代)。
以后加强参数,老账号在下次登录时自动升级。比对用 `hmac.compare_digest`。**任何地方都不存、不记明文**(含日志)。
- 密码规则:**至少 8 位**,不能是 `admin`,拦掉一份常见弱密码表。
- 防爆破:同一 IP、同一账号连错几次逐步加长冷却;提示统一说「账号或密码不对」,不透露账号是否存在。
### 3.1 首次部署:初始账号 `admin / admin` + 强制改密(安全底线)
1. 服务器第一次启动、库里一个账号都没有时,自动建 `admin`,密码 `admin`(入库的同样是哈希)。
2. 这个账号带「必须改密码」标记。用它登录后拿到的是**受限会话**:
**服务端在接口统一入口拦截,除了「改密码」和「退出」,其它所有内容后台接口一律 403「请先修改初始密码」**。不靠前端跳转。
3. 新密码 ≥8 位、不能是 `admin`。改完:清掉标记 → 作废这个账号所有会话 → 用新密码重新登录。
4. 初始密码**不设过期**(店主定)。
> ⚠️ 部署步骤里写死:**服务一启动就马上登录改密**。
> 从部署完到改密之间,公网上谁先用 `admin/admin` 登进去谁就能改掉密码 —— 这段空档越短越好。
### 3.2 服务器命令行(`backend-site/admin.py`)
| 命令 | 干什么 |
|---|---|
| `python3 admin.py user add <用户名> [--email 邮箱]` | 建账号,密码在终端里隐藏输入、输两遍 |
| `python3 admin.py user passwd <账号>` | 直接设新密码;**作废这个账号所有会话** |
| `python3 admin.py user reset <账号>` | 忘了密码用:**作废所有会话** → 生成**随机临时密码**,只打印在执行命令的终端里(不写日志)→ **下次登录必须改密**。加 `--to-admin` 则退回 `admin` |
| `python3 admin.py user disable / enable <账号>` | 停用 / 启用;停用时作废所有会话 |
| `python3 admin.py user list` | 账号、邮箱、是否待改密、最近登录时间 / IP |
| `python3 admin.py user sessions <账号> [--revoke-all]` | 看这个账号在哪些设备登录着;可一键全部踢掉 |
---
## 4. 登录态(会话)
- 登录成功 → 服务端生成随机令牌(`secrets.token_urlsafe(32)`),**库里只存令牌的哈希**,带过期时间。
- Cookie:始终 **HttpOnly + SameSite=Strict**;请求是 https 时加 **Secure**(看反代传来的协议)。
- 「记住我」(默认勾上):Cookie 保留 **30 天**,每次使用自动续期;不勾 = 关掉浏览器就失效(服务端同样 30 天兜底)。
- **服务端主动撤销** = 删掉那一行,下一次请求立刻失效。触发:退出、「退出所有设备」、命令行 `passwd` / `reset` / `disable`、自己改密码(除当前这台)。
- 每个修改请求还要带一个防伪造令牌(CSRF,存在会话里,页面拿到后放请求头)。
- 后台「账号」页能看到自己在哪些设备登录着(浏览器、IP、最近使用时间),可以逐个退出。
---
## 5. 草稿 → 预览 → 发布 → 回滚
- 编辑只写**草稿**;草稿随时可丢弃。
- 「预览」:用草稿数据渲染一份门户 / 下单页(只给登录的人看)。
- 「发布」:弹窗列出这次改了哪些地方(按板块统计增 / 改 / 删),写一句说明(可空)后确认。
- 每次发布存一个**完整版本**(谁、什么时候、说明、内容快照),「发布记录」里能看、能对比、能**一键回到某一版**(回滚本身也算一次发布,可以再回滚)。
- 两个人同时编辑:发布时发现底稿已被别人发布过,提示先看对方改了什么再合并,不静默覆盖。
---
## 6. 数据怎么到页面上
- 数据库(`ys.db`)加表:`cms_users`、`cms_sessions`、`cms_draft`、`cms_versions`、`cms_audit`。
- 发布时把内容写成静态文件 `portal/content/site.json`(下单页 `order/content/order.json`),**原子替换**(先写临时文件再 rename)。
页面直接读静态 JSON:快、能被缓存、**后端挂了网站照样能看**。
- 页面里保留一份内置兜底数据:JSON 读不到时用它,不白屏。
- 价格档位 / 付款方式:发布时同时写回服务器原来那两个文件(`prices.json` / `payinfo.json`),下单逻辑不用改。
---
## 7. 画展传图
1. 后台里拖图上传(PNG / JPEG / WebP,单张 ≤ 20MB)。
2. 服务器先做**结构核验**(沿用 `pngcheck.py` 的思路,补 JPEG / WebP):拒尾部夹带、拒不认识的块;剥掉 EXIF 等元数据。
3. 用 ffmpeg **一次处理一张**生成缩略图和高清版,自动更新媒体清单(`MEDIA` / `hd_cache`)。
单张图片处理是这台服务器允许的(下单预览图现在就这么做);视频不上传,只填 B 站链接。
4. 上传的文件进草稿;发布了才出现在网站上。
---
## 8. 安全清单
- **登录页和内容后台接口只走 https**:nginx 把 http 一律 301 到 https 并加 HSTS;后端再兜一层,反代说不是 https 就拒绝,不收密码。
**没配好证书之前不能开放这个登录页。** 仅服务器本机 http 调试时例外(此时 Cookie 不带 Secure)。
- 所有输入在**服务端**校验:字段类型、长度、链接白名单(`https://`、`mailto:`)、颜色格式、枚举值(星球风格 / 运镜只能选列表里的)。
- 所有文字在页面上**转义输出**,不允许 HTML(防 XSS);需要换行的字段只认换行符。
- 登录、改密、发布、回滚、上传都记审计日志:谁、什么时候、哪个 IP、改了什么。
- 登录接口和上传接口在 nginx 上单独限流。
- 内容后台接口和卡密 / 订单接口分开,权限互不相通。
---
## 9. 分四步做
| 步 | 内容 | 估时 |
|---|---|---|
| 1 | 内容从代码里搬出来:门户 / 下单页改成读 `content/*.json`(带内置兜底) | 1–1.5 天 |
| 2 | 账号与会话:建表、哈希、初始账号 + 强制改密、Cookie、撤销、CSRF、防爆破、命令行 | 1.5 天 |
| 3 | 内容后台页面:各板块编辑、草稿 / 预览 / 发布 / 回滚、账号页、顶栏铅笔图标 | 2–3 天 |
| 4 | 画展传图:核验、ffmpeg 转图、媒体清单 | 1–2 天 |
每步都配测试,至少覆盖:
- 库里查不到明文;
- 错密码登不进;
- 初始账号改密前调其它接口一律 403;
- 改密 / 重置 / 停用后旧会话立即失效;
- 令牌过期;
- http 请求被拒;
- 爆破触发冷却;
- CSRF 缺失被拒;
- 非法链接 / 超长字段被拒;
- 转义正确;
- 发布原子写入;
- 回滚还原一致。
---
## 10. 还没定的
- 署名(关于页「网站构建」那张卡片):后台放开给店主自己改,还是锁成只读?——没定之前按「可以改」做。
---
## 11. 实现对照(和上面设计有出入的地方)
| 设计里写的 | 实际做的 | 为什么 |
|---|---|---|
| 「同一 IP、同一账号连错几次逐步加长冷却」 | 同一 IP 错 5 次 / **同一账号合计错 20 次**才冷却(30s 起翻倍,最长 15 分钟) | 只按账号算的话,别人从外面故意输错几次就能把店主锁在门外;IP 那档仍然很紧 |
| 发布写 `content/site.json` | 同时写 `site.json`(正本)和 `site.js`(`window.JZ_CONTENT = …`,页面同步读) | 页面用同步脚本读,不用改成异步加载,旧代码几乎不动;读不到就用页面内置兜底 |
| 「预览」用草稿渲染一份 | 门户 / 下单页带 `?preview=1` 打开时,额外加载 `/order/api/cms/draft.js`(要登录)覆盖内容;页面底部有「预览草稿」提示条 | 不用另做一套预览页;没登录的人带同样的参数也只看到正式内容 |
| 画展传图 ≤ 20MB | ≤ 10MB | server.py 请求体上限 15MB,base64 后 10MB 的图约 13.4MB |
| 「关于」不允许 HTML | 只认两种简易写法:`[文字](https://网址)` 链接、`` `代码` ``;空一行分段 | 原来的署名卡片里本来就有链接和代码样式,要能保留 |
| 下单页「页面上的提示文字」 | 只做了页头那句话 + 公告条 | 其它提示散在下单页逻辑里,动它风险大;以后要加再逐个接 |
| 署名卡片是否锁定(待定) | 没锁,店主可以改 | 没定之前按「可以改」 |
| 新点亮的世界线放哪 | 自动排位(`portal/assets/universe/layout.js`):中圈不挤的位置,补给线接附近的星,已有的都不动 | 店主要求「新星球的位置和连线要好看、不打架」 |
| 「两个人同时编辑:提示先看对方改了什么再合并」 | 发布时底稿过期 → 409,弹窗二选一:丢掉我的草稿 / 确认后用我的草稿覆盖发布(覆盖前可先看发布记录) | 不做逐字段合并,简单可控 |
| (设计没写) | 部署漏配(没设 `YS_PORTAL_DIR` / `YS_ORDER_DIR`,或门户目录里没有 `content/site.json`)时内容后台**拒绝工作**,不建第一版、不写任何文件 | 否则会从空骨架开始,店主一发布就把网站内容清空 |
| (设计没写) | 价格档位 / 付款方式只有这次发布真改了才写回 `prices.json` / `payinfo.json` | 不覆盖有人用 `admin.py price` 在命令行改过的价格 |
| (设计没写) | 同时最多 2 个密码哈希在算 | 一次 scrypt 要 16MB 内存,服务进程上限 256M |