zqlit/blog

0 Fork 0

Files

T

zqlit 5f27ad321d chore(备份): 异地备份定案为 OpenList 离线 bundle，撤销全部 git 辅仓

用户定案：「辅助仓就用 openlist，其他不再考虑」。
据此把前一轮为 Gitee 铺的路全部收回，git 远端只剩 CNB 一个。

一、git 配置收口
- `pushall` 别名 `origin + gitee` → `!git push origin main`（只推唯一远端）
- 移除 `gitea` remote（自建 23.254.236.47:3001）—— 远端仓库本身没删，
  需要时可 `git remote add` 恢复；改动前配置存
  `.workbuddy-backup/git-remotes.20261006-211516.txt`
- 确认无 gitee 相关 credential 残留

二、发布链路去 Gitee 化（6 处）
- `deploy/editor-api/bootstrap.sh`
    · 删掉 GITEE_URL / GITEE_SSH_KEY 两个变量与「没给私钥就降级」的分支
    · PUSH_REMOTES 默认 → origin
    · 原「配 gitee 辅仓远端」一节改为「清理退役远端」循环（gh/gitee/gitea），
      让从旧部署续用的工作区自动恢复干净
- `docker-compose.editor.yml`、`editor-api/server.mjs` → 默认值 origin
- `editor-api/README.md` → 变量表同步
- `editor-api/Dockerfile` → 注释里的「CNB / GitHub」改「CNB」
- `blog-admin/src/routes/rss/tools.ts` → deploy-notify 的注释里
  「与 Gitea Actions 的构建通知配套」改为中性描述
  （该轮询链路 2026-10-04 起已被 CNB 国内节点直传取代）

三、`scripts/setup-cnb-remotes.sh` 重写为单远端模式
- 去掉 GITEE_URL / GITEE_TOKEN 参数、校验、凭据写入与自检提示
- 新增「清理退役远端」步骤
- 凭据处理改为「已存在空的 credential.helper 就不再添加」，
  不再用 --replace-all —— 本仓另有一个从 `$HOME/.workbuddy/secrets/cnb-token`
  读令牌的自定义 helper，那是有效的，不能被脚本抹掉

四、备份升级为「唯一辅仓」的配置
- 保留份数 3 → 7（一周窗口；每份 605.5 MB ≈ 4.2 GB，F50 有 256 GB）
    · `scripts/backup-task.cmd` 默认参数 --keep 7
    · `scripts/backup-bundle.mjs` 的 KEEP 默认值同步为 7
      （原先写的是 2，一直被命令行参数掩盖着）
- 远端目录 `/本地/备份` → `/本地/备份/blog-bundle`：
  根目录是用户自己在用的（放着 github-zqlit-*、local-repos-* 等手工备份），
  实测发现直接放根下的 bundle 已被清掉 —— 改子目录隔离，避免混放与误删

五、新增 `scripts/backup-run.mjs`：备份的推荐入口 + 失败告警
- 读 `.workbuddy-backup/openlist-backup.env`（只补空缺，环境变量优先）
- 跑 backup-bundle.mjs 并实时透传输出，同时留一份日志尾部
- 退出码非 0 → 经 `scripts/send_mail.js` 发告警邮件（附日志尾部与常见原因）；
  成功默认不发，`--notify-success` 才发
- 退出用 `process.exitCode` 而非 `process.exit()`，避免截断未排干的 stdout
- 发信失败不改判备份退出码 —— 通知不该掩盖真正的故障
- 理由：这是当前**唯一**的异地备份，而「每天自动跑」的任务最典型的失败模式
  恰恰是静默的（F50 被带出门、换了网段、OpenList 没起来、口令改过……），
  没有告警就要等到真要用备份那天才发现
- `scripts/backup-task.cmd` 改调它

六、文档
- `架构总览.md`
    · §1.2 地址地图：备份行改指 F50/OpenList；通知行补「兼做备份失败告警」
    · §2 旅程图：双推改单推，并说明备份换了介质
    · §5.1 / §5.2 推送与远端：只剩 origin；补「已移除远端」表与恢复命令；
      GitHub 退役记录保留并补上「CI 定义也已删除」
    · §5.3 由「辅仓选型」改为「异地备份的定案」—— 明确不走 git 远端；
      平台对比数据保留备查，并注明 `bin/linux/hugo` 出库不必再做了
    · §5.6 补「唯一备份」定位、专属子目录、失败告警、keep 7、SMTP 配置键，
      实测数据更新为本次复测值
    · §6 待办：#2 定案、#3 不必做、#4 已移除、#8 已更新、#10 定位升级，
      新增 #11（F50 目录使用约定）
- `CNB构建落地方案.md` §4.0：双远端改单远端，脚本示例去掉 Gitee 参数
- `README.md`：推送说明改单推；脚本表补 backup-run.mjs

实测（2026-10-06，本轮复测）：
  bundle 7.4s / AES-256-GCM 加密 1.3s / 上传 19.2s（31.6 MB/s）
  / 读回 sha256 一致 → 端到端 60.6s，退出码 0
  告警邮件链路已实测（发出一封「备份成功」验证信）

★ 一处过程记录，供以后避免重复踩坑：
  中途我把「本机沙箱里 `env -u ... cmd > file` 会让输出整个消失」
  误判成 process.exit 截断 stdout，并据此改了日志实现；
  随后用 `env -u FOO echo hi > file`（同样零输出）证伪 ——
  那是沙箱文件重定向的伪影，与脚本无关。相关改动已回滚，
  只留下本身无害的 process.exitCode 写法。

2026-10-06 21:27:28 +08:00

9.1 KiB

Raw Blame History

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 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/* 只有文章相关接口），评论/用户/设置等其它后台模块仍然只认管理员。

环境变量

变量	默认	说明
`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`	依次推送的远端；主仓失败才算发布失败，其余远端失败只警告。异地备份不在此列 —— 走 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（根目录）的「文章编辑后端」一节。

9.1 KiB Raw Blame History Unescape Escape