# 文档地图

仓库的文档分三层，**看文档先看这张表**：

| 层 | 位置 | 什么时候看 |
|---|---|---|
| **入口** | [`../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 使用） |