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 登录到服务器后，编辑环境变量文件：

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

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

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

```bash
GITEA_RUNNER_TOKEN=your_actual_registration_token_here
```

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

### 3. 启动 Gitea Runner

```bash
# 确保在 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 状态

#### 检查容器运行状态
```bash
docker ps | grep rent-act-runner
```

应该看到类似输出：
```
CONTAINER ID   IMAGE                      STATUS         PORTS     NAMES
abc123def456   gitea/act_runner:latest   Up 2 minutes             rent-act-runner
```

#### 查看 Runner 日志
```bash
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` 分支触发工作流：

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

在 Gitea Web 界面查看 Actions 执行情况：
- 仓库 → Actions → 查看工作流运行状态

## 常见问题

### Runner 状态显示 Offline

**原因**：
- Token 不正确
- Runner 容器未启动
- 网络连接问题

**解决**：
```bash
# 查看日志
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"：

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

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

### 重新配置 Runner

```bash
# 停止 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
```

### 查看实时日志

```bash
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. **定期更新镜像**
   ```bash
   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 官方文档](https://docs.gitea.com/usage/actions/overview)
- [Act Runner 文档](https://gitea.com/gitea/act_runner)