Forgejo v17 自建代码托管：Docker 部署、与 Gitea 对比和局限

Forgejo 是一个用 Go 写的自托管代码托管平台，可以理解成装在自己服务器上的 GitHub 替代品：仓库、议题、合并请求、Wiki、包注册表和 CI 都在里面。2026 年 10 月 15 日发布 v17.0，10 月 26 日跟进 v17.0.1。下面按部署、对比、局限三段说清楚它能干什么、哪里会卡住。

一个 Go 二进制撑起的软件工厂

Forgejo 的起点是治理争议。2022 年 10 月，Gitea 的域名与商标被转给一家营利公司，社区在未获同意的情况下失去了对项目归属的控制权。Forgejo 由此成立，2024 年初从软分支转为硬分支，代码库开始独立演进。

现在它的域名由柏林的非营利协会 Codeberg e.V. 托管，官方 FAQ 写明目前没有注册任何商标。许可证方面，v9.0 及之后的版本采用 GPL v3+，v8.0 及更早是 MIT。

功能面覆盖日常开发所需：仓库浏览、blame、diff、合并请求评审、议题与看板、包注册表（npm、PyPI、Docker 等）、Forgejo Actions。Actions 直接使用 GitHub Actions 的工作流语法，多数 YAML 可以搬过来用。

发布节奏是每三个月一个大版本，每年年初那一版转为 LTS。按发布页记录，v15.0 LTS 发布于 2026 年 4 月 16 日，支持到 2027 年 7 月 15 日；v17.0 属于非 LTS，支持到 2027 年 1 月 28 日。

v17.0 带来的变化

按官方发布说明，v17.0 新增了 FUNDING.yml 资助入口，仓库页会多出一个 Donate 按钮；议题与合并请求输入框支持用 # 和 ! 触发自动补全；组织成员可以改为邀请制，在 app.ini 里设 ADD_MEMBERS_BY_INVITATIONS = true，邀请默认 14 天过期。

Actions 侧的动作更多：工作流运行与单个作业可以通过 API 重跑，作业日志支持按步骤和子串过滤，还能取 NDJSON 格式。作业摘要需要 Runner 13.2 或更高版本，摘要写在 $FORGEJO_STEP_SUMMARY 里，同时兼容 GitHub 的变量名。

迁移来源新增 Bitbucket Data Center，可一并导入合并请求、评审与多行评论；从 Gogs、GitLab、Gitea 或 Forgejo 迁移时仓库头像也会带过来。破坏性改动有两处需要留意：渲染文档里以斜杠开头的仓库内链接，解析基准改为仓库根；action run 类 webhook 事件被弃用，换成 workflow run 事件，且请求头与 action 字段有变，接收端要人工核对。

Docker 部署：五步跑起来

官方推荐用容器部署，镜像放在 codeberg.org 的容器仓库里。若该域名访问不畅，可把地址换成 data.forgejo.org 镜像站。完整参数见 Docker 安装文档。

1. 准备 compose 文件，镜像写 codeberg.org/forgejo/forgejo:17，映射 3000:3000 与 222:22。
2. 把 ./forgejo 目录的属主改为 UID/GID 1000，权限不对容器会起不来。
3. 需要外部数据库时加 FORGEJO__database__DB_TYPE=postgres 等变量；不配置则默认用 SQLite。
4. 执行 docker compose up -d，浏览器打开 http://localhost:3000 完成初始化。
5. 用 ssh -F /dev/null git@主机地址 -p 222 验证 SSH 通道是否通。

配置项写在 app.ini 里，容器镜像会自动创建该文件。也可以用 FORGEJO__[SECTION]__[KEY] 形式的环境变量覆盖，例如 FORGEJO__repository__ENABLE_PUSH_CREATE_USER=true 等价于在 [repository] 段写 ENABLE_PUSH_CREATE_USER = true。

容器镜像没有 latest 标签。主版本升级需要人工介入，所以标签策略是：17 跟到该主版本内的补丁版，17.0 只跟 17.0.Y。想省事的场景适合用 17，需要可控的场景锁 17.0.1 这样的具体版本。

另外注意 Docker 版本不低于 20.10.6，否则会出现和 Docker 版本看似无关的故障。rootless 镜像的数据目录是 /var/lib/gitea，SSH 端口映射改成 222:2222。在 Podman 环境下如果报权限错误，给卷挂载加 :Z 或 :z 安全标签；树莓派上绑定目录常出问题，改用带 driver_opts 的命名卷可以绕过。

备份与恢复

官方新增了备份与恢复指南，重点是几个必须一起备份的密钥，漏掉就无法完整还原。整个实例的数据分三块：数据库、仓库目录、以及 app.ini 里的密钥与配置文件。三者不在同一个位置，容易只备了一份。

升级到新的主版本属于必须备份的场景，补丁版升级也建议照做。恢复比修复便宜得多：升级后几天才暴露的问题，往往已经没法回滚，只能在运行中的实例上硬修。

和 Gitea 的对比：治理、许可证与迁移代价

两者日常界面几乎一样，差别在谁掌舵。Gitea 的商标与商业运营归 Gitea Ltd，Forgejo 归 Codeberg e.V.。许可证也不同：Gitea 全程 MIT，另有付费企业版；Forgejo 自 v9.0 起是 GPL v3+，没有付费版本。官方在对比页把分歧归结为治理、安全响应流程和联邦路线。

迁移是这里最需要提醒的一段。按升级指南，Forgejo 只支持从 Gitea v1.22 及更低版本平滑升级，路径是任意 Gitea ≤ 1.22 先升到 Forgejo v10.0.x，再升到更高版本。Gitea 从 v1.23 起就没有受支持的直读路径了。

第三方整理者给出三种替代方案：用社区脚本先把数据库结构降级，再走上面两步；或者新建实例通过 API 拉取仓库、议题与合并请求，代价是时间戳被改写、内部 ID 丢失；或者干脆留在 Gitea。反向迁移同样没有受支持路径，等于单向门。可参考 Botmonster 的对比文章。

局限与需要注意的地方

• 没有官方 Windows 二进制。2024 年社区决定放弃对 Windows 的支持并移除了相关代码，runner 另有社区构建版。
• 联邦功能仍处实验状态。官方 FAQ 明确说可能不打招呼就做破坏性改动，甚至让实例域名在 ActivityPub 联邦中作废。
• 没有商业 SLA。需要 SAML 单点登录、审计日志和合同背书的团队，这边没有对应产品。
• 升级前必须全量备份，升级后跑 forgejo doctor check --all 自查，还要人工过一遍常用流程。
• 队列里可能有跨版本不兼容的序列化数据，升级前建议执行 forgejo manager flush-queues。
• 与 Gitea 的 API 兼容性在缩小，依赖 Gitea 专有接口的内部工具要提前验证。

Codeberg 的平台政策与软件许可是两件事

2026 年 7 月 23 日，Codeberg e.V. 会员就两项动议投票。其中一项承诺不用托管代码和用户数据训练大模型；另一项以 358 票赞成、144 票反对、14 票弃权通过，修改使用条款，禁止主要由生成式 AI 工具写成的项目。详见 Codeberg 官方公告。

公告把理由落在成本与协作信任上，其中提到采购的固态盘从约 700 欧元涨到约 3700 欧元且常常缺货。The Register 的报道补充了一点：以该组织的资源，除非项目主动引起注意，实际执行力度有限。

关键区别在于，这些条款约束的是 codeberg.org 这个托管服务，不是 Forgejo 软件本身。自建实例的政策由你自己定，代码依旧按 GPL v3+ 分发。

适合谁上手

三类人比较合适。想脱离 GitHub 又不想承担 GitLab 资源开销的小团队；需要内网代码托管、又要求许可证干净的组织；想把 CI 留在自己机器上的项目。

上手顺序建议这样走：先在一台 1 核 2G 的机器上用 SQLite 跑通，确认界面和 Actions 符合预期；再切到 PostgreSQL，把备份脚本接进现有流程，可参考自建备份工具清单里的方案；最后考虑把 runner 单独部署。

如果同时还要自托管其他服务，Coolify 那类面板可以省掉反向代理的配置功夫。开发侧若需要接口调试，Bruno 把接口集合存进 Git 仓库的思路和自建 forge 很搭。

常见问题

SQLite 能不能用于生产？小团队和单机部署够用，官方默认就是 SQLite。多人协作或需要并发写入时换 PostgreSQL 更稳妥，配置改 DB_TYPE 即可。

一定要用 codeberg.org 的镜像吗？不一定。容器镜像同时发布在 codeberg.org 与 data.forgejo.org，国内拉取困难时换成镜像站地址即可，标签含义相同。

Gitea 1.23 以上的实例怎么迁？官方没有受支持路径，只能降级数据库结构、走 API 搬运，或者继续留在 Gitea。动手前务必备份并在副本上演练一遍。