GitLab-Runner Shell的安装和配置手册¶

安装Gitlab-Runner¶

在线安装¶

# 1. 添加 GitLab 官方仓库
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

# 2. 安装 runner
sudo apt update
sudo apt install gitlab-runner -y

# 3. 验证安装
gitlab-runner --version

# 应输出 v18.5.0 或类似

离线安装¶

下载各种安装包

https://gitlab.com/gitlab-org/gitlab-runner/-/releases

安装

# 示例：下载 v18.5.0 的 amd64 版本
# VERSION="v18.5.0"
# ARCH="amd64"  # 或 arm64
# wget https://gitlab-runner-downloads.s3.amazonaws.com/${VERSION}/binaries/gitlab-runner-linux-${ARCH} -O gitlab-runner

wget https://gitlab-runner-downloads.s3.amazonaws.com/v18.5.0/binaries/gitlab-runner-linux-amd64 -O gitlab-runner

# 添加执行权限
chmod +x gitlab-runner
sudo mv gitlab-runner /usr/local/bin/

gitlab-runner --version

创建用户

sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner
# 如果要用 Docker
sudo usermod -aG docker gitlab-runner

启动并设置开机自启（systemd）¶

安装 systemd 服务

# sudo vim /etc/systemd/system/gitlab-runner.service
[Unit]
Description=GitLab Runner
After=network.target

[Service]
Type=simple
User=gitlab-runner
Group=gitlab-runner
WorkingDirectory=/home/gitlab-runner
ExecStart=/usr/local/bin/gitlab-runner run --config /etc/gitlab-runner/config.toml
Restart=always
RestartSec=120
EnvironmentFile=-/etc/sysconfig/gitlab-runner

[Install]
WantedBy=multi-user.target

赋权

sudo mkdir -p /etc/gitlab-runner
sudo chown -R root:gitlab-runner /etc/gitlab-runner/
sudo chmod 750 /etc/gitlab-runner/

启动服务

# 重载 systemd 配置（必须！）
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start gitlab-runner
sudo systemctl restart gitlab-runner
# 设置开机自启
sudo systemctl enable gitlab-runner

验证状态

sudo systemctl status gitlab-runner
# 查看日志
journalctl -u gitlab-runner -f

配置 Registration Token¶

登录 GitLab；
进入你的项目或群组；
路径：
项目级：项目 → Settings → CI/CD → Runners → Expand
群组级：群组 → Settings → CI/CD → Runners
复制 Registration token（一串字母数字，如 glrt-xxxxx 或旧版 xxxxxx）

📌 注意：token 是注册用的，不是 .gitlab-ci.yml 中的变量！

注册Gitlab-Runner¶

离线注册命令（在目标服务器执行）¶

sudo gitlab-runner register \
  --non-interactive \
  --url "http://43.138.63.167:7979/" \
  --registration-token "YOUR_REGISTRATION_TOKEN_HERE" \
  --executor "shell" \
  --description "offline-shell-runner" \
  --tag-list "deploy,shell" \
  --run-untagged=false \
  --locked=false

参数说明：

--non-interactive：非交互式，适合脚本；
--executor "shell"：使用 shell 执行器（适合部署）；
其他 executor 如 docker 也可，但需提前安装 Docker。

注册成功后

配置文件自动生成：/etc/gitlab-runner/config.toml
Runner 会自动启动并连接 GitLab（需服务器能访问 GitLab 的 443 端口）
⚠️ 注意：“离线安装” ≠ “完全断网运行”
Runner 仍需能访问 GitLab 服务器（用于拉取任务、上报状态），但不需要访问互联网。

可能出现的问题¶

文件权限问题修复¶

📌 为什么会出现这个问题？你最初可能用 sudo gitlab-runner register 或 sudo gitlab-runner run 初始化了 Runner；这些命令以 root 身份创建了 .runner_system_id；但后来改用 gitlab-runner 用户运行服务，权限未同步。

测试和验证

# 检查权限
ls -la /etc/gitlab-runner/config.toml
ls -la /etc/gitlab-runner/.runner_system_id
# 应显示：-rw-r----- 1 root gitlab-runner ...
# 测试读取
sudo -u gitlab-runner cat /etc/gitlab-runner/config.toml
sudo -u gitlab-runner cat /etc/gitlab-runner/.runner_system_id
# 应成功输出一串 UUID（如：s_b76398b7a01d...）

修复

sudo chown -R root:gitlab-runner /etc/gitlab-runner/
sudo chmod 750 /etc/gitlab-runner/

sudo chown root:gitlab-runner /etc/gitlab-runner/config.toml
sudo chmod 640 /etc/gitlab-runner/config.toml

sudo chown root:gitlab-runner /etc/gitlab-runner/.runner_system_id
sudo chmod 640 /etc/gitlab-runner/.runner_system_id

作业在阶段失败Prepare environment¶

如果某个作业在阶段失败Prepare environment，很可能是 Shell 配置文件中的某些内容导致了失败。常见的失败情况是尝试.bash_logout清除控制台。要解决此错误，请检查/home/gitlab-runner/.bash_logout。例如，如果.bash_logout文件包含如下脚本部分，请将其注释掉并重新启动管道：

if [ "$SHLVL" = 1 ]; then
    [ -x /usr/bin/clear_console ] && /usr/bin/clear_console -q
fi