macos-tools/gitlab/manual-runner-setup.md

GitLab CI/CD 手动设置指南

当前状态

✅ 已完成:

• GitLab CE 16.9.1 实例已启动
• GitLab Runner 容器已运行
• CI/CD 配置模板已创建
• 环境变量配置脚本已准备

⏳ 需要手动完成:

• GitLab 初始密码设置
• Runner 注册 token 获取
• 手动注册 GitLab Runner

手动设置步骤

1. 访问 GitLab 并设置密码

1. 打开浏览器访问: http://192.168.1.83:8890
2. 首次访问会显示设置密码页面
3. 设置管理员密码 (建议: admin123)
4. 使用用户名 root 和设置的密码登录

2. 获取 Runner 注册 Token

有两种方式获取 Runner 注册 token:

方法 A: 实例级别 Runner (推荐)

1. 登录后点击右上角头像
2. 选择 "Admin Area"
3. 左侧菜单找到 "Runners"
4. 点击 "New instance runner"
5. 复制显示的 "Registration token"

方法 B: 群组级别 Runner

1. 创建或选择一个群组
2. 进入群组设置
3. 左侧菜单找到 "CI/CD"
4. 展开 "Runners" 部分
5. 复制注册 token

3. 手动注册 GitLab Runner

打开终端，在 gitlab 目录中运行:

# 注册 Docker Runner
docker exec -it gitlab-runner gitlab-runner register

# 按提示输入以下信息:
# Enter the GitLab instance URL: http://192.168.1.83:8890
# Enter the registration token: [粘贴上面获取的 token]
# Enter a description for the runner: docker-runner
# Enter tags for the runner: docker,build,deploy
# Enter optional maintenance note:
# Enter an executor: docker
# Enter the default Docker image: docker:latest

# 注册 Shell Runner (可选)
docker exec -it gitlab-runner gitlab-runner register

# 按提示输入以下信息:
# Enter the GitLab instance URL: http://192.168.1.83:8890
# Enter the registration token: [使用相同的 token]
# Enter a description for the runner: shell-runner
# Enter tags for the runner: shell,local,scripts
# Enter optional maintenance note:
# Enter an executor: shell

4. 验证 Runner 状态

在 GitLab 管理界面的 Runners 页面检查是否能看到已注册的 Runner。

5. 为 Stock 项目配置 CI/CD

创建测试项目

1. 在 GitLab 中创建新项目，例如 "stock-project"
2. 克隆项目到本地
3. 添加 CI/CD 配置文件

使用提供的模板

# 复制简化配置模板
cp gitlab/ci-templates/.gitlab-ci.yml.simple /path/to/stock-project/.gitlab-ci.yml

# 或者使用完整配置模板
cp gitlab/ci-templates/.gitlab-ci.yml.stock /path/to/stock-project/.gitlab-ci.yml

配置环境变量

运行环境变量配置脚本:

cd gitlab
./setup-ci-env.sh stock-project dev

或者在 GitLab UI 中手动配置:

1. 进入项目设置
2. CI/CD -> Variables
3. 添加必要的环境变量

6. 测试 CI/CD 流水线

1. 创建一个简单的测试文件
2. 提交并推送到 GitLab
3. 观察流水线是否自动运行

快速测试命令

创建一个测试项目:

mkdir test-stock-project
cd test-stock-project
git init
echo "# Test Stock Project" > README.md
echo 'console.log("Hello from CI/CD!");' > test.js

# 添加 package.json
cat > package.json << 'EOF'
{
  "name": "test-stock-project",
  "version": "1.0.0",
  "scripts": {
    "test": "echo 'Running tests...' && node test.js"
  }
}
EOF

# 复制 CI/CD 配置
cp /Users/brunogao/work/codes/tools/macos/gitlab/ci-templates/.gitlab-ci.yml.simple .gitlab-ci.yml

# 提交并推送
git add .
git commit -m "Initial commit with CI/CD"
git remote add origin http://192.168.1.83:8890/root/test-stock-project.git
git push -u origin main

故障排除

GitLab 无法访问

• 检查容器状态: docker ps | grep gitlab
• 查看日志: docker logs gitlab-ce
• 确认端口映射: docker port gitlab-ce

Runner 无法注册

• 确认 GitLab 完全启动 (通常需要 5-10 分钟)
• 检查网络连接
• 验证注册 token 是否正确

流水线不运行

• 确认 Runner 已注册且状态为 "online"
• 检查 .gitlab-ci.yml 文件语法
• 确认 Runner 标签与流水线要求匹配

下一步

完成手动设置后，你将拥有一个完整的 GitLab CI/CD 环境，可以用于:

• 自动化测试
• 代码质量检查
• 自动构建和部署
• 安全扫描
• 环境管理

所有配置文件和脚本都已保存在 gitlab/ 目录中，可供参考和定制。