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 迁移死线」两节；证书管家节补实测与遗留。
69 lines
4.8 KiB
Markdown
69 lines
4.8 KiB
Markdown
# 文档地图
|
||
|
||
仓库的文档分三层，**看文档先看这张表**：
|
||
|
||
| 层 | 位置 | 什么时候看 |
|
||
|---|---|---|
|
||
| **入口** | [`../README.md`](../README.md)、[`../架构总览.md`](../架构总览.md) | 想搞清「这个项目是什么、现在长什么样」 |
|
||
| **当前有效** | 本目录（`docs/*.md`） | 要动某块东西，先看对应的专题文档 |
|
||
| **历史归档** | [`archive/`](archive/) | 想知道「当初为什么这么选」——**不代表现状** |
|
||
|
||
> ⚠️ 归档文档开头都有 `📦 本文档已归档` 标记。里面出现的一切结论，**先去 `架构总览.md` 复核再用**。
|
||
|
||
---
|
||
|
||
## 一、当前有效
|
||
|
||
| 文档 | 内容 | 什么时候更新 |
|
||
|---|---|---|
|
||
| [`证书管家.md`](证书管家.md) | **证书子系统唯一事实源**：现状速览、架构定案（签发在国内机 / Worker 只读）、决策沿革与**勿回退的坑**（§8.4 / §9.9 / §9.11 / §9.12） | 改签发/部署代码前 |
|
||
| [`Gitea迁移指南.md`](Gitea迁移指南.md) | 自建 Gitea 要搬机器时，**必须同步改的全部位置** + 数据迁移 + 验证清单 | 迁移 Gitea 时**从头照着做** |
|
||
| [`架构精简候选.md`](架构精简候选.md) | **待决策清单**：复杂度盘点 + 5 个可精简候选（收益/代价/风险/怎么做）+ 建议执行顺序 | 想「让架构简单点」时看 |
|
||
| [`CNB构建落地方案.md`](CNB构建落地方案.md) | 迁 CNB 的实施方案、流水线细节与实测数据 | 改 `.cnb.yml` / `deploy/Dockerfile` 前 |
|
||
| [`GITEA_SECRETS.md`](GITEA_SECRETS.md) | Gitea 相关凭据清单 —— ⚠️ **含明文凭据，勿外传** | 凭据轮换后 |
|
||
|
||
---
|
||
|
||
## 二、历史归档（`archive/`）
|
||
|
||
### 平台与选型 —— 「当初为什么选它 / 没选它」
|
||
|
||
| 文档 | 结论（一句话） |
|
||
|---|---|
|
||
| [`代码源与构建平台选型.md`](archive/平台与选型/代码源与构建平台选型.md) | CNB / Gitee / GitLab / EdgeOne / ESA 横向对比 → **选 CNB** |
|
||
| [`Gitee方案评估.md`](archive/平台与选型/Gitee方案评估.md) | Gitee 卡单文件 50MB / 单仓 500MB → **未采用** |
|
||
| [`EdgeOne双区域方案评估.md`](archive/平台与选型/EdgeOne双区域方案评估.md) | 境内外双线路方案 → 现用于境外线路 |
|
||
| [`阿里云ESA评估.md`](archive/平台与选型/阿里云ESA评估.md) | 与 EdgeOne 对比 → **未采用** |
|
||
| [`精简方案-只留CF和Hugo.md`](archive/平台与选型/精简方案-只留CF和Hugo.md) | 大精简的设想与边界 |
|
||
| [`砍COS改造步骤.md`](archive/平台与选型/砍COS改造步骤.md) | 腾讯云 COS 下线记录（**已执行完毕**） |
|
||
|
||
### 功能与修复 —— 已完结的一次性改造
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`诊断报告-2026-10-06.md`](archive/功能与修复/诊断报告-2026-10-06.md) | 四问诊断（当天的体检报告） |
|
||
| [`评论孤儿修复方案-2026-10-06.md`](archive/功能与修复/评论孤儿修复方案-2026-10-06.md) | 找回挂在 404 页面上的评论 |
|
||
| [`评论加载优化方案.md`](archive/功能与修复/评论加载优化方案.md) | 评论区加载性能（CF 免费版约束下） |
|
||
| [`在线编辑器集成评估.md`](archive/功能与修复/在线编辑器集成评估.md) | 在线编辑器集成到后台的评估 → **已实现**（见 `editor-api/`） |
|
||
|
||
### 主题与内容 —— Hugo 主题 / 字体 / 样式
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`主题与内容/性能优化（历史）/`](archive/主题与内容/性能优化（历史）/) | 2025 年那轮主题性能优化（18 篇，含 PJAX / JS 按需加载 / 字体子集化）。⚠️ 其中「GitHub Actions」两篇已彻底失效 —— GitHub 已退出本项目 |
|
||
| [`主题与内容/古风官职字符添加指南.md`](archive/主题与内容/古风官职字符添加指南.md) | 字体子集增补生僻字的**操作步骤**（配套 `scripts/add_ancient_chars.py`，现在仍可用） |
|
||
| [`主题与内容/博客字体优化文章规划.md`](archive/主题与内容/博客字体优化文章规划.md) | 字体优化系列文章的选题规划 |
|
||
| [`主题与内容/深色模式表格修复指南.md`](archive/主题与内容/深色模式表格修复指南.md) | 深色模式表格样式问题定位与修复 |
|
||
| [`主题与内容/CLEANUP_GUIDE.md`](archive/主题与内容/CLEANUP_GUIDE.md) | Ying 主题自带文档的清理清单（**已执行**） |
|
||
|
||
---
|
||
|
||
## 三、还有哪些文档不在本表里
|
||
|
||
| 位置 | 说明 |
|
||
|---|---|
|
||
| `blog-admin/README.md`、`blog-admin/部署清单.md` | 评论后端（artalk-cf）的完整说明，**随子系统走** |
|
||
| `editor-api/README.md` | 写作后台 API（国内机容器），含「落盘：写一次，存三处」 |
|
||
| `write-server/`、`write/` 内的文档 | 各自子系统的说明 |
|
||
| `.workbuddy/memory/` | 逐日工作日志与项目长期记忆（**不入库**，仅供本地 agent 使用） |
|