blog/README.md

# 优世界博客（usj.cc）

Hugo 静态博客 + 自研评论后端 + 写作后台 + 证书管家。
**构建与发布跑在腾讯云 CNB**（国内节点），单次发布约 3.5 分钟，境内/境外两条线路一次推完。

> 📖 **想先看懂全局** → [`架构总览.md`](架构总览.md)（架构唯一事实源）
> 🗂 **想找某份文档** → [`docs/README.md`](docs/README.md)（文档地图）
> 🔧 **要动手改东西** → 先看下面「项目构成」找准子系统，再看对应的专题文档

---

## 一、项目构成（五个子系统）

| # | 子系统 | 位置 | 技术栈 | 部署形态 |
|---|---|---|---|---|
| 1 | **内容** | `content/`、`themes/Ying/` | Hugo 0.128.2 extended + Ying 主题 | 产物分发到 3 个 CDN |
| 2 | **评论后端** | `blog-admin/` | artalk-cf：Cloudflare Workers + D1 + KV | 托管（`api.200181.xyz`） |
| 3 | **写作后台** | `write-server/`（线上 `post.usj.cc`）、`write/`（本地）、`editor-api/`（线上发布入口） | Next.js ／ 轻量 Node（零依赖） | 独立主机 ／ 本机 ／ 国内机容器 |
| 4 | **发布基础设施** | `.cnb.yml`、`deploy/Dockerfile` | CNB 流水线 + 又拍云 + 多吉云 + EdgeOne | 托管（CNB，0 元额度内） |
| 5 | **证书管家** | `deploy/cn-certkeeper/`、`blog-admin/src/lib/acme.ts` | 自研 ACME 客户端（纯 WebCrypto，零 npm 依赖） | 国内机容器（签发）+ CF Worker（只读） |

> 子系统 5 的详细设计与「勿回退的坑」见 [`docs/证书管家.md`](docs/证书管家.md)。

---

## 二、目录结构

```
blog/
├── README.md                # ★ 本文（项目入口）
├── 架构总览.md               # ★ 架构唯一事实源
├── docs/                    # 专题文档（地图见 docs/README.md）
│   ├── 证书管家.md
│   ├── Gitea迁移指南.md      # ★ Gitea 换机器时照做
│   ├── CNB构建落地方案.md
│   ├── GITEA_SECRETS.md     # ⚠️ 含明文凭据
│   └── archive/             # 已归档：决策期评估 + 已完结方案
├── .cnb.yml                 # CNB 流水线（push 触发 + 每日定时）
├── content/                 # 文章（Page Bundle：index.md + 图片）
├── themes/Ying/             # 主题
├── static/                  # 原样复制进产物（表情、图片、js …）
├── hugo.toml                # Hugo 主配置
├── bin/linux/hugo           # Hugo extended 0.128.2（linux/amd64，供 CNB 构建用）
├── blog-admin/              # 评论后端（artalk-cf）+ 证书管家的只读面
├── editor-api/              # 写作后台的后端（国内机容器里跑的就是它）
├── write-server/            # 线上写作前端（Next.js）
├── write/                   # 本地写作前端（Windows）
├── deploy/                  # 部署单元
│   ├── Dockerfile           # CNB 构建镜像
│   ├── editor-api/          # bootstrap.sh（一键部署写作后台）
│   ├── cn-certkeeper/       # 证书签发 + 部署容器
│   ├── cn-dns-helper/       # DNS-01 辅助
│   └── gitea/               # Gitea 部署包（原名 gitea-backup/）
└── scripts/                 # 工具脚本（见第五节）
```

> `data/`、`public/`、`.editor-tmp/`、`.workbuddy-backup/` 等为运行时/构建期产物，**已被 `.gitignore` 忽略**。

---

## 三、内容写作

### 文章结构

每篇文章是一个 **Page Bundle**：

```
content/posts/2024/2024-05-01-文章标题/
├── index.md          # 正文
└── 配图.jpg          # 同目录图片（可用相对路径引用）
```

### URL 规则

由 front matter 的 `slug` 决定（`hugo.toml` 里 `permalinks.post = "/:slug"`）：

```yaml
---
title: "我的文章"
date: 2024-05-01
slug: "my-post"
---
```

生成 `https://usj.cc/my-post.html`（uglyURLs，带 `.html`）。

### 隐藏文章

在 front matter 加 `status: hidden`。构建前 `scripts/add_draft_to_hidden.py` 会把它转成
`draft: true`，**不出现在列表里，但直达链接仍可访问**。

### 本地预览

```bash
hugo server -D          # 含草稿
```

---

## 四、发布与留存

### 4.1 一次发布（3 步）

```
① 写作        write-server（网页）或 write/（本地 Windows）
       │
② git push      git pushall  =  git push origin main ; git push gitea main
       │        ├─ origin → cnb.cool/zqlit/blog           （主仓，触发构建）
       │        └─ gitea  → 23.254.236.47:3001/zqlit/blog （自建 Gitea 辅仓，只推不拉）
       ▼
③ CNB 流水线（国内节点，约 3.5 分钟）
       ├─ Hugo 构建 → 同步又拍云 → 刷新又拍云 CDN → 刷新多吉云 CDN
       └─ 部署 EdgeOne Pages（境外线路）→ 上报状态 → 邮件通知
```

- **触发**：推送到 `main`；另有每日 `0 9 * * *`（北京时间）定时构建
- **密钥**：全部来自 CNB 密钥仓库 `zqlit/blog-secrets`，经 `.cnb.yml` 的 `imports` 注入
  —— **仓库里没有任何明文密钥**
- 改动 `main` 即自动上线，本地无需构建

### 4.2 三个留存层（失效模式不同，不能互相替代）

| 层 | 载体 | 保住什么 | 依赖 |
|---|---|---|---|
| **主仓** `origin` | CNB | 源码 + 触发构建 | CNB 平台 |
| **代码辅仓** `gitea` | 自建 Gitea | 在线可 clone、可按提交追溯 | 自己的机器（⚠️ **2026 年 11 月到期，要迁**，见 `docs/Gitea迁移指南.md`） |
| **离线备份** | 中兴 F50 / OpenList | 完整历史 + 所有对象（加密单文件） | 家庭局域网 |

- **推送**：`git pushall` 依次推 `origin` 与 `gitea`；只推主仓用 `git push origin main`
  - 线上写作后台（国内机 `editor-api` 容器）走同一套：`PUSH_REMOTES=origin,gitea`，
    **主仓成功即算发布成功**，辅仓失败只警告不阻断
  - ★ **两边同一条铁律：任何提交都必须先落到 CNB** —— pull 源只有 `origin`，
    只推 `gitea` 的提交后台看不见，下次发布会因 non-fast-forward 被拒
- **离线备份**：本机计划任务每天 03:30 把整仓 bundle（**打包前先 `git fetch --all`**，
  否则备的是过期快照）加密后传到 F50 上的 OpenList（见 `架构总览.md` §5.6）

---

## 五、常用脚本（`scripts/`）

| 脚本 | 用途 | 在哪跑 |
|---|---|---|
| `add_draft_to_hidden.py` | 构建前把 `status: hidden` 转成草稿 | **CI** |
| `refresh_cdn.js` | 刷新多吉云 CDN（零依赖） | **CI** |
| `send_mail.js` | 构建结果邮件通知（零依赖 SMTP） | **CI** |
| `fetch_snapshots.sh` | 构建期拉 conf/友链/友圈快照 → `data/` | **CI** |
| `setup-cnb-remotes.sh` | 重建 git 远端（CNB 主仓 + Gitea 辅仓；顺手清退役远端） | 本机 |
| `pushall.sh` | `git pushall` 的实现：**先 `fetch`+`rebase` 再推** CNB 与 Gitea。为何必须 rebase —— 线上后台发文章会直接推 `main`，本机不先同步必被 rejected | 本机 |
| `backup-run.mjs` | 备份推荐入口：跑 `backup-bundle` + **失败时发告警邮件** | 本机/计划任务 |
| `backup-bundle.mjs` | `git fetch --all` → 整仓 bundle → AES-256-GCM 加密 → WebDAV 传 F50 | 本机/计划任务 |
| `backup-task.cmd` | 上面的计划任务入口（每天 03:30；**内容必须全 ASCII**） | 计划任务 |
| `optimize_images.js` | 图片批量压缩优化 | 本机 |
| `generate_circle_data.js` | 抓友链 RSS 生成朋友圈数据 | 本机 |
| `update_link_lite_json.ps1` | 友链 `links.yaml` → JSON | 本机 |
| `add_ancient_chars.py` / `check_ancient_chars.py` / `merge_chars.py` | 字体生僻字增补与校验 | 本机 |
| `cleanup_duplicates.js` / `migrate_slugs.js` | 一次性维护脚本 | 本机 |

> `deploy_*.sh`（又拍云 / EdgeOne / 定时）是本机手动部署的旧入口，**日常已不需要** ——
> 推送 `main` 由 CNB 自动完成。

---

## 六、文档地图

只列导航，完整说明见 [`docs/README.md`](docs/README.md)。

| 文档 | 内容 |
|---|---|
| [`架构总览.md`](架构总览.md) | ★ **当前架构全貌**（五个子系统、发布链路、运维要点、遗留待办） |
| [`docs/证书管家.md`](docs/证书管家.md) | ★ 证书子系统：现状 + 决策沿革 + 勿回退的坑 |
| [`docs/Gitea迁移指南.md`](docs/Gitea迁移指南.md) | ★ Gitea 换机器：**本仓 9 处写死旧地址**的清单 + 验证步骤 |
| [`docs/架构精简候选.md`](docs/架构精简候选.md) | 复杂度盘点与 5 个可精简候选（想「让架构简单点」时看） |
| [`docs/CNB构建落地方案.md`](docs/CNB构建落地方案.md) | 迁 CNB 的实施方案与实测数据 |
| [`docs/archive/`](docs/archive/) | 决策期评估与已完结方案（**不代表现状**） |
| `blog-admin/README.md`、`blog-admin/部署清单.md` | 评论后端完整说明 |
| `editor-api/README.md` | 写作后台 API（含「落盘：写一次，存三处」） |