zqlit/blog

0 Fork 0

Files

T

zqlit 7abef4ac13 docs: 全量梳理文档结构；补 Gitea 迁移指南 / 架构精简候选；架构总览补证书管家子系统

用户四问：「把项目文件全部理一遍 还有readme文件」「gitea 后面可能还要迁移 帮我写一个迁移文档」
「证书管家做完了吗」「感觉现在架构还是复杂了」

一、文档梳理：根目录 15 个 md → 2 个

根目录只留 README.md（入口）+ 架构总览.md（现状唯一事实源），其余全部归位：

  docs/
  ├── README.md              ← 新增：文档地图（入口 / 当前有效 / 历史归档 三层）
  ├── 证书管家.md             ← 原「函数版证书管家-方案.md」改名
  │                              （它早已是「现状+沿革」文档，标题名不副实 —— 签发早已不在 CF Worker）
  ├── Gitea迁移指南.md        ← 新增
  ├── 架构精简候选.md         ← 新增
  ├── CNB构建落地方案.md / GITEA_SECRETS.md
  └── archive/{平台与选型,功能与修复,主题与内容}/   ← 32 份

- 32 个归档文档统一加 `> 📦 本文档已归档` banner，并指向架构总览
  —— 这个仓库历史文档里全是「权威口径」，混看很容易拿废弃结论当现状
- gitea-backup/ → deploy/gitea/（原名「backup」不准，它是部署包；与其它 deploy 单元并列）
- 新增 md 链接校验（python 脚本，中文路径用 sed 不安全）→ 首轮 18 处断链
  （多一层目录要让 banner 里的相对路径补一个 ../）→ 修正后 0 断链

二、新增 docs/Gitea迁移指南.md（★ 有死线：境外 VPS 11 月到期）

★ 核心价值是「指出迁移面已大幅缩小」：仓库原有的 deploy/gitea/迁移前检查清单.md
（2026-10-04）是为「Gitea + act_runner + 又拍云同步 *整套* 搬迁」写的，**那个前提已经不存在**——
构建归 CNB，runner / upyun-sync / 中转机 / COS 都不需要了。迁移实际只剩「搬数据卷 + 改地址」。

★★ 全文最重要：本仓有 9 处写死了旧地址，按易漏程度排序（1-3 本机，4-5 线上）
  1 本机 .git/config 的 gitea remote
  2 scripts/setup-cnb-remotes.sh 的 GITEA_URL 默认值
  3 deploy/editor-api/bootstrap.sh 的 GITEA_URL 默认值
  4 ★ /srv/editor-api/.env 的 GITEA_URL      ← 漏了会「持续报错但只警告不阻断」，没人发现
  5 ★ /srv/blog 的 gitea remote               ← 同上
  6 docs/GITEA_SECRETS.md
  7-9 架构总览.md / README.md / editor-api/README.md
（不用改：docker-compose.editor.yml、server.mjs、pushall 别名 —— 只引用 remote 名字）

另含：建议新实例改用域名而非 IP（以后搬机器只改 DNS；⚠️ Gitea 28 起只读 ROOT_URL 不读
[server] DOMAIN）；rsync 而非 dump（属主必须 uid/gid 1000）；切换顺序「先建新的→验证→再拆旧的」；
验证清单强调 `git push gitea --dry-run`；第九节给出「干脆不留这个辅仓」的选项与判断依据。

顺带修掉两个硬伤：
- deploy/gitea/docker-compose.yml 的镜像 tag `1.28.0-rootless` 根本不存在
  （Gitea 28 起去掉 1. 前缀）→ 改 28.0.0-rootless（pin 死，不用 latest）
- deploy/gitea/.gitignore 漏了 backups/（跑一次备份就会把含 secrets 的 dump 写进历史）

三、证书管家核实（结论：已上线运行，2 个遗留）

线上实测：容器 Up (healthy)；/preflight 7/7 全过；3 组域名；下次自动续期 04:10。

遗留 ① writeapi.usj.cc 证书没纳管（真问题）：nginx 配置在 /www/conf.d/writeapi.usj.cc.conf，
不在 /www/sites/ 管理树里 → 1Panel 的 ssl/upload+sslID 物化碰不到它。
实测仍是 RSA / CN=usj.cc / 到期 2026-12-07，本项目续期不会更新 → 12 月会断。
遗留 ② dnsapi.usj.cc 没上 HTTPS。
（澄清假问题：200181.xyz 公网看到的 LE 证书是 CF 自家边缘证书，与本项目无关）

四、新增 docs/架构精简候选.md（回应「架构还是复杂了」）

结论：复杂度不在件数，在「跨 6 个环境，其中 4 个要自己维护」。国内机 9 个容器里属于本项目的
只有 3 个，能动的只有 2 个。5 个候选 + 建议执行顺序：
  1 停 certimate 容器（工作流已全停用）——先 stop 观察，别急着删
  2 cn-dns-helper 大概率已是遗留（「Worker 侧签发」时代产物；现在签发在国内机且自带 dnsprovider，
    /preflight 显示 CF 凭据可读；Worker 侧 dnsremoted.ts 已无任何引用）
  3 Gitea：迁 or 不留
  4 两套写作前端收敛（本轮不动，先看使用频率）
  5 writeapi.usj.cc 证书纳管（12 月死线）
并明确列出 6 项「必要复杂度，不建议动」。

五、架构总览补齐证书管家子系统（★ 之前完全缺席）

一个完整子系统在「事实源文档」里一个字都没有 —— 这本身就是文档债。补：
- §0 一句话（四→五个子系统）、§1.1 子系统表、§1.2 地址地图两行
- **新增 §5.7 证书管家**：职责划分 / 为什么非要这么分（Worker 免费版 CPU 10ms）/
  三条不能破的红线（Worker 不得签发 · 证书路由只认 Bearer 会话 · 角色必须正着枚举放行）/
  纳管域名表 / 与 certimate 的关系 / 已知遗留
- .cnb.yml 行数 284 → 337（数字漂了）；头部更新时间 → 2026-10-06；附录表改指 docs/
- §6 待办：#13（证书遗留）、#14（复杂度盘点）新增；#7 改写为「Gitea 11 月到期，★ 有死线」

六、记忆

.workbuddy/memory/MEMORY.md 新增「文档结构」「Gitea 迁移死线」两节；证书管家节补实测与遗留。

2026-10-06 22:27:36 +08:00

8.7 KiB

Raw Blame History

架构精简候选

用途：本文是待决策清单，不是现状描述。现状看 ../架构总览.md。每条都是「已确认可以动、但需要你拍板」的项，附收益 / 代价 / 风险 / 怎么做。

更新时间：2026-10-06

一、复杂度的真实来源：不是「件数多」，是「跨了 6 个环境」

环境	谁在维护	上面跑什么	是否必需
腾讯云 CNB	托管	代码主仓 + 构建 + 发布（7 个 stage）	★ 必需（发布的骨架）
Cloudflare	托管	评论后端 + RSS + 证书只读面 + D1/KV + 200181.xyz 的 DNS	★ 必需（零运维）
国内机 `119.29.215.187`	自己	9 个容器（见下）+ 一堆手工 vhost	部分必需
境外 VPS `23.254.236.47`	自己	Gitea（代码辅仓）	⚠️ 2026 年 11 月到期
家庭 F50 / OpenList	自己	离线加密备份	★ 必需（唯一的离线层）
本机 Windows	自己	备份计划任务、本地写作前端	半必需

四台自维护设备 = 复杂度的真正来源，而不是「用了几个云服务」。托管服务再多也不累人（出问题找平台），自己维护的机器每一台都要有人记得它。

国内机 9 个容器里，属于本项目的只有 3 个：

容器	归属	状态
`editor-api`	本项目	✅ 写作后台的线上发布入口
`cn-certkeeper`	本项目	✅ 证书签发 + 部署
`cn-dns-helper`	本项目	⚠️ 疑似遗留（见候选 2）
`1Panel-certimate-OKCO`	历史遗留	⚠️ 可清（见候选 1）
`1Panel-openresty` / `-mysql`	用户的	面板与站点
`1Panel-alist` / `vaultwarden` / `1Panel-frps`	用户的	与本项目无关

→ 能动的只有两个，而且都很干净。

二、精简候选

候选 1 ★ certimate 容器 —— 停掉 `1Panel-certimate-OKCO`


现状	容器还在跑（`certimate/certimate:v0.4.32`）。但 7 个工作流里「会签发并部署」的 2 条已停用（`enabled=0`），只剩 3 条纯监控告警
为什么可以停	本项目已完全接管签发与部署。certimate 现在唯一的作用是「万一要回滚」，而它的凭据早就导出到 `secrets-backup/`，库文件也有 `.bak-*`
收益	少一个常驻容器（内存是这台机器的短板：总 1967 MB / 已用 791 MB）；少一个「静默竞争」风险源
风险	低。但告警能力会消失 —— 三条监控工作流会随之失效。而本项目的证书监控已由 `cn-certkeeper` 的 `/status` + Worker 后台接管，功能不重叠
怎么做	`docker stop 1Panel-certimate-OKCO` → 观察 1～2 周（覆盖一次 04:10 自动续期 + 一次证书到期检查）→ 确认无碍再考虑删容器与数据卷。别急着删，先 stop

⚠️ 若将来要停用，先确认「证书到期提醒」这一层有人接手（现在是 Worker 后台 + 探针）。

候选 2 ★ `cn-dns-helper` 容器 —— 大概率已是遗留


它是什么	「DNS-01 助手」：接受 `POST /dns/txt`，代调用有 DNS 权限的 Cloudflare API 写 TXT 记录
当初为什么有	Phase 1 时代签发跑在 CF Worker 里，而 Worker 那份 CF token 是 Workers/KV/D1 专用的（没有 Zone/DNS 权限）→ 只好让国内机代写
为什么现在不需要	★ 签发已搬到 `cn-certkeeper`（国内机），它自带 dnsprovider，直接调腾讯云 DNSPod / Cloudflare API。实测 `/preflight` 7/7 全过，其中 `cloudflare → 200181.xyz` 报「可读」= 这份凭据有 Zone 权限 → 不需要中转
代码侧证据	`deploy/cn-certkeeper/lib/dnsprovider.js` 里 `remote` 型是兜底分支（注释写明「用于 CF token 无 DNS 权限的场景」）；Worker 侧 `dnsremoted.ts` 已无任何引用
收益	少一个常驻容器 + 少一个对外 HTTP 端点（虽然只绑回环）
风险	低，但要实测确认：万一某条域名的 DNS-01 仍走 `remote`，停掉会让那次续期失败
怎么验证	① 查 `cn-certkeeper` 的凭据里有没有 `remote` 型（`/preflight` 的 dns 项只列了 `tencent-usj` / `tencent-tt` / `cloudflare`，没有 remote）② 停容器 → 手动跑一次单域续期（`renew-one.mjs`）→ 成功即可判死
结论	建议停掉，跑一次续期验证

候选 3 Gitea —— 迁到新机，还是干脆不留

这是本轮最大的一刀，完整分析见 Gitea迁移指南.md 第九节。摘要：

选项	收益	代价
A. 迁到新机	保留「在线可 clone、可按提交追溯、不受平台规则约束」的副本	继续养一台机器 + 一个要运维的实例（且 Gitea 不参与构建、不参与发布）
B. 不迁，去掉辅仓	少一台机器、少一个部件，架构回到 CNB 主仓 + F50 离线加密 bundle 两层	少一层在线冗余（但离线层是完整历史，且已带失败告警）
C. 换托管平台私有仓	不用自己运维	CNB 已是托管平台，再挂一家同性质的收益有限

判断依据：Gitea 现在挡的是「CNB 跟 GitHub 一样出问题」—— 但离线 bundle 已经覆盖了这个场景。Gitea 多出来的独有价值只有「在线可浏览」与「可增量拉取（不用等一天一次的备份）」。这两点用不上，B 就是合理的简化。

若选 B：deploy/gitea/ 留在仓库里即可（部署包与迁移清单留着，随时能重建），然后按 Gitea迁移指南.md 第三节把那 9 处 gitea 引用清掉 —— 别忘了线上那两处（/srv/editor-api/.env、/srv/blog 的 remote）。

候选 4 写作前端两套并存（`write-server/` vs `write/`）


现状	`write-server/`（Next.js，线上 `post.usj.cc`）+ `write/`（本地 Windows 前端），架构总览已注明「功能重叠」
另外	`editor-api/`（国内机）才是真正的那条发布入口 —— 后台发的文章走它
收益	少维护一套前端；文档里的「写作系统」不再需要解释三个东西的关系
风险	取决于你实际用哪个。若两套都在用，就不是「精简」而是「迁移」
建议	先确认实际使用频率，再决定砍哪个。本轮不动

候选 5 三个手工 vhost 的证书（不是精简，是收尾）

writeapi.usj.cc 的证书没被本项目纳管（配置在 /www/conf.d/，不在 1Panel 站点树里），实测仍是 RSA / 到期 2026-12-07，而本项目续期不会更新它 → 12 月会断。

两条路：

A. 让 cn-certkeeper 覆盖它：把 /www/conf.d/writeapi.usj.cc.conf 的证书路径指到 openlist.usj.cc 那种「已被纳管」的文件，或把它纳入部署目标
B. 在 1Panel 里把它建成正式站点，自然被 ssl/upload + sslID 覆盖

详见 ../架构总览.md §6 待办 #13。

三、明确不建议动的（必要复杂度）

项	为什么保留
又拍云 + 多吉云 + EdgeOne 三个分发目标	境内/境外双线路是业务需求（境内走又拍云→多吉云，境外走 EdgeOne），不是历史堆积
Cloudflare Workers 全家（评论 + RSS + 证书只读面）	零服务器零运维，是本项目最省事的一层
国内机的 `editor-api`	写作后台的发布入口，没有替代品（CF Worker 跑不了 git push）
国内机的 `cn-certkeeper`	CF Worker 免费版 CPU 硬顶 10ms，签发跑不动；用户已否决 CF Paid（比这台机器还贵）
家庭 F50 上的离线备份	唯一不依赖任何平台账号的层
三层留存	三层失效模式不同，不是重复（见 `架构总览.md` §5.3）

四、建议的执行顺序

1. 【立刻】候选 5 —— writeapi.usj.cc 证书纳管（12 月会断，有死线）
2. 【本周】候选 1 —— stop certimate 容器（零风险，观察即可）
3. 【本周】候选 2 —— 停 cn-dns-helper + 跑一次续期验证（大概率能省一个容器）
4. 【11 月前】候选 3 —— Gitea：迁 or 不留（★ 必须决定，机器要到期了）
5. 【有空】候选 4 —— 写作前端收敛（先看使用频率）

前三项做完，国内机上属于本项目的容器从 3 个降到 1 个（只剩 editor-api），自维护环境从 6 个降到 5 个（去掉境外 VPS）。 这才是「感觉复杂」的真正解药 —— 减的是「要记得它」的东西，不是「存在于架构图里」的东西。

8.7 KiB Raw Blame History Unescape Escape