blog/架构总览.md

优世界博客 · 架构总览

更新时间：2026-10-04（CNB 迁移完成当日） 状态：迁移已落地并跑通（四线路全绿，单次发布约 3.5 分钟） 本文档只描述现状；迁移前的复杂度审计与选型过程见文末「相关文档」。

---

0. 一句话

四个子系统，一条 3 步的托管发布链路。构建与发布已从「自建 Gitea + act_runner + 广州中转机」迁到 腾讯云 CNB（cnb.cool） —— 需要自己运维的机器从 3 台降到 0 台。

---

1. 全景

1.1 四个子系统

#	子系统	技术栈	跑在哪	状态
1	内容系统	Hugo 0.128.2 extended + Ying 主题，138 篇 md；产物约 3200 文件 / 424MB	产物分发到 3 个 CDN	正常
2	评论系统	blog-admin/ = artalk-cf（Artalk v2 兼容服务端）+ RSS 机器人	Cloudflare Workers + D1 + KV → api.200181.xyz	✅ 零服务器零运维
3	写作系统	write-server/（Next.js 16，post.usj.cc） write/（本地 Windows 前端）	独立 Docker 主机／本机	可用（两套前端功能重叠）
4	发布基础设施	CNB 流水线（.cnb.yml）+ 又拍云 + 多吉云 + EdgeOne	腾讯云 CNB（托管）	新建，已跑通

1.2 服务与地址地图

角色	地址 / 位置	说明
代码主仓	cnb.cool/zqlit/blog	CNB，私有；构建由它触发
代码备份	github.com/zqlit/blog	仅作备份，不参与构建
构建 + 发布	CNB 流水线（腾讯云国内节点，4 核 8G）	托管，0 元（免费额度内）
密钥仓库	cnb.cool/zqlit/blog-secrets	CNB「密钥仓库」类型，10 项变量经 imports 注入
境内源站	又拍云对象存储	由 CNB 国内节点直传（原为 if: false 的死代码）
国内加速	多吉云 CDN	回源又拍云
境外线路	EdgeOne Pages（项目 hugo-blog，--area overseas）	腾讯 EdgeOne 国际站
评论后端	api.200181.xyz	Cloudflare Workers
通知	QQ 邮件（imql@qq.com）	已收敛为单一通道

关键点：境内、境外仍是两条独立线路，但由同一条流水线一次推完 —— 这是本次迁移最大的结构性改善。

---

2. 一次发布的完整旅程（3 步）

① 写作        write-server（网页） 或  write/（本地 Windows）
       │
② git push      git pushall  =  git push origin main ; git push gitee main
       │        ├─ origin → cnb.cool/zqlit/blog     （主仓，触发构建）
       │        └─ gitee  → gitee.com/…/blog        （辅仓，异地备份，不构建）
       ▼
③ CNB 流水线（国内节点，约 3.5 分钟，7 个 stage 顺序执行）
       ├─ 1. Hugo 构建          草稿隐藏预处理 → hugo --minify --gc → 算构建哈希
       ├─ 2. 同步到又拍云        upx sync（境内直传，非阻断但如实上报）
       ├─ 3. 刷新又拍云 CDN      purge 首页 + sitemap/rss/archives/posts 等固定入口
       ├─ 4. 刷新多吉云 CDN      node scripts/refresh_cdn.js
       ├─ 5. 部署 EdgeOne        edgeone pages deploy --area overseas
       ├─ 6. 上报部署状态        POST api.200181.xyz/api/deploy-status
       └─ 7. 邮件通知            成功 → stages 末尾；失败 → failStages

对照：迁移前是 7 步，中间有 3 个环节是你自己运维的服务器。

---

3. 流水线细节（.cnb.yml，284 行）

触发	条件	说明
push	推送到 main	主链路
crontab	0 9 * * *（Asia/Shanghai）	每天 09:00，与 push 共用同一组 stage（YAML 锚点）

机制	实现
构建镜像	deploy/Dockerfile，hugo 二进制随仓库携带（bin/linux/hugo，linux/amd64）
⚠️ docker 上下文	by: [bin/linux/hugo] —— CNB 的 docker build 只看得见 Dockerfile + by 列出的文件，漏写会报 not found
密钥注入	imports: https://cnb.cool/zqlit/blog-secrets/-/blob/main/secrets.yml
stage 间传状态	落盘 .ci_status（原版靠 needs.*.outputs）
并发控制	lock.cancel-in-progress（对应原 concurrency）
非阻断	又拍云三步 + 状态上报 + 邮件用 allowFailure: true，失败仍写状态如实上报
资源	cpus: 4（4 核 8G）

---

4. 迁移前后对比

维度	迁移前（Gitea 自建）	迁移后（CNB）
发布链路环节	7 步	3 步
自维护机器 / 服务	3 台（Gitea 主机 + act_runner + 广州中转机）	0（构建托管）
流水线定义	GitHub Actions 1169 行	.cnb.yml 284 行
产物传递	打 tar.zst → artifact → 中转机跨境下载	同一 pipeline 共享工作目录，无需传递
又拍云直传	if: false（境外 runner 必挂，从未跑通）	已跑通（国内节点直传）
COS 中转层	需要（存储 + 流量账单）	已砍
github.server_url 兼容分支	8 处	0
通知	3 套（TG / 飞书 / 邮件），约 400 行	1 套（邮件）
图片优化 + 反向 commit	CI 内每轮白跑（15 张老图处理不掉）	未迁（如需保留，照搬 scripts/optimize_images.js）
构建环境	境外 VPS	腾讯云国内节点 4 核 8G
费用	VPS 月租	0 元（100GiB 仓库 + 160 核时/月）
单次发布耗时	—	约 3.5 分钟

原链路里那些补丁（COS 中转 / sync.sh 每分钟轮询 / artifact 打包 / 兼容分支） 唯一根因是「runner 在境外」。CNB 节点在国内，这一整层随之消失。

---

5. 运维要点

5.1 推送

git pushall              # 别名 = git push origin main; git push gitee main
git push origin main     # ← 当前实际只用这条：gitee remote 尚未建立（见 §6 #2）

用 ; 而非 && —— 一段失败不影响另一段（实测：串联 pushurl 时第一个失败会中止后续）。

5.2 远端

remote	地址	角色
origin	https://cnb.cool/zqlit/blog.git	主仓（fetch + push，触发 CNB 构建）
gitee	https://gitee.com/<用户名>/blog.git	辅仓（push，异地备份，不参与构建）
gitea	自建 23.254.236.47:3001	只读参考，稳定后手工删

⚠️ gh（GitHub）已于 2026-10-06 移除。 起因：GitHub 账号被平台标记，随后仓库被按 AUP 合规条款清空 —— 远端留下一条孤立提交（无父提交）：

c21d5669 2026-10-06 20:08:32 +0800 zqlit <zqlit@users.noreply.github.com>
chore: remove repository content (AUP compliance)

同时远端 main 的历史与本地完全分叉（两边只共享 2024-07-11 的 Initial commit， 之后每个提交 SHA 都不同；远端那份是 989 提交、剥离了 .env/私钥/大二进制的变体）。 教训：别把「备份」寄托在会对内容做合规处置的平台上； 且一旦某次历史被重写，SHA 从此再也对不上。 远端配置的改动前快照留在 .workbuddy-backup/git-remotes.20261006-201354.txt。

5.3 辅仓选型（2026-10-06 实测核算）

体积分布（HEAD，实测 457.4 MB / 2509 文件）：

目录	体积	说明
content/（含 posts/）	≈ 308 MB	博客正文与媒体（mp4/mp3/大图），搬不走
bin/linux/hugo	83.1 MB	CNB 构建用的 hugo 二进制，可移出 git
static/	≈ 38 MB	站点静态资源
themes/	20.3 MB	Ying 主题
其余全部	≈ 8 MB	代码、文档、脚本

Gitee 的两条硬约束 —— 都不满足：

约束	Gitee 免费版	本仓库当前	判定
单仓库容量	≤ 500 MB	.git 620 MB	❌ 超 24%
单文件大小	≤ 50 MB	bin/linux/hugo 83.1 MB	❌ 必删
用户总仓库容量	5 GB	620 MB	✅
私有仓协作人数	5 人	个人	✅ 无关

bin/linux/hugo 是硬门槛：不管怎么瘦身历史，只要它还跟踪在 HEAD 里，Gitee 一律拒收。 → 移出后 HEAD ≈ 374 MB，才有一份余量。

对照：阿里云效 Codeup 基础版 —— 两条硬约束一条都不存在：

项	Gitee 免费版	云效 Codeup 基础版
单库容量	≤ 500 MB	Git 5 GiB + LFS 5 GiB
单文件	≤ 50 MB	Web 50 MB / 命令行 200 MB
620 MB 的 .git	超 24%，推不上	占 12.1% ✅
83.1 MB 的 hugo	超 66%，一律拒收	占 41.6% ✅
价格	免费	0 元/人/年，不限人数、不限仓库数

→ 若选 Codeup，bin/linux/hugo 不必出库，deploy/Dockerfile 与 .cnb.yml 的 by: 字段一行都不用改（首推 620 MB 也在其 60 分钟推送超时内）。 注意两点：① 默认「中心组织」只支持阿里云 RAM 账号登录、且必须绑钉钉， 不接受的可选 2025-12 上线的「地域组织」（华东2上海，支持自建账号密码）； ② 基础版无「删库保护」，容量到 90% 提醒、超限直接禁止写操作（连删文件都做不了）。 已有的阿里云 OSS AccessKey 不能用来建 Codeup 仓库 —— git 推送走独立的克隆账号密码或 SSH Key。

★ 但这些都只是「换一个篮子」，不是容灾。 CNB 与 Gitee/Codeup 同属国内大区，GitHub/GitLab 又执行同一套合规逻辑 （本轮 GitHub 被按 AUP 清空即为例证）。 真正的第三层是不依赖任何平台账号的离线备份 —— 见 §5.6。

5.4 凭据

• 令牌存仓库外：~/.workbuddy/secrets/cnb-token
• 本仓 credential.helper 指向一个自定义脚本；.git/config 无明文
• ⚠️ 本机全局 helper 是 GCM（会弹窗、对第三方 HTTPS 远端还会挂死）；wincred 对 cnb.cool 有过「幽灵记录」删不掉 → 故用自定义 helper 绕开

5.5 密钥

• 修改密钥 → 编辑 CNB 密钥仓库的 secrets.yml（网页编辑，禁 clone）
• 本地 cnb-secrets.yml 只是粘贴草稿（已 gitignore，不入库）
• ⚠️ CNB 的 imports 是一层映射（key 就是变量名本身）；又拍云服务名在 CNB 里必须叫 UPYUN_SERVICE（旧 Gitea 里叫 UPYUN_BUCKET，照抄会「变量未定义」）

5.6 整仓离线备份（中兴 F50 / OpenList，2026-10-06 上线）

目标介质：中兴 F50 5G CPE 内置 256 GB 存储，上面跑 OpenList （http://192.168.0.1:5244，WebDAV 端点带 /dav 前缀）。7×24 常开、走局域网、 不依赖任何 git 平台账号 —— 这是它比「再选一个代码托管平台」更值钱的地方。

为什么是 bundle 而不是直接推 git：WebDAV 不支持原子的 rename/lock， 把 bare repo 挂上去直接 git push 会让对象写坏 —— 表面成功、实际随机损坏， 可能几个月后才发现。bundle 是单文件顺序写，没有这个问题。

为什么加密：本仓库历史里含 .env、TLS 私钥、GITEA_SECRETS.md。 介质是一台随身设备的内部存储，明文等于把密钥放在可能丢失 / 刷机 / 送修的设备上。 OpenList 的登录只保护访问通道，不保护存储介质 —— F50 丢了拆开就能读。

为什么不用 gpg：本机 gpg 2.4.9 在 Windows 下已损坏（反复 removing stale lockfile， node spawn 直接 EBUSY）。改用 Node 内置 crypto 的 AES-256-GCM： 零外部依赖、带认证标签（能检测篡改/截断）、可流式处理 600 MB 不爆内存。

加密文件布局：magic(8) | salt(16) | iv(12) | 密文(...) | GCM tag(16)， 密钥由 scrypt(N=32768, r=8, p=1) 从口令派生。

用法（scripts/backup-bundle.mjs，零 npm 依赖）：

node scripts/backup-bundle.mjs                 # 加密 + 上传 + 比对字节数
node scripts/backup-bundle.mjs --verify        # 额外下载回来比对 sha256（端到端最可靠）
node scripts/backup-bundle.mjs --dry           # 只打包加密，不上传
node scripts/backup-bundle.mjs --keep 3        # 远端保留最近 3 份
node scripts/backup-bundle.mjs --list          # 列出远端现有备份
node scripts/backup-bundle.mjs --decrypt <文件> [--out x.bundle]   # 恢复用

配置（按序查找，先找到生效）：环境变量 → ~/.openlist-backup.env → .workbuddy-backup/openlist-backup.env（已在 .gitignore 内）。 键为 OPENLIST_URL / OPENLIST_USER / OPENLIST_PASS / OPENLIST_DIR / BACKUP_PASSPHRASE。

⚠️ BACKUP_PASSPHRASE 是恢复 bundle 的唯一钥匙，必须另存进密码管理器。 但它不构成单点：CNB 主仓与自建 Gitea 仍是明文，口令丢了只是少一份备份。

定时任务：Windows 计划任务 Blog-BundleBackup，每天 03:30（本地） 执行 scripts/backup-task.cmd（默认 --verify --keep 3）。 设置：InteractiveToken + LeastPrivilege、StartWhenAvailable（错过就补跑）、 ExecutionTimeLimit=PT1H、MultipleInstances=IgnoreNew（防重入）。 日志追加到 .workbuddy-backup/logs/backup.log，超 5 MB 自动轮转。

★ backup-task.cmd 内容必须全 ASCII：cmd.exe 按当前代码页（zh-CN 是 GBK） 解析批处理文件，而 node 输出 UTF-8；UTF-8 中文注释会吞掉 CR/LF、 把下一行当命令执行（实测踩到：一条 rem 被当命令跑了）。 ASCII 是 UTF-8 子集，纯英文注释与 node 的中文输出混写不会乱。

恢复流程：

node scripts/backup-bundle.mjs --decrypt blog-<时间戳>.bundle.enc --out blog.bundle
git bundle verify blog.bundle      # 应报 "records a complete history"
git clone blog.bundle blog         # 或 git fetch blog.bundle 'refs/*:refs/*'

实测数据（2026-10-06，由计划任务实际拉起跑通）：

阶段	耗时
git bundle create --all	6.8 ~ 9.9 s（605.5 MB）
AES-256-GCM 加密	1.9 ~ 2.9 s（体积不变）
WebDAV 上传	19.4 ~ 20.6 s → 29.4 ~ 31.3 MB/s
下载回读 + sha256 比对	≈ 19 s，一致

端到端退出码 0；恢复链路已演练（解密 → git bundle verify → 1008 提交完整一致）。

---

6. 遗留待办

#	项	说明
1	gh remote（GitHub）	✅ 已移除（2026-10-06）。GitHub 账号被标记、仓库被 AUP 清空 —— GitHub 已彻底退出本项目的备份体系：远端、推送别名、发布链路、CI 定义全部清干净。辅仓选型见 #2
2	辅仓选型（未定）	当前 pushall 已写成 origin + gitee，但 gitee remote 尚不存在 → 每次 git pushall 的第二段会报错（不影响 CNB 那段）。两条路：Gitee（需先解 §5.3 两条硬约束）或云效 Codeup（见 §5.3 对照，零改造，但需绑钉钉或选「地域组织」）。定下后再 git remote add
3	bin/linux/hugo 出库	83.1MB，超 Gitee 单文件上限。只有选 Gitee 才必须做；选 Codeup 则不必（占其命令行 200MB 上限的 41.6%）。要做的话需改为构建时获取（国内镜像 / CNB 对象存储），并同步改 .cnb.yml 的 by: 字段
4	gitea remote	只读保留，稳定几天后 git remote remove gitea
5	GitHub 侧旧 workflow	✅ 已删除（2026-10-06）。整个 .github/ 目录移除（deploy.yml 1169 行 + aliyun-backup.yml + cleanup.yml）—— GitHub 已不再是任何环节的依赖。旧实现可在 git 历史中查
6	令牌 scope	缺 repo-cnb-history:r（读构建日志）；补上后 agent 可自行排错
7	Gitea 主机 / 广州中转机	发布链路已不依赖；是否退役取决于其它用途
8	README.md	仍写着旧 GitHub Actions 流程，待更新
9	敏感文件仍在跟踪中	.env、GITEA_SECRETS.md、write-server/nginx/ssl/privkey.pem、content/posts/2024/.../setup-secrets.png —— 推任何一个新平台前都应先 git rm --cached 并轮换凭据。⚠️ 当初「不改写历史」的唯一顾虑是备份会分叉；GitHub 那份已消失，这个顾虑没有了 → 现在是 git filter-repo 彻底抹掉它们的最佳窗口（代价：全部提交 SHA 改变、自建 Gitea 需重推）。离线 bundle 已加密（§5.6），不受此影响
10	整仓离线备份	✅ 已上线（2026-10-06），见 §5.6。计划任务 Blog-BundleBackup 每天 03:30 跑，端到端已验证。待补三件安全项：把 BACKUP_PASSPHRASE 抄进密码管理器；给 OpenList 改掉 admin 密码 + 开两步验证（现 otp: false，且旧密码已出现在对话里）；确认 5244 端口未暴露到公网

---

附：相关文档

• CNB构建落地方案.md — 迁移实施方案与实测数据
• 代码源与构建平台选型.md — 平台对比（CNB / Gitee / GitLab / EdgeOne / 阿里云 ESA）
• 砍COS改造步骤.md — COS 下线记录
• EdgeOne双区域方案评估.md、Gitee方案评估.md、阿里云ESA评估.md、精简方案-只留CF和Hugo.md — 决策期评估

证据出处（现行）：.cnb.yml（284 行）、deploy/Dockerfile、bin/linux/hugo、 scripts/send_mail.js、scripts/refresh_cdn.js、scripts/setup-cnb-remotes.sh、 scripts/backup-bundle.mjs、scripts/backup-task.cmd。 原 GitHub Actions 流水线（.github/workflows/deploy.yml，1169 行）已于 2026-10-06 删除， 需要查请翻 git 历史。