升级gitea
This commit is contained in:
+83
-30
@@ -326,42 +326,93 @@ docker compose up -d # 启动
|
||||
|
||||
#### 升级 Gitea
|
||||
|
||||
Gitea 以 Docker 容器运行，升级 = 拉取新镜像 + 重启容器。数据库结构变更会在启动时自动迁移。
|
||||
使用 `upgrade.sh` 升级，**不要**手动 `docker compose pull && up -d`（见下方「为什么不要手动升级」）。
|
||||
|
||||
```bash
|
||||
cd /opt/gitea
|
||||
|
||||
# 1. 备份（必须！）
|
||||
bash backup.sh
|
||||
|
||||
# 2. 查看当前版本
|
||||
curl -s http://127.0.0.1:3000/api/v1/version
|
||||
|
||||
# 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
|
||||
bash upgrade.sh --check # 先看看会发生什么，不做任何改动
|
||||
bash upgrade.sh # 正式升级到 GitHub 最新 release
|
||||
```
|
||||
|
||||
**注意事项：**
|
||||
- 务必查阅 [Gitea 发版说明](https://github.com/go-gitea/gitea/releases) 了解 Breaking Changes
|
||||
- 不支持版本降级，升级前务必备份
|
||||
- 跨多个大版本建议逐版本升级（如 1.21 → 1.22 → 1.23）
|
||||
脚本做的事：
|
||||
|
||||
| 步骤 | 内容 | 失败时 |
|
||||
|------|------|--------|
|
||||
| 1 | 预检：root、依赖命令、MySQL 连通性、数据表数量、磁盘空间 | 直接退出，服务零影响 |
|
||||
| 2 | 拉取目标镜像 | 直接退出，服务零影响 |
|
||||
| 3 | 把当前镜像打上 `pre-upgrade-<时间戳>` 标签作为回滚锚点 | — |
|
||||
| 4 | 停止 Gitea 容器（**MySQL 保持运行**） | 自动拉起原版本 |
|
||||
| 5 | mysqldump + 打包数据目录 + 校验备份完整性 | 自动拉起原版本 |
|
||||
| 6 | 切换镜像启动，Gitea 自动执行数据库迁移 | 自动回滚 |
|
||||
| 7 | 校验镜像 ID / 运行版本 / 接口 / 表行数 / 迁移版本 | 自动回滚 |
|
||||
|
||||
常用参数：
|
||||
|
||||
```bash
|
||||
bash upgrade.sh --check # 只检查，零改动
|
||||
bash upgrade.sh --version 1.26.4 # 升级到指定版本
|
||||
bash upgrade.sh --full-backup # 连仓库和 LFS 一起备份（小实例推荐）
|
||||
bash upgrade.sh --timeout 600 # 大库迁移慢，放宽就绪超时（默认 300 秒）
|
||||
bash upgrade.sh --doctor # 升级后跑一次 gitea doctor 一致性检查
|
||||
bash upgrade.sh --yes # 跳过交互确认（自动化场景）
|
||||
bash upgrade.sh --rollback # 回滚到上次升级前的状态
|
||||
```
|
||||
|
||||
**备份范围说明**
|
||||
|
||||
默认只打包会被升级影响的部分：`gitea/conf`（app.ini）、`gitea/jwt`（OAuth2 签名密钥）、
|
||||
`ssh`（SSH host key）、`gitea/indexers`、`gitea/queues`、头像目录。
|
||||
|
||||
仓库（`git/repositories`）、LFS、软件包**默认不打包** —— 它们是内容寻址的追加式存储，
|
||||
版本迁移只改数据库结构，不会改写这些文件。上百 GB 的实例每次升级都全量打包并不现实。
|
||||
数据库则**每次都完整 mysqldump**，因为那才是升级真正会动的东西。
|
||||
|
||||
小实例想要更保险，加 `--full-backup` 连仓库一起打包。
|
||||
|
||||
**回滚**
|
||||
|
||||
```bash
|
||||
bash upgrade.sh --rollback
|
||||
```
|
||||
|
||||
读取 `.upgrade-state` 里记录的备份与镜像锚点，**回灌 SQL 备份** + 恢复配置目录 + 切回旧镜像。
|
||||
|
||||
> 回滚会把数据库整体退回到升级前的状态，升级之后新产生的 issue、PR、评论、仓库记录都会丢失。
|
||||
> 数据目录用的是合并解压，**不会删除任何仓库或 LFS 文件**。
|
||||
|
||||
#### 为什么不要手动升级
|
||||
|
||||
**一、跨小版本升级不可逆，只切镜像回滚是无效的**
|
||||
|
||||
按 [Gitea 官方文档](https://docs.gitea.com/installation/upgrade-from-gitea/)，只有
|
||||
`a.b.x → a.b.y`（补丁级）才保证数据库结构不变、可以来回切。跨小版本（如 1.25 → 1.27）
|
||||
新版会在启动时改写数据库结构，之后旧版二进制看到新库会直接拒绝启动：
|
||||
|
||||
```
|
||||
Your database (migration version: 286) is for a newer Gitea,
|
||||
newer database for this old Gitea release (280).
|
||||
Gitea will exit to keep your database safe and unchanged.
|
||||
```
|
||||
|
||||
所以想退回旧版本，**唯一正确的办法是回灌升级前的 SQL 备份**。手动改 `version` 表是官方
|
||||
明确警告会丢数据的操作。`upgrade.sh` 的回滚就是按这个路径做的，并且会拒绝执行跨小版本降级。
|
||||
|
||||
**二、`docker compose up -d` 不会因为镜像变了就重建容器**
|
||||
|
||||
容器处于 stopped 状态时，`up -d` 只是把原容器重新 start，结果是「改了配置但还跑着旧镜像」。
|
||||
必须 `--force-recreate`。脚本在启动后强制校验「容器实际运行的镜像 ID == 目标镜像 ID」，
|
||||
不匹配直接回滚。
|
||||
|
||||
**三、`.env` 里的变量已经被 export 到当前 shell**
|
||||
|
||||
部署脚本用 `set -a; source .env` 导出过 `GITEA_IMAGE`，而 docker compose 对环境变量的
|
||||
优先级高于 `.env` 文件 —— 只改文件不改环境变量，compose 仍会读到旧镜像。
|
||||
|
||||
**其它注意事项：**
|
||||
- 升级前查阅 [Gitea 发版说明](https://github.com/go-gitea/gitea/releases) 了解 Breaking Changes
|
||||
- 自定义模板与新版不兼容会导致 5xx 或页面错乱，脚本的首页检查能发现这类问题
|
||||
- MySQL 容器不在 `upgrade.sh` 的升级范围内，需要单独处理（见下）
|
||||
|
||||
#### 升级 MySQL
|
||||
|
||||
@@ -749,6 +800,8 @@ docker compose exec server gitea admin user change-password -u 管理员用户
|
||||
├── .env # 运行时配置（自动生成）
|
||||
├── deploy.sh # 全新服务器一键部署脚本
|
||||
├── backup.sh # MySQL + 数据备份脚本
|
||||
├── upgrade.sh # 安全升级脚本（备份 → 校验 → 自动回滚）
|
||||
├── .upgrade-state # 升级回滚锚点（upgrade.sh 自动生成）
|
||||
├── uninstall.sh # 完全卸载脚本
|
||||
├── .gitignore
|
||||
├── README.md
|
||||
|
||||
Reference in New Issue
Block a user