# Gitea 故障排查

常见问题的诊断和解决方案。

## 配置问题

### 1. 配置文件不存在

**症状**：
```
❌ Gitea 未配置，请运行 /gitea-reset
```

**原因**：
- 首次使用，未进行配置
- 配置文件被删除或移动

**解决方案**：
```bash
/gitea-reset
```

按照提示完成配置。

---

### 2. Token 无效或已过期

**症状**：
```
Token 状态: ✗ 无效或已过期
```

**原因**：
- Token 已过期
- Token 被撤销
- Token 复制不完整

**解决方案**：

1. 重新生成 Token：
   - 登录 Gitea → 设置 → 应用 → 访问令牌
   - 生成新 Token（权限：repo, admin:org, write:runner）
   
2. 更新配置：
   ```bash
   /gitea-reset
   ```

3. 或手动编辑配置文件：
   ```bash
   vim ~/.config/gitea/config.env
   # 更新 GITEA_TOKEN=new_token
   ```

---

### 3. 连接 Gitea 失败

**症状**：
```
❌ 连接失败 (HTTP 404)
❌ 连接失败 (HTTP 500)
```

**原因**：
- URL 错误
- 网络问题
- Gitea 服务器宕机

**诊断步骤**：

1. 检查 URL：
   ```bash
   source ~/.config/gitea/config.env
   echo $GITEA_URL
   ```

2. 测试网络连接：
   ```bash
   curl -s "$GITEA_URL/api/v1/version"
   ```

3. 在浏览器中访问 URL

**解决方案**：
- 修正 URL（不要包含 `/api/v1`）
- 检查网络连接
- 联系 Gitea 管理员

---

### 4. 权限不足

**症状**：
```
❌ 权限不足 (HTTP 403)
⚠ 缺少 admin:org 权限
```

**原因**：
- Token 权限不足
- 不是组织成员

**解决方案**：

1. 重新创建 Token，选择更多权限
2. 联系组织管理员添加为成员
3. 使用个人仓库/Runner 代替组织级别

---

## Runner 问题

### 1. Runner 创建失败

**症状**：
```
❌ 获取注册 Token 失败
❌ Runner 注册失败
```

**原因**：
- Token 缺少 `write:runner` 权限
- 组织不存在
- 网络问题

**诊断步骤**：

1. 检查 Token 权限：
   ```bash
   /gitea-config
   ```

2. 验证组织存在：
   ```bash
   source ~/.config/gitea/config.env
   curl -s -H "Authorization: token $GITEA_TOKEN" \
     "$GITEA_URL/api/v1/orgs/$GITEA_DEFAULT_ORG"
   ```

**解决方案**：
- 更新 Token 权限
- 设置正确的组织：`/gitea-switch-org <org>`

---

### 2. Runner 无法启动

**症状**：
```bash
act_runner daemon --config ...
# 进程立即退出或报错
```

**原因**：
- `act_runner` 未安装
- 配置文件错误
- 端口被占用（cache service）

**诊断步骤**：

1. 检查 act_runner：
   ```bash
   which act_runner
   act_runner --version
   ```

2. 验证配置文件：
   ```bash
   cat ~/.config/gitea/runners/runner-name/config.yaml
   ```

3. 检查端口占用：
   ```bash
   lsof -i :9000
   ```

**解决方案**：

1. 安装 act_runner：
   ```bash
   brew install act_runner
   ```

2. 修复配置文件（确保路径正确）

3. 更改端口（如果 9000 被占用）：
   ```bash
   vim ~/.config/gitea/runners/runner-name/config.yaml
   # 修改 port: 9001
   ```

---

### 3. Runner 已注册但不在线

**症状**：
- Gitea 中看不到 Runner
- Workflow 无法分配到 Runner

**原因**：
- Runner 进程未运行
- 网络连接问题
- Labels 不匹配

**诊断步骤**：

1. 检查 Runner 进程：
   ```bash
   /gitea-list-runners
   ```

2. 查看 Runner 日志：
   ```bash
   tail -f ~/.config/gitea/runners/runner-name/runner.log
   ```

3. 测试 Gitea 连接：
   ```bash
   source ~/.config/gitea/config.env
   curl -s "$GITEA_URL/api/v1/version"
   ```

**解决方案**：

1. 启动 Runner：
   ```bash
   act_runner daemon --config ~/.config/gitea/runners/runner-name/config.yaml
   ```

2. 检查网络和防火墙设置

3. 验证 Labels 匹配

---

### 4. Labels 不匹配

**症状**：
```
Workflow 一直 pending，不执行
```

**原因**：
- Workflow 的 `runs-on` 与 Runner labels 不匹配

**诊断步骤**：

1. 检查 Runner labels：
   ```bash
   /gitea-list-runners
   # 或
   cat ~/.config/gitea/runners/runner-name/.runner | jq '.labels'
   ```

2. 检查 Workflow：
   ```yaml
   jobs:
     build:
       runs-on: darwin-arm64  # 这个 label 必须存在
   ```

**解决方案**：

1. 修改 Workflow 的 `runs-on` 匹配 Runner labels
2. 或重新创建 Runner 使用正确的 labels

---

## Workflow 问题

### 1. Workflow 不触发

**症状**：
- 推送代码后 Workflow 不执行

**原因**：
- 路径过滤不匹配
- 分支不匹配
- Runner 不在线

**诊断步骤**：

1. 检查触发条件：
   ```yaml
   on:
     push:
       paths:
         - 'backend/**'  # 确保修改的文件在此路径下
   ```

2. 检查 Runner 状态：
   ```bash
   /gitea-list-runners
   ```

**解决方案**：
- 修改触发条件（删除或调整 `paths`）
- 确保 Runner 在线
- 检查 Gitea Actions 是否启用

---

### 2. Workflow 执行失败

**症状**：
```
Job failed
```

**原因**：
- 构建命令错误
- 依赖缺失
- Secret 未配置

**诊断步骤**：

1. 查看 Workflow 运行日志（在 Gitea UI 中）
2. 检查 Secrets 配置
3. 在本地手动执行构建命令

**解决方案**：
- 修复构建命令
- 安装缺失的依赖
- 配置必需的 Secrets

---

### 3. Cache 不生效

**症状**：
- 每次构建都重新下载依赖
- 构建时间没有减少

**原因**：
- Cache key 每次都变化
- Cache 目录不正确
- Runner cache service 未启动

**诊断步骤**：

1. 检查 cache key：
   ```yaml
   key: cache-${{ hashFiles('**/lockfile') }}
   # 确保 lockfile 路径正确
   ```

2. 检查 Runner 配置：
   ```yaml
   cache:
     enabled: true
     dir: "..."
   ```

**解决方案**：
- 修正 cache key 的 hash 文件路径
- 确保 Runner cache service 启用
- 检查 cache 目录权限

---

## 仓库操作问题

### 1. 创建仓库失败

**症状**：
```
❌ 仓库已存在
❌ Owner 不存在或无权限
```

**原因**：
- 仓库名冲突
- 组织不存在
- Token 权限不足

**诊断步骤**：

1. 检查仓库是否存在：
   ```bash
   source ~/.config/gitea/config.env
   curl -s -H "Authorization: token $GITEA_TOKEN" \
     "$GITEA_URL/api/v1/repos/owner/repo"
   ```

2. 列出组织的所有仓库：
   ```bash
   curl -s -H "Authorization: token $GITEA_TOKEN" \
     "$GITEA_URL/api/v1/orgs/owner/repos" | jq -r '.[].name'
   ```

**解决方案**：
- 使用不同的仓库名
- 验证组织名正确
- 确保 Token 有 `repo` 权限

---

### 2. Git Remote 添加失败

**症状**：
```
❌ origin remote 已存在
```

**原因**：
- 已经配置了 origin remote

**解决方案**：

1. 查看现有 remote：
   ```bash
   git remote -v
   ```

2. 更新 remote URL：
   ```bash
   git remote set-url origin <new-url>
   ```

3. 或删除后重新添加：
   ```bash
   git remote remove origin
   git remote add origin <new-url>
   ```

---

## 开发环境问题

### 1. Android SDK 未找到

**症状**：
```
ANDROID_HOME not set
SDK location not found
```

**原因**：
- 未安装 Android SDK
- 环境变量未配置
- Runner 用户不同

**诊断步骤**：

1. 检查环境变量：
   ```bash
   echo $ANDROID_HOME
   ls $ANDROID_HOME
   ```

2. 检查 Runner 用户：
   ```bash
   ps aux | grep act_runner
   ```

**解决方案**：

1. 安装 Android SDK：
   ```bash
   brew install --cask android-commandlinetools
   ```

2. 配置环境变量（在 `~/.zshrc`）：
   ```bash
   export ANDROID_HOME=~/android-sdk
   export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
   ```

3. 确保 Runner 以正确用户运行

---

### 2. JDK 版本错误

**症状**：
```
Android Gradle Plugin requires Java 17
```

**原因**：
- JDK 版本过低
- JAVA_HOME 指向错误版本

**诊断步骤**：

```bash
java -version
echo $JAVA_HOME
```

**解决方案**：

1. 安装 JDK 17：
   ```bash
   brew install openjdk@17
   ```

2. 更新 JAVA_HOME：
   ```bash
   export JAVA_HOME=/opt/homebrew/opt/openjdk@17
   export PATH=$PATH:$JAVA_HOME/bin
   ```

---

## API 调用问题

### 1. API 返回 404

**原因**：
- Endpoint 错误
- 资源不存在
- 组织/仓库名错误

**解决方案**：
- 检查 API 路径
- 验证资源存在
- 参考 [API 文档](./api-reference.md)

---

### 2. API 返回 401

**原因**：
- Token 无效
- 未提供 Authorization header

**解决方案**：
- 检查 Token
- 确保 header 格式正确：`Authorization: token YOUR_TOKEN`

---

### 3. API 返回 403

**原因**：
- 权限不足
- Token 缺少必要权限

**解决方案**：
- 重新创建 Token，选择更多权限
- 联系管理员提升权限

---

## 性能问题

### 1. 构建速度慢

**原因**：
- 未使用缓存
- 依赖下载慢
- Runner 性能不足

**解决方案**：

1. 启用缓存：
   ```yaml
   - uses: https://github.com/actions/cache@v3
     with:
       path: ~/.cache
       key: cache-${{ hashFiles('**/lockfile') }}
   ```

2. 使用镜像源（如 Go proxy、npm registry）

3. 升级 Runner 硬件

---

### 2. Cache 占用空间大

**原因**：
- 长时间未清理
- 多个 Runner 共享 cache

**解决方案**：

1. 定期清理：
   ```bash
   ~/.config/gitea/cleanup-cache.sh
   ```

2. 设置 crontab 自动清理：
   ```bash
   crontab -e
   # 添加: 0 3 * * 0 ~/.config/gitea/cleanup-cache.sh
   ```

---

## 诊断工具

### 快速诊断脚本

```bash
#!/bin/bash
echo "=== Gitea 环境诊断 ==="
echo ""

# 1. 配置文件
echo "1. 配置文件:"
config_file="$HOME/.config/gitea/config.env"
if [ -f "$config_file" ]; then
  echo "  ✓ 存在: $config_file"
  source "$config_file"
  echo "  URL: $GITEA_URL"
else
  echo "  ✗ 不存在"
fi
echo ""

# 2. Token 验证
if [ -n "$GITEA_TOKEN" ]; then
  echo "2. Token 验证:"
  response=$(curl -s -w "\n%{http_code}" \
    -H "Authorization: token $GITEA_TOKEN" \
    "${GITEA_URL}/api/v1/user")
  http_code=$(echo "$response" | tail -n1)
  if [ "$http_code" = "200" ]; then
    echo "  ✓ 有效"
  else
    echo "  ✗ 无效 (HTTP $http_code)"
  fi
  echo ""
fi

# 3. Runner 状态
echo "3. Runner 状态:"
runners_dir="$HOME/.config/gitea/runners"
if [ -d "$runners_dir" ]; then
  runner_count=$(ls -1 "$runners_dir" 2>/dev/null | wc -l | tr -d ' ')
  echo "  配置数量: $runner_count"
  
  for runner in $(ls -1 "$runners_dir" 2>/dev/null); do
    config_file="$runners_dir/$runner/config.yaml"
    if pgrep -f "act_runner daemon --config $config_file" > /dev/null; then
      echo "  ✓ $runner (运行中)"
    else
      echo "  ✗ $runner (已停止)"
    fi
  done
else
  echo "  未配置 Runner"
fi
echo ""

# 4. 工具检查
echo "4. 工具检查:"
for tool in act_runner jq curl git; do
  if command -v $tool &> /dev/null; then
    echo "  ✓ $tool"
  else
    echo "  ✗ $tool (未安装)"
  fi
done
```

保存为 `~/.config/gitea/diagnose.sh` 并执行：

```bash
chmod +x ~/.config/gitea/diagnose.sh
~/.config/gitea/diagnose.sh
```

---

## 获取帮助

如果问题仍未解决：

1. **查看日志**：
   - Runner 日志：`~/.config/gitea/runners/runner-name/runner.log`
   - Gitea UI 中的 Workflow 运行日志

2. **检查文档**：
   - [环境配置](./setup-guide.md)
   - [Runner 管理](./runner-management.md)
   - [API 参考](./api-reference.md)

3. **联系支持**：
   - Gitea 官方文档：https://docs.gitea.com/
   - Gitea 社区论坛：https://discourse.gitea.io/

---

## 版本

- **文档版本**: 1.0
- **最后更新**: 2026-01-12