ScCN 编辑器：从构建到上线（操作手册）

面向运维/发布执行者。开发视角见 sccn-backend.md。本仓库默认分支即 codex/editor-backend-integration（ScCN 的自定义分支）。

0. 速查

事项	值
部署路径	`<nginx 站点根>/scratch/`
入口	`/scratch/editor.html`
构建时 `ROOT`	`/scratch/`
API 基址	`/api`（同域）
产物	`scratch-gui-build-<sha>.tar.gz`（约 8 MB，解压约 400 个文件）
当前已验证产物	`ca6ba48` → artifact id 9

1. 前置条件（缺一个都会失败）

后端已发布，且 /api/health 返回 db:"up"
内置素材已导入（Backend: npm run assets:import -- --gui ../scratch-gui） —— 编辑器不回退 Scratch 官方素材站，素材不在后端就加载不出来
nginx 站点根 = Frontend 的 public/ 内容

2. 取构建产物

方式 A：使用已验证的产物（推荐）

若代码没有新提交，直接用已验证的那个：

Actions → 找到 head 为 ca6ba48 的 run → Artifacts
scratch-gui-build-ca6ba48….tar.gz

方式 B：自己触发构建

# 在 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/ 内容（不是 <sha>/build/ 两级）。

Windows（当前生产形态）

$dst = "D:\Program Files\nginx\sccn\Frontend\public\scratch"
New-Item -ItemType Directory -Force -Path $dst | Out-Null
tar -xzf scratch-gui-build-<sha>.tar.gz -C $dst

Linux

tar -xzf scratch-gui-build-<sha>.tar.gz -C /srv/sccn/frontend-public/scratch

解压后目录应当是：

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. 回滚

# 保留上一份产物即可秒回滚
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 立即失效。这是有意的安全设计；如果遇到「加载凭证失效」，重新打开作品即可。

4.9 KiB Raw Permalink Blame History Unescape Escape