GitBucket 4.48.0 介绍与选型指南

目标：判断 GitBucket 4.48.0 是否适合你的团队。本文只做联网溯源（官方仓库、Release 资产、构建文件、Docker Hub 与竞品官方仓库），查询日期 2026-10-27，不在本机部署；安装、Compose、参数与 API 的实测数据见本专栏后续三篇。

一、版本与环境信息

二、它是什么

GitBucket 是一个用 Scala 写的自托管 Git 平台，官方定位三句话：安装简单、界面直观、对 GitHub API 兼容。它把「代码托管 + Issue + Pull Request + Wiki + 组织/用户 + 插件」打包进一个 WAR 文件，java -jar gitbucket.war 就能跑起来，默认用内嵌 H2 数据库，不需要额外装数据库、缓存或消息队列。

这一点决定了它的用户画像：不是要替代 GitLab 的全部能力，而是给「只想要一个能 push、能看代码、能提 PR、还能被 IDE/CI 用 token 调用」的团队一个零依赖方案。

三、架构真相：Scalatra + Jetty + JGit，不是 Akka HTTP

网上不少二手资料把 GitBucket 描述成「Scala + Akka HTTP」，这与 4.48.0 的实际构建文件不符。以 build.sbt 为准，它的运行栈是：

• Web 层：Scalatra 3.2.1（scalatra-javax 系列，基于 Servlet API），模板用 Twirl，JSON 用 json4s-jackson 4.1.1；
• HTTP 容器：内嵌 Jetty 10.0.26，java -jar 时由启动器拉起；也可打成 war 丢进外部 Servlet 容器；
• 持久层：SolidBase 1.1.0 做表结构/数据迁移，底层 JDBC + HikariCP，默认 H2 2.5.250 文件库，可换 PostgreSQL / MySQL；
• Git 层：JGit 6.10.1 负责裸仓库读写与 HTTP 智能协议，Apache SSHD 2.19.0 负责内置 SSH 服务；
• 扩展层：插件以 jar 形式挂载，官方维护 Gist、Emoji、Pages、Notifications 四款插件，社区插件清单在项目 Wiki。

逻辑分层可以简化为：

浏览器 / git CLI / REST 客户端
        │  HTTP(S) 8080/8443 · SSH 29418
        ▼
Scalatra 路由（Web UI + /api/v3）
        │
   Service 层（账户 / 仓库 / Issue / PR / 插件）
        │
JGit 裸仓库 + JDBC(HikariCP) ── H2 文件库 / PostgreSQL / MySQL

关键约束：GitBucket 至今不支持 Jakarta EE。官方 README 明确说明「doesn't support Jakarta EE yet」，意味着 Tomcat 10+、Jetty 11+ 这类 jakarta.servlet 容器不能直接部署，只能用内嵌 Jetty 10 或 Servlet 3.x 的外部容器（如 Tomcat 9）。这不是小细节，很多「war 丢进新容器就 404」的故障都源于此。

四、功能盘点（4.48.0）

4.48.0 的变更重点有三条：为 GitHub 兼容 API 增加数字用户/账户 ID 并提供按数字 ID 管理用户的 API；鉴权相关 API 有改动，部分旧插件可能不兼容；修复最后一个管理员删除保护的问题，并在用户设置页新增 Danger zone。

五、升级风险：4.47/4.48 的大表迁移与 H2 1.x→2.x

官方 README 在 4.48.x 段落专门加了两条警告，值得在选型阶段就纳入评估：

1. 4.47.0 与 4.48.0 含影响 REPOSITORY、ACCOUNT 等核心表的大规模数据库迁移，升级前必须备份数据库，大库升级耗时不可忽略；
2. 如果从 4.42 或更早升级到 4.43+，且使用默认 H2，必须手工做 H2 1.x → 2.x 的文件迁移（官方给出的步骤是用 h2-1.4.199 导出 SQL、再用 h2-2.3.232 导入），并去掉 database.conf 里的 ;MVCC=true。这一步无法由 GitBucket 的自动迁移完成。

换句话说：新装很轻，跨大版本升级不轻。选型时要接受「升级需要停机 + 备份 + 偶尔手工迁移」的运维模型。

六、部署形态：WAR 是主线，官方镜像已停更

GitBucket 有两条部署路径：

• WAR + JVM 托管：下载 gitbucket.war，java -jar 直接跑，或用 systemd 托管，前面挂 Nginx 做 TLS 与域名。这是官方 README 的主推路径，也是本专栏 B1 的实测路线。
• 容器：官方 Docker Hub 仓库 gitbucket/gitbucket 存在，但 2026-10-27 实查其 tag 只到 4.38.4（2022-12-25），latest 也停在同一镜像，没有 4.48.0。也就是说官方镜像已四年未更新，直接用会落后 10 个小版本；若要用容器跑 4.48.0，只能基于官方 WAR 自建镜像。

这个事实直接影响选型：追求「官方容器 + 最新版」的组合在 GitBucket 上不存在。接受 JVM 运维就选 WAR；坚持容器化就要接受自建镜像并自行承担基础镜像维护。

七、与同类平台对比

下表的仓库热度为 2026-10-27 通过各官方仓库 API 实查；技术栈与许可证取自仓库元数据。运行内存一列只写 GitBucket 侧可配置的 JVM 堆上限（本专栏统一按 -Xmx512m 实测），其余项目未在本机实测，不写估算值。

选型结论

优先选 GitBucket 的场景

1. 团队已经在运维 JVM 应用（Tomcat/Jetty、JDK 17、JVM 监控），希望 Git 服务复用同一套发布与监控体系；
2. 规模 ≤20 名开发者、仓库量在数百以内，单节点 2C4G 足够，愿意用 512 MB 堆换低运维成本；
3. 完全内网/离线环境，要求「一个 WAR + 一个数据目录」就能交付，不想引入 PostgreSQL、Redis、Sidekiq 等依赖；
4. 需要 GitHub 风格 API 兼容（IDE、脚本、CI 用 token 调 /api/v3），但不要求 GitLab 级 CI/CD 与权限模型；
5. 愿意用 Scala 写插件，或只需要 Gist/Pages/Emoji 这类官方插件。

不建议选 GitBucket 的场景

一句话：GitBucket 的竞争力是「JVM 世界里最省事的 Git 平台」，不是「功能最全」。把它放在小团队、内网、JVM 运维体系里，它很好用；拿它去对标 GitLab 的 CI/CD 与高可用，结论一定是不要选。

八、参考来源（查询日期 2026-10-27）

• GitBucket 仓库与元数据：https://github.com/gitbucket/gitbucket
• 4.48.0 Release 与资产：https://github.com/gitbucket/gitbucket/releases/tag/4.48.0
• 官方 README（Java 17、安装、H2 迁移、插件）：https://github.com/gitbucket/gitbucket/blob/master/README.md
• 构建依赖（Scalatra/Jetty/JGit/H2 版本）：https://github.com/gitbucket/gitbucket/blob/4.48.0/build.sbt
• 官方镜像标签：https://hub.docker.com/r/gitbucket/gitbucket/tags
• 项目 Wiki（Nginx/Apache、LDAP、插件）：https://github.com/gitbucket/gitbucket/wiki
• H2 1.x→2.x 迁移说明：https://www.h2database.com/html/migration-to-v2.html
• 竞品仓库：https://github.com/go-gitea/gitea · https://codeberg.org/forgejo/forgejo · https://github.com/gitlabhq/gitlabhq · https://github.com/theonedev/onedev · https://github.com/scm-manager/scm-manager

本专栏后续：安装见《Ubuntu 22.04 安装 GitBucket 4.48.0 指南》（{{B1}}）；容器部署见《GitBucket 4.48.0 Docker Compose 部署指南》（{{B2}}）；参数见《GitBucket 4.48.0 配置参数详解》（{{C1}}）；接口见《GitBucket 4.48.0 REST API 详解》（{{D5}}）。