私有化代码托管选型：GitLab与Gitea的分支管理及制品实践

起初团队小的时候Git 仓库放哪都无所谓GitHub 免费版用着也挺顺手。可一旦规模上来代码安全性、权限管控、分支保护、制品沉淀这些问题全来了。我见过不止一个团队代码托管还停留在“网盘传压缩包”或者“谁电脑上有一份最新代码”的原始状态等到线上出问题需要快速回滚时发现根本找不到对应版本的制品包。这篇文章把我在私有化版本控制工具上的选型和实践经验整理出来重点解决三件事能部署在自己服务器上、能把分支管明白、能把构建产物和应用版本对应起来。如果你正在做技术选型或者觉得目前的版本管理方式已经拖累了发布效率下面这些内容应该能帮到你。1. 为什么要放弃公共托管平台转向私有化部署大家最常用的 GitHub、GitLab.com 这类公共平台确实方便开箱即用省去运维成本。但放到企业环境里几个现实问题绕不开。1.1 私有化部署解决的三个核心痛点第一是合规与数据主权。有些项目的代码本身就涉及商业机密或者客户合同里明确要求源码和数据不得离开指定网络环境。把代码放在别人的服务器上哪怕签了保密协议心理那关和合规那关都难过。私有化部署后代码、数据库、备份全部落在我自己的机房或云服务器上审计的时候也说得清。第二是访问体验与稳定性。跨地域访问公共平台网络延迟和偶发的服务不可用是常态。有一次 GitHub 大面积故障我们整个研发团队干等了一个上午什么事都做不了。私有化部署在内网或者专有云环境代码克隆和推送的速度快得多而且不受第三方服务状态影响。第三是深度定制和系统集成。公共平台能提供的 Webhook、API 就那么多真要和内部系统深度打通时经常发现能力不够用。自托管以后我可以随意改配置文件、定制钩子脚本、对接统一登录系统甚至给某个团队单独开启一些特殊规则。1.2 什么样的团队需要现在就切换不是所有团队都非得私有化我总结了几种典型场景团队规模在 10 人以上且涉及商业项目或政务类、金融类项目。有合规审计要求需要记录所有代码访问和操作日志。现有流程中已经需要频繁出制品包希望代码和交付物能关联起来。网络环境特殊比如纯内网开发无法访问外部的代码托管服务。如果以上命中三条及以上私有化部署基本是必然选择。2. 主流私有化版本控制工具横向对比GitLab、Gitea、Gerrit、Gogs、Bitbucket工具圈子里讨论最多的是这几款我基于实际使用体验和社区反馈列了一个对比清单。工具资源占用分支管理能力制品管理集成适合规模部署难度备注GitLab高尤其 Omnibus 包强内置极简工作流、保护分支、Merge Request 审批内置 Package Registry可存容器镜像、npm 包等中大型团队中功能全面但吃内存低配服务器会很吃力Gitea低几百 MB 内存就能跑基础分支和 PR 支持够用但不花哨可通过插件或外部工具集成小团队或个人低轻量搭建快适合预算有限的环境Gerrit中强专为代码评审设计基于 Push 的评审流弱需搭配 Jenkins 等外部方案对评审流程有执念的团队高学习曲线陡不习惯的人会觉得反人类Gogs低基础能力类似 Gitea 的早期版本弱个人或极小团队低发展慢新功能少适合极简需求Bitbucket Data Center中高强与 Jira 深度集成内置对 Artifactory 等外部制品库的集成中大型团队偏 Atlassian 系的中高收费但商业支持好2.1 为什么 GitLab 目前仍是综合体验最稳的选择如果团队没有特殊历史包袱我一般建议先评估 GitLab。它把代码托管、CI/CD、制品库、安全扫描都揉进了一个平台里部署一套就能替代好几套系统。尤其是 GitLab 自带的反向代理和 HTTPS 配置比 Gitea 省心不少。版本选择上建议直接上 GitLab Enterprise Edition 的免费版CE 已经合并进 EE 了现在下载的都是同一个包只是 License 决定功能开关。免费版里分支保护、Merge Request、Webhook、Container Registry 这些关键功能都在足够支撑一个成熟团队的日常运作。2.2 Gitea 低配服务器上的另类选择如果你只有一台 2C4G 的小机器又想跑起一个还算体面的版本控制服务Gitea 是典型的高性价比选择。它用 Go 写的单个二进制文件就能跑部署难度低到基本是“解压即用”。功能上虽然没有 GitLab 那么全但分支、标签、Issue、PR、Webhook 这些核心能力都不缺。有团队把 Gitea 跟 Drone CI 搭配使用效果出奇地好轻量、快速、够用。缺点是制品管理这块基本是空白需要自己额外搭一套。2.3 Gerrit 适合评审文化特别重的团队Gerrit 这套东西比较特别它是把代码审查嵌入了 Git 操作流程里。开发者不能直接 push 到分支所有提交都要经过 refs/for 评审每个提交就是一条评审任务。这对很多团队来说过于繁琐但如果你所在的团队追求严格的代码评审质量它确实能提供这种控制力。不过说实话现在用 Gerrit 的新项目越来越少了GitLab 的 Merge Request 配合强制审批规则已经能覆盖绝大多数评审需求。3. 分支管理能力拆解从热词里的场景说起标题里专门强调了“管得住分支”这个能力在日常协作中太关键了。我注意到最近搜索热词里大量都是关于分支切换、合并、清理、冲突处理的操作问题这说明很多人在真实工作中被分支管理难住了。下面我把几个高频场景和工具的能力对应起来说。3.1 分支保护规则master 和 release 分支不是谁都能碰的不管是 GitLab 还是 Gitea都提供了分支保护规则。把 master、main、release 这类核心分支设为保护分支后普通开发者不能直接 push必须发起合并请求Merge Request / Pull Request由指定角色审批后合入。这样就把“直接改主干”的风险彻底堵住了。我在配置分支保护时有个心得不要只保护主干分支像 develop、test、release/ 前缀的分支都应该纳入保护范围。具体规则可以设置成允许合并的角色Maintainer / Owner必须审批次数Approvals Required至少 1-2 次禁止强制推送Force Push开启删除分支时的限制合并后允许删除但保留历史记录3.2 多人并发下的分支策略git flow 还是 trunk-based分支策略没有银弹得看团队和发布节奏。Git Flow 适合版本迭代周期比较长、需要维护多个发布分支的传统项目Trunk-Based 适合要求快速持续集成、主干一直保持可发布状态的互联网团队。不管用哪种在私有化工具里都建议做几件事在仓库说明文档里写清分支命名规范比如 feature/xxx、bugfix/xxx、release/v1.2.3。设置 CI 流水线让每个新 push 的分支都自动跑一遍编译和测试减少合并时的“惊喜”。定期清理已经合并的分支避免分支列表越来越长。VSCode 里清理分支的操作虽然方便但服务端的垃圾分支还是要靠仓库规则配合。3.3 从热词看常见分支操作误区我翻了一下最近大家搜得最多的问题几乎个个都是日常踩坑的高发点这里集中说一下。master 分支 revert 后其他分支合并 master 冲突这种情况非常典型。开发 A 在 master 上 revert 掉了一个提交开发 B 在 feature 分支上继续开发旧功能等 feature 合并回 master 时发现“复活”了被 revert 的内容或者出现大量冲突。根因在于 revert 本质是生成一个新的反向提交它没有删除原提交的历史。feature 分支的合并基还是旧提交Git 会认为 feature 上缺失了 revert 这个改动于是把旧内容又带回来了。处理办法有两个在 feature 分支上重新基于最新的 master rebase解决完冲突再合并。如果 feature 分支已经公开共享不要用 revert 去撤销 master 提交而应该用 revert 配合后续的手动修复或者干脆用 revert 生成反向提交后在合并时使用git merge --strategy ours这种策略去处理。idea dev 分支代码合并到 test合完之后发现少了好几个文件这个和上面是同一个套路的多分支变体。本质上就是合并时解决冲突不够仔细或者分支的基点太旧导致一部分提交被“掩盖”了。我的建议是每次合并前先做一次 diff 对比工具类都支持分支间 diff 预览。GitLab 的 Merge Request 页面上能看到鲜活的改动列表IDEA 里也可以通过 Git 工具栏直接 Compare Branches。别嫌麻烦合并前多看两眼比合并后排查节省十倍时间。eclipse merge 分支、tortoisegit 切换分支很多老牌桌面工具功能并不差问题通常出在概念理解上。比如 TortoiseGit 切换分支时如果不勾选“Clean working tree”本地未提交的改动会跟随切换覆盖到目标分支的场景非常容易发生。操作规范上建议切换分支前先 commit 或 stash 当前改动保证工作区是干净的。这个习惯养成后分支混动导致的线上问题能减少一大半。3.4 分支合规与审计私有化部署最大的一个优势就是可以做操作审计。GitLab 的管理后台能查到谁在什么时间 push 了哪个分支、谁合并了什么 MR、谁改过仓库设置。对于通过等保测评或有内控要求的团队来说这个功能是硬指标。我习惯设置几个审计相关的最佳实践开启仓库的 Audit Events 记录。设置受保护分支的强制审批并且审批记录可追踪。不允许通过命令行强行跳过多人在线评审所有变更都走 MR。4. 制品管理版本控制工具最容易被低估的一环很多团队一直用的“笨办法”是代码打 tag然后手动去 CI 平台找对应构建产物。慢不说还容易搞错关联。实际上现代版本控制工具已经能把“代码版本”和“制品版本”统一起来。4.1 制品仓库是什么和代码仓库是什么关系代码仓库管理的是源码文件和它们的变更历史制品仓库管理的是构建产物也就是编译出来的包、镜像、二进制文件。二者需要建立对应关系某次构建的产物是由哪个 commit 的源码产生的必须可追溯。以 GitLab 为例它自带的 Package Registry 支持存 Maven、npm、PyPI、容器镜像等常见格式。当 CI 流水线跑完后可以把生成的 jar 包或镜像直接推送到对应的 Project 的制品库里并且和当前的 commit、tag 绑定。这样回滚时只需要找到目标 tag 对应的制品拉下来部署就行。4.2 制品管理的一个实战路径我给出一个实操性强的配置套路这套东西在 GitLab 上可以直接落地代码里维护version.txt或使用 Git tag 作为版本来源。.gitlab-ci.yml中定义构建产物路径并配置artifacts关键字把关键产物上传到流水线。发布阶段执行mvn deploy或docker push把制品推送到 GitLab Package Registry。使用rules限定只有 tag 触发的流水线才会执行发布流程。下面是一段简化版的发布流水线配置供参考stages: - build - release variables: MAVEN_OPTS: -Dmaven.repo.local$CI_PROJECT_DIR/.m2/repository cache: paths: - .m2/repository/ build: stage: build script: - mvn compile only: - branches release: stage: release script: - mvn package - mvn deploy artifacts: paths: - target/*.jar only: - tags这样每次打 tag流水线就会自动构建并发布制品代码和制品之间的追溯链路就建立起来了。4.3 制品保留策略与清理制品库如果不设保留策略很快就会被历史构建堆满磁盘。GitLab 里可以配置制品过期时间比如默认保留 30 天或者只保留每个项目最近 N 个制品。注意发布到生产环境的稳定版本建议单独打 tag并设置永久保留不要随过期策略清理掉。5. 私有化部署的落地实操选型、部署、迁移与日常维护这一节我打算把从零开始做私有化部署的关键步骤拆开讲很多细节不亲自踩一遍真的不知道。5.1 硬件与系统环境规划内存是硬指标。GitLab 的 Omnibus 包建议至少 4GB 内存起步8GB 比较舒服。如果同时跑的 CI Runner 数量多建议内存再加大。Gitea 则只需要 1GB 内存就能顺畅跑。系统方面Ubuntu 20.04 LTS / 22.04 LTS 和 Debian 11/12 都是稳妥的选择。存储盘建议单独挂一块数据盘给代码仓库和制品库。原因很直接系统和数据分离后重装系统不会带走代码历史和制品备份恢复也更方便。部署前把域名规划好比如 git.company.com并提前准备好 SSL 证书。证书过期是很多团队忽略的隐患内网用的自签证书每隔一年要换一次经常出问题。我的经验是直接用内网 CA 或 Lets Encrypt 自动续期省心很多。5.2 安装 GitLab 的最小配置与常用优化GitLab 的安装网上教程很多我这里只列几个容易踩坑的点。第一个坑是内存设置。改/etc/gitlab/gitlab.rb时不要贪多默认自带的功能很多但对内存不友好。建议先显式关掉不用的组件。# 关闭不需要的组件节省内存 prometheus_monitoring[enable] false grafana[enable] false第二个坑是外部 URL 配置。一定要把external_url配置成用户真正访问的地址不然项目克隆链接里会出现localhost所有人克隆时都得手动改。external_url https://git.company.com第三个坑是统一登录。企业里一般已经有 AD 或 LDAPGitLab 支持直接对接这样人员入职和离职的账号管理就不用在多个系统里重复操作了。配置完记得用测试账号验证走一遍登录流程再广而告之。5.3 从旧平台迁移到私有化 GitLab如何降低痛苦迁移迁移看似简单做起来细节很多。GitLab 自带项目导入功能可以从 GitHub、Bitbucket 和另一套 GitLab 直接导入。但要注意几点导入前先检查旧仓库的 LFS 对象、大文件、子模块是否完整否则克隆下来缺文件会非常麻烦。如果是历史全部要保留的用git clone --mirror或者 GitLab 后台的导入都行。只迁移最新代码的话建议把新旧仓库的关联断开避免后续误操作。迁移完成后全局搜索一下代码里写死的旧仓库地址特别是 CI 配置、文档、脚本里的 clone 链接全部替换成新地址。旧平台不要急着关停并行运行两到四周给团队缓冲和适应的时间。5.4 CI/CD 集成与 Runner 配置版本控制工具搭完之后接 CI/CD 是顺理成章的下一步。GitLab Runner 的安装类型要选对Kubernetes 环境用 Kubernetes Executor普通服务器用 Shell 或 Docker Executor 即可。Runner 注册的时候有一个 token 概念不同版本的 GitLab 获取路径不同但都在管理区域的 Runner 页面里。注册完成之后在项目里新建.gitlab-ci.ymlGitLab 就会根据配置自动创建流水线并匹配 Runner。一个小建议Runner 和 GitLab 主服务尽可能放在同一内网避免公网传输代码和制品时的带宽瓶颈。如果是跨地域团队可以考虑为单一代码仓库配置镜像克隆地址把 fetch 压力分散到就近节点。6. 几个容易忽视但影响很大的维护细节很多团队部署完版本控制工具就放着不管了等出了事故才想起来。这几个维护维度的坑我全部踩过属于“平时看不见出事就要命”的类型。6.1 备份与恢复永远要提前演练GitLab 的备份命令很简单gitlab-backup create但恢复正常吗建议每季度做一次“备份恢复演练”在测试服务器上把备份文件恢复起来验证数据和权限是否完整。如果这个动作从来没做过等于你在裸奔。备份文件不要只放在本机磁盘复制一份到异地存储或对象存储里防止单机房事故。6.2 大文件的处理策略Git 本身不适合存大文件。如果你发现仓库克隆速度越来越慢、仓库体积膨胀异常按这个顺序去排查git count-objects -vH看仓库对象体积。检查是否有二进制文件、日志文件被误提交进仓库。考虑使用 Git LFS 管理大文件或者把大的静态资源挪到制品仓库/对象存储里代码仓库只保留引用。6.3 安全配置与账号管理改默认端口这件事见仁见智但对外开放的服务建议至少做好三件事开启防火墙只暴露 80/443管控 SSH 端口来源 IP。全员开启两步验证2FA对管理员账号强制要求。定期审查管理员权限权限最小化离开项目的成员及时移除这个最重要。版本控制工具的权限模型一般分 Owner、Maintainer、Developer、Reporter、Guest 几类。实际设置时不要图省事全给 GitLab 权限按角色分好既保护代码也保护发布流程。7. 我的最终推荐与真实心得作为一个从 GitHub 公共仓库起步、踩过私有化部署各种坑的人我给不同阶段的团队一个明确的选型建议10 人以内、服务器资源有限、不想折腾太多直接用 Gitea半小时就能搭完维护成本几乎为零。20 人以上、或者需要 CI/CD、制品库、安全扫描一站式解决直接上 GitLab按企业级标准来配置。对评审流程有特殊要求的团队可以考虑 Gerrit但也要接受它的学习成本。我个人的真实使用体会是工具好不好用不完全看功能列表更要看它能不能顺着团队已经习惯的流程走。GitLab 之所以适合大多数团队是因为它的 Merge Request 工作流和分支保护做得足够顺滑团队成员几乎只需要改变“从直接 push 改成发 MR”这一个习惯。而 Gitea 胜在轻巧适合希望基础设施极简的小团队。最后给一个建议不管选哪套工具先在测试环境把数据备份、灾难恢复、权限审计这些“不常用但保命”的功能全部验证一遍再正式启用。等出问题了才临时研究那个时候越着急越容易犯错。