zqlit
7abef4ac13
用户四问：「把项目文件全部理一遍 还有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 迁移死线」两节；证书管家节补实测与遗留。
143 lines
8.7 KiB
Markdown
143 lines
8.7 KiB
Markdown
# 架构精简候选
|
||
|
||
> **用途**：本文是**待决策清单**，不是现状描述。现状看 [`../架构总览.md`](../架构总览.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`](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`](../架构总览.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）。
|
||
> **这才是「感觉复杂」的真正解药 —— 减的是「要记得它」的东西，不是「存在于架构图里」的东西。**
|