企业官网建设流程全解析

简介：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配置和频繁升级带来的兼容性问题。用Gitea？Go语言写的是挺快，但当时版本还不够成熟，权限模型相对简单，某些场景下分支保护不够灵活。

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基于Java，JDK版本直接决定了你能不能跑起来。1.9.3官方推荐Java 8，这很关键。我自己一开始图省事装了个Java 11，结果Web界面能打开，但SSH服务的某些加密算法报错，Groovy脚本在执行时也频繁触发“internal error”。后来一问，JGit在Java 9+模块化之后对反射访问限制变严了，导致部分底层操作异常。

所以，装JDK这一步别省。CentOS上直接用openjdk-8：

sudo 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.xml：Web容器配置
• 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.httpPort=8080 server.httpsPort=8443 server.hostname=git.internal.company.com # 数据目录和Git仓库根目录 git.repositoriesFolder=${baseFolder}/git # 允许通过HTTPS创建仓库 web.enableRpcManagement=true web.enableRpcAdministration=true

改配置后重启GitBlit：

pkill -f gitblit.jar java -jar gitblit.jar --baseFolder data >> /var/log/gitblit.log 2>&1 &

这里有个容易踩的坑：修改server.hostname后，如果客户端clone仓库时用的是IP地址而不是域名，会导致Web界面里的克隆地址显示成错误的主机名。建议一开始就想清楚用IP还是域名，保持配置和实际访问方式一致。

3. 配置、权限与日常管理实战

3.1 gitblit.properties关键项逐条解读

这个配置文件是GitBlit的中枢，每一项都值得认真看。我按实战顺序挑几个重点说。

# HTTPS证书配置 server.storePath=${baseFolder}/keystore server.storePassword=changeit

GitBlit默认带了一个自签名证书用于8443端口的HTTPS。如果团队内部不强制HTTPS，用HTTP跑内网问题不大。但如果有跨公网访问的需求，建议配个正规证书。用keytool生成自签名证书也行，步骤不复杂，搜索一下就有。

# 用户认证方式 realm.userService=com.gitblit.FileUserService realm.file=users.conf realm.ldap=...

默认情况下用户信息存在data/users.conf文件里。几十个人的团队用文件够用。规模再往上，可以考虑接LDAP，GitBlit对AD和OpenLDAP都支持得不错，配置大概二十多行，主要是设服务器地址、baseDN、绑定账号。

# 邮件通知 mail.host=smtp.company.com mail.port=25 mail.from=git@company.com mail.username= mail.password=

配置好SMTP后，提交推送、合并请求、权限变更都会自动发邮件，团队成员能第一时间知道动态。这个功能我强烈建议开启，省去了天天问“你推到哪了”的麻烦。

3.2 用户、团队、仓库三层权限模型

GitBlit的权限模型分成三层，设计得简洁清晰，用熟了之后感觉很顺手。

• 用户（User）：最基础的账号单元，绑定用户名、密码、邮箱、SSH公钥
• 团队（Team）：一组用户的集合，可以统一授权，比如“前端组”“后端组”
• 仓库（Repository）：真正的权限被授权对象

每个仓库可以设置：

• 查看：允许浏览代码、克隆
• 克隆/拉取：可读权限
• 推送：可写权限
• 创建分支：是否需要审核
• 删除分支：是否需要审核

这里我给一个建议：不要让普通用户拥有仓库的“创建”权限，而是由管理员统一建仓，仓库命名规范从一开始就定好。比如前端项目统一web/xxx，后端统一api/xxx，服务端统一svc/xxx。用web.enableRpcManagement=true时，用户在Web界面可以自助创建仓库，但如果权限控制不严，第二天就能看到一堆test1、test2、ceshi这种仓库，乱成一锅粥。

我实际管理的团队规模约30人，权限矩阵大概是：

这个矩阵不是一上来就配好的，而是跑了两周之后逐渐调整出来的。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.sshPort=29418 git.sshBindInterface=0.0.0.0

客户端使用前，先在Web界面右上角“账号”里上传自己的SSH公钥。然后就可以用：

git clone ssh://git@git.internal.company.com:29418/项目名.git

注意这里的用户名是git，不是你的GitBlit用户名。GitBlit的SSH服务和系统SSH是两个完全独立的体系，它通过公钥来识别你是哪个用户，所以公钥必须上传，否则连接会被拒绝。

之前见过不少人卡在这一步，连不上SSH就以为是防火墙问题。其实只要把公钥传上去，用ssh -p 29418 git@git.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.log

4.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”出现时，按顺序做这几步：

1. 打开logs/gitblit.log，找最近的ERROR或Exception关键字
2. 定位到第一个Caused by行，那就是根本原因
3. 如果是ClassNotFound、UnsupportedClassVersionError，查JDK版本
4. 如果是IndexOutOfBounds、NullPointerException，多半是某个仓库的元数据损坏，尝试通过GitBlit Web界面“编辑仓库”里的“GC/清理”操作修复
5. 如果是数据库异常，看data/derby目录有没有坏文件，从备份恢复
6. 如果什么都查不到，把日志最后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] Description=GitBlit Git Server After=network.target [Service] Type=simple User=gitblit ExecStart=/usr/bin/java -Xms256m -Xmx1024m -jar /opt/gitblit/gitblit.jar --baseFolder /opt/gitblit/data Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target

这样进程挂了10秒后自动重启，省心很多。

最后补一句：GitBlit自带的Web界面虽然古早，但实用功能一个不少，代码搜索、在线编辑、提交对比、分支合并请求都能操作。对于不熟悉命令行的同事来说，Web界面基本能覆盖90%的日常需求，团队上手成本极低。我个人用下来的感受是，GitBlit更像一个“开箱即用的内部Git服务器”，它不追求功能多到眼花缭乱，而是把该有的基础功能做得稳固。如果你的团队也是几十人规模，预算有限、运维资源紧张，GitBlit 1.9.3值得一试。

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