简介Gitblit 1.9.3 是一款面向开发团队与个人开发者的开源 Git 仓库管理工具安装包适合需要自建轻量级 Git 服务、实现仓库集中管理与细粒度权限控制的场景。该版本以 Java 编写既可独立运行也可嵌入现有 Java Web 应用能够覆盖仓库创建、克隆、推送、拉取及用户组权限分配等日常版本控制需求。资源共 321 个文件约 41.31MB包含 75 个 jar 运行库、可执行 cmd 脚本、conf 配置文件、groovy 扩展脚本以及用于 Web 管理界面的 html、js、css 与 png 等前端资源解压后可按官方文档完成安装与 SMTP、访问权限等配置。已有 347 人下载学习适合正在选型或部署 Git 服务、希望快速搭建团队协作环境的开发者参考使用。 公司里要搭一套内部代码仓库我第一个想到的不是GitLab而是GitBlit 1.9.3。这版本我前后用了三年多从几个人小团队一直撑到几十人并行开发没出过大乱子。今天就把这个版本从部署、配置、权限到“internal error”排查的完整经验写出来给正准备选型或者已经在踩坑的朋友一个参考。GitBlit是个纯Java写的Git仓库托管工具自带Web界面、HTTP/SSH访问、权限管理和内置Git服务一个jar包就能跑。相比GitLab那套动辄几个G内存的庞然大物GitBlit轻得感人512M内存的旧机器都能流畅带起来。1.9.3是2018年前后的稳定版本基于JGit实现不依赖外部Git二进制部署方式极其简单要么直接跑jar要么扔进Tomcat当war包。适合的场景很明确中小团队内部代码托管、个人多设备同步仓库、需要快速上手的Git服务端以及不想折腾复杂运维的环境。1. 为什么选GitBlit一个被低估的轻量方案1.1 GitBlit到底解决了什么问题先说痛点。团队没代码仓库之前代码靠U盘拷贝、网盘传zip、QQ文件发送版本混乱到怀疑人生。搭GitLab一台2G内存的小服务器光是跑GitLab全家桶就已经喘不过气了更别提它那套复杂的Omnibus配置和频繁升级带来的兼容性问题。用GiteaGo语言写的是挺快但当时版本还不够成熟权限模型相对简单某些场景下分支保护不够灵活。GitBlit正好卡在中间。它本身是一个完整的Git服务器实现内置了JGit也就是说从接收push/pull请求到管理仓库元数据全程不需要系统层面安装Git。这在我当时那台CentOS 7旧服务器上非常省心省掉了安装Git、配置用户、管理SSH key这类步骤。而且它自带一套还不错的Web UI代码浏览、提交历史、分支对比、在线编辑都支持团队成员不用额外装客户端就能看代码、提PR合并请求。1.2 1.9.3这个版本的定位GitBlit从2012年发布1.0开始迭代速度并不快但胜在稳定。1.9.3之前有几个版本在LDAP集成和SSH服务上有一些偶发问题而1.9.3恰好把SSH服务、HTTP认证、Groovy hook这些核心模块打磨得比较圆润是很多生产环境长期使用的版本。它的核心组件包括内置Git Daemon支持Git原生协议访问局域网内走git://非常快HTTP/HTTPS服务基于Jetty开箱即用支持Basic和Form两种认证方式SSH服务内置Apache Mina SSHD支持公钥认证和SSH命令操作Web管理界面仓库管理、用户管理、权限分配、在线代码浏览Groovy Hook脚本实现提交通知、CI触发、仓库事件处理LDAP/Active Directory集成对接企业账号体系这些能力对中小团队来说完全够用。1.9.3不需要额外装Redis、PostgreSQL、Nginx这些外围组件一个JVM进程干完所有事。我的生产环境直接一台1核1G的云服务器跑了GitBlit、定时备份任务、还有一个小型静态站点内存常年保持在700M上下。2. 部署环境准备与安装踩坑2.1 基础环境JDK选型是重中之重GitBlit基于JavaJDK版本直接决定了你能不能跑起来。1.9.3官方推荐Java 8这很关键。我自己一开始图省事装了个Java 11结果Web界面能打开但SSH服务的某些加密算法报错Groovy脚本在执行时也频繁触发“internal error”。后来一问JGit在Java 9模块化之后对反射访问限制变严了导致部分底层操作异常。所以装JDK这一步别省。CentOS上直接用openjdk-8sudo yum install -y java-1.8.0-openjdk java -version确认输出里有1.8.0_xxx就行。如果系统里同时装了别的JDK版本记得通过alternatives --config java把默认JDK切到8不然启动脚本会用到错误的Java。Windows环境类似建议装JDK 8u202或更早的1.8版本因为JDK 8后续版本u211改了许可协议虽然功能上没影响但公司环境还是用开源的OpenJDK 8更省事。2.2 两种运行方式独立模式与WAR部署GitBlit官方提供了两种部署方式我在不同环境都试过。独立模式最推荐下载gitblit-1.9.3.tar.gz解压后目录结构如下gitblit.jar主程序gitblit.properties配置文件web.xmlWeb容器配置data/数据目录仓库、用户、配置都在这里logs/日志目录docs/文档启动命令cd /opt/gitblit java -jar gitblit.jar --baseFolder data默认监听8080端口HTTP和8443端口HTTPS。用--baseFolder参数指定数据目录这个很重要后续升级只要备份这个目录就够。WAR模式把gitblit-1.9.3.war丢进Tomcat的webapps目录适合已经有Tomcat基础设施的团队。但WAR模式下日志输出、data目录位置和独立模式有些差异配置起来不如独立模式直观我不太推荐新手折腾。除非公司已有统一的Tomcat运维体系否则直接用独立模式最省心。2.3 初始化配置的核心参数首次启动后用浏览器打开http://服务器IP:8080默认管理员账号是admin密码admin。登录后第一件事就是改密码这是所有用GitBlit的人最容易忽略的安全隐患。随后打开gitblit.properties配置文件有几个参数必须先调# 服务器地址与端口 server.httpPort8080 server.httpsPort8443 server.hostnamegit.internal.company.com # 数据目录和Git仓库根目录 git.repositoriesFolder${baseFolder}/git # 允许通过HTTPS创建仓库 web.enableRpcManagementtrue web.enableRpcAdministrationtrue改配置后重启GitBlitpkill -f gitblit.jar java -jar gitblit.jar --baseFolder data /var/log/gitblit.log 21 这里有个容易踩的坑修改server.hostname后如果客户端clone仓库时用的是IP地址而不是域名会导致Web界面里的克隆地址显示成错误的主机名。建议一开始就想清楚用IP还是域名保持配置和实际访问方式一致。3. 配置、权限与日常管理实战3.1 gitblit.properties关键项逐条解读这个配置文件是GitBlit的中枢每一项都值得认真看。我按实战顺序挑几个重点说。# HTTPS证书配置 server.storePath${baseFolder}/keystore server.storePasswordchangeitGitBlit默认带了一个自签名证书用于8443端口的HTTPS。如果团队内部不强制HTTPS用HTTP跑内网问题不大。但如果有跨公网访问的需求建议配个正规证书。用keytool生成自签名证书也行步骤不复杂搜索一下就有。# 用户认证方式 realm.userServicecom.gitblit.FileUserService realm.fileusers.conf realm.ldap...默认情况下用户信息存在data/users.conf文件里。几十个人的团队用文件够用。规模再往上可以考虑接LDAPGitBlit对AD和OpenLDAP都支持得不错配置大概二十多行主要是设服务器地址、baseDN、绑定账号。# 邮件通知 mail.hostsmtp.company.com mail.port25 mail.fromgitcompany.com mail.username mail.password配置好SMTP后提交推送、合并请求、权限变更都会自动发邮件团队成员能第一时间知道动态。这个功能我强烈建议开启省去了天天问“你推到哪了”的麻烦。3.2 用户、团队、仓库三层权限模型GitBlit的权限模型分成三层设计得简洁清晰用熟了之后感觉很顺手。用户User最基础的账号单元绑定用户名、密码、邮箱、SSH公钥团队Team一组用户的集合可以统一授权比如“前端组”“后端组”仓库Repository真正的权限被授权对象每个仓库可以设置查看允许浏览代码、克隆克隆/拉取可读权限推送可写权限创建分支是否需要审核删除分支是否需要审核这里我给一个建议不要让普通用户拥有仓库的“创建”权限而是由管理员统一建仓仓库命名规范从一开始就定好。比如前端项目统一web/xxx后端统一api/xxx服务端统一svc/xxx。用web.enableRpcManagementtrue时用户在Web界面可以自助创建仓库但如果权限控制不严第二天就能看到一堆test1、test2、ceshi这种仓库乱成一锅粥。我实际管理的团队规模约30人权限矩阵大概是角色权限开发工程师查看、克隆、推送到自己负责的仓库技术Leader在其负责项目的仓库中额外拥有分支管理和合并权限管理员全部权限包括用户管理、仓库删除、配置修改实习生/外部协作者只读权限这个矩阵不是一上来就配好的而是跑了两周之后逐渐调整出来的。GitBlit调整权限非常灵活修改当天就生效不需要重启。3.3 HTTP与SSH双通道使用细节GitBlit同时支持HTTP(S)和SSH两种协议访问仓库。HTTP方式最简单clone地址直接填http://git.internal.company.com/git/项目名.git认证时输入用户名密码。这种方式适合临时、跨网络、不方便配SSH key的场景。SSH方式更推荐日常命令行使用。GitBlit的SSH端口默认是29418不是标准的22因为很多服务器22端口被系统SSH占了。需要在gitblit.properties里确认git.sshPort29418 git.sshBindInterface0.0.0.0客户端使用前先在Web界面右上角“账号”里上传自己的SSH公钥。然后就可以用git clone ssh://gitgit.internal.company.com:29418/项目名.git注意这里的用户名是git不是你的GitBlit用户名。GitBlit的SSH服务和系统SSH是两个完全独立的体系它通过公钥来识别你是哪个用户所以公钥必须上传否则连接会被拒绝。之前见过不少人卡在这一步连不上SSH就以为是防火墙问题。其实只要把公钥传上去用ssh -p 29418 gitgit.internal.company.com命令测试输出Welcome相关信息就说明通了。4. “internal error”高频场景与排查实录说到gitblit internal error这个词组是GitBlit用户搜索量最大的一个词也是我踩坑最多的地方。GitBlit的“internal error”是一个非常泛化的错误意思是服务器内部异常但无法直接识别具体原因。这个报错一旦出现Web界面操作、Git推送、SSH连接都可能断排查起来非常考验经验。4.1 错误长什么样Web界面显示一个模糊的500页面大标题写着An internal error occurred during: 某个操作。仓库列表可能还能打开但一进某个具体仓库的页面就报错或者push代码时直接超时。这种模糊报错的好处是不暴露系统底层细节但对管理员很不友好。好在GitBlit把详细日志都写在logs/gitblit.log里排查第一步永远是打开这个日志看异常堆栈。tail -n 100 /opt/gitblit/logs/gitblit.log4.2 案例一JDK版本不兼容这是最高频的“internal error”诱因。现象是GitBlit能启动Web首页也能打开但一操作就跟资源库相关的功能比如打开提交历史、查看diff就报错。日志里常见的关键字是UnsupportedClassVersionError或NoSuchMethodError。遇到这个我第一个念头就是去查Java版本。java -version如果输出不是1.8立刻安装OpenJDK 8并切换默认版本。这个操作在10分钟内解决了我两次“internal error”一次是Java 11环境一次是误装了Java 17。4.3 案例二JVM内存配置不足另一个经典场景是大仓库或者并发操作多的时候出现OutOfMemoryError。GitBlit默认JVM堆内存比较小如果仓库里塞了好几个G的二进制文件跑索引和diff时很容易爆内存。日志里会看到java.lang.OutOfMemoryError: Java heap space解决方法是修改启动脚本给JVM分配更多内存java -Xms256m -Xmx1024m -jar gitblit.jar --baseFolder data我用的是1G内存的服务器-Xmx1024m刚好不超物理内存。内存稍大的机器可以对称设置。注意-Xms和-Xmx最好设置成一样的值避免JVM动态扩展堆导致的性能抖动。顺便提一句如果仓库里存了大量图片、压缩包这种二进制文件GitBlit的Diff功能会变得很卡。最好的办法是强制大家不要把二进制大文件提交进Git仓库用Git LFS或者专门的制品库如Nexus来管。GitBlit的Web界面在展示二进制diff时也是空白或者报错这不一定是故障。4.4 案例三数据库/配置文件格式问题GitBlit默认使用内置的Derby数据库存储用户和权限信息数据库文件在data/derby目录下。如果服务器突然掉电或者data目录权限不对Derby数据库可能损坏引发internal error。日志中如果出现java.sql.SQLException: Failed to start database gitblit那就是数据库坏了。此时先别急着删数据把data目录做一份完整备份然后尝试从最新的备份恢复。如果没做备份可以用Derby自带的恢复模式尝试但成功率一般。更好的办法是提前把数据目录做成定时快照我在cron里加了每天凌晨打包0 2 * * * tar czf /backup/gitblit-$(date \%w).tar.gz /opt/gitblit/data保留七天的滚动备份出问题能恢复最多一周内的数据。这个习惯救过我一次有次服务器磁盘满导致Derby写入异常就是从备份恢复的。另外手动编辑users.conf或gitblit.properties时一定要用UTF-8编码保存别用Windows记事本默认的ANSI。文件里如果有中文字符编码不对会导致解析失败GitBlit启动时可能直接抛出内部错误。4.5 排查工具与方法当“internal error”出现时按顺序做这几步打开logs/gitblit.log找最近的ERROR或Exception关键字定位到第一个Caused by行那就是根本原因如果是ClassNotFound、UnsupportedClassVersionError查JDK版本如果是IndexOutOfBounds、NullPointerException多半是某个仓库的元数据损坏尝试通过GitBlit Web界面“编辑仓库”里的“GC/清理”操作修复如果是数据库异常看data/derby目录有没有坏文件从备份恢复如果什么都查不到把日志最后200行贴到GitBlit的GitHub Issues里搜相同关键字通常有人遇到过GitBlit自带的com.gitblit.GitBlit命令还提供了一些辅助子命令比如java -cp gitblit.jar com.gitblit.GitBlit --baseFolder data --exportUsers java -cp gitblit.jar com.gitblit.GitBlit --baseFolder data --reload不过实际操作中我用的最多还是“备份-重启-看日志”三板斧。GitBlit进程本身异常稳定真正需要重启的场景一年也没几次。5. 经验补充与长期维护心得部署GitBlit只是一个开始长期维护才是重点。我把自己实际用出来的经验整理一下给准备上生产的朋友参考。备份策略data目录是整个GitBlit的命根子包含所有仓库、用户、权限配置。光复制仓库目录git文件夹不够因为权限和用户信息在Derby数据库里。我现在的备份策略是每天凌晨2点打包整个data目录保留14天再每周异地同步一次。加上Git仓库本身有完整历史恢复成本其实很低。升级注意事项GitBlit版本升级要谨慎尤其是大版本跨越。我在1.8.x升1.9.3时没遇到问题但从1.9.x往2.x升时配置格式有变化需要仔细读官方迁移文档。升级前一定先备份然后在一台测试机上跑通再动生产。GitBlit社区不算特别活跃遇到冷门问题的参考资料相对少所以生产环境不要盲目追求新版本。HTTPS的坑如果公司设置了上网代理客户端走HTTP克隆时可能会被代理拦截表现为下载一半报错。这时候要么配置代理白名单要么直接改用SSH端口连接。GitBlit的HTTP服务虽然方便但公网环境下不如SSH稳定。服务化配置用nohup启动Java进程只是临时方案。要想崩了自动拉起最好用systemd管理我用的unit文件很简单[Unit] DescriptionGitBlit Git Server Afternetwork.target [Service] Typesimple Usergitblit ExecStart/usr/bin/java -Xms256m -Xmx1024m -jar /opt/gitblit/gitblit.jar --baseFolder /opt/gitblit/data Restarton-failure RestartSec10 [Install] WantedBymulti-user.target这样进程挂了10秒后自动重启省心很多。最后补一句GitBlit自带的Web界面虽然古早但实用功能一个不少代码搜索、在线编辑、提交对比、分支合并请求都能操作。对于不熟悉命令行的同事来说Web界面基本能覆盖90%的日常需求团队上手成本极低。我个人用下来的感受是GitBlit更像一个“开箱即用的内部Git服务器”它不追求功能多到眼花缭乱而是把该有的基础功能做得稳固。如果你的团队也是几十人规模预算有限、运维资源紧张GitBlit 1.9.3值得一试。本文还有配套的精品资源点击获取