zqlit/blog
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d3da972c3b21b32e59b4e9a2afe5d28e32e71d22
blog/editor-api/README.md
T
zqlit d3da972c3b feat(editor-api): 线上容器切「CNB 主 + Gitea 备」双推；备份补 fetch 步骤 
用户定案：「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 说明；脚本表更新
2026-10-06 22:27:36 +08:00

180 lines
10 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/*` 只有文章相关接口），
评论/用户/设置等其它后台模块仍然只认管理员。
## 落盘：写一次，存三处（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`）实测配置：
```ini
# /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 并列出候选篇目**，绝不猜。
## 三条不会写坏老文章的底线
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