zqlit
b39dc29753
起因：GitHub 账号被平台标记，随后仓库被按 AUP 合规条款清空 ——
远端只剩一条孤立提交（无父提交、无内容）：
c21d5669 2026-10-06 20:08:32 +0800 zqlit
chore: remove repository content (AUP compliance)
同时远端 main 的历史与本地**完全分叉**：两边只共享 2024-07-11 的 Initial commit，
之后每个提交 SHA 都不同（远端那份 989 提交、剥离了 .env/私钥/大二进制）。
所以 `git push gh main` 无法快进，也不可能再当备份用。
改动：
- `git remote remove gh`（改动前配置存 .workbuddy-backup/git-remotes.20261006-201354.txt）
- `pushall` 别名 → `git push origin main; git push gitee main`
- `scripts/setup-cnb-remotes.sh`：参数化第二个远端为 Gitee，
顺带把「若残留 gh remote 就清掉」做进脚本；Gitee 凭据走 wincred
- `架构总览.md`：§2 发布旅程图、§5.2 远端表、§6 遗留待办全部改指向；
新增 §5.2 的 GitHub 退役记录（含那条孤立提交的原文）
与 §5.3「Gitee 辅仓的两条硬约束」实测核算
- `CNB构建落地方案.md`、`README.md`：远端与 pushall 说明同步
- **发布链路一起去 GitHub 化**（这几处原先都写死了 gh）：
· `deploy/editor-api/bootstrap.sh` GH_URL/GH_SSH_KEY → GITEE_URL/GITEE_SSH_KEY，
remote `gh` → `gitee`，known_hosts/私钥文件名跟着改；
保留原设计：**没给私钥就自动降级成只推 origin**，不会让每次发布都报错
· `docker-compose.editor.yml` PUSH_REMOTES → origin,gitee
· `editor-api/server.mjs` 默认值 → 'origin,gitee'
· `editor-api/README.md` 变量表同步
★ 尚未解决 / 需要决策的两条 Gitee 硬约束（详见 架构总览.md §5.3）：
1. **单文件 ≤ 50MB，而 `bin/linux/hugo` 是 83.1MB**
—— 不管怎么瘦身历史，只要它还跟踪在 HEAD 里，Gitee 一律拒收。
2. 单仓库 ≤ 500MB，而 `.git` 是 620MB
—— 移出那个 83MB 后 HEAD ≈ 374MB，才有余量。
另：线上 editor-api 容器的 .env 仍是 `PUSH_REMOTES=origin,gh`，
且仓库里还有一个 `gh` remote。因为推送逻辑对辅仓失败只警告、不阻断发布
（`git.mjs`：主仓成即算成），所以**线上发布没有坏**；
但要真正切到 Gitee，需要等 Gitee 仓库与私钥就位后再部署一次。
156 lines
5.6 KiB
Markdown
156 lines
5.6 KiB
Markdown
# 优世界博客（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
|
||
▼
|
||
CNB 主仓 zqlit/blog ──触发──► CNB 流水线（国内节点，约 3.5 分钟）
|
||
├─ Hugo 构建
|
||
├─ 同步到又拍云（境内源站）
|
||
├─ 刷新又拍云 CDN
|
||
├─ 刷新多吉云 CDN
|
||
├─ 部署 EdgeOne Pages（境外线路）
|
||
└─ 邮件通知
|
||
```
|
||
|
||
- **推送**：`git pushall` = `git push origin main; git push gitee main`
|
||
（`origin` = CNB 主仓，触发构建；`gitee` = 辅仓，异地备份、不构建）
|
||
- **触发**：推送到 `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 主仓 + GitHub 备份） | 本机 |
|
||
| `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` | 评论后端部署步骤 |
|