1. 为什么我要折腾一个自建代码托管平台作为一个常年跟代码打交道的开发者我对“代码放哪”这件事一直比较敏感。公司内部项目丢私有GitLab个人开源项目丢GitHub这几乎是行业默认配置。但在实际使用过程中我越来越清楚地意识到一个问题把代码交到第三方平台手里本质上是在用便利换主权——特别是当你手里的仓库越来越多、团队协作成员越来越杂、公司的合规要求越来越严格的时候自建一个代码托管平台就成了绕不开的选项。我之前试过GitLab功能确实全面但资源占用实在离谱。一台2核4G的轻量服务器跑个GitLab CE直接把内存吃到90%以上光PostgreSQL和Redis就把家底掏空一半更不用说Gitaly、Puma、Sidekiq这些组件每个都要占一块内存。后来也试过Gitea轻倒是轻但我个人对它的维护节奏和部分设计一直有点不放心。直到我接触到Madeira这个基于Rust写的开源Git托管平台才感觉终于找到了一个真正符合预期的方案。Madeira这个名字你可能不太熟悉它定位是“永久免费、完全开源、内置CI/CD、低资源占用的自托管Git服务”。最打动我的一点是它的社区版和商业版没有任何功能阉割也不像某些平台那样在许可证条款里藏着陷阱。换句话说只要你愿意动手你就能拥有一个属于自己的、功能齐全的代码托管平台而且不必付出高昂的授权费用。这篇文章我会把自己从选型到部署、再到日常维护踩过的坑全部梳理一遍。如果你正在纠结要不要自建Git服务器或者已经受够了自家平台的内存告警那这篇应该能帮你省下不少时间。2. 选型对比GitLab、Gitea、Madeira的硬核差距2.1 资源占用是我换平台的第一个理由选型这件事我向来主张拿数据说话。我分别在三台配置完全相同的2核4G服务器上部署了GitLab CE、Gitea和Madeira然后做了一个最简单的压力测试同时克隆一个200MB的仓库观察各自的内存和CPU表现。测试结果让我挺意外的。GitLab CE刚启动完就吃掉了将近3.5GB内存CPU空闲状态下依然有5%-10%的占用率因为后台的Sidekiq队列和Prometheus监控一直在跑。Gitea确实很轻整套服务稳定在200MB左右的内存占用CPU几乎可以忽略不计但在功能完整性上明显做了取舍——它的内置CI/CD能力非常基础很多流程还是要依赖外部工具比如Drone、Jenkins来补齐。Madeira的表现介于两者之间但更偏向Gitea那一侧。基于Rust写的原生编译二进制单进程运行不依赖额外的数据库服务——它直接用Git的裸仓库文件系统做存储配合SQLite记录元数据。实测下来稳定运行时的内存占用大概在300MB左右CPU在闲置时基本处于0.1%以下这个表现让我直接把它列入了候选名单。2.2 功能完整度比GitLab差在哪、好在哪很多人一听“轻量”就觉得功能肯定缺胳膊少腿实际上Madeira在功能完整度上做得比我想象中好很多。它内置了完整的仓库管理、分支保护、Pull Request流程、Issue追踪、Wiki、项目看板、团队权限控制这些日常高频功能一个都不少。跟GitLab对比缺失的主要是那些企业级的高级特性比如多集群Kubernetes集成、复杂的审计日志规则、父子流水线依赖图。说实话这些功能对于绝大多数中小团队和个人开发者来说一年都用不上几次。反而Madeira自带一套基于YAML配置的CI/CD引擎配置语法和GitLab CI非常相似迁移成本极低——如果你已经把GitLab的.gitlab-ci.yml写得滚瓜烂熟切换到Madeira的.madeira-ci.yml几乎可以无缝上手。作为对比Gitea在CI这块确实要薄一些它的Actions功能虽然一直在迭代但很多第三方插件和Runner的兼容性问题依然存在。Madeira从底层架构上就为CI/CD做了专门优化构建任务的调度、缓存管理和日志流式输出都做得很细致这一点在实际使用中体感非常明显。2.3 社区与生态沉淀下来才是真正能用的东西选一个开源项目不能只看它今天多能打还得看它能不能持续进化。Madeira的代码托管在GitHub上提交频率相当稳定基本上每个月都有功能更新和bug修复社区讨论区也很活跃。虽然它的用户基数跟GitLab不是一个量级但好处是核心团队对issue的响应速度很快我提过一个关于SSH端口配置的文档问题两天之内就被关闭并补充了说明。另外一个值得提的点是Madeira对硬件要求极其友好这意味着你不需要专门买一台高配服务器来伺候它。我在自己的NAS上跑了一个实例用Docker方式部署内存限制设为512MB运行了大半年没有任何异常。相比之下GitLab在NAS上根本跑不动——光是Ruby进程组的内存需求就让人头疼。维度GitLab CEGiteaMadeira内存占用3-4GB200MB300MB编程语言Ruby/Go混合GoRust内置CI/CD完整、但依赖组件多基础完整、轻量许可证部分功能商业版MITApache-2.0部署复杂度高低低适合场景中大型企业极简需求轻量完整CI诉求3. 实操过程从零搭建一个可用的Madeira服务3.1 环境准备与Docker部署方案我选择用Docker方式部署原因很简单升级方便、环境隔离、回滚容易。如果你不想用Docker官方也提供Linux下的二进制直接运行方式但需要手动管理systemd服务、数据目录权限和进程守护灵活但繁琐。先交代一下我的部署环境一台Debian 12服务器2核4G配置系统盘剩余空间80GB。网络方面我给它分配了一个域名解析到这台机器的公网IP为了后续配置HTTPS做准备。在生产环境里我强烈建议不要裸奔HTTP除非你只是在内网自嗨。Docker安装阶段就跳过命令了任何一台现代Linux发行版都可以通过官方脚本快速完成。重点来看docker-compose.yml这个文件我用了很长一段时间之后最终定稿的配置是这样的version: 3.8 services: madeira: image: madeira/madeira:latest container_name: madeira restart: always ports: - 3000:3000 - 2222:22 volumes: - ./data:/var/lib/madeira - ./config:/etc/madeira - /etc/ssl/madeira:/etc/ssl/madeira:ro environment: - MADEIRA_DOMAINgit.yourdomain.com - MADEIRA_HTTP_PORT3000 - MADEIRA_SSH_PORT2222这里有两个关键点需要解释一下。第一个是SSH端口映射。因为我的服务器上跑了其他服务22端口被系统SSH占用所以我把Madeira的SSH端口映射成了2222。这意味着你在克隆仓库的时候URL里不能直接用gityourdomain.com:user/repo.git而要写成ssh://gityourdomain.com:2222/user/repo.git。如果不希望这样最简单的办法是让你的宿主机SSH占用其他端口把22端口让给Madeira。第二个关键点是数据卷挂载。我单独把./data和./config两个目录挂出来目的只有一个备份恢复时不用折腾容器内部路径。Docker容器被删了重建只要这两个目录还在数据就不会丢。很多新手是在这一步栽了跟头以为容器还在就等于数据安全结果清理无用的镜像时手一抖把容器也删了连着内部数据一起消失。3.2 配置域名与反向代理让服务暴露得干净一点Docker起来之后Madeira默认监听3000端口。如果你打算直接用IP加端口的方式访问也不是不行但生产环境建议用域名加HTTPS的组合。我用Nginx做反向代理配置非常简单server { listen 80; server_name git.yourdomain.com; return 301 https://$host$request_uri; } server { listen 443 ssl; server_name git.yourdomain.com; ssl_certificate /etc/letsencrypt/live/git.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/git.yourdomain.com/privkey.pem; client_max_body_size 500m; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } location /api/ { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } }这里有一个细节很容易被忽略client_max_body_size。Git仓库在推送大文件时HTTP请求体可能非常大。如果Nginx默认的1MB限制没有调整你会发现推送超过50MB的仓库时进度条卡死在最后一步然后报出413 Request Entity Too Large。我一开始就被这个问题坑了半小时还以为是Madeira配置出了问题。另外一个细节是WebSocket代理头。如果你的团队会用到MadeiraWeb终端功能在线查看仓库文件、执行简单命令就必须在/api/路径下加上Upgrade和Connection头否则WebSocket连接会失败。这个坑我在升级到某个版本后才遇到因为旧版本不需要WebSocket新版本加了在线终端功能后我一度以为反向代理坏了。3.3 SSL证书与SSH公钥的收尾配置证书我用Lets Encrypt申请借助certbot自动续期。配置好Nginx之后重启服务https访问就能正常跑起来。如果你对证书续期有担忧可以加一个cron任务每个月自动执行certbot renew再把Nginx reload一下。到这里基础的部署就算完成了。但第一次用管理员账号登录后台之后我建议先做以下几件事第一在管理面板里关闭公开注册功能。默认情况下Madeira允许任何人注册账号内网无所谓但如果是公网环境开放注册意味着任何人可以拉取你公开仓库的代码或者创建仓库消耗磁盘这不是什么大问题但会让垃圾账号泛滥。第二配置邮件服务。没有邮件服务就没办法发送注册验证邮件、密码重置链接和通知邮件。我一开始跳过这一步结果有个同事忘记密码之后点“找回密码”迟迟收不到邮件最后只能在后台手动重置密码。第三调整默认的仓库大小限制。Madeira默认单仓库大小限制是2GB如果你的团队会存放一些较大的二进制文件或数据集建议在管理面板里调高。当然这只对HTTP推拉起约束作用SSH协议不受这个限制影响。4. 团队权限、CI/CD与日常运维的核心细节4.1 权限模型从个人项目到企业级协作Madeira的权限体系设计得比较清爽不像有些平台把权限搞得比操作系统还要复杂。它有四个层级平台管理员、组织所有者、仓库管理员、普通成员。平台管理员拥有最高权限可以管理所有用户、所有组织和系统设置。组织所有者管理自己组织下的项目、成员和团队。仓库管理员管理单个仓库的分支、合并请求和协作者。在实际使用中我摸索出一套最适合我们团队的模式整个公司一个组织每个项目独立仓库研发小组对应一个Team然后给Team分配仓库的读取或写入权限。这样新同事入职只需要把他加入对应的Team所有相关仓库的权限自动生效不需要每个仓库手动配置一遍。分支保护是另外一个非常值得用起来的功能。我在主分支main上开启了“禁止直接推送必须走Pull Request”的规则同时限定只有仓库管理员可以合并。这样有效避免了有人图省事、绕过Review直接把半成品代码推到主分支的情况。推送规则还支持正则表达式匹配路径也就是你可以做到“特定目录只允许特定角色修改”这在多团队协作一个仓库时非常有用。4.2 内置CI/CD跟GitLab CI几乎无缝迁移Madeira内置的CI/CD引擎对我这种从GitLab迁移过来的用户来说友好程度远超预期。流水线定义文件在仓库根目录下的.madeira-ci.yml写法跟GitLab CI基本一致也有stages、jobs、before_script、artifacts、cache这些关键词。举个例子一个简单的Go项目流水线大概是这样的stages: - build - test - deploy build-job: stage: build image: golang:1.21 script: - go mod download - go build -o myapp . artifacts: paths: - myapp expire_in: 1 week test-job: stage: test image: golang:1.21 script: - go test ./... -coverprofilecoverage.out needs: - build-job deploy-job: stage: deploy image: alpine:latest script: - apk add --no-cache openssh-client - scp myapp rootprod-server:/opt/apps/ only: - main这里的artifacts天然支持作业之间的产物传递。构建阶段生成的二进制测试阶段可以直接使用部署阶段再传给生产服务器。我在配置Runner的时候把它理解成一个轻量化的Jenkins AgentRunner从队列里拉取任务在隔离的容器环境中执行脚本日志流式回传任务结束后销毁容器不留下任何污染。Runner的配置也是一条命令的事在管理面板里生成一个注册token然后执行madeira runner register --token xxx。Runner可以跑在和Madeira同一台机器上也可以单独部署到其他机器上后者更适合需要隔离构建环境的大型项目。实测下来同样一个包含50个job的流水线Madeira Runner的调度速度比我的旧Jenkins快了一个量级——起一个新容器只要几百毫秒相比之下Jenkins启动一个agent的耗时简直感人。4.3 备份与恢复我做了一次完整的容灾演练自托管平台最怕的就是数据丢了没法恢复。GitLab在备份这块做得非常重动不动就是几个GB的打包文件。Madeira的数据结构简单得多裸仓库文件加上元数据数据库。我的备份策略是每天凌晨3点用rclone把./data和./config整个目录同步到对象存储上保留最近7天的备份。恢复的时候只需要把目录放回去重启容器即可。步骤不超过5分钟。为了验证这个过程可靠我特意做了一次演练把容器停掉将数据目录改名然后用备份目录覆盖回来再启动容器。登录后台所有仓库、成员、权限、CI记录全部完好如初。唯一需要留意的是如果你中途改过域名或邮件服务配置恢复时可能需要在后台重新确认一下设置。5. 常见问题与排查技巧实录5.1 注册邮件发不出去的真相这个是我踩过最深的坑。明明在后台配置了SMTP发送测试邮件也提示成功但用户注册时就是收不到验证邮件。排查了老半天最后发现是服务器所在的云厂商把25端口给封了——很多云厂商默认不允许外发25端口的SMTP流量防止垃圾邮件泛滥。解决方案是改用465端口SMTPS或587端口SMTPSTARTTLS并在配置里明确指定端口和加密方式。如果你用的是国内云服务器这个问题几乎一定会遇到建议提前规划。不要一上来就怀疑配置写错先自查一下出网端口是否被限制。5.2 SSH克隆时提示Permission denied这个问题的成因比较多我整理了一个排查顺序第一步确认SSH公钥是否已经添加到后台的账户设置里。注意要添加的是公钥不是私钥很多人搞反了。第二步测试ssh -T gityourdomain.com -p 2222看能不能正常返回欢迎信息。如果提示连接被拒检查防火墙是否放行了对应端口。第三步确认克隆URL里写的是端口2222而不是系统SSH的22端口。还有一个比较隐蔽的坑如果你用多个Git服务~/.ssh/config文件里可能会为同一个Host配置了错误的IdentityFile。解决办法是给不同的Git服务配不同的Host别名。配置文件里指定正确的HostName和Port避免默认私钥冲突。我在同时使用GitHub和Madeira的时候就遇到了这个问题GitHub用着正常但Madeira一直认证失败原因就是config文件里把同一个私钥指向了错误的主机。5.3 CI任务一直卡在pending状态这个通常不是Madeira的问题而是Runner没有注册成功或者标志不对。检查三步Runner进程是否存活Runner是否注册到了正确的实例地址Runner的标签是否匹配流水线中指定的tags关键词。我之前有一台Windows机器想作为Runner结果注册的时候没有指定平台的执行器导致Runner无法处理Docker类型的job。后来在注册命令里显式指定--executor docker问题就消失了。另外需要注意如果你的Runner部署在NAT后面它主动连接Madeira服务端不需要入站端口但出站到Madeira服务端的端口必须畅通。5.4 大仓库克隆速度慢的优化办法Git本身对大仓库的克隆就不太友好尤其是包含大量历史提交的仓库首次克隆要下载全量对象。Madeira支持在仓库设置里开启“浅克隆”推荐在克隆命令上也可以加上--depth1参数减少数据量。对于长期维护下来的大仓库可以从推送规范上做优化不要往仓库里提交编译产物、依赖包、媒体资源等大文件。如果实在要存大文件可以用Git LFS配合Madeira的LFS支持它默认集成了LFS存储层不用额外部署LFS服务器。这一点比一些竞品做得更好很多开源平台都有LFS插件但默认启用的并不多。实测一个2GB的LFS仓库拉取速度稳定在80MB/s左右对我来说完全够用了。6. 我在实际使用中的几点体会用了大半年Madeira之后我真心觉得它在“轻量与功能完整”之间找了一个很舒服的平衡点。它确实不是功能最全的那个但它是让我在没有运维团队的情况下也能安心跑起来的那个。从部署到日常维护整个链路清清爽爽没有一堆半自动化的组件在后台互相拉扯。对于个人开发者、中小团队、以及想在NAS或小型服务器上自托管Git服务的场景它都非常合适。最后分享一个小技巧Madeira升级其实非常省心——Docker方式部署的话拉取新镜像并重建容器就行数据目录自动兼容我大版本升级过两次没有遇到任何需要手动迁移的问题。如果你还对外面的托管平台有所顾虑或者单纯想给自己保留一个完全自主的代码堡垒找一个周末下午部署一套你会回来感谢这个项目的。