fix: 修正 Gitea Runner 标签配置并添加设置文档
## 修改内容 - 修正 act-runner 标签从 `rent-deploy:docker://node:18-alpine` 改为 `self-hosted,rent-deploy` 以匹配工作流要求 - 添加 Gitea Runner 完整配置指南文档 ## 配置说明 Runner 标签必须与 .gitea/workflows/deploy.yml 中的 `runs-on: [self-hosted, rent-deploy]` 完全匹配 ## 后续步骤 服务器管理员需要： 1. 在 Gitea Web 界面获取 Registration Token 2. 设置环境变量 GITEA_RUNNER_TOKEN 3. 运行 docker-compose up -d act-runner 4. 验证 Runner 状态为 Online 详细步骤参见：deploy/docker/GITEA_RUNNER_SETUP.md Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,192 @@
|
||||
# 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)
|
||||
@@ -33,7 +33,7 @@ services:
|
||||
# 注册后在 Gitea Web 界面获取 token，填入下面配置
|
||||
- GITEA_RUNNER_REGISTRATION_TOKEN=${GITEA_RUNNER_TOKEN:-change_me}
|
||||
- GITEA_RUNNER_NAME=rent-deploy-runner
|
||||
- GITEA_RUNNER_LABELS=rent-deploy:docker://node:18-alpine
|
||||
- GITEA_RUNNER_LABELS=self-hosted,rent-deploy
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
- act_runner_data:/data
|
||||
|
||||
Reference in New Issue
Block a user