docs: 全量梳理文档结构；补 Gitea 迁移指南 / 架构精简候选；架构总览补证书管家子系统
用户四问：「把项目文件全部理一遍 还有readme文件」「gitea 后面可能还要迁移 帮我写一个迁移文档」
「证书管家做完了吗」「感觉现在架构还是复杂了」
一、文档梳理：根目录 15 个 md → 2 个
根目录只留 README.md（入口）+ 架构总览.md（现状唯一事实源），其余全部归位：
docs/
├── README.md ← 新增：文档地图（入口 / 当前有效 / 历史归档 三层）
├── 证书管家.md ← 原「函数版证书管家-方案.md」改名
│ （它早已是「现状+沿革」文档，标题名不副实 —— 签发早已不在 CF Worker）
├── Gitea迁移指南.md ← 新增
├── 架构精简候选.md ← 新增
├── CNB构建落地方案.md / GITEA_SECRETS.md
└── archive/{平台与选型,功能与修复,主题与内容}/ ← 32 份
- 32 个归档文档统一加 `> 📦 本文档已归档` banner，并指向架构总览
—— 这个仓库历史文档里全是「权威口径」，混看很容易拿废弃结论当现状
- gitea-backup/ → deploy/gitea/（原名「backup」不准，它是部署包；与其它 deploy 单元并列）
- 新增 md 链接校验（python 脚本，中文路径用 sed 不安全）→ 首轮 18 处断链
（多一层目录要让 banner 里的相对路径补一个 ../）→ 修正后 0 断链
二、新增 docs/Gitea迁移指南.md（★ 有死线：境外 VPS 11 月到期）
★ 核心价值是「指出迁移面已大幅缩小」：仓库原有的 deploy/gitea/迁移前检查清单.md
（2026-10-04）是为「Gitea + act_runner + 又拍云同步 *整套* 搬迁」写的，**那个前提已经不存在**——
构建归 CNB，runner / upyun-sync / 中转机 / COS 都不需要了。迁移实际只剩「搬数据卷 + 改地址」。
★★ 全文最重要：本仓有 9 处写死了旧地址，按易漏程度排序（1-3 本机，4-5 线上）
1 本机 .git/config 的 gitea remote
2 scripts/setup-cnb-remotes.sh 的 GITEA_URL 默认值
3 deploy/editor-api/bootstrap.sh 的 GITEA_URL 默认值
4 ★ /srv/editor-api/.env 的 GITEA_URL ← 漏了会「持续报错但只警告不阻断」，没人发现
5 ★ /srv/blog 的 gitea remote ← 同上
6 docs/GITEA_SECRETS.md
7-9 架构总览.md / README.md / editor-api/README.md
（不用改：docker-compose.editor.yml、server.mjs、pushall 别名 —— 只引用 remote 名字）
另含：建议新实例改用域名而非 IP（以后搬机器只改 DNS；⚠️ Gitea 28 起只读 ROOT_URL 不读
[server] DOMAIN）；rsync 而非 dump（属主必须 uid/gid 1000）；切换顺序「先建新的→验证→再拆旧的」；
验证清单强调 `git push gitea --dry-run`；第九节给出「干脆不留这个辅仓」的选项与判断依据。
顺带修掉两个硬伤：
- deploy/gitea/docker-compose.yml 的镜像 tag `1.28.0-rootless` 根本不存在
（Gitea 28 起去掉 1. 前缀）→ 改 28.0.0-rootless（pin 死，不用 latest）
- deploy/gitea/.gitignore 漏了 backups/（跑一次备份就会把含 secrets 的 dump 写进历史）
三、证书管家核实（结论：已上线运行，2 个遗留）
线上实测：容器 Up (healthy)；/preflight 7/7 全过；3 组域名；下次自动续期 04:10。
遗留 ① writeapi.usj.cc 证书没纳管（真问题）：nginx 配置在 /www/conf.d/writeapi.usj.cc.conf，
不在 /www/sites/ 管理树里 → 1Panel 的 ssl/upload+sslID 物化碰不到它。
实测仍是 RSA / CN=usj.cc / 到期 2026-12-07，本项目续期不会更新 → 12 月会断。
遗留 ② dnsapi.usj.cc 没上 HTTPS。
（澄清假问题：200181.xyz 公网看到的 LE 证书是 CF 自家边缘证书，与本项目无关）
四、新增 docs/架构精简候选.md（回应「架构还是复杂了」）
结论：复杂度不在件数，在「跨 6 个环境，其中 4 个要自己维护」。国内机 9 个容器里属于本项目的
只有 3 个，能动的只有 2 个。5 个候选 + 建议执行顺序：
1 停 certimate 容器（工作流已全停用）——先 stop 观察，别急着删
2 cn-dns-helper 大概率已是遗留（「Worker 侧签发」时代产物；现在签发在国内机且自带 dnsprovider，
/preflight 显示 CF 凭据可读；Worker 侧 dnsremoted.ts 已无任何引用）
3 Gitea：迁 or 不留
4 两套写作前端收敛（本轮不动，先看使用频率）
5 writeapi.usj.cc 证书纳管（12 月死线）
并明确列出 6 项「必要复杂度，不建议动」。
五、架构总览补齐证书管家子系统（★ 之前完全缺席）
一个完整子系统在「事实源文档」里一个字都没有 —— 这本身就是文档债。补：
- §0 一句话（四→五个子系统）、§1.1 子系统表、§1.2 地址地图两行
- **新增 §5.7 证书管家**：职责划分 / 为什么非要这么分（Worker 免费版 CPU 10ms）/
三条不能破的红线（Worker 不得签发 · 证书路由只认 Bearer 会话 · 角色必须正着枚举放行）/
纳管域名表 / 与 certimate 的关系 / 已知遗留
- .cnb.yml 行数 284 → 337（数字漂了）；头部更新时间 → 2026-10-06；附录表改指 docs/
- §6 待办：#13（证书遗留）、#14（复杂度盘点）新增；#7 改写为「Gitea 11 月到期，★ 有死线」
六、记忆
.workbuddy/memory/MEMORY.md 新增「文档结构」「Gitea 迁移死线」两节；证书管家节补实测与遗留。
This commit is contained in:
zqlit committed
1 parent
d3da972c3b
commit
7abef4ac13
48 files changed
+782
-100
No files matched your search
@@ -0,0 +1,161 @@
|
||||
# =============================================================================
|
||||
# Gitea 可移植部署包 —— 把所有「博客相关服务」打包成 docker-compose
|
||||
#
|
||||
# 目标：任何一台机器上，只要：
|
||||
# 1. git clone 本仓库（含 gitea-backup/ 目录）
|
||||
# 2. 准备 data/ 数据卷（迁移时从旧机器打包过来）
|
||||
# 3. 复制 .env.example 为 .env 并填好
|
||||
# 4. docker compose up -d
|
||||
# 就能拉起整套环境。
|
||||
#
|
||||
# 包含的服务：
|
||||
# - gitea 代码托管（境外已停用 GitHub Actions，构建全走这里）
|
||||
# - runner Gitea Actions 的执行器（act_runner，跑博客构建/部署）
|
||||
# - upyun-sync 又拍云同步（原 1Panel 计划任务，容器化后不再依赖面板）
|
||||
#
|
||||
# write-server（写作后台）源码仍在仓库根 write-server/，这里用相对路径引用，
|
||||
# 不搬源码。如需一起管理，取消下面 write-server 段的注释。
|
||||
# =============================================================================
|
||||
|
||||
name: gitea-backup
|
||||
|
||||
services:
|
||||
# ---------------------------------------------------------------------------
|
||||
# Gitea —— 代码托管 + CI 调度中心
|
||||
# 数据：SQLite 单文件（/data/gitea/gitea.db）+ app.ini，全部在挂载卷里
|
||||
# 迁移：把旧机器 /opt/gitea/data 整个 rsync 到本机 ./data/gitea 即可
|
||||
# ---------------------------------------------------------------------------
|
||||
gitea:
|
||||
# ★ 2026-10-06 修正：Gitea 28 起去掉了历史的 `1.` 前缀 ——
|
||||
# 原写的 `1.28.0-rootless` **这个 tag 根本不存在**，`docker compose up` 会卡在第一屏。
|
||||
# 实测（`docker pull`）：`28.0.0-rootless` ✅ / `latest` ✅ / `1.28.0-rootless` ❌。
|
||||
# 这里 pin 死版本，避免被 `latest` 悄悄升级。
|
||||
image: gitea/gitea:28.0.0-rootless
|
||||
container_name: gitea
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- USER_UID=1000
|
||||
- USER_GID=1000
|
||||
- TZ=Asia/Shanghai
|
||||
# 数据库用内置 SQLite，无需额外容器
|
||||
- GITEA__database__DB_TYPE=sqlite3
|
||||
# 域名与基础 URL（必须与你备案域名一致）
|
||||
- GITEA__server__DOMAIN=${GITEA_DOMAIN}
|
||||
- GITEA__server__ROOT_URL=${GITEA_ROOT_URL}
|
||||
- GITEA__server__SSH_DOMAIN=${GITEA_SSH_DOMAIN}
|
||||
- GITEA__server__SSH_PORT=${GITEA_SSH_PORT}
|
||||
# 关闭注册，只有你一个人用
|
||||
- GITEA__service__DISABLE_REGISTRATION=true
|
||||
ports:
|
||||
- "${GITEA_HTTP_PORT}:3000"
|
||||
- "${GITEA_SSH_PORT}:2222"
|
||||
volumes:
|
||||
- ./data/gitea:/data
|
||||
- /etc/timezone:/etc/timezone:ro
|
||||
- /etc/localtime:/etc/localtime:ro
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:3000/api/v1/version"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 30s
|
||||
networks:
|
||||
- gitea-net
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# act_runner —— Gitea Actions 执行器（跑博客的构建 + 部署流水线）
|
||||
# 首次启动后需到 Gitea 后台「站点管理 → Actions → Runners」拿注册 token，
|
||||
# 然后 exec 进容器执行一次注册（详见 README「首次初始化」）
|
||||
# ---------------------------------------------------------------------------
|
||||
runner:
|
||||
image: gitea/act_runner:0.2.11
|
||||
container_name: gitea-runner
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- TZ=Asia/Shanghai
|
||||
- GITEA_INSTANCE_URL=${GITEA_ROOT_URL}
|
||||
# 注册 token：首次跑前手动填进 .env（见 README）
|
||||
- GITEA_RUNNER_REGISTRATION_TOKEN=${RUNNER_REGISTRATION_TOKEN}
|
||||
volumes:
|
||||
- ./data/runner:/data
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
depends_on:
|
||||
gitea:
|
||||
condition: service_healthy
|
||||
networks:
|
||||
- gitea-net
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# upyun-sync —— 又拍云同步（原 1Panel 计划任务「又拍云同步(国内中转)」）
|
||||
# 容器化后：不再依赖 1Panel，随 compose 一起迁移。
|
||||
# 工作目录 ./data/upyun-sync 里放 sync.sh / upx / cos_sign.py 等。
|
||||
# 注意：此服务用 host 网络（要访问宿主机已配好的证书/代理时更省事）。
|
||||
# ---------------------------------------------------------------------------
|
||||
upyun-sync:
|
||||
image: alpine:3.20
|
||||
container_name: upyun-sync
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- TZ=Asia/Shanghai
|
||||
# 又拍云凭据（从 .env 注入，容器内脚本读取）
|
||||
- UPYUN_SERVICE=${UPYUN_BUCKET}
|
||||
- UPYUN_OPERATOR=${UPYUN_OPERATOR}
|
||||
- UPYUN_PASSWORD=${UPYUN_PASSWORD}
|
||||
volumes:
|
||||
- ./data/upyun-sync:/opt/upyun-sync
|
||||
entrypoint: ["/bin/sh", "-c"]
|
||||
command:
|
||||
- |
|
||||
apk add --no-cache curl bash python3 py3-pip tar zstd openssl >/dev/null 2>&1 || true
|
||||
# 引导 upx（若 data 里没有）
|
||||
if [ ! -x /opt/upyun-sync/upx ]; then
|
||||
echo "引导 upx..."
|
||||
cd /tmp && curl -fsSL -o upx.tgz \
|
||||
"https://collection.b0.upaiyun.com/softwares/upx/upx_0.4.9_linux_amd64.tar.gz" \
|
||||
&& tar -xzf upx.tgz upx && mv upx /opt/upyun-sync/upx && chmod 755 /opt/upyun-sync/upx || \
|
||||
curl -fsSL -o upx.tgz \
|
||||
"https://github.com/upyun/upx/releases/download/v0.4.9/upx_0.4.9_linux_amd64.tar.gz" \
|
||||
&& tar -xzf upx.tgz upx && mv upx /opt/upyun-sync/upx && chmod 755 /opt/upyun-sync/upx
|
||||
fi
|
||||
# 每分钟跑一次 sync.sh（等价原 1Panel 的 * * * * * 计划任务）
|
||||
while true; do
|
||||
if [ -x /opt/upyun-sync/sync.sh ]; then
|
||||
bash /opt/upyun-sync/sync.sh || echo "[$(date -Is)] sync.sh 退出码 $?"
|
||||
else
|
||||
echo "[$(date -Is)] 缺少 sync.sh，跳过"
|
||||
fi
|
||||
sleep 60
|
||||
done
|
||||
networks:
|
||||
- gitea-net
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# write-server（可选，默认注释）—— 写作后台
|
||||
# 源码在仓库根 write-server/，这里用相对路径引用。
|
||||
# 若要把写作后台也纳入本部署包，取消下面整段注释，
|
||||
# 并确保 write-server/ 目录与 gitea-backup/ 同级。
|
||||
# ---------------------------------------------------------------------------
|
||||
# write-server:
|
||||
# build:
|
||||
# context: ../write-server
|
||||
# dockerfile: Dockerfile
|
||||
# container_name: write-server
|
||||
# restart: unless-stopped
|
||||
# ports:
|
||||
# - "8016:8016"
|
||||
# volumes:
|
||||
# - ../..:/blog # 博客根目录（与 write-server 原 compose 一致）
|
||||
# - ./data/write-server/recycle:/app/recycle
|
||||
# - ./data/write-server/logs:/app/logs
|
||||
# - ./data/write-server/backups:/app/backups
|
||||
# environment:
|
||||
# - NODE_ENV=production
|
||||
# - PORT=8016
|
||||
# - BLOG_ROOT=/blog
|
||||
# - TZ=Asia/Shanghai
|
||||
# networks:
|
||||
# - gitea-net
|
||||
|
||||
networks:
|
||||
gitea-net:
|
||||
driver: bridge
|
||||
Reference in new issue
Block a user