rent/deploy/docker/GITEA_RUNNER_SETUP.md

Gitea Runner 配置指南

前提条件

• Gitea 已通过 Docker 部署并运行
• 有服务器 SSH 访问权限
• Docker 和 Docker Compose 已安装

配置步骤

1. 获取 Runner Registration Token

1. 登录 Gitea Web 界面（http://your-server:3002）
2. 进入仓库：rent 项目
3. 点击 Settings → Actions → Runners
4. 点击 "Create new Runner" 按钮
5. 复制显示的 Registration Token（类似：abcd1234efgh5678ijkl）

2. 在服务器上设置环境变量

SSH 登录到服务器后，编辑环境变量文件：

# 进入 docker 部署目录
cd /path/to/deploy/docker

# 创建或编辑 .env 文件
nano .env

添加以下内容（替换为实际的 Token）：

GITEA_RUNNER_TOKEN=your_actual_registration_token_here

保存并退出（Ctrl+O, Enter, Ctrl+X）

3. 启动 Gitea Runner

# 确保在 docker-compose.gitea.yml 所在目录
cd /path/to/deploy/docker

# 启动 Runner（如果 Gitea 已运行，只启动 runner）
docker-compose -f docker-compose.gitea.yml up -d act-runner

# 或者重启整个 Gitea 服务
docker-compose -f docker-compose.gitea.yml up -d

4. 验证 Runner 状态

检查容器运行状态

docker ps | grep rent-act-runner

应该看到类似输出：

CONTAINER ID   IMAGE                      STATUS         PORTS     NAMES
abc123def456   gitea/act_runner:latest   Up 2 minutes             rent-act-runner

查看 Runner 日志

docker logs rent-act-runner

成功的日志应该包含：

Runner registered successfully
Labels: self-hosted,rent-deploy

在 Gitea Web 界面验证

1. 返回 Settings → Actions → Runners
2. 应该看到 rent-deploy-runner 状态为 Online ✅
3. 标签显示为 self-hosted, rent-deploy

5. 测试 CI/CD

推送代码到 test 分支触发工作流：

# 在本地开发机器
git checkout test
git merge dev
git push origin test

在 Gitea Web 界面查看 Actions 执行情况：

• 仓库 → Actions → 查看工作流运行状态

常见问题

Runner 状态显示 Offline

原因：

• Token 不正确
• Runner 容器未启动
• 网络连接问题

解决：

# 查看日志
docker logs rent-act-runner

# 重新注册（先停止并删除旧容器）
docker-compose -f docker-compose.gitea.yml down act-runner
docker volume rm rent-act-runner_act_runner_data
docker-compose -f docker-compose.gitea.yml up -d act-runner

Docker 权限错误

如果看到 "permission denied while trying to connect to the Docker daemon socket"：

# 检查 /var/run/docker.sock 权限
ls -l /var/run/docker.sock

# 如果需要，调整权限
sudo chmod 666 /var/run/docker.sock

重新配置 Runner

# 停止 Runner
docker-compose -f docker-compose.gitea.yml stop act-runner

# 删除 Runner 数据（会清除注册信息）
docker volume rm docker_act_runner_data

# 更新环境变量中的 Token
nano .env

# 重新启动
docker-compose -f docker-compose.gitea.yml up -d act-runner

查看实时日志

docker logs -f rent-act-runner

配置说明

环境变量

• GITEA_INSTANCE_URL: Gitea 实例地址（容器内网络地址）
• GITEA_RUNNER_REGISTRATION_TOKEN: 从 Gitea 获取的注册 Token
• GITEA_RUNNER_NAME: Runner 名称（可自定义）
• GITEA_RUNNER_LABELS: Runner 标签，必须包含 self-hosted,rent-deploy

卷挂载

• /var/run/docker.sock: 允许 Runner 使用宿主机 Docker（用于构建和部署）
• act_runner_data:/data: Runner 数据持久化

网络

Runner 必须与 Gitea 在同一 Docker 网络（gitea），以便通信。

安全建议

1. 不要将 Token 提交到 Git

   • Token 应该放在 .env 文件中
   • 确保 .env 已添加到 .gitignore

2. 定期更新镜像

   docker-compose -f docker-compose.gitea.yml pull
   docker-compose -f docker-compose.gitea.yml up -d
   

3. 限制 Runner 权限

   • 只在必要时挂载 Docker socket
   • 考虑使用专用的部署用户

工作流触发分支

根据 .gitea/workflows/deploy.yml 配置：

• ✅ prod 分支 → 部署到生产环境
• ✅ test 分支 → 部署到测试环境
• ❌ dev 分支 → 不触发部署（仅代码推送）

参考资料

• Gitea Actions 官方文档
• Act Runner 文档