From 380f3cae4407d26a31b346b6d7833f6f0e564e35 Mon Sep 17 00:00:00 2001 From: DHEnry Date: Sun, 25 Oct 2026 20:44:16 +0800 Subject: [PATCH] docs: editor release handbook (artifact, landing path, post-deploy checks, rollback) --- docs/sccn-release.md | 128 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 docs/sccn-release.md diff --git a/docs/sccn-release.md b/docs/sccn-release.md new file mode 100644 index 000000000..2d341ad82 --- /dev/null +++ b/docs/sccn-release.md @@ -0,0 +1,128 @@ +# ScCN 编辑器：从构建到上线（操作手册） + +> 面向运维/发布执行者。开发视角见 [sccn-backend.md](sccn-backend.md)。 +> 本仓库默认分支即 `codex/editor-backend-integration`（ScCN 的自定义分支）。 + +## 0. 速查 + +| 事项 | 值 | +| --- | --- | +| 部署路径 | `/scratch/` | +| 入口 | `/scratch/editor.html` | +| 构建时 `ROOT` | `/scratch/` | +| API 基址 | `/api`（同域） | +| 产物 | `scratch-gui-build-.tar.gz`（约 8 MB，解压约 400 个文件） | +| 当前已验证产物 | `ca6ba48` → artifact id 9 | + +## 1. 前置条件（缺一个都会失败） + +1. **后端已发布**，且 `/api/health` 返回 `db:"up"` +2. **内置素材已导入**（`Backend: npm run assets:import -- --gui ../scratch-gui`） + —— 编辑器不回退 Scratch 官方素材站，素材不在后端就加载不出来 +3. nginx 站点根 = Frontend 的 `public/` 内容 + +## 2. 取构建产物 + +### 方式 A：使用已验证的产物（推荐） + +若代码没有新提交，直接用已验证的那个： + +- Actions → 找到 head 为 `ca6ba48` 的 run → Artifacts +- `scratch-gui-build-ca6ba48….tar.gz` + +### 方式 B：自己触发构建 + +```sh +# 在 fork 上推任意提交，或直接触发工作流 +curl -X POST \ + -H "Authorization: token <你的 Gitea token>" \ + -H "Content-Type: application/json" \ + -d '{"ref":"codex/editor-backend-integration"}' \ + https://git.shuiankongjian.top/api/v1/repos/ScCN/scratch-gui/actions/workflows/ci.yml/dispatches +``` + +工作流共 9 步：checkout → 装 Node 22 → npm 镜像 → **git insteadOf 代理** → `npm ci` +→ micro:bit 载荷 → sccn 单测 → 构建（`ROOT=/scratch/`）→ 打包上传。 + +> ⚠️ `package-lock.json` 里的 GitHub 依赖**必须保持 `git+ssh://git@github.com/...` 规范形式**， +> 靠 CI 的 `url.insteadOf` 把流量导到镜像。直接改 lock 里的 URL 会让 npm 解析失败 +> （见提交 `24152b4`）。 + +## 3. 落地到站点 + +产物是 **tar.gz 内含构建后的 `build/` 内容**（不是 `/build/` 两级）。 + +### Windows（当前生产形态） + +```powershell +$dst = "D:\Program Files\nginx\sccn\Frontend\public\scratch" +New-Item -ItemType Directory -Force -Path $dst | Out-Null +tar -xzf scratch-gui-build-.tar.gz -C $dst +``` + +### Linux + +```sh +tar -xzf scratch-gui-build-.tar.gz -C /srv/sccn/frontend-public/scratch +``` + +解压后目录应当是： + +```text +scratch/ + editor.html ← 入口 + index.html + fullscreen.html + embed.html + js/ ← webpack 产物，publicPath = /scratch/ + static/ +``` + +> **不要**把产物放进站点根目录（`/editor.html`），否则 chunk 会去找 `/js/...` 而 404。 + +## 4. 发布后自检（逐条做，30 秒能完成） + +| # | 操作 | 期望 | +| --- | --- | --- | +| 1 | 打开 `/scratch/editor.html` | 编辑器加载，无白屏 | +| 2 | F12 → Network，筛选 `js/` | 全部 200，路径都是 `/scratch/js/...` | +| 3 | 点「素材库」 | 有内置角色/背景/声音（说明素材已导入） | +| 4 | 新建作品 → 修改 → 保存 | 提示保存成功 | +| 5 | 刷新页面 / 重新打开 | 作品内容还在（说明后端写入正常） | +| 6 | 打开 `/scratch/editor.html#<作品ID>` | 直接加载该作品 | +| 7 | 未登录状态下保存 | 提示登录，而不是静默失败 | + +第 2 条最关键：**任何 `/js/`（不带 `/scratch/` 前缀）的 404 都说明放错目录了**。 + +## 5. 常见故障 + +| 现象 | 原因 | 处理 | +| --- | --- | --- | +| 白屏，Network 里 `/js/*.js` 404 | 产物放在站点根而不是 `/scratch/` | 挪到 `/scratch/` | +| 素材库为空 / 加载失败 | 后端未导入素材 | 跑 `assets:import`，再用 `--check` 复核 | +| 保存报 401 | 未登录，或 Cookie 跨站被拦 | 确认同域访问、`COOKIE_SECURE` 与协议匹配 | +| 保存报 409「作品已更新」 | 乐观锁：别处已保存 | 预期行为，重新加载后编辑 | +| 保存报 403「已设为闭源」 | 作品为 closed，非作者不能取源码 | 预期行为 | +| 构建卡在 `npm ci` | lock 被改成了非 ssh 形式 | 恢复 `git+ssh://git@github.com/...`，见第 2 节 | + +## 6. 回滚 + +```sh +# 保留上一份产物即可秒回滚 +mv scratch scratch.bak-<日期> +tar -xzf <上一版>.tar.gz -C scratch +``` + +编辑器是纯静态产物，回滚不影响后端数据（作品保存在后端 `storage/`）。 + +## 7. 与后端的版本兼容 + +| 后端要求 | 说明 | +| --- | --- | +| `/api/editor/config` | 编辑器读取上传上限、会话地址 | +| `/api/editor/session` | 判断登录态与可保存性 | +| `/api/projects/:id/editor` | 下发 `projectToken`（5 分钟，绑定作品+修订号） | +| `/api/editor/assets/internalapi/asset/:name/get` | 素材读取（公开、不可变） | + +> **修订号绑定**：作品一旦保存，revision 递增，旧的 `projectToken` 立即失效。 +> 这是有意的安全设计；如果遇到「加载凭证失效」，重新打开作品即可。 -- 2.54.0