zqlit/blog
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3eeafa07b2dec6f1ee24378e8405adb193256c5a
blog/README.md
T
zqlit 3eeafa07b2 fix(证书管家): writeapi.usj.cc 证书纳管（相对软链接）；pushall 改为先 rebase 再推 
用户：「动手 推送吧」—— 动手处理两个有死线的遗留。

一、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 标注完成
2026-10-06 22:54:58 +08:00

177 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 优世界博客（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（含「落盘：写一次，存三处」） |
Reference in new issue View Git Blame Copy Permalink