gitblit-1.9.3 内网自托管 Git 服务部署与权限配置实战-开发者社区

简介：Gitblit-1.9.3 是一款开源 Git 仓库管理工具，面向需要自建代码托管服务的开发团队与运维人员，可独立运行或嵌入 Java Web 应用，提供仓库创建、克隆、推送、拉取及细粒度权限控制等全流程支持。该版本在界面交互、性能与安全性上有所改进，并修复了早期版本的若干缺陷，适合中小团队搭建内部版本控制平台。资源包共 321 个文件，约 41.31MB，以 jar 核心库、html 与 js 前端页面、css 样式、png 图标资源为主，另含 groovy 扩展脚本、cmd 启动与服务注册脚本、conf 与 properties 配置模板及多语言 tmpl 文件，覆盖运行、配置与扩展各环节。目前已有 352 人学习下载。解压后可按文档完成仓库存储路径、访问权限与邮件通知等配置，快速落地团队协作与代码安全管理。

1. 为什么 2024 年还有人折腾 gitblit-1.9.3：一个被低估的自托管 Git 方案

如果你手上有一台内网服务器、几个人的小团队、又不想把代码托管到外部平台，gitblit-1.9.3 大概率是你绕不开的一个选项。它是一个纯 Java 实现的 Git 服务端，单个 jar 包就能跑起来，自带 Web 界面、仓库管理、权限控制、HTTP/SSH 两种协议支持，甚至内置了工单和文档浏览。很多人第一次听到它会觉得"这不是十几年前的东西吗"，但恰恰是这种"老而稳"的特性，让它在离线环境、内网隔离环境、教学实验环境里一直有生命力。

这篇文章不讲空泛的架构吹捧，只讲一件事：拿到 gitblit-1.9.3 这个包，怎么从零把它跑成一个能用的团队 Git 服务，参数怎么调，权限怎么配，以及我在实际部署里踩过的那些坑。适合两类人：一类是需要在没有外网的环境里搭 Git 服务的运维或开发，另一类是想搞懂一个 Java Web 服务从 jar 到生产可用到底要补哪些东西的工程师。读完你应该能自己复现一套可用的部署，并且知道哪些默认配置必须改。

2. 从 jar 到可访问服务：gitblit-1.9.3 的最小可用部署

2.1 先搞清楚 gitblit 的运行形态和依赖边界

gitblit 有两种典型运行方式：一种是java -jar gitblit.jar直接前台跑，适合调试；另一种是配合gitblit.sh/gitblit.cmd脚本以服务方式后台运行，适合生产。它的核心依赖只有一个像样的 JRE，1.9.3 这个版本对 JDK 8 兼容最好，用 JDK 11 也能跑，但如果你用 JDK 17 以上，可能会遇到反射相关的警告甚至启动失败，这是很多人第一次翻车的地方。

它的目录结构在首次启动后会自动生成，关键目录有这么几个：data/放配置和仓库元数据，data/git/是实际的裸仓库存储位置，data/ssh/放 SSH 主机密钥，logs/是日志。理解这几个目录，后面排查问题基本就是在这几个地方转。

提示：不要用 root 直接跑 gitblit，仓库文件属主会乱，后面迁移或备份时权限问题会让你很头疼。建一个专用系统用户，比如gitblit，所有操作都用它。

2.2 首次启动与基础配置文件的定位

假设你已经把gitblit-1.9.3.tar.gz解压到了/opt/gitblit，第一步是确认 Java 版本，然后做一次前台启动，观察它到底生成了什么。

# 确认 Java 版本，1.9.3 建议 JDK 8 或 11 java -version # 进入解压目录 cd /opt/gitblit # 前台启动，第一次会生成 data 目录和默认配置 # 注意：这里用 -Xmx 限制堆内存，默认可能偏大 java -Xmx512m -jar gitblit.jar --baseFolder data

启动过程中终端会打印一堆日志，重点看两行：一行是Gitblit started，说明服务起来了；另一行是 HTTP 端口，默认是 8080 或者 8443（HTTPS）。如果卡在某个地方不动，八成是端口被占用或者 data 目录权限不对。

启动成功后，data/gitblit.properties就是主配置文件。这个文件内容很多，但真正需要你动的没几个。我一般会先改这几项：

# 服务监听地址，0.0.0.0 表示所有网卡 server.httpBindInterface = 0.0.0.0 # HTTP 端口，冲突就换 server.httpPort = 8080 # 对外访问地址，影响克隆 URL 的生成，必须改成实际 IP 或域名 web.canonicalUrl = http://192.168.1.100:8080 # 仓库存储根目录，默认在 data/git 下 git.repositoriesFolder = data/git # 关闭匿名访问，强制登录 web.authenticateViewPages = true

web.canonicalUrl这一项特别容易被忽略。如果你不改，Web 界面上显示的克隆地址会是http://localhost:8080/xxx.git，别人复制过去根本用不了。这个坑我见过至少三次，每次都是"为什么我克隆不了"的经典问题。

2.3 用脚本方式做成后台服务

前台跑只能验证能不能用，真正部署要让它后台常驻。gitblit 自带的脚本在service/目录下，Linux 用gitblit.sh，但直接用它需要改几个变量。

# 复制服务脚本到系统目录 sudo cp /opt/gitblit/service/gitblit.sh /etc/init.d/gitblit sudo chmod +x /etc/init.d/gitblit # 编辑脚本，改这几行 # GITBLIT_PATH=/opt/gitblit # GITBLIT_BASE_FOLDER=/opt/gitblit/data # GITBLIT_USER=gitblit # JAVA_HOME=/usr/lib/jvm/java-11-openjdk

改完之后用service gitblit start启动，再用service gitblit status看状态。如果启动失败，去logs/gitblit.log里找Exception关键字，通常能直接定位到是配置项写错还是权限问题。

这里有个细节：脚本里的GITBLIT_USER如果和你实际运行用户不一致，会导致 data 目录写不进去，日志里会报Permission denied。解决办法很简单，把 data 目录整个 chown 给那个用户就行。

sudo chown -R gitblit:gitblit /opt/gitblit/data

2.4 验证服务可用的三个动作

服务起来之后，别急着交付，先做三个验证。第一，浏览器打开http://你的IP:8080，能看到登录页；第二，用默认管理员账号admin/admin登录，进去第一件事就是改密码；第三，创建一个测试仓库，用命令行克隆一次。

# 克隆测试，注意 URL 里的用户名密码方式 git clone http://admin:你的密码@192.168.1.100:8080/r/test.git # 如果走 SSH，需要先把公钥加到用户设置里 git clone ssh://admin@192.168.1.100:29418/r/test.git

SSH 端口默认是 29418，不是 22，这个也经常有人搞混。如果 SSH 克隆报Connection refused，先确认server.sshPort配置和防火墙放行情况。

3. 权限模型与仓库管理：gitblit 真正需要配对的几件事

3.1 用户、团队、仓库权限的三层关系

gitblit 的权限模型是"用户 → 团队 → 仓库权限"三层。用户可以直接授权，也可以通过加入团队继承权限。仓库权限分得比较细：VIEW（能看到）、CLONE（能克隆）、PUSH（能推送）、CREATE（能建仓库）、DELETE（能删仓库）、OWNER（完全控制）。

实际配置里，我建议按团队来管，不要给单个用户直接授权。原因很简单：人员变动时你只需要改团队成员，不用去每个仓库里翻权限。具体做法是在 Web 界面Users里建团队，比如dev-team、ops-team，然后在仓库的Edit页面里把权限授给团队。

注意：PUSH权限和分支保护是两回事。gitblit 1.9.3 支持按分支设置访问控制，但配置入口藏得比较深，在仓库设置的高级选项里，需要手动写access.restrictions属性。如果只是想让某些人不能推 main 分支，用这个比整体收回 PUSH 更合适。

3.2 批量建仓库和迁移已有仓库

手动在界面上点着建仓库，超过十个就是折磨。gitblit 支持通过配置文件批量导入，也支持直接把已有的裸仓库目录拷进去再刷新。

批量导入的做法是编辑data/gitblit.properties，加上一行：

# 指定一个仓库列表文件，每行一个仓库名 git.repositoryImportFile = data/repos.list

然后data/repos.list里写：

project-a.git project-b.git project-c.git

重启服务后，gitblit 会自动在data/git下创建这些裸仓库。如果是迁移已有仓库，直接把xxx.git目录整个拷到data/git/下，然后在 Web 界面点Refresh或者重启服务，它会自动识别。

这里有个坑：拷进去的仓库如果属主不是运行用户，gitblit 能识别但推送会失败，报insufficient permission。所以拷贝完记得 chown。

sudo chown -R gitblit:gitblit /opt/gitblit/data/git/project-a.git

3.3 备份策略：别等硬盘挂了才想起来

gitblit 的备份其实很简单，因为核心数据就两块：data/git/下的裸仓库，和data/gitblit.properties加data/users.conf这些配置文件。我的习惯是每天凌晨用 rsync 同步一次到另一台机器。

# 备份脚本示例，放到 crontab 里每天跑 #!/bin/bash BACKUP_DIR=/backup/gitblit/$(date +%Y%m%d) mkdir -p $BACKUP_DIR rsync -av --delete /opt/gitblit/data/git/ $BACKUP_DIR/git/ cp /opt/gitblit/data/gitblit.properties $BACKUP_DIR/ cp /opt/gitblit/data/users.conf $BACKUP_DIR/ # 保留最近 7 天 find /backup/gitblit -maxdepth 1 -type d -mtime +7 -exec rm -rf {} \;

这个脚本没什么技术含量，但关键时刻能救命。我见过一次因为误删仓库目录导致整个团队一天工作白干的情况，从那以后备份脚本就成了标配。

3.4 邮件通知和 Web 钩子的最小配置

gitblit 支持在推送时发邮件通知，也支持调用 Web 钩子。邮件配置在gitblit.properties里：

# 开启邮件通知 mail.server = smtp.example.com mail.port = 25 mail.username = gitblit@example.com mail.password = 你的密码 mail.fromAddress = gitblit@example.com # 开启推送通知 mail.notificationEnabled = true

Web 钩子则在仓库设置里配，填一个 URL，推送时会发 POST 请求过去。这个功能适合对接内部的 CI 系统或者消息机器人。不过要注意，1.9.3 的钩子是同步调用的，如果目标 URL 响应慢，会拖慢推送速度，所以目标服务最好做异步处理。

4. 避坑指南：gitblit-1.9.3 部署里最容易翻车的五个点

4.1 启动报错 "Unsupported major.minor version"

现象：执行java -jar gitblit.jar直接抛异常，提示 class 文件版本不支持。

原因：你用的 JDK 版本和 gitblit 编译时的版本不匹配。1.9.3 是用 JDK 8 编译的，如果你用 JDK 17 跑，某些依赖库会报这个错。

解决：换 JDK 8 或 11。如果服务器上必须用高版本 JDK，可以用--add-opens参数临时绕过部分反射限制，但不保证所有功能正常。最稳的做法还是装一个 JDK 11 专门给它用。

4.2 Web 界面能打开但克隆地址是 localhost

现象：登录后进仓库页面，显示的克隆 URL 是http://localhost:8080/xxx.git，别人复制过去用不了。

原因：web.canonicalUrl没改，默认值就是 localhost。

解决：改成实际 IP 或域名，然后重启服务。改完如果还不生效，清一下浏览器缓存，因为页面可能被缓存了。

4.3 SSH 克隆提示 "Host key verification failed"

现象：第一次用 SSH 克隆时，命令行提示主机密钥验证失败。

原因：SSH 客户端不认识这台服务器的密钥，需要手动确认一次。

解决：执行ssh -p 29418 admin@你的IP，会提示是否信任，输入 yes 即可。如果还是不行，检查data/ssh/下的密钥文件是否存在，权限是否是 600。

4.4 推送大文件时超时或 413 错误

现象：推送一个几百 MB 的仓库时，中途断开，或者报 HTTP 413。

原因：gitblit 默认对 HTTP 请求体大小有限制，而且反向代理（如果有）也可能有独立限制。

解决：在gitblit.properties里调大web.maxUploadSize，默认好像是 100MB 左右，改成你需要的值。如果前面有 Nginx，还要改client_max_body_size。

# 调大上传限制，单位字节 web.maxUploadSize = 1073741824

4.5 服务跑一段时间后内存溢出

现象：运行几天后服务无响应，日志里出现OutOfMemoryError。

原因：默认 JVM 堆内存可能不够，尤其是仓库多、访问频繁的时候。

解决：在启动脚本里显式设置-Xmx和-Xms，比如-Xmx1024m -Xms512m。同时检查是不是有仓库特别大导致内存占用高，必要时把大仓库单独迁移到别的实例。

5. 进阶技巧：让 gitblit-1.9.3 在内网环境里更好用

5.1 用反向代理加 HTTPS 和域名

内网环境里直接暴露 8080 端口不太优雅，用 Nginx 做一层反向代理，顺便把 HTTPS 加上，是更常见的做法。配置大概是这样：

server { listen 443 ssl; server_name git.internal.example.com; ssl_certificate /etc/nginx/cert/git.crt; ssl_certificate_key /etc/nginx/cert/git.key; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 大文件推送需要调大超时 proxy_read_timeout 300s; proxy_send_timeout 300s; } }

配完之后记得把web.canonicalUrl改成https://git.internal.example.com，否则克隆地址还是不对。另外proxy_read_timeout一定要调大，默认 60 秒对于大仓库推送来说太短了。

5.2 用 API 做自动化仓库创建

gitblit 提供了一套 REST API，可以用脚本批量建仓库、加用户。比如创建一个仓库：

# 用 admin 账号调 API 创建仓库 curl -u admin:密码 -X POST \ "http://192.168.1.100:8080/rpc?req=CREATE_REPOSITORY" \ -d "name=auto-created-repo" \ -d "description=通过API创建"

这个接口在自动化流程里很有用，比如新项目立项时自动建仓库并分配权限。不过要注意，API 的认证方式和 Web 界面一样，密码别硬编码在脚本里，用环境变量传。

5.3 监控与日志轮转

gitblit 的日志默认写在logs/gitblit.log，时间长了会很大。用 logrotate 做一下轮转：

/opt/gitblit/logs/gitblit.log { daily rotate 7 compress missingok notifempty copytruncate }

copytruncate这个选项很重要，因为 gitblit 不会自己重新打开日志文件，用 copytruncate 可以避免重启服务。

监控方面，最简单的办法是定时请求一下 Web 首页，看返回码是不是 200。如果要更细，可以解析日志里的异常关键字，超过阈值就告警。

5.4 一个我坚持了三年的习惯

每次部署完 gitblit，我都会做一件事：把data/gitblit.properties里所有改过的项单独记一个 diff 文件，和部署脚本放在一起。原因是有一次服务器迁移，我直接拷了 data 目录过去，结果新机器上服务起不来，排查了半天才发现是某个配置项里写死了旧机器的路径。从那以后，配置变更必须留痕，这比任何文档都管用。

gitblit-1.9.3 不是什么新潮的东西，但它在内网自托管这个场景里足够稳、足够简单。把上面这些配好，跑个几年问题不大。希望帮到你。

本文还有配套的精品资源，点击获取

gitblit-1.9.3 内网自托管 Git 服务部署与权限配置实战