# 迁移前检查清单（2026-10-04 实测）

> 目标：把境外机 `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 死的旧版本上会有兼容风险，**版本必须 ≥ 旧机**。