diff --git a/交接文档-2026-10.md b/交接文档-2026-10.md index 04a4a11..268ccf9 100644 --- a/交接文档-2026-10.md +++ b/交接文档-2026-10.md @@ -19,6 +19,7 @@ 7. [部署与运维](#7-部署与运维) 8. [测试与验证](#8-测试与验证) 9. [已知未验证 / 待确认](#9-已知未验证--待确认) +10. [下一步:内容后台(设计已定,未实现)](#10-下一步内容后台设计已定未实现) --- @@ -351,3 +352,18 @@ python3 admin.py sweep # 清过期成品 + 核销(建议每天 - 渲染机、真实 Blender、爱发电真实回调、手机通知脚本(读 `calls.jsonl` 的那段不在仓库里)都没有端到端测过。 - 下单页里的链接是站点根路径(`/#/home`、`/order/`),本地从仓库根目录起服务时「首页」会跳到仓库根,线上没问题。 - 署名按要求没改(「苏达 · 大肥鱼」)。 + +--- + +## 10. 下一步:内容后台(设计已定,未实现) + +网站前端所有展示内容(门户各板块、下单页的模板与文字、价格与付款)以后要能在网页后台里改,不用再改代码。 +完整设计见仓库根目录 **`内容后台设计.md`**,要点: + +- 跟开单后台分开:内容后台跑在服务器上、公网能打开登录页,入口是门户顶栏最右边一个不带字的铅笔图标;内容账号碰不到卡密和订单。 +- 登录用**用户名或邮箱 + 密码**,密码用 `hashlib.scrypt`(或 `pbkdf2_hmac`)加盐存哈希,不存明文;会话是服务端令牌(库里只存哈希)+ 过期,Cookie 始终 HttpOnly + SameSite=Strict、https 下加 Secure,「记住我」30 天,服务端能主动撤销。 +- 首次部署自动建 `admin / admin`,**首次登录强制改密**:改密前服务端只放行改密码和退出,其它接口一律 403。⚠️ 部署完要**马上**登录改密。 +- 密码至少 8 位;服务器命令行能建账号、改密、重置(作废旧会话 + 临时密码 + 下次必须改)、停用、查设备。 +- 登录页和后台接口只走 https;草稿 → 预览 → 发布,每次发布留版本可一键回滚;画展能直接传图(服务器核验 + 去元数据 + 生成缩略图)。 +- 分四步做,估时约 6–8 天。 + diff --git a/内容后台设计.md b/内容后台设计.md new file mode 100644 index 0000000..de70361 --- /dev/null +++ b/内容后台设计.md @@ -0,0 +1,155 @@ +# 内容后台 · 设计说明(2026-10-05 定稿,待实现) + +> 目的:网站前端所有**展示内容**都能在网页后台里改,不用再改代码、再部署。 +> 状态:**只是设计,还没写代码**。各条已和店主逐条确认;页面样子另有一份可点的静态预览(不在仓库里);代码按本文第 9 节分四步做。 + +--- + +## 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. 还没定的 + +- 署名(关于页「网站构建」那张卡片):后台放开给店主自己改,还是锁成只读?——没定之前按「可以改」做。