# 优世界博客（usj.cc）

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

> 架构全貌、迁移前后对比、运维要点 → [`架构总览.md`](架构总览.md)

---

## 一、项目构成

| 子系统 | 位置 | 技术栈 |
|---|---|---|
| **内容** | `content/`、`themes/Ying/` | Hugo 0.128.2 extended + Ying 主题 |
| **评论后端** | `blog-admin/` | artalk-cf：Cloudflare Workers + D1 + KV（`api.200181.xyz`） |
| **写作后台** | `write-server/`（线上 `post.usj.cc`）、`write/`（本地 Windows） | Next.js |
| **发布** | `.cnb.yml`、`deploy/` | CNB 流水线 + Dockerfile |

---

## 二、目录结构

```
blog/
├── .cnb.yml                 # ★ CNB 流水线（push + 每日定时）
├── deploy/Dockerfile        # 构建镜像（hugo 二进制由 bin/linux/hugo 提供）
├── bin/linux/hugo           # Hugo extended 0.128.2（linux/amd64，供 CNB 构建用）
├── content/
│   ├── posts/<年>/<日期>-<标题>/   # 文章（Page Bundle，index.md + 图片）
│   ├── about.md / links.md / circles.md / archives.md
├── themes/Ying/             # 主题（layout / assets / data）
├── static/                  # 原样复制进产物（emotion 表情、image、js …）
├── blog-admin/              # 评论后端（artalk-cf）
├── write-server/            # 线上写作后台
├── write/                   # 本地写作前端
├── scripts/                 # 各类工具脚本（见第六节）
├── hugo.toml                # Hugo 主配置
└── 架构总览.md              # ★ 架构文档
```

---

## 三、内容写作

### 文章结构

每篇文章是一个 **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          # 含草稿
```

---

## 四、发布流程

```
写作（write-server / write/）
   │  git pushall   （= git push origin main ; git push gitea main）
   ▼
origin → CNB 主仓 zqlit/blog ──触发──► CNB 流水线（国内节点，约 3.5 分钟）
                                ├─ Hugo 构建
                                ├─ 同步到又拍云（境内源站）
                                ├─ 刷新又拍云 CDN
                                ├─ 刷新多吉云 CDN
                                ├─ 部署 EdgeOne Pages（境外线路）
                                └─ 邮件通知

gitea → 自建 Gitea（23.254.236.47:3001）  代码同步辅仓：只推不拉、不参与构建
```

- **推送**：`git pushall` —— 依次推 `origin`（CNB 主仓，触发构建）与 `gitea`（自建 Gitea 代码同步辅仓）
  ；只推主仓用 `git push origin main`
- **备选异地备份**：**不走 git 远端**。本机计划任务每天 03:30 把整仓 bundle
  加密后传到中兴 F50 上的 OpenList（见 `架构总览.md` §5.6）
- **触发**：推送到 `main`；另有每日 `0 9 * * *`（北京时间）定时构建
- **密钥**：全部来自 CNB 密钥仓库 `zqlit/blog-secrets`，经 `.cnb.yml` 的 `imports` 注入，
  **仓库里没有任何明文密钥**
- 改动 `main` 即自动上线，本地无需构建

---

## 五、三个子系统

### 内容系统

Hugo + Ying 主题。`hugo.toml` 控站点信息、永久链接、Artalk 地址、弹幕等。

### 评论系统（`blog-admin/`）

自研的 **Artalk v2 兼容服务端**，跑在 Cloudflare Workers + D1（SQLite）+ KV：

- 前端用官方 Artalk 客户端（`themes/Ying/assets/js/libs/Artalk.js`，本地打包，非 CDN）
- 后端 API 基址 `https://api.200181.xyz`（评论 `/api/v2/*` 与 RSS 订阅 `/api/*` 同一 Worker）
- 部署：`cd blog-admin && npm run deploy`（详细步骤见 `blog-admin/README.md`、`部署清单.md`）

### 写作后台

- `write-server/`：线上版（Next.js），部署在独立主机
- `write/`：本地 Windows 版

---

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

| 脚本 | 用途 | 在哪跑 |
|---|---|---|
| `add_draft_to_hidden.py` | 构建前把 `status: hidden` 转成草稿 | **CI** |
| `refresh_cdn.js` | 刷新多吉云 CDN（零依赖） | **CI** |
| `send_mail.js` | 构建结果邮件通知（零依赖 SMTP） | **CI** |
| `setup-cnb-remotes.sh` | 切换/重建 git 远端（CNB 主仓 + 自建 Gitea 辅仓；顺手清掉退役远端） | 本机 |
| `backup-run.mjs` | 备份的推荐入口：跑 `backup-bundle` + **失败时发告警邮件** | 本机/计划任务 |
| `backup-bundle.mjs` | 整仓 bundle → AES-256-GCM 加密 → WebDAV 传中兴 F50（见 架构总览 §5.6） | 本机/计划任务 |
| `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 自动完成。

---

## 七、相关文档

| 文档 | 内容 |
|---|---|
| `架构总览.md` | **当前架构全貌**（子系统、发布链路、迁移前后对比、运维要点） |
| `CNB构建落地方案.md` | 迁 CNB 的实施方案与实测数据 |
| `代码源与构建平台选型.md` | 平台对比（CNB / Gitee / GitLab / EdgeOne / 阿里云 ESA） |
| `砍COS改造步骤.md` | 腾讯云 COS 下线记录 |
| `blog-admin/README.md` | 评论后端完整说明 |
| `blog-admin/部署清单.md` | 评论后端部署步骤 |