zqlit/blog
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5f27ad321d76d526faea40c4fb2203da43d330f1
blog/editor-api/README.md
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

156 lines
9.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`，编辑永远改不了署名。
**身份怎么传进来**（两条通道，本服务不存任何账号）：
1. **Worker 反代通道**：请求带共享令牌 `X-Editor-Token`（浏览器拿不到），
Worker 鉴权通过后注入 `X-Editor-Uid` / `X-Editor-User`（encodeURIComponent 过的昵称）/
`X-Editor-Role`。令牌对得上，这组头就是可信的。
只有令牌、没有身份头 → 按管理员处理（兼容 curl 调试和旧版 Worker）。
2. **国内机直连通道**（浏览器直接开 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 并列出候选篇目**，绝不猜。
## 三条不会写坏老文章的底线
1. **没动 front matter → 原文一个字节都不重写。**
判断方式是「把前端传来的字段合并进已解析对象，再和已解析对象深比较」；相等就原样照抄
`frontMatterRaw`。这样解析器对冷门语法理解有偏差也无所谓。前端也配合：只回传**真正改了**的字段。
2. **换行风格原样保留**（CRLF/LF）。仓库 `.gitattributes` 是 `* text=auto`，仓库存 LF、
Windows 工作区是 CRLF，统一化会产生整文件 diff。
3. **front matter 与正文间的空行原样保留**。语料里 111 篇有空行、19 篇没有；
正文剥掉前导空行给编辑框，回写时按原文件的风格还原。
## 测试
```bash
# ① 纯函数往返：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
```
## 本地联调
```bash
# 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`（根目录）的「文章编辑后端」一节。
Reference in new issue View Git Blame Copy Permalink