zqlit
3eeafa07b2
用户：「动手 推送吧」—— 动手处理两个有死线的遗留。
一、writeapi.usj.cc 的证书（12 月会断）→ 已解决
现状复核推翻了上一轮的判断：
· 上一轮记的「它的 ssl_certificate 引用不在 /www/sites/ 树里」是**错的** ——
/www/conf.d/writeapi.usj.cc.conf 里明确写着
ssl_certificate /www/sites/writeapi.usj.cc/ssl/fullchain.pem;
· 真正原因是**它在 1Panel 面板上根本不是一个网站**（面板共 11 个站点，没有它），
所以 `findWebsite('writeapi.usj.cc')` 必然抛「找不到网站」→
加进 one_panel_sites 只会让**每次续期都报错**（而且只警告不阻断，长期没人发现）
· 实测确认：redeploy 时其余 5 个站点正常，只有它失败
解法：**不写一行代码** —— 它与 artalk.usj.cc 本来就同用一张 *.usj.cc 证书，
让它用**相对软链接跟随 artalk** 即可，随续期自动更新：
ln -sfn ../../artalk.usj.cc/ssl/fullchain.pem /1panel/1panel/www/sites/writeapi.usj.cc/ssl/fullchain.pem
★★ 踩到的坑：软链接**必须相对路径**
宿主 /1panel/1panel/www/sites/ ↔ 容器内 /www/sites/（1Panel 的 openresty 跑在容器
`1Panel-openresty-Kmh2`）。第一版写成宿主绝对路径 → **容器侧断链** →
nginx -s reload **静默失败**（保留旧配置、服务不中断、握手照旧拿旧证书）→
表面全绿，真实后果是「等某天 nginx 重启，writeapi 的 HTTPS 直接挂」。
唯一线索是 worker 进程的启动时间没变 —— **所以验收必须看 worker 是否真的重启**。
验收（全部实测）：
替换前 CN=usj.cc / LiteSSL RSA CA / 2026-12-07（mtime 10-04 21:50）
替换后 CN=*.usj.cc / LiteSSL ECC CA / 2027-01-04
容器内 head -1 → -----BEGIN CERTIFICATE----- / -----BEGIN PRIVATE KEY-----
预检 syntax is ok / test is successful
reload → signal process started；**worker 22:51:39 重启**（证明软链接真被读了）
握手 SNI=writeapi.usj.cc → *.usj.cc / Jan 4 2027；实访 /health → HTTP 200
新增 deploy/cn-certkeeper/src/dump-cert.mjs：把 KV 里（AES-GCM 加密）的证书导成明文 PEM，
补上「KV ↔ 手工 vhost 磁盘文件」之间原先不存在的桥。只读，用完即删（含明文私钥）。
操作层的两个坑（写进文档）：
· 1Panel 文件 API **拒绝写 .mjs**（返回 500「目标路径不存在」，实为可执行扩展名过滤）；
往新建的 root:root 700 目录写也会失败 → 临时脚本用
`docker exec -i … sh -c 'cat > 路径' < 本地文件` 送
· cnrun.py（1Panel 计划任务通道）偶发「退出码 0 但零输出」；
加 `timeout 30 docker exec …` 包一层即稳定，判断状态优先看容器内直接证据
二、配置回退 + 文档更正
· certkeeper-config.mjs：把 writeapi 从 one_panel_sites 移除，换成一段注释说明
「它不是 1Panel 站点，别加进来」+ 软链接做法 + 必须相对的警告；
线上 config.kv 同步回退（sha256 与改动前完全一致 ccac2530…）
· 更正「3 个手工 vhost」的说法：vaultwarden **是**正常纳管的站点（面板 #13，
主域名 vw.usj.cc，别名才是 vaultwarden）→ 手工 vhost 实际只剩 writeapi + dnsapi
· dnsapi.usj.cc 重新定性为**不做**：它是 cn-dns-helper 的反代入口
（proxy_pass 127.0.0.1:8018，仅 HTTP），去留应与 cn-dns-helper 一起决定，
不该单独给一个待退役的服务加 HTTPS
三、pushall 加固：先 fetch + rebase 再推（本次真实撞到的问题）
推 CNB 时被 rejected —— 因为线上写作后台（editor-api）发文章会**直接推 main**，
本机两笔提交与之分叉。这不是异常，是**日常**。原别名直接 push，必然反复撞。
· 新增 scripts/pushall.sh：fetch → 已在远端之后则 rebase → 推所有远端
- 冲突时**停在 rebase 中途**交人工（不强推、不丢东西）
- 工作区不干净时 git 自己会拒绝 rebase（不会吞改动）
- 任一远端失败**不改判另一个**（主仓失败辅仓照样推），退出码以第一次失败为准
- ⚠️ 修了自己写的一处疏漏：`if ! cmd; then ec=$?` 的 $? 是**取反后**的结果（0），
不是 git 的退出码 —— 必须显式 ec=1（靠 set -o pipefail 保证管道退出码不被 sed 掩盖）
· setup-cnb-remotes.sh 的别名改指向脚本；README 脚本表补这一行
四、文档
· docs/证书管家.md：速览表「已知遗留」→ 已解决；§9.14 遗留段重写（含纠正自己写错的判据
「路径像不像不构成判据，要直接查面板站点清单」）；**新增 §9.15**
「手工 vhost 的证书：用相对软链接跟随已纳管站点」（机制 + 路径坑 + 三条验收 + dump-cert 用法）
· docs/架构精简候选.md：候选 5 标记完成，补上「为什么 A 走不通、B 未采用」；
执行顺序里划掉它
· 架构总览.md：§5.7「已知遗留」重写（2 个手工 vhost + vaultwarden 更正）；
§6 待办 #13 改为已解决、#14 标注完成
优世界博客（usj.cc）
Hugo 静态博客 + 自研评论后端 + 写作后台 + 证书管家。 构建与发布跑在腾讯云 CNB（国内节点），单次发布约 3.5 分钟，境内/境外两条线路一次推完。
📖 想先看懂全局 →
架构总览.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。
二、目录结构
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"）：
---
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，不出现在列表里，但直达链接仍可访问。
本地预览
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。
| 文档 | 内容 |
|---|---|
架构总览.md |
★ 当前架构全貌（五个子系统、发布链路、运维要点、遗留待办） |
docs/证书管家.md |
★ 证书子系统：现状 + 决策沿革 + 勿回退的坑 |
docs/Gitea迁移指南.md |
★ Gitea 换机器：本仓 9 处写死旧地址的清单 + 验证步骤 |
docs/架构精简候选.md |
复杂度盘点与 5 个可精简候选（想「让架构简单点」时看） |
docs/CNB构建落地方案.md |
迁 CNB 的实施方案与实测数据 |
docs/archive/ |
决策期评估与已完结方案（不代表现状） |
blog-admin/README.md、blog-admin/部署清单.md |
评论后端完整说明 |
editor-api/README.md |
写作后台 API（含「落盘：写一次，存三处」） |