添加迁移

2026-04-07 01:49:16 +08:00
parent 5b0b7998ec
commit 3b01ca8ed3
3 changed files with 1454 additions and 13 deletions
--- a/gitea/README.md
+++ b/gitea/README.md
@@ -63,7 +63,7 @@ scp -r gitea/ root@服务器IP:/opt/gitea
 ```bash
 ssh root@服务器IP
 cd /opt/gitea
-chmod +x deploy.sh backup.sh
+chmod +x deploy.sh backup.sh upgrade.sh migrate.sh

 # 首次运行 → 自动安装系统依赖 + Docker + Nginx
 # 然后生成 .env 配置文件（密码已随机生成）并退出
@@ -226,24 +226,215 @@ docker compose down           # 停止并移除容器
 docker compose up -d          # 启动
 ```

-### 升级 Gitea
+### 升级组件（一键脚本）
+
+```bash
+cd /opt/gitea
+chmod +x upgrade.sh
+
+# 交互式选择要升级的组件
+bash upgrade.sh
+
+# 或直接指定组件
+bash upgrade.sh gitea      # 仅升级 Gitea
+bash upgrade.sh mysql      # 仅升级 MySQL
+bash upgrade.sh nginx      # 仅升级 Nginx
+bash upgrade.sh certbot    # 仅升级 Certbot
+bash upgrade.sh docker     # 仅升级 Docker
+bash upgrade.sh all        # 升级全部
+```
+
+> 脚本会自动显示当前版本、执行备份、拉取新镜像、重启服务并验证。
+
+---
+
+### 手动升级详细步骤
+
+#### 升级 Gitea
+
+Gitea 以 Docker 容器运行，升级 = 拉取新镜像 + 重启容器。数据库结构变更会在启动时自动迁移。

 ```bash
 cd /opt/gitea

-# 1. 先备份
+# 1. 备份（必须！）
 bash backup.sh

-# 2. 拉取新镜像
-docker compose pull
+# 2. 查看当前版本
+curl -s http://127.0.0.1:3000/api/v1/version

-# 3. 重启
+# 3. 修改目标版本（编辑 .env 中的 GITEA_IMAGE）
+#    ● 查看最新版本号: https://github.com/go-gitea/gitea/releases
+#    ● 或访问: https://hub.docker.com/r/gitea/gitea/tags
+vi .env
+# 修改: GITEA_IMAGE=gitea/gitea:1.25.5  ← 替换为目标版本号
+
+# 4. 拉取新镜像
+docker compose pull server
+
+# 5. 重启（自动执行数据库迁移）
+docker compose up -d server
+
+# 6. 检查日志确认启动成功
+docker compose logs -f server
+# 看到 "Starting new Web server: tcp:0.0.0.0:3000" 表示成功
+# Ctrl+C 退出日志
+
+# 7. 验证新版本
+curl -s http://127.0.0.1:3000/api/v1/version
+```
+
+**注意事项：**
+- 务必查阅 [Gitea 发版说明](https://github.com/go-gitea/gitea/releases) 了解 Breaking Changes
+- 不支持版本降级，升级前务必备份
+- 跨多个大版本建议逐版本升级（如 1.21 → 1.22 → 1.23）
+
+#### 升级 MySQL
+
+**小版本升级（8.0.x → 8.0.y）**— 安全，直接拉取新镜像：
+
+```bash
+cd /opt/gitea
+
+# 1. 备份
+bash backup.sh
+
+# 2. 拉取最新 8.0 补丁
+docker compose pull db
+
+# 3. 重启 MySQL
+docker compose up -d db
+
+# 4. 等待就绪，确认版本
+docker compose exec db mysql --version
+
+# 5. 重启 Gitea 刷新连接
+docker compose restart server
+```
+
+**大版本升级（8.0 → 8.4 / 9.0）**— 需要导出/导入数据：
+
+```bash
+cd /opt/gitea
+
+# 1. 完整备份
+bash backup.sh
+
+# 2. 导出数据库
+docker compose exec -T db mysqldump \
+    -u root -p"${DB_ROOT_PASSWORD}" \
+    --single-transaction --routines --triggers \
+    --databases gitea > /tmp/gitea_mysql_export.sql
+
+# 3. 停止所有服务
+docker compose down
+
+# 4. 备份 MySQL 数据目录
+cp -a /var/lib/mysql/gitea /var/lib/mysql/gitea.bak
+
+# 5. 清空数据目录（新版本将重新初始化）
+rm -rf /var/lib/mysql/gitea/*
+
+# 6. 修改 docker-compose.yml 中的镜像版本
+#    将 image: mysql:8.0 改为 image: mysql:8.4
+vi docker-compose.yml
+#    MySQL 8.4+ 如不需要旧认证插件，可删除 --mysql-native-password=ON
+
+# 7. 启动新版本 MySQL（等待初始化完成）
+docker compose up -d db
+docker compose logs -f db
+# 看到 "ready for connections" 后 Ctrl+C
+
+# 8. 导入数据
+docker compose exec -T db mysql \
+    -u root -p"${DB_ROOT_PASSWORD}" < /tmp/gitea_mysql_export.sql
+
+# 9. 启动 Gitea
 docker compose up -d

-# 4. 检查日志
-docker compose logs -f server
+# 10. 确认版本
+docker compose exec db mysql --version
 ```

+**注意事项：**
+- MySQL 仅支持相邻大版本升级（8.0 → 8.4 → 9.0），不可跨版本
+- 确认 Gitea 对目标 MySQL 版本的兼容性
+- 回滚方法：`docker compose down` → 恢复数据目录和 docker-compose.yml → 重启
+
+#### 升级 Nginx
+
+Nginx 通过系统包管理器安装，使用系统更新升级：
+
+```bash
+# 1. 查看当前版本
+nginx -v
+
+# 2. 更新 Nginx
+apt-get update && apt-get install -y --only-upgrade nginx
+# CentOS/RHEL: yum update -y nginx
+
+# 3. 验证配置文件无语法错误
+nginx -t
+
+# 4. 平滑重载（不中断服务）
+systemctl reload nginx
+
+# 5. 确认新版本
+nginx -v
+```
+
+> Nginx 的 `reload` 是平滑重载，不会中断现有连接。只有配置文件变化才需要重载。
+
+#### 升级 Certbot + 续期 SSL 证书
+
+```bash
+# 1. 查看当前版本
+certbot --version
+
+# 2. 更新 Certbot
+apt-get update && apt-get install -y --only-upgrade certbot python3-certbot-nginx
+# CentOS/RHEL: yum update -y certbot python3-certbot-nginx
+
+# 3. 确认新版本
+certbot --version
+
+# 4. 查看证书状态
+certbot certificates
+
+# 5. 测试续期流程（不实际续期）
+certbot renew --dry-run
+
+# 6. 查看证书到期时间
+openssl x509 -enddate -noout -in /etc/letsencrypt/live/你的域名/fullchain.pem
+
+# 如证书即将到期或需要强制续期:
+certbot renew --force-renewal --post-hook 'systemctl reload nginx'
+```
+
+> 证书自动续期已由 deploy.sh 配置 cron（每天 03:00 检查），通常无需手动操作。
+
+#### 升级 Docker
+
+```bash
+# 1. 查看当前版本
+docker --version
+docker compose version
+
+# 2. 更新 Docker Engine + Compose
+apt-get update && apt-get install -y --only-upgrade \
+    docker-ce docker-ce-cli containerd.io docker-compose-plugin
+# CentOS/RHEL: yum update -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+
+# 3. 确认版本
+docker --version
+docker compose version
+
+# 4. 确认容器正常运行
+docker compose ps
+```
+
+> Docker 更新后服务会自动重启，容器在 `restart: always` 策略下会自动恢复。
+
 ### 定时自动备份

 ```bash
@@ -284,6 +475,116 @@ gunzip < /var/backups/gitea/db_20260406_030000.sql.gz | \
 docker compose up -d
 ```

+### 迁移到新服务器（一键脚本）
+
+将已部署的 Gitea 完整迁移到另一台服务器，包含数据库、仓库、LFS、配置等全部数据。
+
+> 参考 [Gitea 官方备份与恢复文档](https://docs.gitea.com/zh-cn/administration/backup-and-restore)
+
+```bash
+# ===== 旧服务器 =====
+cd /opt/gitea
+chmod +x migrate.sh
+
+# 导出迁移包（会自动停服 → mysqldump → 打包数据 → 打包配置）
+bash migrate.sh export
+# 生成: /var/backups/gitea/gitea_migrate_日期.tar.gz
+
+# 传输到新服务器
+scp /var/backups/gitea/gitea_migrate_*.tar.gz root@新服务器IP:/opt/gitea/
+```
+
+```bash
+# ===== 新服务器 =====
+# 前提：已安装 Docker（可先运行 deploy.sh 的 Docker 安装步骤，或手动安装）
+mkdir -p /opt/gitea
+cd /opt/gitea
+
+# 导入迁移包（会自动恢复配置 → 恢复数据 → 导入数据库 → 启动 → regenerate hooks → doctor check）
+bash migrate.sh import gitea_migrate_日期.tar.gz
+
+# 验证迁移完整性
+bash migrate.sh verify
+```
+
+**脚本自动完成的操作：**
+
+| 阶段 | 操作 |
+|------|------|
+| 导出 | 停止 Gitea → mysqldump 导出数据库 → 打包 Gitea 数据目录 → 打包部署配置 → 生成迁移包 |
+| 导入 | 解压 → 恢复配置 → 恢复数据目录 → 启动 MySQL → 导入数据库 → 启动 Gitea → regenerate hooks → doctor check |
+| 验证 | 检查容器状态 → API 可达性 → 数据库连接 → 仓库/用户数量 → 数据目录完整性 → Nginx 状态 |
+
+**迁移后注意事项：**
+- 如域名或 IP 变更，导入前需修改 `.env` 中的 `GITEA_DOMAIN`
+- 域名变更后需更新 DNS 解析并重新申请 SSL 证书：`certbot certonly --webroot -w /var/www/certbot -d 新域名`
+- 如新服务器未安装 Nginx/Certbot，可运行 `bash deploy.sh` 补装（脚本会跳过已有组件）
+- 确保新服务器 Gitea 版本 ≥ 旧服务器版本（不支持降级）
+- 官方建议使用 `mysqldump` 而非 `gitea dump` 的 XORM 导出（脚本已采用此方案）
+
+<details>
+<summary>手动迁移步骤（不使用脚本）</summary>
+
+```bash
+# ===== 旧服务器 =====
+cd /opt/gitea
+
+# 1. 停止 Gitea
+docker compose stop server
+
+# 2. 导出数据库
+docker compose exec -T db mysqldump \
+    -u root -p"${DB_ROOT_PASSWORD}" \
+    --single-transaction --routines --triggers \
+    --databases gitea > gitea-db.sql
+
+# 3. 停止全部
+docker compose down
+
+# 4. 打包数据
+tar czf gitea-data.tar.gz -C /var/lib/gitea .
+
+# 5. 打包配置
+tar czf gitea-config.tar.gz .env docker-compose.yml nginx/ *.sh
+
+# 6. 传输
+scp gitea-db.sql gitea-data.tar.gz gitea-config.tar.gz root@新服务器:/opt/gitea/
+```
+
+```bash
+# ===== 新服务器 =====
+cd /opt/gitea
+
+# 7. 恢复配置
+tar xzf gitea-config.tar.gz
+vi .env  # 如需修改域名
+
+# 8. 恢复数据
+mkdir -p /var/lib/gitea
+tar xzf gitea-data.tar.gz -C /var/lib/gitea
+chown -R 1000:1000 /var/lib/gitea
+
+# 9. 启动 MySQL 并导入
+docker compose up -d db
+# 等待就绪...
+docker compose exec -T db mysql \
+    -u root -p"${DB_ROOT_PASSWORD}" \
+    --default-character-set=utf8mb4 < gitea-db.sql
+
+# 10. 启动 Gitea
+docker compose up -d
+
+# 11. 重新生成 Git Hooks（必须！否则 push 会失败）
+docker compose exec -u git server \
+    /usr/local/bin/gitea -c /data/gitea/conf/app.ini admin regenerate hooks
+
+# 12. 运行 doctor 修复潜在问题
+docker compose exec -u git server \
+    /usr/local/bin/gitea -c /data/gitea/conf/app.ini doctor check --all --fix
+```
+
+</details>
+
 ---

 ## 五、安全加固清单
@@ -322,11 +623,14 @@ docker compose exec server gitea admin user change-password -u 管理员用户
 - 确认 Git 提交邮箱与 GPG 密钥邮箱一致

 **Q: 如何迁移到新服务器？**
-1. 旧服务器执行 `bash backup.sh`
-2. 复制部署目录 `/opt/gitea/`、数据 `/var/lib/gitea/`、备份 `/var/backups/gitea/` 到新服务器
-3. 新服务器执行 `bash deploy.sh`
-4. 修改域名 DNS 指向新服务器 IP
-5. 重新申请 SSL 证书：`certbot certonly --webroot -w /var/www/certbot -d 域名`
+使用迁移脚本一键完成，详见上方「迁移到新服务器」章节：
+```bash
+# 旧服务器导出
+bash migrate.sh export
+# 新服务器导入
+bash migrate.sh import gitea_migrate_xxx.tar.gz
+bash migrate.sh verify
+```

 ---

@@ -338,6 +642,8 @@ docker compose exec server gitea admin user change-password -u 管理员用户
 ├── .env.example                    # 环境变量模板
 ├── .env                            # 运行时配置（自动生成）
 ├── deploy.sh                       # 全新服务器一键部署脚本
+├── upgrade.sh                      # 组件升级脚本（Gitea/MySQL/Nginx/Certbot/Docker）
+├── migrate.sh                      # 服务器迁移脚本（导出/导入/验证）
 ├── backup.sh                       # MySQL + 数据备份脚本
 ├── .gitignore
 ├── README.md
@@ -366,3 +672,8 @@ docker compose exec server gitea admin user change-password -u 管理员用户
 /etc/nginx/sites-available/gitea    # Nginx HTTPS 配置（由 deploy.sh 生成）
 /etc/letsencrypt/live/域名/         # SSL 证书（由 Certbot 管理）
 ```
+
+## 官方文档
+
+- Gitea 官方文档（英文）：<https://docs.gitea.com/>
+- Gitea 官方文档（中文）：<https://docs.gitea.com/zh-cn/>