在 Debian 上用 GitLab 搭建团队协作环境
一 环境准备与安装
- 更新系统并安装依赖
- sudo apt update && sudo apt upgrade -y
- sudo apt install -y curl openssh-server ca-certificates tzdata perl
- 可选:安装邮件服务 sudo apt install -y postfix(用于通知与找回密码)
- 添加 GitLab 官方 APT 仓库并安装
- curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
- 设置外部访问地址并安装:sudo EXTERNAL_URL=“http://your-domain-or-ip” apt install -y gitlab-ce
- 初始化与启动
- 应用配置:sudo gitlab-ctl reconfigure
- 常用运维:sudo gitlab-ctl start|stop|restart|status
- 日志排查:sudo gitlab-ctl tail;服务日志位于 /var/log/gitlab
- 防火墙放行
- sudo ufw allow 80/tcp
- sudo ufw allow 443/tcp
- sudo ufw allow 22/tcp
- sudo ufw reload
- 访问与初始化
- 浏览器访问配置的 external_url,首次使用 root 账户设置密码
- 建议为生产环境启用 HTTPS/Let’s Encrypt(见下文)
二 团队与项目初始化
- 创建项目与成员邀请
- 登录后新建项目,选择可见性:Private / Internal / Public
- 项目设置 → 成员 → 添加成员并分配角色(如 Developer / Maintainer / Reporter)
- 本地克隆与初始提交
- git clone git@your-domain-or-ip:group/project.git
- cd project && git config --global user.name “Your Name” && git config --global user.email “you@example.com”
- echo “# project” > README.md
- git add . && git commit -m “init” && git push -u origin main
- 分支策略建议
- 主干分支:main(受保护,仅允许通过合并请求合入)
- 开发分支:develop
- 功能分支:feature/,修复分支:bugfix/,发布分支:release/,热修复:hotfix/
三 协作流程与代码质量
- 基于 Merge Request 的协作
- 从功能分支推送:git checkout -b feature/login && git push origin feature/login
- 在 GitLab 发起 Merge Request(MR):源分支 feature/login → 目标分支 develop
- 指派评审人、设置 WIP(Work In Progress)状态,讨论与迭代后合并
- 代码审查与自动化
- 在 MR 中进行行级评论、批注与建议;通过后合并
- 提交信息关联任务:在提交或 MR 描述中使用 Fixes #123 自动关闭 Issue #123
- 议题与里程碑
- 使用 Issues / Labels / Milestones 管理需求与缺陷、分配负责人、跟踪进度
- 持续集成与交付
- 在项目根目录创建 .gitlab-ci.yml 定义流水线(示例见下文)
- 安装 Runner:sudo apt install -y gitlab-runner
- 注册 Runner:sudo gitlab-runner register(选择 shell 或 docker 执行器),完成后在项目设置中启用
- 示例 .gitlab-ci.yml(Node.js)
- stages: [build, test, deploy]
- build_job:
- stage: build
- script:
- artifacts:
- test_job:
- stage: test
- script: npm test – --ci
- deploy_job:
- stage: deploy
- script:
- rsync -avz --delete dist/ user@server:/var/www/app/
- only: [main]
四 安全与运维要点
- 权限与访问控制
- 项目级与组级权限精细化配置;保护 main 分支,要求 MR、评审与流水线通过后再合并
- 网络安全
- 仅开放 80/443/22;限制数据库、Redis 等内部管理端口对外访问
- 启用 HTTPS/TLS;生产环境建议使用 Let’s Encrypt
- 在 /etc/gitlab/gitlab.rb 中启用:
- letsencrypt[‘enable’] = true
- letsencrypt[‘contact_emails’] = [‘admin@example.com’]
- 重新配置:sudo gitlab-ctl reconfigure
- 备份与恢复
- 手动备份(默认路径 /var/opt/gitlab/backups):sudo gitlab-rake gitlab:backup:create
- 恢复:sudo gitlab-ctl stop → sudo gitlab-rake gitlab:backup:restore BACKUP=备份文件名 → sudo gitlab-ctl start
- 资源与维护
- 建议生产环境至少 4GB 内存,团队与 CI 负载较高时提升配置
- 定期更新系统与安全补丁,监控 /var/log/gitlab 与关键指标
- 如需容器化部署,可使用官方 Docker 镜像并挂载配置/数据/日志卷,合理规划端口映射与资源配额
五 常见问题与快速排障
- 访问异常:检查 external_url、防火墙与端口占用(ss -tlnp | grep ‘:80|:443|:22’)
- Runner 不可用:确认 Runner 已注册、状态为 active,并与项目可见性/Runner 标签匹配
- 合并受阻:确认目标分支保护策略、评审通过、流水线成功,必要时使用 rebase 或 squash and merge
- 邮件无法发送:核对 SMTP 配置并重载:sudo gitlab-ctl reconfigure
- 升级与回滚:遵循官方升级路径,先备份再执行 apt 升级,保留最近可用版本以便回滚