告别GitHub手把手教你用Gitblit在Windows 10上搭建私人局域网Git服务器附SourceTree配置如果你打开GitHub十次有八次在转圈如果你只是想让同办公室的几个同事共享代码、不想把私有仓库暴露到公网如果你不想折腾Linux、不想为了一个小团队就上K8s那套重型全家桶——这篇文章就是给你写的。我花了一个周末时间在Windows 10上把Gitblit完整搭了起来配合SourceTree做日常提交推送运行几个月下来非常稳定。整个过程不复杂真正卡人的地方往往就那几个今天一次说清楚。先说结论Gitblit是一个纯Java编写的轻量级Git服务器单文件包部署自带Web管理界面支持HTTP/HTTPS/SSH协议数据落地在本地文件系统不需要额外装MySQL。对Windows重度用户来说这几乎是零依赖的选择非常适合团队内部使用。下面从选型到踩坑按我实际操作的顺序一步步讲。1. 为什么放着GitHub不用要自己搭一套局域网Git服务器1.1 先搞清楚私人局域网Git服务器到底解决什么问题很多团队最开始用GitHub是因为它开箱即用、生态好PR、Issue、Actions全都内置了。但实际用起来你会遇到几个现实问题。第一私有仓库的限制。GitHub免费版虽然已经支持无限私有仓库但协作者数量是有限制的。超过人数之后就要收费小团队可能觉得无所谓但我就见过老板一看到付费页面就直接说算了。第二代码安全与合规场景。有些公司内部项目、外包项目、甲方交付代码明确要求不能上传到公网平台。这时候你需要的不是一个云服务而是一台自己控制的服务器。第三内网环境的高速协作。局域网内的推送和拉取速度是外网没法比的尤其是仓库里塞了大图片、编译产物这些大文件时体验差距非常明显。一个几GB的仓库在内网走HTTP推送比经过公网快太多了。第四也是最现实的——外网访问的稳定性。GitHub的访问质量你我都懂在办公室拉代码拉到一半断连、网页登录打不开、图标一直转圈这些场景会严重打断开发节奏。注意我这里不讨论任何绕过网络限制的手段只从团队自身可控基础设施的角度来分析。如果你所在团队有完全离线内网或局域网隔离的需求自建Git服务器就是最稳妥的方案。1.2 表面是搭个服务实际上是搭一套团队协作设施自建Git服务器本质上不只是装个软件它涉及四个层面版本库存储代码文件怎么存、路径怎么规划、备份怎么处理。访问控制谁能读、谁能写、仓库管理员怎么分配。传输协议走HTTP、HTTPS还是SSH各有优劣。客户端工具一堆同事不可能都用命令行必须有一个图形化客户端把日常操作封装好。我见过不少人一上来就盯着下载哪个软件纠结结果服务器装好了同事不会用或者权限乱得分分钟能互相覆盖代码。所以这篇文章不只讲Gitblit的部署还会把用户体系、SourceTree客户端配置、日常使用坑点一起串起来讲。1.3 Gitblit、Gitea、GitLab横向对比为什么我选Gitblit在Windows环境上搭Git服务器你绕不开三个主流方案Gitblit、Gitea、GitLab。我当初也纠结过这里给出我当时对比的真实结论。对比项GitblitGiteaGitLab社区版运行环境需要JRE纯Java自包含二进制Go语言需要Ruby环境或Docker是否有数据库依赖无纯文件系统存储默认SQLite可选MySQL/PostgreSQL必须PostgreSQL/MySQLWindows原生支持非常好直接跑bat脚本有Windows exe但中文社区资料偏Linux官方不建议Windows裸装自带Web管理界面有界面朴素但完整有界面现代有功能最全资源占用约200MB内存约100MB内存至少2GB起步内置用户/权限体系完整完整完整PR/MR、CI等功能无复杂的MR偏向轻协作有简单的PR全功能部署难度极低低高我的结论是如果团队只有几个人、核心诉求就是有个地方放代码、能控制权限、能走HTTP方便SourceTree使用Gitblit在Windows上的综合体验是第一名。它不用数据库备份就是复制文件夹配置全部在一个properties文件里改完重启即生效自带用户管理、仓库权限、Web端代码浏览够用且不冗余。如果你需要完整的Merge Request审批流、内置CI/CD流水线Gitea会更合适。但从Windows 10局域网私有Git服务器这个标题的场景来说Gitblit是那个最不折腾的选择。2. 环境准备JDK版本和Git基础组件一个都不能错2.1 先装JDK版本选择直接影响后续稳定性Gitblit是基于Java的Web应用所以第一步是装Java运行环境。这里有个关键决策装JRE还是JDK我直接建议装JDK因为JDK自带JRE而且部分Gitblit功能在完整JDK环境下更不会出幺蛾子。版本选什么Gitblit官网要求Java 8及以上我用的是1.9.3版本搭配Java 1.8.0_202跑的非常稳定。后来试过Java 17也可以运行但Java 8是经过最多人验证的路径没必要为了新版而新版。尤其你后面还要跑SourceTree等一堆开发工具Java 8的兼容性最好。下载JDK之后双击安装路径建议改成C:\Java\jdk1.8.0_202这种没有空格的目录。默认装在C:\Program Files\Java\下面其实也能跑但空格在后续命令行操作中容易引发奇奇怪怪的路径问题能避开就避开。2.2 JAVA_HOME环境变量配置90%的人第一步就错在这里装完JDK后需要配置两个环境变量JAVA_HOME和PATH。右键此电脑→属性→高级系统设置→环境变量在系统变量区域点击新建变量名: JAVA_HOME 变量值: C:\Java\jdk1.8.0_202注意变量值要写到JDK的根目录不是bin目录也不是jre目录。写错了Gitblit启动脚本就找不到Java。然后找到系统变量里的Path变量点击编辑新增一行%JAVA_HOME%\bin这里有一个非常经典的问题如果你安装了多个Java版本Path里的顺序会导致java -version输出不是你预期的版本。Gitblit启动时使用的是JAVA_HOME指定的版本但命令行里java命令用的是Path里第一个找到的Java。所以尽量保证只有一个Java在环境变量里生效或者把%JAVA_HOME%\bin放在Path列表的最前面。配置完后重新打开一个命令行窗口注意必须是新窗口旧窗口读不到新环境变量输入java -version javac -version两个命令都能正常输出版本号就说明环境就绪了。如果提示不是内部或外部命令先别急着重装检查变量值是不是配错了。2.3 Git for Windows到底要不要装这个问题很多人会纠结。Gitblit服务器本身不需要你安装Git for Windows它内部有一套纯Java实现的Git处理引擎仓库的创建、提交、分支管理都在Java层面完成。但如果你的Windows服务器上同时需要命令行Git操作或者你后面要用脚本做备份、钩子hook装一个Git for Windows会更顺手。从客户端角度来看SourceTree在Windows上必须依赖一个Git环境。SourceTree安装时会让你选内置Git还是系统Git无论选哪个本质都是Git for Windows的变体。所以结论是服务器端可装可不装推荐装方便日常命令行维护。客户端电脑必须要有Git环境用SourceTree内置的就行。以后我讲解备份、巡检都会用到Git命令所以现在直接在Windows上装一个Git for Windows一路默认下一步即可版本选择最新的64位稳定版。3. Gitblit配置的四个关键点改错了服务起不来3.1 下载与解压目录规划比想象中重要Gitblit在官方平台GitHub Releases页面或官网下载站提供zip压缩包下载后解压到服务器上。我选择的目录是D:\Gitblit这样系统盘C盘崩了重装系统也不会弄丢代码。解压后的目录结构如下Gitblit/ ├── gitblit.bat # Windows启动脚本 ├── gitblitw.exe # 注册为系统服务的工具 ├── defaults.properties # 默认配置模板 ├── data/ # 数据目录配置和仓库都在这里 │ ├── gitblit.properties # 实际生效的配置文件 │ └── repositories/ # 默认仓库存放位置 ├── ext/ └── web/注意一个关键点gitblit.properties文件在第一次启动后才会生成它是从defaults.properties拷贝过来的。所以第一次启动前不要手贱去找不到配置文件的地方纠结先运行一次脚本生成配置再来修改。3.2 四个必须改的配置项照着改就行用文本编辑器打开D:\Gitblit\data\gitblit.properties重点修改以下几项。第一HTTP端口。Gitblit默认使用8080端口。server.httpPort 80808080在本地开发环境经常被各种服务占用建议直接改成不常用的端口比如10080或18080。真实项目里我改了18080因为之前有同事机器上的Tomcat占着8080导致访问时灵时不灵排查了很久才发现是端口冲突。第二HTTPS端口和协议开关。局域网默认不需要开启HTTPS但因为Gitblit默认会启用server.httpsPort的配置如果端口被占启动会失败。server.httpPort 18080 server.httpsPort 0 server.httpBindInterface 0.0.0.0注意server.httpsPort 0代表禁用HTTPS。server.httpBindInterface 0.0.0.0表示监听所有网络接口这样才能让局域网内的其他机器访问到。如果默认是127.0.0.1那是仅本机访问这个坑很多人会踩。第三仓库存储路径。默认仓库放在data/repositories下。如果数据盘空间大建议改到独立目录。我是用相对路径在data目录里所以不用改。如果希望仓库放在其他盘符可以写绝对路径git.repositoriesFolder D:/GitRepos第四基础URL。这个配置是很多部署问题背后的根源web.mountParameters /或者如果你通过反向代理访问需要设置server.contextPath。局域网直连场景不用管默认即可。3.3 启动服务与验证配置是否生效双击gitblit.bat窗口会一闪而过不对正常会保持运行输出日志。如果窗口闪退那90%是JAVA_HOME配置不对。验证方法java -jar gitblit.jar --baseFolder data更稳妥的方式是先进入命令行手动执行启动脚本这样即使报错错误信息也会留在窗口里。启动成功后浏览器访问http://localhost:18080/你会看到Gitblit的登录页面。默认管理员账号是admin密码是admin首次登录后会强制要求修改密码。注意改完gitblit.properties后需要重启服务才能生效。如果是用批处理启的关掉窗口再双击一次如果是注册成了Windows服务就重启服务。3.4 要不要把Gitblit注册成Windows服务日常使用时如果你不想每次开机都手动双击启动脚本可以用Gitblit自带的gitblitw.exe。先安装为服务需要命令行进入Gitblit目录cd /d D:\Gitblit gitblitw.exe //IS//Gitblit --DisplayNameGitblit Git Server --InstallD:\Gitblit\gitblitw.exe --JvmC:\Java\jdk1.8.0_202\bin\server\jvm.dll --StartModejvm --StopModejvm --StartClasscom.gitblit.GitBlit --StopClasscom.gitblit.GitBlit --StartParams--baseFolder,data,--repositoriesFolder,data/git这个命令参数容易记混我的建议是如果不是部署到真正的公共服务环境直接用gitblit.bat就够了。开机启动的问题可以用任务计划程序里加一个启动时运行gitblit.bat解决比注册服务更直观出了问题也好排查。4. 用户与仓库权限先建用户还是先建仓库顺序很关键4.1 首次登录后第一时间把admin密码改了用admin / admin登录后系统会提示修改密码。这个过程别跳过因为局域网内同事知道默认密码就可以直接登录你的Web管理后台把你的仓库配置翻个底朝天。修改路径右上角admin→账户→修改密码。改完后进入管理能力更强的界面。4.2 创建用户按人建账号而不是按组点击顶部菜单用户标签再点击新建用户。每个同事单独建一个账号用户名建议与系统登录名保持一致比如zhangsan方便管理。创建用户时必须设置密码同时要选择一个角色。Gitblit的权限体系里有三种核心角色角色权限范围#admin管理员可管理所有仓库和用户#developer开发者可创建仓库但不能管理其他用户#user普通用户只能访问被授予权限的仓库如果是团队负责人或技术组长可以给#developer角色如果是普通开发人员只给#user即可。我踩过的坑是一开始图省事给所有人都发了#admin结果一位同事误操作把别人的仓库删了——别问我怎么知道的权限真的得管严。4.3 创建仓库Web端创建和Git命令推送创建在仓库标签页点击新建仓库填写名称比如project-web注意名称里不要带中文和空格。它会自动生成访问路径http://192.168.x.x:18080/r/project-web.git其中/r/是仓库根路径的固定前缀。另一个创建方式是在本地仓库执行git remote add origin http://192.168.100.5:18080/r/project-web.git git push -u origin master第一次往不存在的仓库路径推送时Gitblit会提示仓库不存在。如果你想支持推送到不存在的仓库时自动创建GitHub叫push to create需要在gitblit.properties里设置git.createRepositories true这需要事先在用户权限组里给对应用户#admin权限否则会被拒绝。我更推荐使用Web端先创建仓库再让同事去克隆这样权限控制更清晰仓库描述、初始分支等都能提前设置好。4.4 仓库权限模型给用户分配能读到哪一层进入仓库页面点击左侧权限标签可以看到Gitblit的访问限制模型。它支持按仓库级别控制用户权限有四种级别Viewer只读可以浏览代码和克隆仓库不能推送。Contributor读写可以推送代码但管理操作如删除分支、修改仓库设置受限。Admin完全管理该仓库包括修改仓库配置、管理权限。无权限默认不能看到仓库。我把同事的默认角色设为#user然后针对每个仓库单独给他分配Contributor权限。这样每个仓库的访问人员都必须明确指定权限边界很干净。5. 局域网访问防火墙放行与IP规划5.1 为什么本机能访问局域网其他电脑死活连不上这是搭建过程中几乎所有人都会遇到的第一个大坑。当你修改完配置、启动服务、本机浏览器能正常访问后同事那台电脑输入http://本机IP:18080/却提示无法访问。90%的原因是Windows防火墙默认拦截了8080或18080端口的外部入站请求。解决办法打开控制面板→Windows Defender防火墙→高级设置→入站规则→新建规则选择端口协议选TCP端口填18080操作选允许连接应用范围可以选专用或域配置文件。这里有个细节Windows网络配置文件分为专用和公用两种。如果你所在网络被识别为公用网络而你的放行规则只勾选了专用依然会被拦截。建议直接勾选所有配置文件省心。提示如果你改过Gitblit端口记得防火墙规则里的端口必须保持一致别改完端口忘了同步防火墙。5.2 用IP地址访问还是配置主机名局域网访问Git服务器用得最多的方式就是IP地址。但需要注意如果你的服务器电脑用的是DHCP动态获取IP重启路由器或DHCP租约过期后IP可能变化。为了避免同事本子里的远端地址失效最好给服务器设置一个静态IP。设置方法右键右下角网络图标→打开网络和Internet设置→更改适配器选项→右键以太网→属性→选中Internet协议版本4 (TCP/IPv4)→属性然后配置IP地址: 192.168.100.5 子网掩码: 255.255.255.0 默认网关: 192.168.100.1 DNS服务器: 192.168.100.1IP地址根据自己的路由器网段来定别照抄我的。另外如果你希望同事用主机名访问比如http://git-server:18080/那就在每台客户端的C:\Windows\System32\drivers\etc\hosts文件里加一行192.168.100.5 git-server不过这需要每台电脑都配比直接用IP麻烦。小团队我建议直接用IP省事。5.3 多网卡场景下的一点提醒服务器如果同时插了有线网卡和无线网卡0.0.0.0监听虽然能让两个网卡都访问但同事访问时用的IP地址必须是你实际网段的IP。比如有线是192.168.100.5无线是192.168.200.5同事在192.168.100.x网段就只能访问192.168.100.5不能访问192.168.200.5。这个原理其实很简单但排查起来容易绕晕。6. SourceTree配置从克隆到第一次提交6.1 先把SourceTree的Git环境选对SourceTree是Atlassian出品的免费Git图形化客户端在Windows上跟Gitblit配合非常顺滑。安装完成后第一次启动会引导你选择Git版本。这里有一个常见的困惑SourceTree询问的是使用内置Git还是系统Git。我的建议是选择使用系统Git——也就是你之前手动安装的Git for Windows。原因很简单内置Git的版本更新滞后而且和某些系统的编码设置可能存在兼容性问题用系统Git自己可控。配置方法工具→选项→Git在Git版本区域选择使用系统Git并确认路径是C:\Program Files\Git\bin\git.exe。6.2 克隆仓库地址格式别搞错打开SourceTree点击克隆按钮弹出克隆对话框。源URL填http://192.168.100.5:18080/r/project-web.git目标路径选一个本地目录比如D:\workspace\project-web克隆类型选择完整克隆点击克隆后SourceTree会弹出认证窗口要求输入Gitblit的用户名和密码。这里第一次输入就是了。顺利的话仓库内容会拉到本地分支、标签都能正常显示。这里有个小细节如果你的仓库还没有任何提交空仓库克隆时SourceTree会提示这是一个空仓库。我不会直接在这个空目录里手动建一堆文件而是建议先在Gitblit的Web管理界面创建一个带README的初始仓库或者本地先建立一些基础文件再推送上去。6.3 提交、推送、拉取的完整链路验证克隆下来后我习惯先做一次完整的本地修改→提交→推送→拉取链路的验证确认真个流程全通。步骤在本地项目文件夹新建一个文件比如README.md写一行内容。SourceTree工作区里能看到未暂存的文件点击暂存所有。输入提交信息点击提交。点击推送远端选择origin和要推送的分支master或main确认推送成功。让另外一台电脑再次克隆这个仓库修改文件后推送然后回到这台电脑点击拉取看能否拉取到改动。如果这整套流程都顺利通过你的Git服务就已经真正可用了。6.4 要不要改造SSH协议SourceTree默认走HTTP协议好处是用户名密码认证简单局域网内也不需要额外配置SSH密钥。但HTTP方式每次Clone时都要输入密码除非SourceTree帮你记住了凭据。如果你不想频繁输密码有两个方案方案一SourceTree会调用Windows凭据管理器保存HTTP密码一次输入后基本不用再输入。方案二使用SSH协议。需要在Gitblit的Web管理界面里配置每个用户的SSH公钥然后在SourceTree里生成密钥、加载私钥克隆地址格式变为ssh://admin192.168.100.5:29418/project-web.git。注意SSH的端口默认是29418不是HTTP的18080。我的实际体验是局域网内HTTP足够没必要为了省一次密码去配置SSH密钥管理。但如果你要在多台电脑上反复Clone那SSH密钥免密登录会舒服很多。Gitblit本身支持SSH功能但首次配置还得在用户设置里上传公钥一步都不能少。7. 这几个月用下来的坑和心得一次讲完7.1 端口冲突比你想的更常见部署初期发现浏览器访问http://localhost:18080/页面打不开。排查发现是本机装了一个服务占用了18080端口。用命令检查netstat -ano | findstr 18080如果看到占用进程记下PID最后一列用任务管理器详细信息标签页按PID找到进程确认不是系统关键进程后停掉它或者给Gitblit换个端口。这里我建议给Gitblit专门预留一个不常用端口比如19418以后基本不会再撞车。7.2 中文文件名与代码仓库的编码问题Gitblit仓库里如果包含中文文件名Web界面偶尔会出现乱码这是编码设置问题。Windows系统默认的编码是GBKGitblit内部默认UTF-8。处理方式分两步第一在客户端Git里设置提交信息编码git config --global i18n.commitencoding utf-8 git config --global i18n.logoutputencoding utf-8第二处理文件名乱码git config --global core.quotepath false这样设置完以后SourceTree里的中文文件名基本不会再显示成\345\274\200\346\272\220这串转义字符。7.3 SourceTree每次操作都要密码到底怎么治如果你用的是HTTP方式SourceTree会通过Windows凭据管理器保存凭据。但如果你发现每次都要求输入密码那通常是因为在SourceTree的仓库设置里远程URL写的是IP但你在凭据管理器保存的是另一个地址的凭据。查一下控制面板→凭据管理器→Windows凭据把和Gitblit相关的通用凭据删掉然后在SourceTree里再操作一次让它弹出认证框并勾选记住密码。7.4 备份与迁移复制文件夹就够了Gitblit最方便的一点是备份极其简单。只需要找到data目录把整个文件夹复制走就是一个完整的备份。备份仓库直接复制data/repositories下的所有目录。备份用户与配置直接复制data/gitblit.properties和data/users.conf用户数据存在这个文件里。我在每个周五下午做一次整体备份用一个简单的批处理脚本完成xcopy /E /I /Y D:\Gitblit\data D:\GitServerBackup\gitblit_data迁移到新服务器时装好相同版本Gitblit和JDK把data目录原样覆盖回去用户、仓库、权限全部恢复不需要任何导入导出动作。7.5 要不要上HTTPS和加密传输局域网环境下很多人纠结要不要启用HTTPS。我的答案是除非你的代码敏感度非常高或者需要跨网段传输否则局域网HTTP完全够用。Gitblit开启HTTPS需要在gitblit.properties里配置证书路径和密码配置起来并不复杂但一旦启用所有客户端的SourceTree、Git命令行都要同步信任证书否则你会看到一连串的证书警告反而影响使用体验。7.6 一个容易被忽略的权限陷阱删除分支的权限Gitblit的Contributor权限默认是可以推送代码的但不会允许你随意删除远端分支。删除分支需要仓库管理员权限。这个默认设计我一开始觉得麻烦后来发现它其实帮忙挡了很多误删分支的意外。最后分享一点实际体会Gitblit看起来简单但恰恰是这种少即是多的设计让它特别适合跑在Windows局域网里。它不需要你成为运维专家也不会跟你玩什么版本升级变脸存文件、管用户、走HTTP干净利落。如果你正在为团队找一个轻量的自建Git方案照着这篇文章的路径走一遍半天之内一定能把服务跑起来。以后要是哪天仓库数量大了或者团队规模明显增长再考虑迁移Gitea也不迟——至少到那时你已经把Git服务器从0到1的每个环节都摸透了。