docs: Windows same-origin /scratch/ deployment runbook

docs/sccn-deploy-windows.md

@@ -0,0 +1,69 @@
+# Windows 单机部署 Runbook（编辑器同域子路径）
+
+对应 `docs/07-editor-deployment.md`（Linux 独立域名方案）。本仓库主站部署形态是
+**Windows + 单个 nginx**（`D:\Program Files\nginx`），所以编辑器采用**同域子路径 `/scratch/`**，
+构建产物从 Gitea Actions Artifact 下载，人工落地。
+
+## 1. 下载编辑器构建产物
+
+Backend / Frontend CI 同款流程：Gitea → `ScCN/scratch-gui` → Actions → 选中目标运行
+→ 底部 Artifacts 下载 `scratch-gui-build-<sha>.zip`，内含 `scratch-gui-build-<sha>.tar.gz`。
+
+构建时已固定 `ROOT=/scratch/`、`SCCN_API_BASE=/api`：所有 JS chunk 引用都带 `/scratch/` 前缀，
+必须放在 `sccn/Frontend/public/scratch/` 下；API 走同域 `/api`。
+
+## 2. 落地到主站静态目录
+
+```powershell
+# 解出的 build/ 内容 = editor.html、static/、js/ 等
+# 目标目录：nginx 站点根下的 scratch（与 Frontend 的 public 同级结构）
+tar -xzf scratch-gui-build-<sha>.tar.gz -C "D:\Program Files\nginx\sccn\Frontend\public\scratch"
+```
+
+`editor.html` 即入口：`https://<主站>/scratch/editor.html`，`#<作品ID>` 参数直接加载作品。
+
+## 3. 首次部署前：导入内置素材（服务器上执行）
+
+素材走后端存储，**必须先导入再发编辑器**（编辑器不再回退 Scratch 官方素材站）：
+
+```sh
+# 在 /srv 或服务器上的 Backend 目录
+npm run assets:import -- --gui ../scratch-gui        # 需要 scratch-gui 源码目录在旁边
+npm run assets:import -- --gui ../scratch-gui --check # 全部通过才发布
+```
+
+约 1,305 个去重素材（53.1 MiB），写入 `.env` 的 `PROJECT_STORAGE_DIR`。
+服务器无法访问外网时，按 `docs/07-editor-deployment.md` 第 3 节用素材种子包离线导入。
+
+## 4. nginx 配置（主站 server 块内）
+
+主站已有 `/api/` 反向代理（sccn-api.js 在用），编辑器同域复用即可，无需新 location：
+
+```nginx
+# 主站 server 块（sccn/Frontend/public 为 root）里只确认这两点：
+# 1) /api/ 反代到 Backend 127.0.0.1:3000（既有）
+# 2) client_max_body_size 至少 50m（编辑器上传作品/素材，与后端限制一致）
+client_max_body_size 50m;
+
+# /scratch/ 是纯静态：root 覆盖策略默认 try_files 即可，无需单独 location
+```
+
+修改后 `nginx -t` 通过再 reload。编辑器页面把 `$request_uri` 含访问凭证的作品 GET
+计入日志无害，但注意不要在 `/api/` 全路径上开共享缓存（会话与私有作品接口）。
+
+## 5. 验收清单
+
+```sh
+# 1. 编辑器可达
+curl --fail -I https://<主站>/scratch/editor.html
+# 2. API 健康（同域后端）
+curl --fail https://<主站>/api/health
+# 3. 内置素材直读（一个示例 MD5；换成 --check 清单里的即可）
+curl --fail -I "https://<主站>/api/editor/assets/internalapi/asset/809d9b47347a6af2860e7a3a35bce057.svg/get/"
+```
+
+浏览器：
+1. 打开 `/scratch/editor.html`，新作品默认角色/背景正常（素材全部来自 `/api/`，无外站请求）。
+2. 主站登录后（cookie 同域直接共享），编辑器右上角应显示已登录用户，可「我的作品」/保存。
+3. `editor.html#<主站社区的公开作品ID>` 能加载作品；闭源作品仅作者可载入源码。
+4. 修改后 Ctrl/S 保存，刷新主站社区页可见新修订。