5a05d5ab53
- 新增：统一的 git 命令文档（add/commit/push/pull 等） - 新增：整合的 Gitea 技能文档（API、运行器、工作流等） - 新增：工作流模板（Android、Go、Node.js 等） - 移除：已弃用的旧命令脚本和发布脚本 - 改进：.gitignore 添加敏感文件保护规则 - 改进：AGENTS.md 完善了开发规范和示例 此次重组统一了命令和技能的文档结构，便于后续维护和扩展。
693 lines
11 KiB
Markdown
693 lines
11 KiB
Markdown
# 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
|