在 CentOS 上落地 GitLab CI/CD 的完整方案
一 架构与准备
- 组件分工
- GitLab(服务器):托管代码、解析 .gitlab-ci.yml、调度作业。
- GitLab Runner(执行器):在 CentOS 上运行具体作业,支持 Shell、Docker 等执行器。Runner 可独立部署在同一台或专用机器上。
- 基础环境
- 系统建议:CentOS 7/8(或兼容的 RHEL 系发行版)。
- 开放端口:SSH 22、HTTP 80、HTTPS 443(如使用域名与 HTTPS)。
- 可选:安装 Docker 以便使用容器化作业环境。
二 安装与注册 GitLab Runner
- 安装 Runner(CentOS)
- 添加仓库并安装:
- curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh | sudo bash
- sudo yum install -y gitlab-runner
- 作为服务运行:
- sudo systemctl enable --now gitlab-runner
- sudo gitlab-runner status
- 注册 Runner
- 获取注册信息:进入项目 Settings > CI/CD > Runners,复制 URL 与 Registration token。
- 交互注册:
- sudo gitlab-runner register
- 依次填写:GitLab 实例 URL、项目 Token、Runner 描述、标签(如:linux,shell)、执行器(如:shell 或 docker)。
- 关键选项说明:
- tags:用于匹配作业;若作业未设置 tags,需将 Runner 的 Run untagged jobs 设为 true 才可执行。
- executor:简单场景用 shell;需要隔离与一致性时选 docker。
三 编写 .gitlab-ci.yml 与触发流水线
- 最小可用示例(Shell 执行器)
- stages:
- build_job:
- stage: build
- script:
- echo “Building…”
- mkdir -p build && echo “ok” > build/status.txt
- artifacts:
- test_job:
- stage: test
- script:
- echo “Testing…”
- test -f build/status.txt
- deploy_job:
- stage: deploy
- script:
- when: manual
- only:
- 推送并查看
- git add .gitlab-ci.yml && git commit -m “Add CI” && git push origin main
- 在 CI/CD > Pipelines 查看运行与日志;部署作业可点击 Play 手动触发。
四 常见执行器与场景示例
- Shell 执行器(简单直接,适合已有环境)
- 优点:直接使用宿主机工具链;缺点:环境一致性依赖宿主机。
- Docker 执行器(推荐,环境一致、易扩展)
- 示例(Node.js + 缓存 + 工件):
- image: node:16
- stages:
- cache:
- build_job:
- stage: build
- script:
- artifacts:
- test_job:
- 如需数据库等服务,可使用 services(如 postgres:13)。
五 安全与排错要点
- Runner 与权限
- 使用 shell 执行器时,Runner 以 gitlab-runner 用户运行;涉及写入 /var/www 等目录需提前授权或使用具备权限的部署方式(如通过 SSH 密钥、sudo 规则或制品拉取部署)。
- 分支与触发控制
- 用 only/except 或更推荐的 rules 精确控制作业触发;生产部署建议 when: manual 并配合 rules 限制分支。
- 常见错误
- 作业未运行:检查 tags 是否匹配,或 Runner 是否允许 untagged 作业。
- 脚本换行符问题:Windows 换行(CRLF)导致脚本执行报错,可在 CI 中加入 sed -i ‘s/\r$//’ script.sh 或使用 dos2unix。
- 找不到命令(如 npm: command not found):使用 Docker 执行器或在 Shell 执行器中预装依赖;前端项目可在 CI 中安装 Node.js/npm 后再构建。