自建一套代码托管服务这件事我前后折腾过不下五轮。最早是为了把一个十几个人的内网项目从U盘拷压缩包的原始状态里拽出来后来是因为外包团队的代码不方便放到公有托管平台上再后来纯粹是想给自己留一个不依赖外网的备份点。项目标题里写的这套组合——Gitblit 做服务端、Git for Windows 做本地命令行、TortoiseGit 做图形界面——是我试过之后觉得对中小团队最省心的一条路。Gitblit 是个纯 Java 的轻量 Git 服务端一个 jar 加几个配置文件就能跑起来不像 GitLab 那样要吃掉好几个 G 的内存Git for Windows 提供原生的 git 命令和 Git BashTortoiseGit 这只小乌龟则让不习惯敲命令的同事也能看懂分支、提交、推送这些概念。这篇东西我会从零把三件套装完配好讲透包括 5080 端口怎么改、commit 时那串-c diff.mnemonicprefixfalse参数是什么鬼、configure git.exe 识别不到怎么救、中文包不生效等等一路踩过的坑都摊开说。不管你是刚接触版本控制的新人还是想给团队搭个内部仓库的老手照着走一遍基本不会卡住。1. 为什么要自己搭一套 Git 服务1.1 三条路线对比公有托管、GitLab、Gitblit先把选型这件事说清楚因为很多人上来就问用哪个软件好其实真正的问题是你需要什么。公有托管平台最大的优势是省事注册就能用但它的前提是你的代码可以放到别人的服务器上。一旦涉及甲方保密条款、内部业务逻辑、或者单纯是网络环境不允许访问外部服务这条路就断了。而且有些团队的网络策略比较严格本地开发机根本连不上外部托管站点这不是技术问题是管理问题只能靠自建解决。GitLab 是功能最全的自建方案CI/CD、Issue、代码评审、容器镜像仓库一应俱全。但它的代价也很明显官方推荐的配置是 4 核 8G 起步跑起来内存就被吃掉一大半。我见过有人在 2G 内存的云主机上硬装 GitLab装完之后连 SSH 登录都要等十几秒最后只能扩容。对于只是想给团队提供一个能提交能拉取能看历史的仓库的场景GitLab 属于典型的杀鸡用牛刀。Gitblit 则走了另一个极端。它是纯 Java 写的整个发行包解压出来大概七八十兆跑起来常驻内存 200M 到 400M 之间一台 1 核 1G 的机器就能稳稳支撑十几个人的日常使用。它不提供 CI/CD没有 Issue 跟踪只有仓库管理、权限控制、简单的代码浏览和 Pull Request 功能——但这恰好覆盖了 80% 中小团队的核心需求。我第一次把它跑起来的时候有点不适应因为太安静了没有任何构建队列在后台嗡嗡转就是安安静静地提供 Git 服务。三条路线的对比如下方案资源占用部署难度功能范围适合场景公有托管平台无极低完整代码可外放、网络畅通GitLab 自建4核8G起中高完整中大型团队、需要 CI/CDGitblit 自建1核1G可跑低仓库权限PR中小团队、内网环境1.2 Gitblit 的适用边界与这套组合的定位得承认 Gitblit 有它的天花板。它是一个个人主导的开源项目更新节奏不算快最新稳定版长期停留在 1.9.x。它没有内置的代码质量扫描没有制品库权限模型也相对简单——只有管理员、用户、只读这几档配合仓库级别的授权。如果你的团队已经有几十号人、需要按组划分权限、还要接入流水线那我还是建议上 GitLab 或者 Gitea。但这套组合真正的价值在于学习曲线平缓且完全离线可用。我在给新同事做培训的时候会让他们先在自己电脑上把 Git TortoiseGit 装好然后连到内网的 Gitblit 上从建仓库、克隆、改文件、提交、推送、切分支这一整条链走一遍。整个过程不依赖外网不怕他们把测试代码误传到公开平台上出错了直接删仓库重来。这种随便折腾的安全感对新手建立信心特别重要。这套三件套的分工也很清晰Gitblit 是服务器负责存仓库、管用户、发权限Git for Windows 是发动机所有真正的版本控制动作都是它执行的包括 TortoiseGit 在背后也是调用它TortoiseGit 是仪表盘,把命令行的操作翻译成右键菜单和对话框。理解了这层关系后面遇到问题就好定位了——界面点不动八成是 TortoiseGit 找不到 Git提交推送报错八成是 Git 本身或者网络/权限的问题网页打不开那是 Gitblit 服务端的事。分清楚责任田排错效率能高一大截。2. 动手之前环境准备与几个绕不开的决策2.1 机器与系统轻量到什么程度服务端这台机器我给的最低配置建议是 1 核 CPU、1G 内存、20G 硬盘。听起来很寒酸但实测下来十几个人的团队每天几十次提交这个配置绰绰有余。真正吃资源的是仓库历史增长如果项目里有大量二进制文件设计稿、安装包、视频素材仓库体积会迅速膨胀这时候主要瓶颈是磁盘 IO 和容量而不是 CPU。我自己维护的那个仓库跑了三年多里面塞了几个含图片资源的项目git目录总共也就涨到几个 G定期用git gc清理一下效果很明显。操作系统这块Gitblit 是跨平台的Windows、各种 Linux 发行版都能跑。之所以这篇重点讲 Windows 下的部署是因为很多内网环境里服务器就是台 Windows 机器运维同事更熟悉这套操作。Windows Server 2012 以后的版本或者 Windows 10/11 专业版都可以家用版也能跑但服务注册会有些限制。Linux 下其实就是把installService.cmd换成install-service.sh配置文件的逻辑完全一样所以理解了 Windows 的流程迁移到 Linux 基本是平移。有一点要提前说这台机器的 IP 最好固定。因为后面所有客户端的仓库地址里都要写这个 IP一旦变了每个人都要改 remote 地址非常麻烦。公司内网的话让网管配个静态 IP云主机直接绑定弹性 IP。域名的话可选如果内网有 DNS 服务器可以给这台机器加个git.内网域名的记录比记 IP 舒服得多。2.2 Java 环境怎么装才不会踩版本坑Gitblit 依赖 Java 运行环境这一步是整个搭建过程里最容易出幺蛾子的地方。先说结论装 JDK 8 或 JDK 11 都行不建议直接上 JDK 17 及以上除非你确认用的是对应版本的 Gitblit。Gitblit 1.9.x 官方说明是支持 Java 8 及以上但社区里反馈在较新的 JDK 上偶尔会出现加密相关的异常尤其是启用 HTTPS 的时候因为新版 JDK 对加密套件的默认策略收紧了。稳妥起见用 JDK 8 或 11兼容性最好。安装方式我推荐直接用免安装的绿色包解压到某个目录然后手动配环境变量。这么做的好处是不污染系统将来要升级或者换版本直接改JAVA_HOME指向新目录就行不用走卸载流程。具体操作是把 JDK 解压到比如D:\java\jdk-11然后右键此电脑→属性→高级系统设置→环境变量新建一个JAVA_HOME值填D:\java\jdk-11再把%JAVA_HOME%\bin加到Path里。配完之后打开一个新的命令行窗口敲java -version能打印出版本号就说明配好了。注意这里有个细节一定要新开一个命令行窗口验证因为环境变量是在窗口启动时读取的老窗口里改了看不到效果。这个坑我踩过改完变量在原来的 cmd 里反复敲java -version都报不是内部或外部命令一度以为配置错了折腾半天才发现是新开窗口的问题。如果系统里同时装了多个 Java 版本java -version显示的可能是别人。这时候可以用where java看看 Path 里哪个排在前面。Gitblit 启动脚本读取的是JAVA_HOME所以只要这个变量指对了服务跑起来用的就是你想要的那个版本。实在不放心可以在 Gitblit 的启动脚本里显式指定set JAVA_HOMED:\java\jdk-11一劳永逸。2.3 端口规划为什么很多人最后都落在 5080Gitblit 默认的 HTTP 端口是 8080HTTPS 是 8443。但现实情况是8080 这个端口太抢手了Tomcat、Jenkins、各种中间件的管理后台都默认用它。你在一台机器上装了好几个服务第一个占住 8080第二个启动就会报端口被占用。热搜里频繁出现的gitblit网页5080端口其实就是大家把默认的 8080 改成了 5080给 8080 腾位置或者纯粹是为了避免冲突。改端口很简单后面讲配置文件的时候会具体说就是在default.properties里把server.httpPort的值从 8080 改成 5080。改完之后访问地址就变成http://服务器IP:5080。这里提醒一句改完端口如果发现访问不了先别急着怀疑配置多半是防火墙没放行。Windows 防火墙默认只放行少数端口需要手动添加入站规则允许 5080 的 TCP 流量。Linux 下则是firewalld或iptables的事。这个排查顺序我建议养成习惯先看服务进程在不在再看端口有没有在监听netstat -ano | findstr 5080最后看防火墙。端口规划还有个小建议如果你打算同时开 HTTP 和 HTTPS最好让它们之间留出规律比如 HTTP 用 5080、HTTPS 用 5081或者 HTTP 5080、SSH 29418 保持默认。Gitblit 的 SSH 协议默认端口就是 29418这个端口相对冷门一般不用改除非公司网络策略对它有限制。SSH 方式的好处是推送拉取不用每次输密码用密钥就行后面在 TortoiseGit 那节我会详细讲怎么配。3. Gitblit 服务端搭建全流程拆解3.1 下载、解压与目录规划Gitblit 的官方站点是 gitblit.com在 Download 页面能找到各个版本的发行包。选择的时候认准文件名里的gitblit-x.x.x.zip这种打包版它比.tar.gz在 Windows 下更省事。我一般会选最新的稳定版写这篇的时候最新稳定线是 1.9.x 系列具体小版本号变化不影响配置逻辑。下载下来直接用系统自带的解压功能解压可能会丢失一些文件权限相关的信息虽然 Windows 下影响不大但我习惯用 7-Zip 解压稳妥一点。解压之后你会看到一个包含gitblit.cmd、installService.cmd、default.properties、data目录等的文件夹。给它找个干净的落脚点我惯用的路径是D:\gitblit不要把路径设得太深也不要放在桌面我的文档这种带中文和空格的目录里因为后面注册服务和写脚本的时候路径里有空格会让命令行参数解析出问题得额外加引号很麻烦。目录结构里几个关键文件的作用我用表格列一下方便你心里有数文件/目录作用gitblit.cmd前台运行启动脚本调试用installService.cmd注册为 Windows 服务的脚本default.properties主配置文件所有核心参数在这data存放配置的实际生效副本、用户文件、仓库data/git默认的仓库存储目录data/users.conf用户账号文件logs运行日志这里有个很多人会懵的点你改了根目录下的default.properties但服务可能读的是data目录下的那份。因为首次启动时Gitblit 会把根目录的配置复制一份到data目录之后以data里的为准。所以我的习惯是直接改data目录下的default.properties避免改了不生效还到处找原因。这个坑我在早期版本上栽过改了端口重启完全没反应愣是对着配置文件反复看了半个多小时。3.2 default.properties 逐项拆解这个文件是整个 Gitblit 的大脑下面几项是我每次部署必改的逐条说清楚为什么改。第一项绑定地址。默认情况下 Gitblit 会监听所有网卡如果你只想让内网访问可以设置server.httpBindInterface。但更常见的情况是不需要动它让它监听0.0.0.0就行通过防火墙去控制谁能访问。我这边的习惯是保持默认把访问控制交给防火墙配置本身越简单越好维护。第二项端口。找到这一行server.httpPort 8080把 8080 改成你要的端口比如 5080。如果同时要开 HTTPS对应改server.httpsPort。这里注意 1.8 及更早的版本字段名是gitblit.httpPort1.9.x 之后改成了server.httpPort。如果你照着老教程改发现没生效先确认一下你手上的版本用的是哪个字段名别照着抄错了。第三项仓库目录。默认是git.repositoriesFolder ${baseFolder}/git${baseFolder}会自动解析成data目录。如果你想单独挂一块大盘来存仓库就把这个值改成绝对路径比如D:/gitblit-repos。注意这里用正斜杠Windows 下 Java 配置文件里用反斜杠可能被当成转义字符。这个改动建议在正式启用前做好因为仓库创建之后就跟着这个目录走中途改的话得手动迁移数据。第四项站点名称和界面语言web.siteName 内部代码仓库改成一个团队能一眼认出来的名字就行。第五项账户类型。Gitblit 支持几种认证模式最简单的就是基于本地文件realm.userService ${baseFolder}/users.conf保持默认即可用户都写在users.conf里适合小团队。如果团队规模大、想对接统一认证它还能接 LDAP 或 AD但那就属于进阶玩法了先把基础跑通再说。改完配置保存然后运行gitblit.cmd做一次前台启动测试。第一次启动会在控制台打印一堆初始化日志看到类似Gitblit server is running的输出就说明起来了。这时候打开浏览器访问http://服务器IP:5080应该能看到登录页。默认管理员账号是admin密码也是admin第一件事就是去改掉它这个后面说。3.3 注册成 Windows 服务并自启前台gitblit.cmd的窗口一关服务就停了生产环境不能这么干。Gitblit 提供了服务注册脚本installService.cmd。直接双击运行通常也能成功但如果遇到权限或路径问题就用管理员身份打开命令行切到 Gitblit 目录再执行。这个脚本里其实内置了好几个变量最需要留意的是ARCH它用来告诉服务用 32 位还是 64 位模式运行。如果你的 JDK 是 64 位就要确保这里设置成amd64。我遇到过一次注册后服务起不来查日志发现是位数不匹配JDK 是 64 位的脚本默认按 x86 加载结果就是找不到合适的运行时。改对之后服务就乖乖起来了。注册成功后去服务管理器运行services.msc应该能看到一个名字类似gitblit的服务。把它设成自动启动这样服务器重启之后它会自己拉起来。手动测试的话在服务上右键启动、停止即可。如果你的脚本里服务名不太一样以脚本里set SERVICE_NAME那一行的实际值为准。这里有个隐蔽的坑服务运行的账户和工作目录可能和你手动运行时不一样。服务默认可能以LocalSystem账户跑而它的工作目录未必是你解压 Gitblit 的那个目录。如果启动失败多半是相对路径解析出了问题。解决办法是在注册脚本里加上set CDD:\gitblit这一类的设置明确指定工作目录。另外服务账户对这个目录要有读写权限尤其是data、logs目录LocalSystem一般权限足够如果你改成别的账户运行记得授权。验证服务是否真的起来了最快的办法就是看logs目录下有没有新的日志文件写入以及浏览器能不能访问。两项都对上就说明服务跑成功了。3.4 首次登录、改密码与权限模型用 admin/admin 登录进去之后右上角进用户设置第一件事就是改掉这个默认密码。这事没有任何商量余地——一个内网服务里存着全部代码管理员密码还是 admin等于把仓库钥匙插在门上。改密码的地方在用户配置里新密码设复杂一点至少别用 123456。改完密码接下来是建用户。Gitblit 的管理界面里用户页签可以新增账号填用户名、显示名、邮箱、初始密码就行。权限模型是分层的系统管理员能管全部普通用户能访问被授权的仓库只读用户只能看不能推。对大多数团队来说建三五个账号就够用了。仓库授权是重点。新建或编辑仓库的时候有一个权限页签可以把具体用户或团队加进来给 Read、Push、Create 等不同级别的权限。这里我有个实践心得不要给所有人管理员权限哪怕团队很小。因为管理员能删仓库一个误操作可能把几个月的提交记录带走。正确的做法是给开发者配置可读取、可推送只在真正需要管理仓库的人身上开管理员。每个仓库的权限可以单独设也可以按团队批量授权团队可以在管理界面里建把人往里塞然后整个团队一起授权人多了省事。Gitblit 还支持匿名访问。web.allowAnonymousAccess设为true的话任何人不登录就能浏览仓库列表。除非你确实想让全公司的人都能看到代码否则保持关闭。我见过有团队图方便开了匿名只读结果过了一段时间发现有外部人员通过内网扫描发现了这个地址虽然只是只读但代码泄露风险已经存在了。这种时候再回头收紧权限已经晚了一步。4. Git for Windows 安装与最小必要配置4.1 下载与安装向导里每一个选项的含义服务端搞定轮到客户端。先去 git-scm.com 下载 Git for Windows安装包名字类似Git-2.4x.x-64-bit.exe。这里提醒一句网上有些第三方站点会把老版本或者捆绑了别的东西的安装包包装得很像官方版认准 git-scm.com 这个官方域名别从搜索结果里随便点一个。热搜里git下载安装教程这个词能说明问题很多人是在这一步就下载到了不对的东西。双击安装前几步是许可协议和安装路径路径保持默认的C:\Program Files\Git就行。真正需要逐项决策的是后面那些勾选项我一个个说。Select Components这一步勾上 Windows Explorer integration 下的Git Bash Here和Git GUI Here这两个能让你在任意文件夹右键直接打开 Git 环境日常很实用。其余像Associate .git* configuration files、Associate .sh files to be run with Bash建议都保持勾选。后面的 TrueType 字体、每日检查更新可选可不选看个人喜好。Choosing the default editor这一步默认是 Vim。如果你没用过 Vim第一次 commit 时它会把你关在一个全屏编辑器里退出得按Esc然后:wq新手很容易懵。我一般改选成 Notepad 或者 VS Code如果有的话。实在没有用系统自带的 Notepad 也比 Vim 友好一点虽然它会有些编码上的小毛病。Adjusting your PATH environment这一步最关键三个选项Use Git from Git Bash only只允许在 Git Bash 里用 git 命令环境变量不动Git from the command line and also from 3rd-party software推荐允许在 cmd、PowerShell 和第三方工具里用 gitUse Git and optional Unix tools from the Command Prompt会把find、sort这些 Unix 工具也塞进 Path可能覆盖系统自带的同名命令不建议选。一定要选中间那个否则后面 TortoiseGit 很可能找不到 git.exe就是热搜里那个configure git.exe 无法识别到 git.exe path问题的常见成因之一。Choosing the SSH executable保持默认的 OpenSSH 就行。Choosing HTTPS transport backend选 Use the OpenSSL library兼容性最好。Configuring the line ending conversions这一项中文叫行结束符转换三个选项里推荐第一个Checkout Windows-style, commit Unix-style它在检出时转成 CRLF、提交时转回 LF能有效避免跨平台协作时的换行符混乱。后面几项终端模拟器、git pull行为、凭据管理器没有特殊需求就保持默认。凭据管理器建议保留 Git Credential Manager它能帮你记住 HTTPS 密码省得每次推送都输。4.2 装完之后 git 命令用不了的排查装完了不等于就能用。最典型的报错就是热搜里那句话git : 无法将git项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查...。这基本只有一个原因PATH 没配好或者你用的是安装时选错的那一档。排查顺序这样走。第一步关掉所有命令行窗口重新开一个。环境变量在窗口启动时加载老窗口不认新配置。第二步敲git --version如果还报错在 cmd 里执行where git看看能不能找到路径。第三步如果where也找不到就去系统环境变量里看看 Path 里有没有C:\Program Files\Git\cmd这一项。没有的话手动加上然后重新开窗口验证。还有一种情况是装了但被别的软件干扰了。有些软件会自带一份精简版的 git把它塞进 Path 前面导致系统调用的不是你刚装的那个完整版。这种时候where git会列出多个路径排在前面的那个就是实际生效的。要么调整 Path 顺序要么在 TortoiseGit 里直接指定完整的 git.exe 路径绕开这个歧义。如果是在 PowerShell 里报错、在 cmd 里正常那可能是 PowerShell 的 profile 脚本改动了 Path。用$env:Path看一下当前会话里的路径对比系统设置找到差别就好办了。4.3 必须做的全局配置与免密方案命令能跑了之后先做几项全局配置这些是一次性设置之后所有仓库都受益。打开命令行git config --global user.name 你的名字 git config --global user.email 你的邮箱公司.com git config --global core.autocrlf true git config --global init.defaultBranch main前两项是身份标识每一次提交都会带上这两个信息写错了历史记录里就留下错误的作者改起来要重写历史很麻烦。所以第一步就把这两个配好。core.autocrlf true配合刚才安装时的换行符选项处理 Windows 和 Linux 协作的换行问题。init.defaultBranch main让新建仓库的默认分支叫 main 而不是 master现在主流托管平台都往这个方向走了本地保持一致能少些困惑。免密这块分两种协议。用 HTTPS 方式克隆第一次推送会弹出账号密码框输对了之后 Git Credential Manager 会记住下次就不问了。用 SSH 方式的话要先在本机生成密钥对把公钥配到 Gitblit 上。命令是ssh-keygen -t rsa -b 4096 -C 你的邮箱公司.com一路回车默认生成在~/.ssh/id_rsa和~/.ssh/id_rsa.pub。id_rsa是私钥绝对不能外传id_rsa.pub是公钥就是你要贴到服务器上的那串文本。这个公钥待会儿在讲 TortoiseGit 的时候会一起说怎么配到 Gitblit。还有个小技巧方便查看历史和提交图git config --global alias.lg log --oneline --graph --all --decorate配完之后敲git lg就能看到漂亮的提交树比默认的git log直观得多。这属于锦上添花但用过就回不去了。5. TortoiseGit 安装与中文包5.1 安装顺序与 configure git.exe 识别问题TortoiseGit也就是大家嘴里的小乌龟官网是 tortoisegit.org。它必须依赖已经装好的 Git for Windows所以正确的顺序是先装 Git再装 TortoiseGit顺序反了后面还得重来。下载安装包选 64 位版本一路下一步。安装完会提示重启电脑或者至少重启一次 Windows 资源管理器任务管理器里找到 explorer.exe 重启因为它是作为资源管理器插件工作的不重启右键菜单里不会出现小乌龟的选项。安装向导走到最后一步通常会有一个Configure Git的界面问你 git.exe 在哪。如果这一步自动填好了说明前面 Git 装得没问题直接下一步。如果这里报错或者你当时点了跳过就会撞上那个经典问题——configure git.exe 无法识别到 git.exe path。表现是 TortoiseGit 装是装了但一操作就提示找不到 git。补救办法是在任意文件夹右键 → TortoiseGit → Settings → General 页找到 Git.exe Path 这一栏。如果它是空的或者填错了手动填进去。正确路径一般有两种C:\Program Files\Git\bin里面有 git.exe或者C:\Program Files\Git\cmd里面有 git.cmdTortoiseGit 也能识别。填完点Check now能弹出 git 的版本号就对了。我建议填C:\Program Files\Git\cmd这个目录因为它同时包含了 git.exe 和 git.cmd兼容性更好。如果之前 4.2 那节里 Path 有问题导致命令行用不了 git那 TortoiseGit 这里多半也识别不到先把命令行的 PATH 修好再来配置它一劳永逸。5.2 中文包不生效的几种原因小乌龟原版是英文的官方提供了语言包LanguagePack。下载的时候版本号必须和主程序完全一致比如主程序是 2.17.0语言包也得是 2.17.0。版本对不上会出现装了没反应或者界面部分汉化、部分还是英文的诡异情况。这就是热搜里tortoisegit中文包不生效出现频率高的原因。安装语言包之后还是去 Settings → General在 Language 下拉框里选中文简体确定。如果下拉框里根本没有中文选项说明语言包没被识别到——重启资源管理器再说或者检查语言包是不是装到了主程序同一个目录下。还有个容易忽略的点语言包对某些对话框和提示的本地化覆盖并不完整尤其是较新的功能可能还是英文。这不是安装错误是翻译进度的问题正常现象不用反复折腾。我用下来觉得核心的提交、推送、分支操作这些高频界面都汉化得挺好日常使用没什么障碍。5.3 SSH Key 生成并配置到 Gitblit免密推送在 TortoiseGit 里稍微绕一点因为它默认用的是 PuTTY 那套密钥体系。有两种方案我分别说。方案一继续用刚才在 Git Bash 里生成的 OpenSSH 密钥。TortoiseGit 也能配置成使用 OpenSSH在 Settings → Network 里把 SSH client 从默认的TortoiseGitPlink改成ssh.exe的路径指向C:\Program Files\Git\usr\bin\ssh.exe。这样它就用你在 Git Bash 里生成的那对密钥了省得再生成一份。方案二用 TortoiseGit 自带的 PuTTYgen 生成一对.ppk格式的密钥。这个工具在开始菜单的 TortoiseGit 程序组里能找到或者在 Settings → Network 里点生成密钥。 生成时它会让你在窗口里随机晃动鼠标来产生随机数晃得越随意越安全。生成完保存私钥.ppk文件和公钥一段文本。不管用哪种方案公钥都要贴到 Gitblit 上。登录 Gitblit 网页面板点右上角进个人用户设置找到SSH Keys页签把公钥内容整段粘进去保存。之后用 SSH 协议克隆仓库地址形如ssh://git服务器IP:29418/仓库名.git就再也不用输密码了。用.ppk方案的话还需要让 TortoiseGit 找到这把私钥。可以在 Settings → Git → Remote 里针对具体仓库指定 PuTTY 私钥文件或者用 Pageant 这个代理工具把.ppk加载进去常驻。我个人偏好 Pageant 方案一次加载所有仓库通用重启后重新加载一下就行。注意私钥文件等同于你的身份凭证随手拷给别人或者放进仓库都会造成安全风险。公钥可以随便给私钥只留在自己机器上。6. 日常使用clone、上传文件与切换分支6.1 Gitblit 网页端建仓与网页上传文件服务端和客户端都齐了开始用。第一步在 Gitblit 网页上建仓库。登录之后找到仓库菜单点新建填仓库名建议用英文和连字符比如project-web别用中文和空格因为仓库名会成为 URL 的一部分中文会编码成乱七八糟的字符命令行里操作也容易出问题。填好之后选访问权限一般设成私有的然后保存。仓库建好之后页面上会显示两个克隆地址一个是 HTTP 的形如http://服务器IP:5080/r/仓库名.git一个是 SSH 的形如ssh://git服务器IP:29418/仓库名.git。把 HTTP 那个复制下来下一步就用。很多人问gitblit如何上传文件答案分两种。一种是通过克隆到本地再推送这是标准做法下一节讲。另一种是 Gitblit 网页自带的上传文件功能——它对单个小文件很顺手进入仓库后找到对应目录有个上传入口选好文件它会直接帮你提交一次。但要注意网页上传对大文件和批量文件很不友好一次传太多或者文件太大容易超时。所以这个功能我只用来传个说明文档、配置文件之类的小东西涉及整个项目还是老老实实走命令行或小乌龟。还有一种情况是仓库是全新的、空的网页上会提示你先做一次初始化。空仓库推代码没问题但如果你本地也不是仓库就得先git init一下加个远程地址再推。这个流程对新手有点绕我在下一节把完整命令列出来。6.2 命令行与图形界面两条路径先说命令行这是基本功理解了它图形界面的一切操作你都能对应上。在自己电脑上找个文件夹打开 Git Bash执行git clone http://服务器IP:5080/r/project-web.git cd project-web这样仓库就落到本地了。往里加文件、改代码然后提交git add . git commit -m 初始化项目结构 git push第一次git push会让你输 Gitblit 的账号密码输完 Git Credential Manager 就记住了。这三条命令里git add .是把所有改动放进暂存区git commit是把暂存区的内容定格成一次历史记录git push是把它送到服务器。理解工作区 → 暂存区 → 本地仓库 → 远程仓库这条链路比死记命令重要得多。如果提交信息写错了比如打错字或者忘了加内容可以用git commit --amend这个命令会把最近一次提交重新打开让你编辑可以改提交信息也可以把刚git add进去的新文件并进这次提交。注意它修改的是最近一次且尚未推送到远端的提交如果已经推上去了再 amend本地和远端的提交历史就会分叉得用push -f强推团队协作时这种操作要慎之又慎。再说 TortoiseGit。同样的流程在克隆下来的文件夹里右键 → Git Commit → master它会弹出提交对话框上半部分列改动的文件勾选要提交的下半部分写提交信息点 Commit。推送则是右键 → TortoiseGit → Push。整个过程不用记命令对不熟悉终端的同事特别友好。TortoiseGit 背后调用的命令如果打开它的日志能看到完整形态类似git -c diff.mnemonicprefixfalse -c core.quotepathfalse --no-optional-locks status ...。这串里-c diff.mnemonicprefixfalse是关闭 diff 时前缀字母的缩写形式-c core.quotepathfalse是让中文文件名在输出里正常显示而不是变成八进制转义码--no-optional-locks是禁止 Git 写一些可选的锁文件避免和图形界面同时操作时冲突。这些参数是 TortoiseGit 自动加的你平时不用管但看到日志里这串东西时知道它是正常现象不是哪里配错了。6.3 TortoiseGit 切换分支等高频操作分支是版本控制的精髓用起来其实很简单。TortoiseGit 里切换分支叫 Switch/Checkout。在仓库文件夹右键 → TortoiseGit → Switch/Checkout在弹出的对话框里选目标分支确定就切过去了。如果本地还没有那个分支点分支下拉框可以看到远程分支选一个它会自动帮你创建本地跟踪分支。建新分支也是类似入口叫 Create Branch起个名字比如feature-login基于当前分支创建然后切过去开始干活。等开发完成再切回主分支合并。这个过程在命令行里是git checkout -b feature-login、git checkout main、git merge feature-login图形界面把这一串变成了几个对话框。日常用 TortoiseGit 最爽的几个功能我列一下右键的 Show log 能看提交历史配合 Show Reflog 还能看本地操作记录误删分支有时候能从这里找回来Revert 能撤销工作区的改动Diff 能对比两个版本的文件差异。学会看日志和 diff排查这段代码是谁改的、什么时候改的这类问题会非常快。切分支的时候有个常见困惑工作区有未提交的改动时切分支可能失败或者带着改动一起切过去。图形界面会弹提示问你怎么处理命令行则会报错让你先 stash 或者提交。我的做法是切分支前先用git status看一眼确认工作区干净再切养成这个习惯能避开很多我的改动去哪了的惊魂时刻。7. 故障速查与安全加固7.1 问题速查表把前面散落的坑集中一下做成一张表出问题的时候对着查能省不少时间。现象最可能的原因处理办法网页打不开服务没启动 / 端口占错 / 防火墙拦截看进程和日志netstat查端口放行防火墙改了端口不生效改的是根目录配置实际读的是 data 目录改 data 目录下的 default.properties命令行提示 git 无法识别PATH 没配或选错了安装档位检查 Path 里的 Git 目录重开窗口TortoiseGit 找不到 gitGit.exe Path 没填或填错Settings 里手动指定点 Check now中文包不生效版本号不匹配装与主程序完全同版本的语言包推送一直要密码没配凭据或没用 SSH用凭据管理器记住或配 SSH 密钥服务开机不自启服务是手动启动类型服务属性里改成自动网页上传大文件失败网页上传有大小和超时限制改用 clone push 方式7.2 备份与迁移自建服务最大的好处是数据在你自己手里但反过来没人替你备份。Gitblit 的数据核心就两样data/git目录所有仓库和data下的配置文件、用户文件。备份策略我推荐两步走。第一步把整个data目录用文件级的方式定期同步到一个另外的存储上比如网络附加存储或者另一台机器。同步工具用系统的任务计划配合 robocopy 之类的就行每天凌晨跑一次。这一步保的是服务器整块硬盘挂了也不怕。第二步针对每个仓库做 Git 级别的镜像备份。用git clone --mirror http://服务器IP:5080/r/project-web.git backup/project-web.git--mirror会把所有分支、标签、引用完整拉下来。之后定期进去git fetch --all更新一下。这种镜像的好处是它是一个标准的裸仓库将来哪怕 Gitblit 不在了直接把这个裸仓库拷到任何支持 Git 的地方都能继续用迁移成本几乎为零。迁移的时候也简单在新机器上把 Gitblit 装好把旧机器的data目录整体复制过去注意路径和端口配置保持一致或者同步修改启动服务即可。仓库的远程地址如果 IP 变了客户端那边得更新一下 remote用git remote set-url origin 新地址一条命令搞定。7.3 加固从 .git 目录暴露说起最后聊一个必须重视的点。Git 仓库运行的时候会在工作目录下生成一个隐藏的.git文件夹里面装着全部历史。如果这个目录被部署到了 Web 服务器的站点根目录下并且没有做访问控制别人就可能通过浏览器直接访问到里面的文件进而还原出整个项目的源码和提交历史。这就是所谓的git 目录泄露搜索引擎里能搜到相关讨论本质上是部署疏忽造成的。防护的办法其实不复杂。不要把 Git 工作目录直接当成网站的发布目录。如果非要在服务器上克隆代码把仓库放在站点目录之外用发布脚本把需要上线的文件复制到 Web 根目录。如果架构上无法避免就在 Web 服务器配置里显式禁止访问.git路径让它直接返回 404。这是一个几行配置就能做好的事却能挡住一大类风险。对 Gitblit 本身除了改掉默认密码、关闭匿名访问还建议把管理后台的访问限制在内网不对外网开放端口定期检查用户列表把离职人员的账号及时停用如果启用了 HTTPS用一张可信的证书别长期用自签证书否则浏览器报错会让人习惯性地忽略警告反而埋下隐患。这些经验听着琐碎但只要服务对外开放过一天就值得按这个标准来一遍。注意内网不等于安全。很多数据泄露的源头恰恰是以为内网没人看的服务。权限和备份这两件事在服务上线第一天就该做好而不是等出事之后补。这套三件套我从头搭到尾的次数多了越发觉得真正的门槛不在软件安装而在于搞清楚每一层在干什么。Gitblit 管的是代码放哪、谁能拿Git 管的是版本怎么变TortoiseGit 管的是怎么让不敲命令的人也玩得转。三者边界清晰出问题的时候先想清楚是哪一层的事答案基本就浮出来了。我个人踩得最惨的一次是服务注册成功后以为万事大吉结果服务器重启没自启第二天全组推不了代码才发现服务是手动启动类型——从那以后我每次部署完都要重启一次机器验证自启。另一个小技巧分享给你给内网的 Gitblit 起个短域名就算 IP 变了也只改一处比挨个通知大家改 remote 地址省心太多。
Gitblit + Git + TortoiseGit 内网代码托管搭建指南
自建一套代码托管服务这件事我前后折腾过不下五轮。最早是为了把一个十几个人的内网项目从U盘拷压缩包的原始状态里拽出来后来是因为外包团队的代码不方便放到公有托管平台上再后来纯粹是想给自己留一个不依赖外网的备份点。项目标题里写的这套组合——Gitblit 做服务端、Git for Windows 做本地命令行、TortoiseGit 做图形界面——是我试过之后觉得对中小团队最省心的一条路。Gitblit 是个纯 Java 的轻量 Git 服务端一个 jar 加几个配置文件就能跑起来不像 GitLab 那样要吃掉好几个 G 的内存Git for Windows 提供原生的 git 命令和 Git BashTortoiseGit 这只小乌龟则让不习惯敲命令的同事也能看懂分支、提交、推送这些概念。这篇东西我会从零把三件套装完配好讲透包括 5080 端口怎么改、commit 时那串-c diff.mnemonicprefixfalse参数是什么鬼、configure git.exe 识别不到怎么救、中文包不生效等等一路踩过的坑都摊开说。不管你是刚接触版本控制的新人还是想给团队搭个内部仓库的老手照着走一遍基本不会卡住。1. 为什么要自己搭一套 Git 服务1.1 三条路线对比公有托管、GitLab、Gitblit先把选型这件事说清楚因为很多人上来就问用哪个软件好其实真正的问题是你需要什么。公有托管平台最大的优势是省事注册就能用但它的前提是你的代码可以放到别人的服务器上。一旦涉及甲方保密条款、内部业务逻辑、或者单纯是网络环境不允许访问外部服务这条路就断了。而且有些团队的网络策略比较严格本地开发机根本连不上外部托管站点这不是技术问题是管理问题只能靠自建解决。GitLab 是功能最全的自建方案CI/CD、Issue、代码评审、容器镜像仓库一应俱全。但它的代价也很明显官方推荐的配置是 4 核 8G 起步跑起来内存就被吃掉一大半。我见过有人在 2G 内存的云主机上硬装 GitLab装完之后连 SSH 登录都要等十几秒最后只能扩容。对于只是想给团队提供一个能提交能拉取能看历史的仓库的场景GitLab 属于典型的杀鸡用牛刀。Gitblit 则走了另一个极端。它是纯 Java 写的整个发行包解压出来大概七八十兆跑起来常驻内存 200M 到 400M 之间一台 1 核 1G 的机器就能稳稳支撑十几个人的日常使用。它不提供 CI/CD没有 Issue 跟踪只有仓库管理、权限控制、简单的代码浏览和 Pull Request 功能——但这恰好覆盖了 80% 中小团队的核心需求。我第一次把它跑起来的时候有点不适应因为太安静了没有任何构建队列在后台嗡嗡转就是安安静静地提供 Git 服务。三条路线的对比如下方案资源占用部署难度功能范围适合场景公有托管平台无极低完整代码可外放、网络畅通GitLab 自建4核8G起中高完整中大型团队、需要 CI/CDGitblit 自建1核1G可跑低仓库权限PR中小团队、内网环境1.2 Gitblit 的适用边界与这套组合的定位得承认 Gitblit 有它的天花板。它是一个个人主导的开源项目更新节奏不算快最新稳定版长期停留在 1.9.x。它没有内置的代码质量扫描没有制品库权限模型也相对简单——只有管理员、用户、只读这几档配合仓库级别的授权。如果你的团队已经有几十号人、需要按组划分权限、还要接入流水线那我还是建议上 GitLab 或者 Gitea。但这套组合真正的价值在于学习曲线平缓且完全离线可用。我在给新同事做培训的时候会让他们先在自己电脑上把 Git TortoiseGit 装好然后连到内网的 Gitblit 上从建仓库、克隆、改文件、提交、推送、切分支这一整条链走一遍。整个过程不依赖外网不怕他们把测试代码误传到公开平台上出错了直接删仓库重来。这种随便折腾的安全感对新手建立信心特别重要。这套三件套的分工也很清晰Gitblit 是服务器负责存仓库、管用户、发权限Git for Windows 是发动机所有真正的版本控制动作都是它执行的包括 TortoiseGit 在背后也是调用它TortoiseGit 是仪表盘,把命令行的操作翻译成右键菜单和对话框。理解了这层关系后面遇到问题就好定位了——界面点不动八成是 TortoiseGit 找不到 Git提交推送报错八成是 Git 本身或者网络/权限的问题网页打不开那是 Gitblit 服务端的事。分清楚责任田排错效率能高一大截。2. 动手之前环境准备与几个绕不开的决策2.1 机器与系统轻量到什么程度服务端这台机器我给的最低配置建议是 1 核 CPU、1G 内存、20G 硬盘。听起来很寒酸但实测下来十几个人的团队每天几十次提交这个配置绰绰有余。真正吃资源的是仓库历史增长如果项目里有大量二进制文件设计稿、安装包、视频素材仓库体积会迅速膨胀这时候主要瓶颈是磁盘 IO 和容量而不是 CPU。我自己维护的那个仓库跑了三年多里面塞了几个含图片资源的项目git目录总共也就涨到几个 G定期用git gc清理一下效果很明显。操作系统这块Gitblit 是跨平台的Windows、各种 Linux 发行版都能跑。之所以这篇重点讲 Windows 下的部署是因为很多内网环境里服务器就是台 Windows 机器运维同事更熟悉这套操作。Windows Server 2012 以后的版本或者 Windows 10/11 专业版都可以家用版也能跑但服务注册会有些限制。Linux 下其实就是把installService.cmd换成install-service.sh配置文件的逻辑完全一样所以理解了 Windows 的流程迁移到 Linux 基本是平移。有一点要提前说这台机器的 IP 最好固定。因为后面所有客户端的仓库地址里都要写这个 IP一旦变了每个人都要改 remote 地址非常麻烦。公司内网的话让网管配个静态 IP云主机直接绑定弹性 IP。域名的话可选如果内网有 DNS 服务器可以给这台机器加个git.内网域名的记录比记 IP 舒服得多。2.2 Java 环境怎么装才不会踩版本坑Gitblit 依赖 Java 运行环境这一步是整个搭建过程里最容易出幺蛾子的地方。先说结论装 JDK 8 或 JDK 11 都行不建议直接上 JDK 17 及以上除非你确认用的是对应版本的 Gitblit。Gitblit 1.9.x 官方说明是支持 Java 8 及以上但社区里反馈在较新的 JDK 上偶尔会出现加密相关的异常尤其是启用 HTTPS 的时候因为新版 JDK 对加密套件的默认策略收紧了。稳妥起见用 JDK 8 或 11兼容性最好。安装方式我推荐直接用免安装的绿色包解压到某个目录然后手动配环境变量。这么做的好处是不污染系统将来要升级或者换版本直接改JAVA_HOME指向新目录就行不用走卸载流程。具体操作是把 JDK 解压到比如D:\java\jdk-11然后右键此电脑→属性→高级系统设置→环境变量新建一个JAVA_HOME值填D:\java\jdk-11再把%JAVA_HOME%\bin加到Path里。配完之后打开一个新的命令行窗口敲java -version能打印出版本号就说明配好了。注意这里有个细节一定要新开一个命令行窗口验证因为环境变量是在窗口启动时读取的老窗口里改了看不到效果。这个坑我踩过改完变量在原来的 cmd 里反复敲java -version都报不是内部或外部命令一度以为配置错了折腾半天才发现是新开窗口的问题。如果系统里同时装了多个 Java 版本java -version显示的可能是别人。这时候可以用where java看看 Path 里哪个排在前面。Gitblit 启动脚本读取的是JAVA_HOME所以只要这个变量指对了服务跑起来用的就是你想要的那个版本。实在不放心可以在 Gitblit 的启动脚本里显式指定set JAVA_HOMED:\java\jdk-11一劳永逸。2.3 端口规划为什么很多人最后都落在 5080Gitblit 默认的 HTTP 端口是 8080HTTPS 是 8443。但现实情况是8080 这个端口太抢手了Tomcat、Jenkins、各种中间件的管理后台都默认用它。你在一台机器上装了好几个服务第一个占住 8080第二个启动就会报端口被占用。热搜里频繁出现的gitblit网页5080端口其实就是大家把默认的 8080 改成了 5080给 8080 腾位置或者纯粹是为了避免冲突。改端口很简单后面讲配置文件的时候会具体说就是在default.properties里把server.httpPort的值从 8080 改成 5080。改完之后访问地址就变成http://服务器IP:5080。这里提醒一句改完端口如果发现访问不了先别急着怀疑配置多半是防火墙没放行。Windows 防火墙默认只放行少数端口需要手动添加入站规则允许 5080 的 TCP 流量。Linux 下则是firewalld或iptables的事。这个排查顺序我建议养成习惯先看服务进程在不在再看端口有没有在监听netstat -ano | findstr 5080最后看防火墙。端口规划还有个小建议如果你打算同时开 HTTP 和 HTTPS最好让它们之间留出规律比如 HTTP 用 5080、HTTPS 用 5081或者 HTTP 5080、SSH 29418 保持默认。Gitblit 的 SSH 协议默认端口就是 29418这个端口相对冷门一般不用改除非公司网络策略对它有限制。SSH 方式的好处是推送拉取不用每次输密码用密钥就行后面在 TortoiseGit 那节我会详细讲怎么配。3. Gitblit 服务端搭建全流程拆解3.1 下载、解压与目录规划Gitblit 的官方站点是 gitblit.com在 Download 页面能找到各个版本的发行包。选择的时候认准文件名里的gitblit-x.x.x.zip这种打包版它比.tar.gz在 Windows 下更省事。我一般会选最新的稳定版写这篇的时候最新稳定线是 1.9.x 系列具体小版本号变化不影响配置逻辑。下载下来直接用系统自带的解压功能解压可能会丢失一些文件权限相关的信息虽然 Windows 下影响不大但我习惯用 7-Zip 解压稳妥一点。解压之后你会看到一个包含gitblit.cmd、installService.cmd、default.properties、data目录等的文件夹。给它找个干净的落脚点我惯用的路径是D:\gitblit不要把路径设得太深也不要放在桌面我的文档这种带中文和空格的目录里因为后面注册服务和写脚本的时候路径里有空格会让命令行参数解析出问题得额外加引号很麻烦。目录结构里几个关键文件的作用我用表格列一下方便你心里有数文件/目录作用gitblit.cmd前台运行启动脚本调试用installService.cmd注册为 Windows 服务的脚本default.properties主配置文件所有核心参数在这data存放配置的实际生效副本、用户文件、仓库data/git默认的仓库存储目录data/users.conf用户账号文件logs运行日志这里有个很多人会懵的点你改了根目录下的default.properties但服务可能读的是data目录下的那份。因为首次启动时Gitblit 会把根目录的配置复制一份到data目录之后以data里的为准。所以我的习惯是直接改data目录下的default.properties避免改了不生效还到处找原因。这个坑我在早期版本上栽过改了端口重启完全没反应愣是对着配置文件反复看了半个多小时。3.2 default.properties 逐项拆解这个文件是整个 Gitblit 的大脑下面几项是我每次部署必改的逐条说清楚为什么改。第一项绑定地址。默认情况下 Gitblit 会监听所有网卡如果你只想让内网访问可以设置server.httpBindInterface。但更常见的情况是不需要动它让它监听0.0.0.0就行通过防火墙去控制谁能访问。我这边的习惯是保持默认把访问控制交给防火墙配置本身越简单越好维护。第二项端口。找到这一行server.httpPort 8080把 8080 改成你要的端口比如 5080。如果同时要开 HTTPS对应改server.httpsPort。这里注意 1.8 及更早的版本字段名是gitblit.httpPort1.9.x 之后改成了server.httpPort。如果你照着老教程改发现没生效先确认一下你手上的版本用的是哪个字段名别照着抄错了。第三项仓库目录。默认是git.repositoriesFolder ${baseFolder}/git${baseFolder}会自动解析成data目录。如果你想单独挂一块大盘来存仓库就把这个值改成绝对路径比如D:/gitblit-repos。注意这里用正斜杠Windows 下 Java 配置文件里用反斜杠可能被当成转义字符。这个改动建议在正式启用前做好因为仓库创建之后就跟着这个目录走中途改的话得手动迁移数据。第四项站点名称和界面语言web.siteName 内部代码仓库改成一个团队能一眼认出来的名字就行。第五项账户类型。Gitblit 支持几种认证模式最简单的就是基于本地文件realm.userService ${baseFolder}/users.conf保持默认即可用户都写在users.conf里适合小团队。如果团队规模大、想对接统一认证它还能接 LDAP 或 AD但那就属于进阶玩法了先把基础跑通再说。改完配置保存然后运行gitblit.cmd做一次前台启动测试。第一次启动会在控制台打印一堆初始化日志看到类似Gitblit server is running的输出就说明起来了。这时候打开浏览器访问http://服务器IP:5080应该能看到登录页。默认管理员账号是admin密码也是admin第一件事就是去改掉它这个后面说。3.3 注册成 Windows 服务并自启前台gitblit.cmd的窗口一关服务就停了生产环境不能这么干。Gitblit 提供了服务注册脚本installService.cmd。直接双击运行通常也能成功但如果遇到权限或路径问题就用管理员身份打开命令行切到 Gitblit 目录再执行。这个脚本里其实内置了好几个变量最需要留意的是ARCH它用来告诉服务用 32 位还是 64 位模式运行。如果你的 JDK 是 64 位就要确保这里设置成amd64。我遇到过一次注册后服务起不来查日志发现是位数不匹配JDK 是 64 位的脚本默认按 x86 加载结果就是找不到合适的运行时。改对之后服务就乖乖起来了。注册成功后去服务管理器运行services.msc应该能看到一个名字类似gitblit的服务。把它设成自动启动这样服务器重启之后它会自己拉起来。手动测试的话在服务上右键启动、停止即可。如果你的脚本里服务名不太一样以脚本里set SERVICE_NAME那一行的实际值为准。这里有个隐蔽的坑服务运行的账户和工作目录可能和你手动运行时不一样。服务默认可能以LocalSystem账户跑而它的工作目录未必是你解压 Gitblit 的那个目录。如果启动失败多半是相对路径解析出了问题。解决办法是在注册脚本里加上set CDD:\gitblit这一类的设置明确指定工作目录。另外服务账户对这个目录要有读写权限尤其是data、logs目录LocalSystem一般权限足够如果你改成别的账户运行记得授权。验证服务是否真的起来了最快的办法就是看logs目录下有没有新的日志文件写入以及浏览器能不能访问。两项都对上就说明服务跑成功了。3.4 首次登录、改密码与权限模型用 admin/admin 登录进去之后右上角进用户设置第一件事就是改掉这个默认密码。这事没有任何商量余地——一个内网服务里存着全部代码管理员密码还是 admin等于把仓库钥匙插在门上。改密码的地方在用户配置里新密码设复杂一点至少别用 123456。改完密码接下来是建用户。Gitblit 的管理界面里用户页签可以新增账号填用户名、显示名、邮箱、初始密码就行。权限模型是分层的系统管理员能管全部普通用户能访问被授权的仓库只读用户只能看不能推。对大多数团队来说建三五个账号就够用了。仓库授权是重点。新建或编辑仓库的时候有一个权限页签可以把具体用户或团队加进来给 Read、Push、Create 等不同级别的权限。这里我有个实践心得不要给所有人管理员权限哪怕团队很小。因为管理员能删仓库一个误操作可能把几个月的提交记录带走。正确的做法是给开发者配置可读取、可推送只在真正需要管理仓库的人身上开管理员。每个仓库的权限可以单独设也可以按团队批量授权团队可以在管理界面里建把人往里塞然后整个团队一起授权人多了省事。Gitblit 还支持匿名访问。web.allowAnonymousAccess设为true的话任何人不登录就能浏览仓库列表。除非你确实想让全公司的人都能看到代码否则保持关闭。我见过有团队图方便开了匿名只读结果过了一段时间发现有外部人员通过内网扫描发现了这个地址虽然只是只读但代码泄露风险已经存在了。这种时候再回头收紧权限已经晚了一步。4. Git for Windows 安装与最小必要配置4.1 下载与安装向导里每一个选项的含义服务端搞定轮到客户端。先去 git-scm.com 下载 Git for Windows安装包名字类似Git-2.4x.x-64-bit.exe。这里提醒一句网上有些第三方站点会把老版本或者捆绑了别的东西的安装包包装得很像官方版认准 git-scm.com 这个官方域名别从搜索结果里随便点一个。热搜里git下载安装教程这个词能说明问题很多人是在这一步就下载到了不对的东西。双击安装前几步是许可协议和安装路径路径保持默认的C:\Program Files\Git就行。真正需要逐项决策的是后面那些勾选项我一个个说。Select Components这一步勾上 Windows Explorer integration 下的Git Bash Here和Git GUI Here这两个能让你在任意文件夹右键直接打开 Git 环境日常很实用。其余像Associate .git* configuration files、Associate .sh files to be run with Bash建议都保持勾选。后面的 TrueType 字体、每日检查更新可选可不选看个人喜好。Choosing the default editor这一步默认是 Vim。如果你没用过 Vim第一次 commit 时它会把你关在一个全屏编辑器里退出得按Esc然后:wq新手很容易懵。我一般改选成 Notepad 或者 VS Code如果有的话。实在没有用系统自带的 Notepad 也比 Vim 友好一点虽然它会有些编码上的小毛病。Adjusting your PATH environment这一步最关键三个选项Use Git from Git Bash only只允许在 Git Bash 里用 git 命令环境变量不动Git from the command line and also from 3rd-party software推荐允许在 cmd、PowerShell 和第三方工具里用 gitUse Git and optional Unix tools from the Command Prompt会把find、sort这些 Unix 工具也塞进 Path可能覆盖系统自带的同名命令不建议选。一定要选中间那个否则后面 TortoiseGit 很可能找不到 git.exe就是热搜里那个configure git.exe 无法识别到 git.exe path问题的常见成因之一。Choosing the SSH executable保持默认的 OpenSSH 就行。Choosing HTTPS transport backend选 Use the OpenSSL library兼容性最好。Configuring the line ending conversions这一项中文叫行结束符转换三个选项里推荐第一个Checkout Windows-style, commit Unix-style它在检出时转成 CRLF、提交时转回 LF能有效避免跨平台协作时的换行符混乱。后面几项终端模拟器、git pull行为、凭据管理器没有特殊需求就保持默认。凭据管理器建议保留 Git Credential Manager它能帮你记住 HTTPS 密码省得每次推送都输。4.2 装完之后 git 命令用不了的排查装完了不等于就能用。最典型的报错就是热搜里那句话git : 无法将git项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查...。这基本只有一个原因PATH 没配好或者你用的是安装时选错的那一档。排查顺序这样走。第一步关掉所有命令行窗口重新开一个。环境变量在窗口启动时加载老窗口不认新配置。第二步敲git --version如果还报错在 cmd 里执行where git看看能不能找到路径。第三步如果where也找不到就去系统环境变量里看看 Path 里有没有C:\Program Files\Git\cmd这一项。没有的话手动加上然后重新开窗口验证。还有一种情况是装了但被别的软件干扰了。有些软件会自带一份精简版的 git把它塞进 Path 前面导致系统调用的不是你刚装的那个完整版。这种时候where git会列出多个路径排在前面的那个就是实际生效的。要么调整 Path 顺序要么在 TortoiseGit 里直接指定完整的 git.exe 路径绕开这个歧义。如果是在 PowerShell 里报错、在 cmd 里正常那可能是 PowerShell 的 profile 脚本改动了 Path。用$env:Path看一下当前会话里的路径对比系统设置找到差别就好办了。4.3 必须做的全局配置与免密方案命令能跑了之后先做几项全局配置这些是一次性设置之后所有仓库都受益。打开命令行git config --global user.name 你的名字 git config --global user.email 你的邮箱公司.com git config --global core.autocrlf true git config --global init.defaultBranch main前两项是身份标识每一次提交都会带上这两个信息写错了历史记录里就留下错误的作者改起来要重写历史很麻烦。所以第一步就把这两个配好。core.autocrlf true配合刚才安装时的换行符选项处理 Windows 和 Linux 协作的换行问题。init.defaultBranch main让新建仓库的默认分支叫 main 而不是 master现在主流托管平台都往这个方向走了本地保持一致能少些困惑。免密这块分两种协议。用 HTTPS 方式克隆第一次推送会弹出账号密码框输对了之后 Git Credential Manager 会记住下次就不问了。用 SSH 方式的话要先在本机生成密钥对把公钥配到 Gitblit 上。命令是ssh-keygen -t rsa -b 4096 -C 你的邮箱公司.com一路回车默认生成在~/.ssh/id_rsa和~/.ssh/id_rsa.pub。id_rsa是私钥绝对不能外传id_rsa.pub是公钥就是你要贴到服务器上的那串文本。这个公钥待会儿在讲 TortoiseGit 的时候会一起说怎么配到 Gitblit。还有个小技巧方便查看历史和提交图git config --global alias.lg log --oneline --graph --all --decorate配完之后敲git lg就能看到漂亮的提交树比默认的git log直观得多。这属于锦上添花但用过就回不去了。5. TortoiseGit 安装与中文包5.1 安装顺序与 configure git.exe 识别问题TortoiseGit也就是大家嘴里的小乌龟官网是 tortoisegit.org。它必须依赖已经装好的 Git for Windows所以正确的顺序是先装 Git再装 TortoiseGit顺序反了后面还得重来。下载安装包选 64 位版本一路下一步。安装完会提示重启电脑或者至少重启一次 Windows 资源管理器任务管理器里找到 explorer.exe 重启因为它是作为资源管理器插件工作的不重启右键菜单里不会出现小乌龟的选项。安装向导走到最后一步通常会有一个Configure Git的界面问你 git.exe 在哪。如果这一步自动填好了说明前面 Git 装得没问题直接下一步。如果这里报错或者你当时点了跳过就会撞上那个经典问题——configure git.exe 无法识别到 git.exe path。表现是 TortoiseGit 装是装了但一操作就提示找不到 git。补救办法是在任意文件夹右键 → TortoiseGit → Settings → General 页找到 Git.exe Path 这一栏。如果它是空的或者填错了手动填进去。正确路径一般有两种C:\Program Files\Git\bin里面有 git.exe或者C:\Program Files\Git\cmd里面有 git.cmdTortoiseGit 也能识别。填完点Check now能弹出 git 的版本号就对了。我建议填C:\Program Files\Git\cmd这个目录因为它同时包含了 git.exe 和 git.cmd兼容性更好。如果之前 4.2 那节里 Path 有问题导致命令行用不了 git那 TortoiseGit 这里多半也识别不到先把命令行的 PATH 修好再来配置它一劳永逸。5.2 中文包不生效的几种原因小乌龟原版是英文的官方提供了语言包LanguagePack。下载的时候版本号必须和主程序完全一致比如主程序是 2.17.0语言包也得是 2.17.0。版本对不上会出现装了没反应或者界面部分汉化、部分还是英文的诡异情况。这就是热搜里tortoisegit中文包不生效出现频率高的原因。安装语言包之后还是去 Settings → General在 Language 下拉框里选中文简体确定。如果下拉框里根本没有中文选项说明语言包没被识别到——重启资源管理器再说或者检查语言包是不是装到了主程序同一个目录下。还有个容易忽略的点语言包对某些对话框和提示的本地化覆盖并不完整尤其是较新的功能可能还是英文。这不是安装错误是翻译进度的问题正常现象不用反复折腾。我用下来觉得核心的提交、推送、分支操作这些高频界面都汉化得挺好日常使用没什么障碍。5.3 SSH Key 生成并配置到 Gitblit免密推送在 TortoiseGit 里稍微绕一点因为它默认用的是 PuTTY 那套密钥体系。有两种方案我分别说。方案一继续用刚才在 Git Bash 里生成的 OpenSSH 密钥。TortoiseGit 也能配置成使用 OpenSSH在 Settings → Network 里把 SSH client 从默认的TortoiseGitPlink改成ssh.exe的路径指向C:\Program Files\Git\usr\bin\ssh.exe。这样它就用你在 Git Bash 里生成的那对密钥了省得再生成一份。方案二用 TortoiseGit 自带的 PuTTYgen 生成一对.ppk格式的密钥。这个工具在开始菜单的 TortoiseGit 程序组里能找到或者在 Settings → Network 里点生成密钥。 生成时它会让你在窗口里随机晃动鼠标来产生随机数晃得越随意越安全。生成完保存私钥.ppk文件和公钥一段文本。不管用哪种方案公钥都要贴到 Gitblit 上。登录 Gitblit 网页面板点右上角进个人用户设置找到SSH Keys页签把公钥内容整段粘进去保存。之后用 SSH 协议克隆仓库地址形如ssh://git服务器IP:29418/仓库名.git就再也不用输密码了。用.ppk方案的话还需要让 TortoiseGit 找到这把私钥。可以在 Settings → Git → Remote 里针对具体仓库指定 PuTTY 私钥文件或者用 Pageant 这个代理工具把.ppk加载进去常驻。我个人偏好 Pageant 方案一次加载所有仓库通用重启后重新加载一下就行。注意私钥文件等同于你的身份凭证随手拷给别人或者放进仓库都会造成安全风险。公钥可以随便给私钥只留在自己机器上。6. 日常使用clone、上传文件与切换分支6.1 Gitblit 网页端建仓与网页上传文件服务端和客户端都齐了开始用。第一步在 Gitblit 网页上建仓库。登录之后找到仓库菜单点新建填仓库名建议用英文和连字符比如project-web别用中文和空格因为仓库名会成为 URL 的一部分中文会编码成乱七八糟的字符命令行里操作也容易出问题。填好之后选访问权限一般设成私有的然后保存。仓库建好之后页面上会显示两个克隆地址一个是 HTTP 的形如http://服务器IP:5080/r/仓库名.git一个是 SSH 的形如ssh://git服务器IP:29418/仓库名.git。把 HTTP 那个复制下来下一步就用。很多人问gitblit如何上传文件答案分两种。一种是通过克隆到本地再推送这是标准做法下一节讲。另一种是 Gitblit 网页自带的上传文件功能——它对单个小文件很顺手进入仓库后找到对应目录有个上传入口选好文件它会直接帮你提交一次。但要注意网页上传对大文件和批量文件很不友好一次传太多或者文件太大容易超时。所以这个功能我只用来传个说明文档、配置文件之类的小东西涉及整个项目还是老老实实走命令行或小乌龟。还有一种情况是仓库是全新的、空的网页上会提示你先做一次初始化。空仓库推代码没问题但如果你本地也不是仓库就得先git init一下加个远程地址再推。这个流程对新手有点绕我在下一节把完整命令列出来。6.2 命令行与图形界面两条路径先说命令行这是基本功理解了它图形界面的一切操作你都能对应上。在自己电脑上找个文件夹打开 Git Bash执行git clone http://服务器IP:5080/r/project-web.git cd project-web这样仓库就落到本地了。往里加文件、改代码然后提交git add . git commit -m 初始化项目结构 git push第一次git push会让你输 Gitblit 的账号密码输完 Git Credential Manager 就记住了。这三条命令里git add .是把所有改动放进暂存区git commit是把暂存区的内容定格成一次历史记录git push是把它送到服务器。理解工作区 → 暂存区 → 本地仓库 → 远程仓库这条链路比死记命令重要得多。如果提交信息写错了比如打错字或者忘了加内容可以用git commit --amend这个命令会把最近一次提交重新打开让你编辑可以改提交信息也可以把刚git add进去的新文件并进这次提交。注意它修改的是最近一次且尚未推送到远端的提交如果已经推上去了再 amend本地和远端的提交历史就会分叉得用push -f强推团队协作时这种操作要慎之又慎。再说 TortoiseGit。同样的流程在克隆下来的文件夹里右键 → Git Commit → master它会弹出提交对话框上半部分列改动的文件勾选要提交的下半部分写提交信息点 Commit。推送则是右键 → TortoiseGit → Push。整个过程不用记命令对不熟悉终端的同事特别友好。TortoiseGit 背后调用的命令如果打开它的日志能看到完整形态类似git -c diff.mnemonicprefixfalse -c core.quotepathfalse --no-optional-locks status ...。这串里-c diff.mnemonicprefixfalse是关闭 diff 时前缀字母的缩写形式-c core.quotepathfalse是让中文文件名在输出里正常显示而不是变成八进制转义码--no-optional-locks是禁止 Git 写一些可选的锁文件避免和图形界面同时操作时冲突。这些参数是 TortoiseGit 自动加的你平时不用管但看到日志里这串东西时知道它是正常现象不是哪里配错了。6.3 TortoiseGit 切换分支等高频操作分支是版本控制的精髓用起来其实很简单。TortoiseGit 里切换分支叫 Switch/Checkout。在仓库文件夹右键 → TortoiseGit → Switch/Checkout在弹出的对话框里选目标分支确定就切过去了。如果本地还没有那个分支点分支下拉框可以看到远程分支选一个它会自动帮你创建本地跟踪分支。建新分支也是类似入口叫 Create Branch起个名字比如feature-login基于当前分支创建然后切过去开始干活。等开发完成再切回主分支合并。这个过程在命令行里是git checkout -b feature-login、git checkout main、git merge feature-login图形界面把这一串变成了几个对话框。日常用 TortoiseGit 最爽的几个功能我列一下右键的 Show log 能看提交历史配合 Show Reflog 还能看本地操作记录误删分支有时候能从这里找回来Revert 能撤销工作区的改动Diff 能对比两个版本的文件差异。学会看日志和 diff排查这段代码是谁改的、什么时候改的这类问题会非常快。切分支的时候有个常见困惑工作区有未提交的改动时切分支可能失败或者带着改动一起切过去。图形界面会弹提示问你怎么处理命令行则会报错让你先 stash 或者提交。我的做法是切分支前先用git status看一眼确认工作区干净再切养成这个习惯能避开很多我的改动去哪了的惊魂时刻。7. 故障速查与安全加固7.1 问题速查表把前面散落的坑集中一下做成一张表出问题的时候对着查能省不少时间。现象最可能的原因处理办法网页打不开服务没启动 / 端口占错 / 防火墙拦截看进程和日志netstat查端口放行防火墙改了端口不生效改的是根目录配置实际读的是 data 目录改 data 目录下的 default.properties命令行提示 git 无法识别PATH 没配或选错了安装档位检查 Path 里的 Git 目录重开窗口TortoiseGit 找不到 gitGit.exe Path 没填或填错Settings 里手动指定点 Check now中文包不生效版本号不匹配装与主程序完全同版本的语言包推送一直要密码没配凭据或没用 SSH用凭据管理器记住或配 SSH 密钥服务开机不自启服务是手动启动类型服务属性里改成自动网页上传大文件失败网页上传有大小和超时限制改用 clone push 方式7.2 备份与迁移自建服务最大的好处是数据在你自己手里但反过来没人替你备份。Gitblit 的数据核心就两样data/git目录所有仓库和data下的配置文件、用户文件。备份策略我推荐两步走。第一步把整个data目录用文件级的方式定期同步到一个另外的存储上比如网络附加存储或者另一台机器。同步工具用系统的任务计划配合 robocopy 之类的就行每天凌晨跑一次。这一步保的是服务器整块硬盘挂了也不怕。第二步针对每个仓库做 Git 级别的镜像备份。用git clone --mirror http://服务器IP:5080/r/project-web.git backup/project-web.git--mirror会把所有分支、标签、引用完整拉下来。之后定期进去git fetch --all更新一下。这种镜像的好处是它是一个标准的裸仓库将来哪怕 Gitblit 不在了直接把这个裸仓库拷到任何支持 Git 的地方都能继续用迁移成本几乎为零。迁移的时候也简单在新机器上把 Gitblit 装好把旧机器的data目录整体复制过去注意路径和端口配置保持一致或者同步修改启动服务即可。仓库的远程地址如果 IP 变了客户端那边得更新一下 remote用git remote set-url origin 新地址一条命令搞定。7.3 加固从 .git 目录暴露说起最后聊一个必须重视的点。Git 仓库运行的时候会在工作目录下生成一个隐藏的.git文件夹里面装着全部历史。如果这个目录被部署到了 Web 服务器的站点根目录下并且没有做访问控制别人就可能通过浏览器直接访问到里面的文件进而还原出整个项目的源码和提交历史。这就是所谓的git 目录泄露搜索引擎里能搜到相关讨论本质上是部署疏忽造成的。防护的办法其实不复杂。不要把 Git 工作目录直接当成网站的发布目录。如果非要在服务器上克隆代码把仓库放在站点目录之外用发布脚本把需要上线的文件复制到 Web 根目录。如果架构上无法避免就在 Web 服务器配置里显式禁止访问.git路径让它直接返回 404。这是一个几行配置就能做好的事却能挡住一大类风险。对 Gitblit 本身除了改掉默认密码、关闭匿名访问还建议把管理后台的访问限制在内网不对外网开放端口定期检查用户列表把离职人员的账号及时停用如果启用了 HTTPS用一张可信的证书别长期用自签证书否则浏览器报错会让人习惯性地忽略警告反而埋下隐患。这些经验听着琐碎但只要服务对外开放过一天就值得按这个标准来一遍。注意内网不等于安全。很多数据泄露的源头恰恰是以为内网没人看的服务。权限和备份这两件事在服务上线第一天就该做好而不是等出事之后补。这套三件套我从头搭到尾的次数多了越发觉得真正的门槛不在软件安装而在于搞清楚每一层在干什么。Gitblit 管的是代码放哪、谁能拿Git 管的是版本怎么变TortoiseGit 管的是怎么让不敲命令的人也玩得转。三者边界清晰出问题的时候先想清楚是哪一层的事答案基本就浮出来了。我个人踩得最惨的一次是服务注册成功后以为万事大吉结果服务器重启没自启第二天全组推不了代码才发现服务是手动启动类型——从那以后我每次部署完都要重启一次机器验证自启。另一个小技巧分享给你给内网的 Gitblit 起个短域名就算 IP 变了也只改一处比挨个通知大家改 remote 地址省心太多。
