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 迁移死线」两节；证书管家节补实测与遗留。
2026-10-06 22:27:36 +08:00
1 parent d3da972c3b
commit 7abef4ac13
@@ -0,0 +1,26 @@
+# =============================================================================
+#  Gitea 部署包环境变量模板
+#  用法：cp .env.example .env  然后按需修改
+#  ⚠️ 本文件是模板（占位符），真正的 .env 含密钥，已被 .gitignore 排除，勿提交
+# =============================================================================
+
+# ---- Gitea 域名与端口 ----
+# 备案域名（与你在 DNS 解析到本机 IP 的一致）
+GITEA_DOMAIN=gitea.usj.cc
+# 访问地址（http/https 按你的反代决定）
+GITEA_ROOT_URL=https://gitea.usj.cc/
+# SSH 克隆地址
+GITEA_SSH_DOMAIN=gitea.usj.cc
+# 宿主机对外暴露的端口
+GITEA_HTTP_PORT=3001
+GITEA_SSH_PORT=2222
+
+# ---- act_runner 注册 token ----
+# 首次启动后，到 Gitea 后台「站点管理 → Actions → Runners」生成，
+# 填到这里，然后重建 runner 容器完成注册。
+RUNNER_REGISTRATION_TOKEN=请到Gitea后台生成并填入
+
+# ---- 又拍云凭据（upyun-sync 用）----
+UPYUN_BUCKET=imzql
+UPYUN_OPERATOR=1770186415
+UPYUN_PASSWORD=请填入又拍云操作员密码
@@ -0,0 +1,16 @@
+# Gitea 部署包 —— 忽略规则
+
+# 环境变量（含密钥）：忽略 .env，但保留模板 .env.example
+.env
+!.env.example
+
+# 数据卷（迁移时单独打包，不进 git）
+data/
+
+# ★ 2026-10-06 补：backup.sh 的产物落在 backups/，含 secrets 与完整 data 卷
+#   （gitea.db / app.ini / runner 凭据）。原先漏了这一条，跑一次备份再 `git add .`
+#   就会把凭据写进历史。
+backups/
+
+# write-server 运行时产物（若纳入）
+*.log
@@ -0,0 +1,148 @@
+# Gitea 部署包
+
+> ⚠️ **2026-10-06 更新：本包的使用方式已经变了。**
+>
+> 它是为「**Gitea + act_runner + 又拍云同步** 整套可移植部署」设计的，
+> 但 **构建已由 CNB 托管**，所以 **runner 与 upyun-sync 都不需要了**。
+> Gitea 现在的角色只剩**代码辅仓**（只推不拉、不参与构建）。
+>
+> **要迁移 Gitea，请看 [`docs/Gitea迁移指南.md`](../../docs/Gitea迁移指南.md)** ——
+> 那里有本仓 9 处写死旧地址的完整清单，以及「迁移实际只剩搬数据 + 改地址」的结论。
+>
+> 本包现状：**只 `docker compose up -d gitea` 就够了**，下面 compose 里的
+> `runner` / `upyun-sync` 两段可以忽略。
+>
+> 已修正的两个硬伤（2026-10-06）：
+> - `docker-compose.yml` 镜像 tag `1.28.0-rootless` **不存在** → 改为 `28.0.0-rootless`
+> - `.gitignore` 漏了 `backups/` → 已补（`backup.sh` 产物含 secrets 与完整 data 卷）
+
+---
+
+把博客相关的**代码托管（Gitea）+ CI 执行器（act_runner）+ 又拍云同步**打包成一套 docker-compose，
+目标：**任何一台机器上，复制文件 + 一条命令就能拉起整套环境**，彻底告别「迁移要半天手工操作」。
+
+> 背景：境外那台 2C2G 服务器（23.254.236.47）十一月到期，且后续可能没时间慢慢迁移。
+> 这个部署包就是把「迁移成本」从「半天手工」压到「copy + up」。
+
+---
+
+## 包含哪些服务
+
+| 服务 | 镜像 | 说明 |
+|---|---|---|
+| **gitea** | `gitea/gitea:1.28.0-rootless` | 代码托管 + CI 调度。SQLite 单文件，数据全在 `data/gitea/` |
+| **runner** | `gitea/act_runner:0.2.11` | Gitea Actions 执行器，跑博客构建/部署 |
+| **upyun-sync** | `alpine:3.20` | 又拍云同步（原 1Panel 计划任务「又拍云同步(国内中转)」，容器化后不再依赖面板） |
+| write-server | （可选，默认注释） | 写作后台，源码在仓库根 `write-server/` |
+
+**不在本部署包里的**（它们有自己的形态，不适合塞进 compose）：
+
+| 服务 | 形态 | 为什么不在 |
+|---|---|---|
+| 博客站点 | 静态文件 + CDN | 构建产物由 runner 推给 EdgeOne / 又拍云，不是常驻服务 |
+| 评论后端 artalk-cf | Cloudflare Workers | 无服务器，`wrangler deploy` 部署，见 `blog-admin/` |
+| write-server | 独立 Docker | 可选纳入，见 compose 注释 |
+
+---
+
+## 目录结构
+
+```
+gitea-backup/
+├── docker-compose.yml     # 核心：三个服务 + 网络
+├── .env.example           # 变量模板（复制成 .env）
+├── .gitignore             # 忽略 .env 和 data/
+├── README.md              # 本文档
+├── scripts/
+│   ├── backup.sh          # 一键备份：gitea dump + 打包 data 卷
+│   └── restore.sh         # 一键恢复
+└── data/                  # 数据卷（git 忽略，迁移时打包）
+    ├── gitea/             #   Gitea 数据（gitea.db + app.ini + 仓库）
+    ├── runner/            #   act_runner 配置
+    └── upyun-sync/        #   同步脚本 + upx + cos_sign.py
+```
+
+---
+
+## 首次部署（新机器）
+
+### 1. 准备代码和数据
+
+```bash
+# 克隆仓库（含 gitea-backup）
+git clone <你的仓库> && cd <仓库>/gitea-backup
+
+# 迁移数据：从旧机器把数据卷 rsync 过来
+# （旧机器 23.254.236.47 上）
+rsync -av --progress /opt/gitea/data/ 新机器:/path/to/gitea-backup/data/gitea/
+# 又拍云同步目录同理：
+rsync -av --progress /opt/upyun-sync/ 新机器:/path/to/gitea-backup/data/upyun-sync/
+```
+
+### 2. 配置
+
+```bash
+cp .env.example .env
+# 编辑 .env：填域名、端口、又拍云密码
+```
+
+### 3. 启动
+
+```bash
+docker compose up -d
+docker compose ps          # 确认三个服务都 healthy/running
+```
+
+### 4. 注册 runner（首次必做）
+
+```bash
+# 到 Gitea 后台：站点管理 → Actions → Runners → 创建 runner → 复制注册 token
+# 把 token 填进 .env 的 RUNNER_REGISTRATION_TOKEN，然后：
+docker compose up -d --force-recreate runner
+# 回到后台确认 runner 已在线（绿色）
+```
+
+---
+
+## 备份
+
+```bash
+bash scripts/backup.sh
+# 产物：backups/gitea-dump-<时间戳>.zip（含 gitea dump + app.ini）
+#        backups/data-<时间戳>.tar.gz（含完整 data 卷）
+```
+
+`gitea dump` 会导出仓库 + 用户 + 配置 + secrets（加密），是最完整的一站式备份。
+
+## 恢复（灾难场景）
+
+```bash
+bash scripts/restore.sh backups/gitea-dump-<时间戳>.zip
+# 或手动：把 data 卷解回 data/，然后 docker compose up -d
+```
+
+---
+
+## 从旧机器迁移的完整清单（十一月到期前照着做）
+
+1. 新机器装 docker + docker compose
+2. `rsync` 旧机器 `/opt/gitea/data` → 新机器 `data/gitea/`
+3. `rsync` 旧机器 `/opt/upyun-sync` → 新机器 `data/upyun-sync/`
+4. `cp .env.example .env` 并填好
+5. `docker compose up -d`
+6. 后台重新注册 runner（token 会变）
+7. DNS 把 `gitea.usj.cc` 指向新机器 IP
+8. 验证：`git push` 一次，看 Actions 是否正常构建部署
+
+> ⚠️ 第 6 步 runner token 每次重新注册都会变，旧 token 作废，必须在后台重新拿。
+
+---
+
+## 关于「又拍云同步」的容器化说明
+
+原 1Panel 计划任务是 `bash /opt/upyun-sync/sync.sh`，每分钟跑一次，负责：
+从 COS 拉构建产物 → 解压 → `upx sync` 到又拍云 → purge → 刷多吉云。
+
+容器化后逻辑不变，只是**用 `while sleep 60` 循环替代了 cron**（不再依赖 1Panel）。
+注意：`sync.sh` 里如果还引用 COS（`cos_sign.py` 签 COS 地址），说明 COS 还没砍；
+如果已改为「拉 Gitea artifact」，则 `cos_sign.py` 可以删掉。
@@ -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
@@ -0,0 +1,36 @@
+#!/bin/bash
+# =============================================================================
+#  Gitea 部署包 —— 一键备份
+#  备份内容：
+#    1. gitea dump（仓库 + 用户 + 配置 + secrets 加密导出）
+#    2. 完整 data 卷（gitea.db / app.ini / runner 配置 / upyun-sync 目录）
+#  产物输出到 backups/ 目录
+# =============================================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(dirname "$SCRIPT_DIR")"
+BACKUP_DIR="$ROOT_DIR/backups"
+STAMP="$(date +%Y%m%d-%H%M%S)"
+
+mkdir -p "$BACKUP_DIR"
+
+echo "==> 1/2 导出 Gitea dump（含 secrets）..."
+docker compose -f "$ROOT_DIR/docker-compose.yml" exec -T gitea \
+  gitea dump --config /data/gitea/conf/app.ini \
+  --file /data/gitea-dump.zip \
+  -R -S 2>/dev/null || {
+    echo "⚠️  gitea dump 失败（容器可能未运行），跳过，仅备份 data 卷"
+  }
+# 把 dump 产物从容器拷出来
+docker compose -f "$ROOT_DIR/docker-compose.yml" cp \
+  gitea:/data/gitea-dump.zip "$BACKUP_DIR/gitea-dump-$STAMP.zip" 2>/dev/null || true
+
+echo "==> 2/2 打包 data 卷..."
+tar -czf "$BACKUP_DIR/data-$STAMP.tar.gz" -C "$ROOT_DIR" data/
+
+echo ""
+echo "✅ 备份完成："
+ls -lh "$BACKUP_DIR" | tail -5
+echo ""
+echo "⚠️  产物含密钥，请勿上传网盘/公开仓库。"
@@ -0,0 +1,55 @@
+#!/bin/bash
+# =============================================================================
+#  Gitea 部署包 —— 一键恢复
+#  用法：bash restore.sh <backups/data-<时间戳>.tar.gz>
+#        或  bash restore.sh <backups/gitea-dump-<时间戳>.zip>（仅恢复 dump）
+# =============================================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(dirname "$SCRIPT_DIR")"
+
+if [ $# -lt 1 ]; then
+  echo "用法：bash restore.sh <备份文件>"
+  echo "  - data-*.tar.gz       恢复完整 data 卷"
+  echo "  - gitea-dump-*.zip    仅恢复 gitea dump"
+  exit 1
+fi
+
+SRC="$1"
+
+if [ ! -f "$SRC" ]; then
+  echo "❌ 找不到备份文件：$SRC"
+  exit 1
+fi
+
+echo "==> 停止服务..."
+docker compose -f "$ROOT_DIR/docker-compose.yml" down 2>/dev/null || true
+
+case "$SRC" in
+  *data-*.tar.gz)
+    echo "==> 恢复 data 卷..."
+    tar -xzf "$SRC" -C "$ROOT_DIR"
+    echo "✅ data 卷已恢复到 $ROOT_DIR/data/"
+    ;;
+  *gitea-dump-*.zip)
+    echo "==> 恢复 gitea dump..."
+    docker compose -f "$ROOT_DIR/docker-compose.yml" up -d gitea
+    sleep 5
+    docker compose -f "$ROOT_DIR/docker-compose.yml" cp \
+      "$SRC" gitea:/data/restore.zip
+    docker compose -f "$ROOT_DIR/docker-compose.yml" exec -T gitea \
+      gitea restore --config /data/gitea/conf/app.ini --file /data/restore.zip
+    echo "✅ gitea dump 已恢复"
+    ;;
+  *)
+    echo "❌ 无法识别的备份文件类型：$SRC"
+    exit 1
+    ;;
+esac
+
+echo "==> 启动服务..."
+docker compose -f "$ROOT_DIR/docker-compose.yml" up -d
+
+echo "✅ 恢复完成，检查状态："
+docker compose -f "$ROOT_DIR/docker-compose.yml" ps
@@ -0,0 +1,173 @@
+# 迁移前检查清单（2026-10-04 实测）
+
+> ⚠️ **本文写于 2026-10-04，部分内容已过时。**
+> 当时的迁移目标是「把 **Gitea + act_runner + 又拍云同步** 整套搬走」——
+> **现在构建已由 CNB 托管，runner / upyun-sync / 中转机 都不需要了**，迁移面大幅缩小。
+>
+> 👉 **要迁移请看 [`docs/Gitea迁移指南.md`](../../docs/Gitea迁移指南.md)**（现行版本，
+> 含「本仓 9 处写死旧地址」的完整清单）。
+> 本文保留的价值：容器网络写法、资源评估、rsync 属主、`ROOT_URL` 那几条仍然成立。
+
+> 目标：把境外机 `23.254.236.47` 上的 Gitea + runner 搬到**国内机**（当前中转机
+> `119.29.215.187`，Ubuntu 24.04）。
+> 下面是**照着做完再动手**的清单。带 ★ 的是会**直接卡住迁移**的硬伤。
+
+---
+
+## 一、★ 硬伤：compose 里 pin 的 Gitea 镜像 tag 不存在
+
+`docker-compose.yml:29`
+
+```yaml
+image: gitea/gitea:1.28.0-rootless      # ❌ 这个 tag 不存在
+```
+
+**原因**：**Gitea 28.0.0 起去掉了历史 `1.` 前缀** —— 原本的 `1.28.0` 现在就叫 `28.0.0`。
+境外那台 `/api/v1/version` 实测返回 `{"version":"28.0.0"}`。
+
+**已在目标机实测（`docker pull`，决定性）**：
+
+| 镜像 tag | 结果 |
+|---|---|
+| `gitea/gitea:1.28.0-rootless` | ❌ `not found` |
+| `gitea/gitea:28.0.0-rootless` | ✅ 可拉取 |
+| `gitea/gitea:latest` | ✅ 可拉取 |
+| `gitea/act_runner:0.2.11` | ✅ 可拉取 |
+| `gitea/act_runner:4.0.0` | ❌ `not found` |
+
+**改**：`gitea/gitea:28.0.0-rootless`（建议 pin 死版本，别用 `latest`，免得下次再被动升级）。
+`28.0.0-rootless` 与 `latest` **已经拉到目标机上了**，迁移时省一次等待。
+
+---
+
+## 二、★ `.gitignore` 没忽略 `backups/`
+
+`scripts/backup.sh` 的产物落在 `backups/`：
+
+```
+backups/gitea-dump-<时间戳>.zip   # gitea dump，含 secrets（加密但仍是敏感物）
+backups/data-<时间戳>.tar.gz      # 完整 data 卷：gitea.db / app.ini / runner 凭据 / upyun 目录
+```
+
+而 `.gitignore` 里**只有** `.env` / `data/` / `*.log` —— **没有 `backups/`**。
+跑一次备份，这两个文件就出现在仓库里了，`git add .` 一下全进历史。
+
+**改**：`.gitignore` 加一行 `backups/`。
+
+---
+
+## 三、凭据散落情况（迁移时容易漏）
+
+| 位置 | 内容 | 风险 |
+|---|---|---|
+| `gitea-backup/.env.example` | `UPYUN_BUCKET=imzql`、`UPYUN_OPERATOR=1770186415` | **真实值**，不是占位符 |
+| `write-server/nginx/ssl/privkey.pem` | SSL 私钥 | **已被 git 跟踪**（仓库历史里有） |
+| 中转机 `/opt/upyun-sync/sync.sh` | 又拍云密码 + 多吉云 AK/SK **明文硬编码** | 该文件会被整体搬进 `data/upyun-sync/` |
+| 本地 `.git/config` 的 `gitea` remote | `http://用户:密码@...` | 明文写在 remote URL 里 |
+
+容器化后 `upyun-sync` 是用 `.env` 注入凭据的，但 `sync.sh` 里**又硬编码了一份** ——
+两套并存，容易改一处漏一处。建议统一成只读环境变量。
+
+---
+
+## 四、容器网络：脚本要走服务名，别绕公网
+
+`upyun-sync` 容器与 `gitea` 同在 `gitea-net` 这个 bridge 网络里。
+如果脚本里继续用 `https://gitea.usj.cc`，会**出到公网 DNS 再绕回来**（还可能撞上 CDN）。
+
+**改**：`sync.sh` 里 `GITEA` 默认值改成 `http://gitea:3000`（compose 服务名 + 容器内端口）。
+脚本已经写成 `GITEA="${GITEA:-...}"`，用环境变量覆盖即可，不必改脚本。
+
+---
+
+## 五、反向代理要补一条
+
+目标机上 **OpenResty 已占用 80/443**（1Panel 托管的站点）。
+`gitea` 容器映射的是宿主 `3001`（HTTP）/ `2222`（SSH），**这两个端口在目标机是空闲的**
+（已实测）。
+
+要让 `https://gitea.usj.cc` 生效，需在 1Panel 的 OpenResty 里加一个反代站点
+→ `127.0.0.1:3001`，并配好证书。DNS 也要把 `gitea.usj.cc` 指到目标机。
+
+> ⚠️ Gitea 28 起**不再读取 `[server] DOMAIN`**，实例域名（含默认 SSH 域名）全部来自 `ROOT_URL`。
+> compose 里两个都填了，所以没问题；但改域名时**只需改 `ROOT_URL`**。
+
+---
+
+## 六、资源评估：内存是短板
+
+目标机现状（实测）：
+
+| 项 | 值 |
+|---|---|
+| CPU | **2 核** |
+| 内存 | **1.9 G**（已用 665 M，free 126 M，buff/cache 1369 M） |
+| **Swap** | 1987 M，**已用 832 M** ← 已经在吃 swap |
+| 磁盘 | 50 G，已用 17 G，**剩 31 G** |
+| 已在跑 | 1Panel(3721)、mysql 8.4、certimate、OpenResty(80/443)、frps、alist、vaultwarden |
+
+要再加进：**Gitea + act_runner + 一次 hugo 构建**（构建要跑 npm ci、hugo --minify、
+打包 ~380 MB 产物）。这台机器现在就已经在换页了，**2 G 内存很紧**。
+
+磁盘侧估算（够用但不宽裕）：Gitea 数据（仓库全历史，含大量图片）+ artifact
+（~380 MB/次 × 保留 7 天）+ `data/upyun-sync/` 里的产物副本（~750 M）≈ **6–10 G**。
+
+**建议**：迁移前把内存加到 **4 G**；或将 `mysql` 等非必需容器停掉腾资源。
+
+---
+
+## 七、★ 迁移后会变的架构（决定要不要保留中转机）
+
+`deploy.yml` 里 `Upload to UpYun` 那一步现在写死 `if: false`，注释原话：
+
+> 国内线路由腾讯云广州中转机兜底……**将来若把 runner 挪到国内，把下面的 `if: false` 删掉即可恢复。**
+
+也就是说 **runner 一旦在国内，又拍云直传就可行**（当初失败是因为境外出口被 GSLB 调度到坏节点）。
+那时整条链路可以简化成：
+
+```
+runner(国内) → build → 又拍云直传 → purge → 多吉云刷新
+```
+
+**「中转机 + sync.sh + Gitea artifact 给中转机」这一层就可以整个删掉。**
+
+但有两个代价要权衡：
+
+1. **EdgeOne Pages 部署会变成跨境**（境内 runner → 境外 EdgeOne）。目前 runner 在境外，
+   这一步是零跨境的。需要实测耗时是否可接受。
+2. 又拍云直传要补 **`upx purge`**（现在这一步在 sync.sh 里，deploy.yml 的直传步骤没有）。
+   多吉云刷新 finalize 里已有（`upyun_status == success` 时才刷）。
+
+> 建议：**先按「保留 artifact 传递」把迁移做完**（artifact 在 build → deploy-edgeone
+> 之间是必需的，无论如何都要留），跑通之后再单独决定要不要砍中转机。
+> 别把「迁移」和「架构简化」两件事混在一次变更里。
+
+---
+
+## 八、迁移顺序（照做）
+
+1. **先修本文档第一节的镜像 tag**，`docker compose up` 才不会卡在第一屏
+2. 补 `.gitignore` 的 `backups/`
+3. 目标机：`mkdir -p data/gitea data/runner data/upyun-sync`
+4. 旧机器 rsync 数据（沿用 README 的路径）：
+   - `/opt/gitea/data/` → `data/gitea/`
+   - `/opt/upyun-sync/` → `data/upyun-sync/`
+   - ⚠️ 用 `rsync -a` 保留属主；Gitea rootless 镜像按 **uid/gid 1000** 跑，
+     属主不对会起不来
+5. `cp .env.example .env` 并填好（`ROOT_URL` 必填）
+6. **停掉 1Panel 的计划任务「又拍云同步(国内中转)」`id=15`** —— 否则
+   容器版 `upyun-sync` 与它**同时**同步，双写又拍云
+7. `docker compose up -d` → `docker compose ps` 三个服务 healthy
+8. Gitea 后台重新拿 runner 注册 token → 填 `.env` → `up -d --force-recreate runner`
+9. OpenResty 加反代站点 + DNS 切 `gitea.usj.cc`
+10. 验证：`git push` 一次，看 Actions 是否正常构建部署
+
+---
+
+## 九、尚未核实的两点
+
+- `scripts/backup.sh` 里 `gitea dump --config ... -R -S`：这两个参数的语义需核对
+  （担心是「跳过仓库」之类，导致 dump 不完整）。**建议实跑一次备份，检查 zip 里有没有
+  `repositories/`**。
+- 旧机器上的 `docker-compose.yml` 里 Gitea 用的到底是哪个 tag（`latest` 还是 pin 的版本）——
+  直接把 `:latest` 的数据目录搬到一个 pin 死的旧版本上会有兼容风险，**版本必须 ≥ 旧机**。