zqlit
d3da972c3b
用户定案：「editor-api 容器 采用 cnb主仓 gitea备份仓 openlist文件备份」。
三层各有各的失效模式，不能互相替代：
① 主仓 origin = CNB —— 源码 + 触发构建，依赖 CNB 平台
② 代码辅仓 gitea = 自建 Gitea —— 不受第三方平台规则约束，可 clone / 按提交追溯
③ 离线备份 = F50/OpenList —— 单一加密文件，平台全挂也能恢复
一、线上容器实测切双推（国内机 119.29.215.187）
先探测出两个关键事实：
· 国内机**能**直连自建 Gitea（/api/v1/version → 200，0.38s）
· 国内机**够不到**家里的 OpenList（192.168.0.1 私有地址，6s 超时）
→ 「文件备份」这一层只能由家庭机发起，国内机做不到（下面的 fetch 修复正因此
改动：
· /srv/blog 停在 432cf5e3，落后 origin/main 10 个提交且是其后代
→ git merge --ff-only 追平到 448b898e，**未强推**
· 挂 gitea 远端（凭据编在 URL 里，同本机做法）
· .env：PUSH_REMOTES=origin → origin,gitea；追加 GITEA_URL/USER/PASS
· docker-compose.yml 默认值同步为 ${PUSH_REMOTES:-origin,gitea}
· docker compose up -d --build 重建
验证（全部实测通过）：
· 启动日志 [editor-api] 分支 main 推送远端 origin, gitea
· curl /health → "remotes":["origin","gitea"]
· 容器内推 origin ✅ / 推 gitea ✅（推临时分支 → ls-remote 确认 → 删分支，无残留）
· 三处 main 对齐 448b898e（本地 / origin / gitea）；工作区干净
二、备份侧：修掉一个静默漏洞 —— 打包前必须先 fetch
git bundle create --all 取的是**本地已知** ref，其中 refs/remotes/origin/main
停在上次 fetch/pull 的位置。而这份备份跑在**家里**那台机器上，工作区并不会
随写作后台（editor-api）的发布自动更新。所以原先是：后台新发的文章**一篇都不
在备份里**，而备份照样报「成功」—— 失败是静默的。
· backup-bundle.mjs 打包前插入 git fetch --all --tags --prune
- 失败**不致命**（离线也得出得来备份）→ 降级为「用本地已有 ref 打包」+ 显著告警
- 新增 --no-fetch 可跳过；步骤号 1/6..6/6 → 0/7..6/7
- 新增一行 `快照 origin/main = <sha> <时间> <标题>` —— 恢复时第一件要确认的就是它
· backup-run.mjs：头部补三层说明；失败邮件的「常见原因」加上 fetch 降级这一条
验证：fetch 3s 拉完 origin+gitea → 打包 3.6s → 加密 1.7s → 上传 19.2s(31.5MB/s)
→ 读回 sha256 一致，快照 = 448b898e
三、bootstrap.sh：修掉另一个静默陷阱
脚本每次都会**重写** .env，而 .env 是 GITEA_PASS 的唯一落点 →
「重跑一次但没现给 GITEA_PASS」会把辅仓推送**静默关掉**（PUSH_REMOTES 降级成
origin），不报错、不提示，直到要恢复时才发现 Gitea 早就没在同步。
· 改为：命令行没给就从旧 .env 里捡回来（显式传新值仍优先）
· 并把 GITEA_URL/USER/PASS 也写进 .env（容器不读这几个键，仅作复用锚点）
· 该逻辑用 4 个用例离线验证（有/无 .env、显式覆盖、.env 里没 PASS），
并确认 set -euo pipefail 下不会被 [ -n ] && cmd 这类写法误触发退出
四、文档
· 架构总览.md：§1.2 地址地图加 editor-api 行；§2 旅程图补「两条推送入口同一套语义」；
§5.2 加「线上容器的推送目标」段（含验证方法与 pull 源只有 origin 的铁律）；
§5.6 加「打包前必须 git fetch」+「覆盖范围」表（诚实列出够不到的部分）；
§6 待办 #4/#10 更新、新增 #12
· editor-api/README.md：新增「落盘：写一次，存三处」
· README.md：推送说明补线上后台那一路与 fetch 说明；脚本表更新
editor-api —— 只做「在线编辑文章」的轻量后端
给 api.200181.xyz/admin 的「文章编辑」tab 当后端。零 npm 依赖（只用 node 内置模块），
所以没有 npm ci、没有锁文件、没有供应链风险，镜像也小。
它做什么 / 不做什么
只做这一件事：读写 content/posts/<YYYY>/<目录>/index.md，外加把图片放进文章同级目录，
以及把改动 commit + push 触发上线。
不做：评论、AI 摘要、部署编排、订阅……那些在 Worker 里。 账号体系也不在这里（见下节），本服务只认 Worker 转发时声明的身份。
角色：管理员 / 编辑（2026-10-05 加）
后台有两种角色，账号体系的唯一事实源是 Cloudflare 侧 D1 的 users.role 列
（'' 普通评论用户 / 'editor' 编辑 / 'admin' 管理员，与 is_admin 同步）：
| 管理员 | 编辑 | |
|---|---|---|
| 文章列表 | 全部 | 只有自己写的 |
| 读 / 改 / 删 / 传图 | 任意文章 | 只能碰自己的（越权一律 403） |
| 发布 | 全量 git add content static |
只 add 自己名下的文章目录（不会顺走别人未发布的改动） |
| 新建文章 | 可指定作者 | 归属与署名由服务端钉死（伪造 author_id 无效） |
| 评论/用户/设置/订阅 | ✓ | ✗（Worker 和本服务两层都拒） |
归属怎么记：文章 front matter 里的 author_id（= 后台用户 id，数字）。
- 用 id 不用昵称 —— 管理员随时可能改昵称，按昵称比对会「丢文章」。
- 老文章（改造前写的）没有这个字段 → 回退成按
author昵称认领； 编辑本人第一次保存时会自动补上author_id，正式划到自己名下。 - 服务端在保存/新建时忽略前端传来的
author/author_id，编辑永远改不了署名。
身份怎么传进来（两条通道，本服务不存任何账号）：
- Worker 反代通道：请求带共享令牌
X-Editor-Token（浏览器拿不到）， Worker 鉴权通过后注入X-Editor-Uid/X-Editor-User（encodeURIComponent 过的昵称）/X-Editor-Role。令牌对得上，这组头就是可信的。 只有令牌、没有身份头 → 按管理员处理（兼容 curl 调试和旧版 Worker）。 - 国内机直连通道（浏览器直接开 writeapi.usj.cc/admin/）：
POST /admin/login把 账号密码转发给 Cloudflare 的/api/v2/user/access_token校验，通过后签发本机 HttpOnly Cookie 会话，会话里存{uid, name, role}。写文章那条链路依然不出境。- Cloudflare 连不上时：本机管理员账号（
ADMIN_USER/ADMIN_PASS）仍能登录（应急通道）； 其它账号会收到 503「校验不了」，而不是误导性的 401。 - 「国内线路」一键跳转（
/admin/handoff）的 HMAC 签名覆盖时间戳+uid+名字+角色—— 编辑跳过去还是编辑，不会变成管理员。
- Cloudflare 连不上时：本机管理员账号（
三层结构
浏览器 ──► Cloudflare Worker (api.200181.xyz) ──► editor-api (这台服务器上)
/api/v2/editor/* 127.0.0.1:8017
只做「登录鉴权 + 注入令牌与身份转发」 真正读写文件 / git
- 浏览器永远接触不到
EDITOR_TOKEN：它只存在 Worker 的 secret 里。 - 容器端口只绑宿主机
127.0.0.1，公网扫不到；外面那层是 nginx 的/editor-api/。 - 鉴权复用后台登录会话：管理员和编辑都放行（
/editor/*只有文章相关接口）， 评论/用户/设置等其它后台模块仍然只认管理员。
落盘：写一次，存三处（2026-10-06 定案）
| 层 | 载体 | 说明 |
|---|---|---|
| 主仓 | origin = CNB（cnb.cool/zqlit/blog） |
唯一的 fetch 源，推送即触发构建 |
| 代码辅仓 | gitea = 自建 23.254.236.47:3001 |
只推不拉，代码留档；失败不阻断发布 |
| 文件备份 | 中兴 F50 上的 OpenList | 整仓加密 bundle，由家里那台机器每天 03:30 跑（国内机够不到家庭局域网，故不在这边） |
线上容器（国内机 119.29.215.187）实测配置：
# /srv/editor-api/.env
PUSH_REMOTES=origin,gitea
改完必须验：curl -s http://127.0.0.1:8017/health 的 remotes 字段应为 ["origin","gitea"]；
容器启动日志也会打一行 [editor-api] 分支 main 推送远端 origin, gitea。
写权限用「推临时分支 → ls-remote 确认 → 删分支」实测 ——
别用 --dry-run，远端落后时它会误报 non-fast-forward。
⚠️ 铁律：任何提交都必须先落到 CNB。 pull 源只有
origin， 在别处只推了gitea的提交后台看不见（git pull不从它拉）， 下一次发布就会因 non-fast-forward 被拒。
环境变量
| 变量 | 默认 | 说明 |
|---|---|---|
EDITOR_TOKEN |
必填 | 编辑器令牌。没设直接拒绝启动。openssl rand -hex 32 生成 |
BLOG_ROOT |
/blog |
博客仓库（git 工作区）路径 |
PORT |
8017 |
监听端口 |
BIND_HOST |
0.0.0.0 |
容器内监听地址；靠 compose 的端口映射限成 127.0.0.1 |
TRASH_DIR |
/app/trash |
删除文章的回收目录（在仓库外，不进 git） |
GIT_BRANCH |
main |
工作分支 |
PUSH_REMOTES |
origin,gitea |
依次推送的远端；主仓失败才算发布失败，其余远端失败只警告。origin=CNB 主仓（推送即触发构建），gitea=自建 Gitea 代码同步辅仓（需给 GITEA_PASS 才配得上，见 bootstrap.sh）。异地备份不在此列 —— 走 OpenList 上的加密 bundle（scripts/backup-bundle.mjs） |
GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL |
blog-editor |
自动提交的作者 |
DEFAULT_AUTHOR |
空 | 新建文章时 front matter author 的默认值 |
MAX_UPLOAD_MB |
20 |
单张图片上限 |
GIT_PATHS |
content,static |
git add 的范围（不会把别的东西误提交） |
BLOG_BASE |
空 | 博客对外地址（如 https://usj.cc）。配了列表/编辑页才返回绝对链接，「预览」按钮才能直接开新窗口 |
slug 生成规则（与 write-server 一致）
新文章不填 slug 时自动生成 YYYYMMDDHHMMSS（本地时间 14 位），
目录名 <YYYY-MM-DD>-<标题段>-<slug>——与 write-server 的 makeSlug（src/lib/bot/helpers.ts）
和 computeDirPath（src/lib/bot/sessions.ts）一字不差。仓库里 2026-06 之后
的文章全是这个风格。不要用标题当 slug。
接口
除 GET /health 外一律要凭据：X-Editor-Token（Worker 通道，附带身份头）
或本机会话 Cookie（国内直连通道），没有就 401。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /health |
健康检查（免鉴权） |
| GET | /posts?q=&page=&perPage= |
列表（含 slugConflict 撞名标记；编辑只看到自己的） |
| POST | /posts |
新建，body {frontMatter:{title,...}, content} |
| GET | /posts/:id |
读单篇（id = 目录名，见下） |
| PUT | /posts/:id |
保存，body {content, frontMatter} |
| DELETE | /posts/:id |
移到回收目录 |
| POST | /upload?name=x.png&key=:id |
原始二进制直传，落到文章同级目录（编辑必须带 key） |
| GET | /git/status |
分支 / 改动文件 / 最近提交（编辑只看到自己目录的改动，返回里 scoped:true） |
| POST | /git/publish |
{message} → add + commit + pull --rebase + push（编辑只 add 自己的目录） |
| POST | /git/sync |
pull --rebase --autostash |
| GET/POST | /admin/session /admin/login /admin/logout |
国内直连后台的登录会话 |
| GET | /admin/handoff?ts=&u=&n=&r=&t= |
「国内线路」免登录跳转（签名覆盖身份） |
为什么用目录名当 id，不用 slug
仓库里真实存在 5 组 slug 撞名的文章（20210901、20211122、20211128、20211223、20240602）。
Hugo 的 permalink 是 /:slug，撞名时线上必有一篇被另一篇覆盖 —— 也就是说这 10 篇里有 5 篇
线上本来就打不开。如果按 slug 定位，编辑器会静默地打开/保存到另一篇文件上，直接毁数据。
所以：id 用目录名（文件系统保证唯一、单段路径），slug 降级为展示字段 + slugConflict 告警；
拿撞名的 slug 来查会返回 409 并列出候选篇目，绝不猜。
三条不会写坏老文章的底线
- 没动 front matter → 原文一个字节都不重写。
判断方式是「把前端传来的字段合并进已解析对象，再和已解析对象深比较」；相等就原样照抄
frontMatterRaw。这样解析器对冷门语法理解有偏差也无所谓。前端也配合：只回传真正改了的字段。 - 换行风格原样保留（CRLF/LF）。仓库
.gitattributes是* text=auto，仓库存 LF、 Windows 工作区是 CRLF，统一化会产生整文件 diff。 - front matter 与正文间的空行原样保留。语料里 111 篇有空行、19 篇没有； 正文剥掉前导空行给编辑框，回写时按原文件的风格还原。
测试
# ① 纯函数往返：split/join/parse/stringify 对全部真实文章逐字节还原
node test/frontmatter-roundtrip.mjs
# ② 保存往返（最重要）：每篇都「读出来原样存回去」，断言 sha256 不变；测完自动还原
BLOG_ROOT=E:/GitHub/blog node test/save-roundtrip.mjs
# ③ 接口端到端（对真实仓库跑，测完自动还原）
BLOG_ROOT=E:/GitHub/blog node server.mjs & # 另开终端
node test/api-e2e.mjs http://127.0.0.1:8017 devtoken
# ④ 角色权限矩阵（自带一次性 git 仓库，不碰真仓库）
node test/role-perm.mjs
# ⑤ date 时分秒（自带一次性临时仓库）：新建补时刻、同一天不再撞、保存不抹时刻
node test/date-time.mjs
本地联调
# 1) 后端（角色测试可以直接指到 .editor-tmp/uitest/blog 那个一次性仓库）
EDITOR_TOKEN=devtoken BLOG_ROOT=E:/GitHub/blog node server.mjs
# 2) Worker（blog-admin 目录）—— ★ 本机要先清代理环境变量，否则 wrangler dev 卡死在启动
env -u http_proxy -u https_proxy -u HTTP_PROXY -u HTTPS_PROXY npx wrangler dev --port 8799
# .dev.vars 里配 EDITOR_API_BASE=http://127.0.0.1:8017 EDITOR_TOKEN=devtoken
# 本地 D1 要先给 users 加 role 列（线上同理，见部署清单）
部署见 部署清单.md（根目录）的「文章编辑后端」一节。