zqlit
c217d20c30
后端（新增 editor-api/，零 npm 依赖，只用 node 内置模块）： - 只做文章相关：列表/读取/新建/保存/删除/图片上传/git 状态·发布·同步 - front matter 往返保真：未改动的块按字节照抄，CRLF/块标量/引号写法都不动 - 列表用目录名当 id，slug 撞名不再静默改错文件（返回 409 列候选） - 鉴权只有一条路：X-Editor-Token（只存在 Worker 侧，浏览器拿不到） - 端口只绑 127.0.0.1，由宿主机 nginx 反代出去 部署（新增 deploy/editor-api/bootstrap.sh）： - 一条命令在新机器上完成 克隆仓库→写 .env→起容器→健康检查 - 状态全在两个目录（/srv/blog 仓库工作区 + /srv/editor-api 配置）， 迁移 = 复制目录或在新机重跑本脚本，容器本身无状态 Cloudflare Worker 侧（blog-admin）： - src/routes/editor.ts：鉴权 + 反代，浏览器只跟 Worker 说话 - 管理面板新增「文章编辑」：两栏布局 + 快捷插入面板（13 项短代码， 与 write-server 的 ShortcutPanel 一致）+ 底部 草稿/保存/发布 - 系统设置改为 schema 驱动的表单，且**以运行时实际生效的配置为准** （frontend_conf/captcha/moderator/ip_region/site_default + KV human_check）， 修复「表单显示一套、评论系统跑另一套」的脱节问题 验证：tsc 0 错；front matter 往返 130/130；保存往返 130/130； API e2e 44/44；无头 Chrome UI e2e 14/14
111 lines
5.5 KiB
Markdown
111 lines
5.5 KiB
Markdown
# editor-api —— 只做「在线编辑文章」的轻量后端
|
||
|
||
给 `api.200181.xyz/admin` 的「文章编辑」tab 当后端。**零 npm 依赖**（只用 node 内置模块），
|
||
所以没有 `npm ci`、没有锁文件、没有供应链风险，镜像也小。
|
||
|
||
## 它做什么 / 不做什么
|
||
|
||
只做这一件事：读写 `content/posts/<YYYY>/<目录>/index.md`，外加把图片放进文章同级目录，
|
||
以及把改动 commit + push 触发上线。
|
||
|
||
**不做**：评论、AI 摘要、部署编排、用户体系、订阅……那些要么在 Worker 里，要么已经不需要了。
|
||
|
||
## 三层结构
|
||
|
||
```
|
||
浏览器 ──► Cloudflare Worker (api.200181.xyz) ──► editor-api (这台服务器上)
|
||
/api/v2/editor/* 127.0.0.1:8017
|
||
只做「登录鉴权 + 注入 X-Editor-Token 转发」 真正读写文件 / git
|
||
```
|
||
|
||
- 浏览器**永远接触不到** `EDITOR_TOKEN`：它只存在 Worker 的 secret 里。
|
||
- 容器端口只绑宿主机 `127.0.0.1`，公网扫不到；外面那层是 nginx 的 `/editor-api/`。
|
||
- 鉴权是复用后台已有的管理员登录（`isAdminRequest`），不用再造一套账号。
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 默认 | 说明 |
|
||
|---|---|---|
|
||
| `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,gh` | 依次推送；主仓失败才算发布失败，备份仓失败只警告 |
|
||
| `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`，没有就 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` | 原始二进制直传，落到文章同级目录 |
|
||
| GET | `/git/status` | 分支 / 改动文件 / 最近提交 |
|
||
| POST | `/git/publish` | `{message}` → add + commit + pull --rebase + push |
|
||
| POST | `/git/sync` | pull --rebase --autostash |
|
||
|
||
### 为什么用目录名当 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
|
||
```
|
||
|
||
## 本地联调
|
||
|
||
```bash
|
||
# 1) 后端
|
||
EDITOR_TOKEN=devtoken BLOG_ROOT=E:/GitHub/blog node server.mjs
|
||
|
||
# 2) Worker（blog-admin 目录）
|
||
npx wrangler dev --port 8799
|
||
# .dev.vars 里配 EDITOR_API_BASE=http://127.0.0.1:8017 EDITOR_TOKEN=devtoken
|
||
```
|
||
|
||
部署见 `部署清单.md`（根目录）的「文章编辑后端」一节。
|