简介Gitblit 是一款基于 Java 的开源 Git 仓库管理工具1.9.3 为稳定版本。它面向需要快速搭建内部 Git 服务的中小型团队或个人开发者提供仓库创建、克隆、推送、拉取以及精细的访问权限控制相比命令行或复杂平台更加轻量易用。资源包为 RAR 压缩包共 321 个文件大小约 41.31MB。其中 75 个 jar 文件构成运行核心35 个 html、24 个 js、23 个 css 是内置 Web 管理界面另有 groovy 脚本、Windows 下的 cmd/exe 服务安装卸载脚本及若干配置文件基本覆盖了在 Windows 环境部署日常维护所需内容。资源目前已有 352 人学习。解压后可按官方文档配置仓库存储位置、用户权限和邮件通知利用其用户组和角色机制为不同团队分配读写权限。对于希望减少维护成本、又需要稳定 Git 托管环境的用户这套包可直接作为本地或局域网内版本控制服务的起点。1. Gitblit 1.9.3自带 Web 管理的轻量 Git 服务器一个人也能玩转如果你在一个小团队里维护代码既不想搭一台完整的 GitLab又嫌裸 Gitolite 的权限配置太绕Gitblit 1.9.3 是最省事的那一类选择。它就是一个 Java 写的 Git 服务器自带 Web 管理界面仓库、用户、权限、推送钩子都能在浏览器里点出来不需要额外装数据库。部署完大概半小时内能跑通Windows 和 Linux 都能跑仓库默认存在本地目录真实场景下它还能扛住几十人规模的日常推送。这篇笔记我会从安装讲到服务化再把重启和迁移这些运维细节一次说清适合正在选型或已经在用 Gitblit 但没时间翻文档的人。2. 安装与启动JDK 环境、目录结构与首次配置2.1 下载之前先确认 Java 版本Gitblit 1.9.3 是基于 Java 的 Web 应用底层跑的是内嵌的 Jetty所以在解压之前先确认机器上的 JDK 版本。1.9.3 要求 Java 8 及以上实际我建议直接用 JDK 11 或 JDK 17我在这两个版本上都跑过没遇到过兼容性问题。JDK 8 也能跑但如果你机器上同时有多个 Java 版本启动脚本会去读 JAVA_HOME 环境变量这一步别偷懒。# Linux / macOS 下确认 Java 版本 java -version # 如果没有设置过 JAVA_HOME在 /etc/profile 里补上 export JAVA_HOME/usr/lib/jvm/java-11-openjdk-amd64 export PATH$JAVA_HOME/bin:$PATH环境变量配好之后用java -version能输出openjdk version 11.x说明环境没问题。Windows 用户在系统设置里加 JAVA_HOME 指向 JDK 安装目录即可路径里不要带空格比如C:\Program Files\Java这种路径会让某些启动脚本解析出错我一般把 JDK 解压到C:\jdk11这种短路径下。2.2 解压、建数据目录、启动服务下载 gitblit-1.9.3 压缩包后解压到的目录就是程序目录。Gitblit 默认会把配置和仓库数据放在用户目录下的.gitblit文件夹里但生产环境我建议把数据目录显式指出来方便做备份。常见做法是在解压目录下建一个data文件夹然后在配置里指定。# 以 Linux 为例 mkdir -p /opt/gitblit tar -zxvf gitblit-1.9.3.tar.gz -C /opt/gitblit --strip-components1 cd /opt/gitblit mkdir -p dataWindows 下直接解压到D:\gitblit同样建一个data文件夹。接下来启动服务Windows 用gitblit.batLinux 用gitblit.sh。第一次启动时Gitblit 会在 data 目录下生成一套完整的配置文件和默认仓库。# Linux 前台启动方便观察日志 cd /opt/gitblit ./gitblit.sh --baseFolder data--baseFolder参数指定数据目录这是整个部署里最关键的参数。启动后控制台会输出 Jetty 启动信息默认监听 8080HTTP和 8443HTTPS两个端口。打开浏览器访问http://服务器IP:8080就能看到 Gitblit 的登录页默认管理员账号是 admin密码也是 admin首次登录会强制要求修改密码。2.3 gitblit.properties 里哪些参数值得改数据目录生成后data/gitblit.properties就是主配置文件。不需要全读先改这几项就够用参数默认值说明git.repositoriesFolder${baseFolder}/git裸仓库存放根目录web.httpPort8080HTTP 端口web.httpsPort8443HTTPS 端口server.httpsBindInterface留空绑定 HTTPS 的网卡地址git.sshPort29418SSH 端口克隆地址会用到web.forceHttpfalse置为 true 时强制使用 HTTP 访问改完配置后重启 Gitblit才会生效。这里我踩过一次坑把git.repositoriesFolder改到了其他磁盘路径但忘了给那个目录写权限结果启动成功、创建仓库时报错。所以路径权限一定要先确认Linux 下常见做法是让启动用户拥有目标目录的所有权或者把目录 chmod 755。3. 仓库、用户与权限把团队协作规则落到 Gitblit 上3.1 创建仓库的两种方式界面操作和命令行登录管理员账号后在「版本库」页面点击「创建版本库」填写名称和描述就能建仓库。Gitblit 默认创建的是裸仓库bare repository适合做服务器端存储。仓库名称建议用团队名/项目名的格式例如devops/deploy-script这样在 SSH 地址里一眼能看出归属。如果仓库数量较多或者需要脚本化批量创建也可以用命令行调 Gitblit 的 REST API# 用管理员账号通过 API 创建仓库 curl -u admin:你的密码 \ -X POST http://localhost:8080/api/1.0/create/repositories/devops/deploy-script?namedeploy-scriptdescriptiondeployment%20scripts注意提交 JSON 或表单参数时仓库路径以斜杠分隔create/repositories后面的路径就是仓库名。API 方式创建仓库适合初始化大批库时用但日常管理我还是推荐界面操作毕竟合并请求、分支权限这些配置在页面上更直观。3.2 用户、团队和权限模型Gitblit 的权限模型分三层用户user、团队team、仓库权限repository permission。比起直接给每个用户单配权限我一般先建团队再把用户拉进团队里。比如建一个developers团队仓库权限设为「RW」建一个viewers团队权限设为「R」。用户加入团队后自动继承对应权限。仓库权限有四种查看R、克隆RW、推送RW、管理RW 且能改仓库设置。实际使用中「克隆」和「推送」常常会被误解有人觉得能克隆就能推送其实在 Gitblit 里这是两个权限级别。如果用户只能克隆不能推送客户端 push 时会提示deny updating a hidden ref或者403这点后面排查章节会展开。3.3 分支权限与推送规则Gitblit 1.9.3 支持按分支做精细控制。在仓库设置页的「分支」标签里可以把master、main或release/*这样的分支设为「禁止强制推送」或「仅团队管理员可推送」。这套规则对生产分支保护很有效防止有人手滑git push --force把历史推没了。配置格式是一个列表每行一条匹配规则refs/heads/master RW 团队名 refs/heads/release/** R 团队成员名 refs/heads/feature/** RW 团队成员名R表示只读RW表示能推送新分支但不能强推RW表示允许强制推送。这个文件改动后立即生效不需要重启服务。我通常会把master分支设为仅管理员 RW普通开发者只有 R配合代码评审流程问题会少很多。4. 常见问题排查端口、中文乱码与权限失效4.1 8443 端口起不来不是 Gitblit 的问题现象启动时日志没有报错但浏览器访问https://IP:8443一直超时HTTP 的 8080 端口正常。原因8443 端口被其他服务占用或者防火墙没放行。最常见的是公司服务器上已有其他 Web 服务占用了 8443。还有一次我发现是本机开了虚拟机网络端口被虚拟网卡进程占用。解决先用netstat -ano | findstr 8443Windows或lsof -i:8443Linux看占用情况。确认被占就改web.httpsPort比如改成 8444然后重启 Gitblit。改端口后克隆地址里的端口也会跟着变页面上会自动更新不用担心。另外如果只在内网用直接把 https 停了也行把web.httpsPort设成 0 就能禁用 HTTPS。4.2 登录后中文仓库名显示乱码现象仓库名含中文时网页下拉框正常但 Git 客户端克隆下来的文件夹名变成一串%E6%9F%90之类的字符。原因Git 默认对非 ASCII 路径做百分号编码仓库目录里存的中文名其实没乱是客户端显示的问题。还有一种情况是仓库描述里的中文在 Windows 启动的服务下乱码那是文件编码问题。解决客户端设置git config --global core.quotepath false路径里的中文就能正常显示。Gitblit 服务端这边保持默认 UTF-8 编码配置文件里不要手动改成 GBK否则描述文字会变乱码。Windows 服务器上如果日志乱码在启动脚本gitblit.bat里加一行set JAVA_TOOL_OPTIONS-Dfile.encodingUTF-8再重启。从那以后我部署 Gitblit 时第一件事就是把这个参数写进启动脚本。4.3 用户能克隆但推不上去权限等级没给够现象团队成员git push时报remote: error: cannot update repo或者直接被拒绝。原因用户在仓库权限里被设成了「R」只能克隆不能推送。或者用户所在的团队权限是「RW」但他想要推送的新分支不在允许路径里。解决到仓库设置页把该用户的权限改为「RW」或「RW」。如果仓库启用了分支保护规则检查refs/heads/feature/**这类通配是否覆盖了用户要推送的分支。通配符按路径匹配feature/**不会匹配feature本身所以分支命名要规范别一会儿feature-001一会儿feature/001。4.4 重启后配置变回默认数据目录指错了现象改了gitblit.properties里的端口重启后端口又变回 8080。原因启动脚本没有带--baseFolder data参数Gitblit 默认去读~/.gitblit下的配置你改的是data目录下的另一份配置。解决确认启动命令带上了--baseFolder或者在gitblit.properties头部把baseFolder这个变量直接写死。Windows 服务方式启动时服务安装脚本里也要传参否则服务默认不带。这个坑隐藏得很深我当时排查了很久最后看进程启动参数才发现是目录指歪了。4.5 服务起来了但页面打不开本机回环地址问题现象在服务器本机用localhost:8080能打开页面远程访问却打不开。原因web.bindInterface默认绑定的是本机回环地址或者网卡绑定的 IP 不对。解决把web.bindInterface设为0.0.0.0代表监听所有网卡。改完重启后再用http://服务器IP:8080访问。这一步在云服务器上尤其容易踩因为云主机一般有好几个虚拟网卡。5. 重启与服务化开机自启、日志定位和状态管理5.1 前台启动与后台运行的差别开发环境前台启动没问题但生产环境一旦关闭 SSH 窗口Gitblit 进程就跟着退了。这个问题被称为 Gitblit 重启后的第一大坑——重启服务器后服务不见了或者关窗口后服务直接停止。Linux 上要想让进程后台跑很多人会写nohup ./gitblit.sh 但这样拿不到进程管理能力重启后还要手动拉起来不省心。我推荐用 systemd 管理。在/etc/systemd/system/gitblit.service写一个服务文件把启动和停止交给系统管。[Unit] DescriptionGitblit Git Server Afternetwork.target [Service] Typeforking Usergitblit Groupgitblit EnvironmentJAVA_HOME/usr/lib/jvm/java-11-openjdk-amd64 ExecStart/opt/gitblit/gitblit.sh --baseFolder /opt/gitblit/data Restarton-failure [Install] WantedBymulti-user.targetTypeforking 是因为 gitblit.sh 内部会通过 nohup 把 Java 进程转成后台进程服务管理器拿到的是启动脚本的退出状态。如果启动失败Restarton-failure会在 10 秒后重试拉起这个机制帮我挡住过几次因为内存不足导致的进程崩溃。5.2 常见重启操作service 与 systemctl依靠 systemd 服务文件状态查看、重启、开机自启都标准化了# 重新读取服务文件改过 service 文件后必须执行 sudo systemctl daemon-reload # 启动、停止、查看状态 sudo systemctl start gitblit sudo systemctl stop gitblit sudo systemctl status gitblit # 设置开机自启 sudo systemctl enable gitblit每次升级配置或替换 jar 包后要重启 Gitblit执行sudo systemctl restart gitblit就够了。重启前先确认进程真的在跑再用tail -n 50 /opt/gitblit/data/logs/gitblit.log看日志尾部。日志文件路径在配置里由logs.folder指定默认就在数据目录下的 logs 文件夹里。Windows 服务器上的做法是用 Gitblit 自带的service.bat安装 Windows 服务。以管理员身份打开 cmd进入解压目录后执行service.bat install安装完成后在 Windows 服务管理里能找到一个叫 Gitblit 的服务设为自动启动即可。卸载服务执行service.bat uninstall。Windows 服务方式下日志同样写到 data/logs 目录但要以「服务账户」的权限对 data 目录有读写权否则服务起后创建不了仓库。5.3 重启失败时看什么三步定位法Gitblit 重启失败时别急着反复点启动。我一般按这个顺序查先看日志再看端口最后看权限。# 第一步日志尾部通常有明确异常堆栈 tail -n 100 /opt/gitblit/data/logs/gitblit.log # 第二步确认端口被占用 lsof -i:8080 -i:8443 # 第三步确认数据目录权限 ls -ld /opt/gitblit/data /opt/gitblit/data/git日志里如果出现java.net.BindException: Address already in use就是端口冲突把旧的 Gitblit 进程杀掉再重启。如果出现Exception opening socket多半是权限或防火墙问题检查端口放行规则。还有一次日志里全是OutOfMemoryError那是 JVM 内存不够在gitblit.sh里调整-Xmx参数比如改成-Xmx512m或-Xmx1g加到 JAVA_OPTS 里即可。从那以后我每次改完配置重启前都会先看一眼日志尾部不急着点启动按钮这个习惯已经救了很多次场。6. 进阶技巧HTTPS 证书、备份迁移与钩子实践6.1 用自签证书支起 HTTPS 访问默认情况下 Gitblit 的 HTTPS 端口只提供自签证书浏览器会报不安全警告。内网用可以忽略但如果要接外部工具或让客户端不弹警告可以用keytool生成一张自签证书并导入 Gitblit 的证书库。Gitblit 的 HTTPS 配置在gitblit.properties里的keystore相关项生成证书时注意 CN 填服务器的域名或 IP并且把证书密码写进web.httpsKeystorePassword。keytool -genkey -alias gitblit -keyalg RSA \ -keystore /opt/gitblit/data/gitblit.jks -storetype JCEKS \ -dname CNgit.example.com -validity 3650生成完在配置里指到该文件重启后 Gitblit 就用自己的证书走 HTTPS 了。这个操作对团队内部用很实用克隆地址变成https://git.example.com:8443/...后客户端不再需要频繁点「继续访问」。如果是内网工具链要拉代码建议再把这个自签证书导入到各客户端的信任库免去SSL certificate problem的报错。6.2 备份迁移整个 data 目录就是后悔药Gitblit 的仓库、用户、权限、配置全在 data 目录里所以备份非常简单——拷贝 data 目录即可。迁移到新服务器时新机器装好相同的 Gitblit 版本把 data 目录整个复制过去启动后所有仓库和权限原样回来。我通常会同时备份gitblit.properties、git仓库目录和users.conf其中users.conf里存的是用户信息和加密后的密码。# 备份前先停服务保证文件一致性 systemctl stop gitblit tar -czf gitblit-backup-$(date %Y%m%d).tar.gz /opt/gitblit/data systemctl start gitblit迁移后记得检查 SSH 克隆地址因为服务器的 IP 或主机名变了Git 客户端的 remote 地址也要改。这一步没人会替你提醒我曾在迁移后第二天收到同事反馈说推不上去原因就是 remote 还指向老 IP。6.3 用 Groovy 钩子做推送通知Gitblit 1.9.3 自带 Groovy 钩子机制在仓库设置页可以把钩子脚本绑定到某个仓库的推送事件上。比如推送后自动钉钉通知、发邮件或者触发 Jenkins 构建。钩子脚本放在 data/groovy 目录里面已经有一些示例脚本。一个最简单的 post-receive 钩子示例// notify.groovy: 推送完成后输出一条日志 def commitList repository.getRevWalk() logger.info(收到推送仓库: ${repository.name})这段脚本会被 Gitblit 在每次推送完成后执行。通过钩子把代码推送事件接到自动化流程里是 Gitblit 进阶用法里性价比最高的一环它让一个小型 Git 服务器也能具备 GitLab Webhook 的部分能力。1.9.3 的功能边界大概就在这——日常代码托管、权限管理、简单自动化完全够用但别拿它当 GitLab 那样的大型平台去扩展。希望这篇笔记能让你少翻几次logs/gitblit.log也希望你能从 Gitblit 的部署和维护中学到一些通用的运维习惯。我从第一次在 Windows 上被baseFolder整得焦头烂额到现在把 systemd 服务文件写进模板里直接复用经历了大量试错希望这些经验帮你把坑提前填平。Gitblit 1.9.3 不算新但稳定、轻量、配置简单做好备份和服务化管理它能在一台低配服务器上安静跑好几年。本文还有配套的精品资源点击获取