Forgejo 升级指南-未完纪

本指南面向 Forgejo 管理员，介绍升级流程与故障排查，也覆盖从早至 Gitea 1.2.0 的版本迁入。以下内容依据核对时 latest 页面，导航标示 v16.0.5；实际操作应核对目标版本发布说明。

发布生命周期

稳定版：当前最新正式版本接受三个月完整支持、错误和安全修复；下一稳定版发布后，还有两周窗口。
LTS：每年第一季度发布，接受一年三个月的重要错误修复与安全支持。
实验版：当前开发版本包含新功能，不应用于生产。

可以关注或订阅安全公告仓库的 RSS，提前获知安全版本的预计发布日期。提前公告不披露漏洞细节，便于管理员安排升级。

语义化版本

Forgejo 从 7.0.0 起遵循语义化版本：破坏性变更通常伴随首个版本数字改变，例如 7.x 到 8.0.0。发布说明记录这些变更，某些安装环境需要手工介入。

7.0.0 以前，1.19、1.20、1.21 都包含破坏性变更，当时的编号不符合这一规则。

完整备份

升级到新稳定版前必须做完整备份，例如 1.20 到 1.21；即使只是 7.0.0 到 7.0.1 的补丁更新，备份也很有必要。

可靠方法是对 Forgejo 使用的全部存储做同一时间点的同步快照。如果 SQLite、仓库等都位于虚拟机所挂载的单个 QCOW2 磁盘上，原文列出 QEMU 快照作为可在运行期间取得一致备份的例子；实际仍须确保快照覆盖相关存储及一致性要求。

如果附件存于 S3、数据库使用 PostgreSQL、Git 仓库位于远程文件系统、队列在 Redis 中，原文要求在备份期间关闭 Forgejo，取得一致状态。

最简单的单文件系统且无镜像任务、无用户活动场景，可用 forgejo dump 收集为 ZIP，并对 PostgreSQL/MySQL 另外使用原生数据库备份工具。原文指出，forgejo dump 中包含的 SQL 导出存在长期问题，重新导入新数据库时可能出错，不能替代原生备份。SQLite 数据库文件已经包含在 ZIP 内，不需再另做 SQL dump。

验证功能

升级前后都需要仔细验证。升级后立即发现问题，还容易恢复升级前备份；若数日或数周后才发现，恢复旧备份会涉及后来产生的数据，此时不能视为无损回退。

运行 forgejo doctor check --all --log-file /tmp/doctor.log，确认没有问题。
在 Web 界面手工检查典型使用场景，预先列出检查清单避免遗漏。
出现问题时提高日志级别并查看日志；无法定位时，可先向 Forgejo 社区求助。

从 Gitea 迁入的准备

原文说明支持最高至 Gitea 1.22 的迁入，分两步：

从符合条件的 Gitea 版本升级至 Forgejo v10.0.x。
从 Forgejo v10.0.x 升级至大于 v10 的目标 Forgejo 版本。

不能据此推断任意更新的 Gitea 版本都能直接迁入。

Forgejo 升级前的准备

检查模板目录的源代码变更，手工分析并更新定制 CSS 和内容。

查找 CustomPath 时，原文要求在管理员登录后的站点管理配置页查看，不要仅靠 forgejo help 推断路径。

执行 forgejo manager flush-queues 清空队列。若超时，原文建议增大 --timeout 后再执行。队列保存序列化数据，跨版本不保证兼容，所以此步骤很重要。

Docker 安装的原文最低要求为Docker 20.10.6。低于要求时，可能出现看起来与 Docker 版本无关的问题。

执行升级

先阅读下文与具体来源版本有关的注意事项，确认不受影响或完成相应处理。符合升级路径时，通过替换二进制或容器镜像升级到目标正式版本，升级过程负责迁移。随后按前文检查功能。

故障排查

默认日志输出到控制台。需要日志文件时，原文建议在 app.ini 中移除其他 [log] 节，采用下面配置，然后在 Forgejo 日志目录中查找 *.log：

 ; To show all SQL logs, you can also set LOG_SQL=true in the [database] section
 [log]
 LEVEL=debug
 MODE=console,file
 ROUTER=console,file
 XORM=console,file
 ENABLE_XORM_LOG=true
 FILE_NAME=forgejo.log
 [log.file.router]
 FILE_NAME=router.log
 [log.file.xorm]
 FILE_NAME=xorm.log

原配置注释还提到在 [database] 中设置 LOG_SQL=true。日志可能包含敏感业务数据，收集和分享时应根据内容处理。

从版本 x.y 直接到 x.y+2 失败时，可以按各系列的最后补丁逐步升级并验证，帮助定位问题系列。原文的历史例子是 1.19.3-0 到 1.21.6-0 失败，则先到 1.19 系列最后的 1.19.4-0 并验证，再到 1.20 系列最后的 1.20.6-0 并验证。这些是旧版本排障案例，不是当前推荐安装版本。

数据库版本不符

数据库记录版本，用于防止意外降级。例如，将 Forgejo 1.20 降到 1.19 会拒绝启动，以免破坏数据库内容。

原因不明的失败与旧案例

原文针对 SQLite 登录后空白页或 HTTP 500列出历史处理：升级至 Forgejo 1.19.3-0 或更高，运行 gitea doctor check --all --fix。

这里保留了原文的 gitea 命令名。它属于特定历史案例，不能未经核对当作当前 Forgejo 的通用修复命令。

特定版本与升级路径

从 16.0 以前升级至 16.0 或以后：可选清理

仓库中有一些较小的 hook 与 description 文件，新版 Forgejo 不再需要。清理是可选项，尤其适用于仓库众多的实例，不能当作一般升级的必做步骤。

原文假定 REPO_PATH 指向所有 Forgejo 仓库所在目录：

export REPO_PATH="/path/to/forgejo/data/forgejo-repositories"

Git hooks

服务端 Git hooks 是裸仓库中的脚本，部分用于权限检查和仓库状态更新。自定义用户 hooks 默认禁用，原文因安全原因不推荐启用；管理员仍可手工放置脚本，或在 DISABLE_GIT_HOOKS 设为 false 时允许用户创建。

Forgejo 界面里的 Webhooks 是另一项功能，不受这次变化影响。

从 v16.0.0 起，Forgejo 所需 hooks 已集中管理。旧的自动生成 hooks 与样例文件可以清理。只有确认所有仓库均没有自定义服务端 hooks 时，才可考虑原文的目录删除示例：

find "$REPO_PATH" -mindepth 3 -maxdepth 3 -name hooks -exec rm -rf {} \;

原文还给出检查非空、非样例、非自动生成 hook 文件的办法：

find "$REPO_PATH" -maxdepth 5 -wholename "*/hooks/*" -type f -size +0 |\
   grep -v '\.sample$'                                                |\
   xargs -d '\n' grep -L "AUTO GENERATED BY GITEA"

原文把没有输出作为“没有自定义 hooks”的判断依据。实际判断还必须确认遍历路径、权限、过滤条件和命令成功状态，不能把报错或未遍历到文件也当作没有自定义 hooks。

如果有需要保留的自定义 hooks，应原地保留，原文说明它们升级后仍应可用。自动生成和样例文件可分别清理：

find "$REPO_PATH" -maxdepth 5 -wholename "*/hooks/*" -type f |\
   xargs -d '\n' grep -l "AUTO GENERATED BY GITEA"           |\
   xargs -d '\n' rm

find "$REPO_PATH" -maxdepth 4 -name "*.sample" -type f -delete

这些命令包含删除动作，必须先核对目标目录和备份。本文为忠实记录保留它们，没有执行。

Description 文件

原文说明，这些文件以前由 git init 自动创建，新版不再创建，Forgejo 不使用它们，可以作为可选清理对象：

find "$REPO_PATH" -mindepth 3 -maxdepth 3 -name description -type f -delete

同样，实际删除前应核对目标及是否包含管理员自行保留的内容。

更旧的 Forgejo、Gitea 或 Gogs

从 Forgejo/Gitea 1.20.3-0 或更早版本，以及 Gogs 迁入时，还应阅读旧版升级提示。最初使用 Gogs 的实例，即使已经迁到 Gitea，也需要查看相关说明。

从 Gitea 升级的详细说明

Forgejo 已成为 Gitea 的硬分叉，原文所述兼容迁入范围截至 Gitea 1.22。详细步骤见从 Gitea 升级。

文章版权归作者所有，未经允许请勿转载。

THE END

技术译文

Forgejo 升级指南