从旧版 Gitea 升级

请按照以下步骤确保顺利升级到新的 Gitea 版本。

查看变更日志以了解重大更改

为了使 Gitea 更好，一些重大更改是不可避免的，尤其是在大型里程碑版本中。在升级之前，请阅读 Gitea 博客上的变更日志 并检查重大更改是否会影响您的 Gitea 实例。

验证是否存在已弃用的配置选项

新版本的 Gitea 通常会带来更改的配置语法或选项，这些选项通常会在站点管理面板顶部至少显示一个发布周期。如果这些警告未解决，Gitea 可能会拒绝在后续版本中启动。

备份以进行降级

Gitea 保持与补丁版本的前两个字段相同的兼容性（a.b.x -> a.b.y），这些补丁版本可以使用相同的数据库结构进行升级和降级。否则（a.b.? -> a.c.?），较新的 Gitea 版本会将旧数据库升级到可能与旧版本不同的新结构。

例如

从	到	结果
1.4.0	1.4.1	✅
1.4.1	1.4.0	⚠️ 不推荐，请自行承担风险！虽然如果数据库结构没有更改，它可能有效，但强烈建议使用备份进行降级。
1.4.x	1.5.y	✅ 数据库将升级。您可以直接从 1.4.x 升级到最新的 1.5.y。
1.5.y	1.4.x	❌ 数据库已升级，无法用于旧版 Gitea，请使用备份进行降级。

由于您无法在升级后的数据库上运行旧版 Gitea，因此在数据库升级之前应始终进行备份。

如果您在生产环境中使用 Gitea，即使是在补丁版本之间升级，也始终强烈建议在升级之前进行备份。

备份步骤

• 停止 Gitea 实例
• 备份数据库
• 备份 Gitea 配置
• 备份 APP_DATA_PATH 中的 Gitea 数据文件
• 备份 Gitea 外部存储（例如：如果使用 S3/MinIO 或其他存储）

如果您使用具有快照功能的云服务或文件系统，则对 Gitea 数据卷和相关对象存储进行快照会更加方便。

准备好所有步骤后，下载新版本，停止应用程序，执行备份，然后启动新应用程序。在每次启动时，Gitea 都会验证数据库是否是最新的，并将自动执行任何必要的迁移。根据数据库的大小，这在第一次启动时可能需要一些额外的时间，在此期间应用程序将不可用。

使用 Docker 升级

• docker pull 最新的 Gitea 版本。
• 停止正在运行的实例，备份数据。
• 使用 docker 或 docker-compose 启动较新的 Gitea Docker 容器。

从软件包升级

• 停止正在运行的实例，备份数据。
• 使用您的软件包管理器将 Gitea 升级到最新版本。
• 启动 Gitea 实例。

从二进制文件升级

• 将最新的 Gitea 二进制文件下载到临时目录。
• 停止正在运行的实例，备份数据。
• 将已安装的 Gitea 二进制文件替换为下载的二进制文件。
• 启动 Gitea 实例。

可在 Gitea 源代码树中的 contrib/upgrade.sh 中找到一个用于在 Linux 上部署自动执行这些步骤的脚本。

注意自定义模板

Gitea 的模板结构和变量可能会在版本之间发生变化，如果您使用的是自定义模板，请注意您的模板是否与您正在使用的 Gitea 兼容。

如果自定义模板与 Gitea 版本不匹配，您可能会遇到：50x 服务器错误、页面组件丢失或功能异常、页面布局奇怪等问题。删除或更新不兼容的模板，Gitea 网页将恢复正常工作。