Files

Voson 5a05d5ab53 chore: 重构 OpenCode 命令和技能文档体系

- 新增：统一的 git 命令文档（add/commit/push/pull 等）
- 新增：整合的 Gitea 技能文档（API、运行器、工作流等）
- 新增：工作流模板（Android、Go、Node.js 等）
- 移除：已弃用的旧命令脚本和发布脚本
- 改进：.gitignore 添加敏感文件保护规则
- 改进：AGENTS.md 完善了开发规范和示例

此次重组统一了命令和技能的文档结构，便于后续维护和扩展。

2026-01-13 00:27:21 +08:00

11 KiB

Raw Blame History

Gitea 故障排查

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

配置问题

1. 配置文件不存在

症状：

❌ Gitea 未配置，请运行 /gitea-reset

原因：

首次使用，未进行配置
配置文件被删除或移动

解决方案：

/gitea-reset

按照提示完成配置。

2. Token 无效或已过期

症状：

Token 状态: ✗ 无效或已过期

原因：

Token 已过期
Token 被撤销
Token 复制不完整

解决方案：

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

或手动编辑配置文件：

vim ~/.config/gitea/config.env
# 更新 GITEA_TOKEN=new_token

3. 连接 Gitea 失败

症状：

❌ 连接失败 (HTTP 404)
❌ 连接失败 (HTTP 500)

原因：

URL 错误
网络问题
Gitea 服务器宕机

诊断步骤：

检查 URL：

source ~/.config/gitea/config.env
echo $GITEA_URL

测试网络连接：
```
curl -s "$GITEA_URL/api/v1/version"
```
在浏览器中访问 URL

解决方案：

修正 URL（不要包含 /api/v1）
检查网络连接
联系 Gitea 管理员

4. 权限不足

症状：

❌ 权限不足 (HTTP 403)
⚠ 缺少 admin:org 权限

原因：

Token 权限不足
不是组织成员

解决方案：

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

Runner 问题

1. Runner 创建失败

症状：

❌ 获取注册 Token 失败
❌ Runner 注册失败

原因：

Token 缺少 write:runner 权限
组织不存在
网络问题

诊断步骤：

检查 Token 权限：
```
/gitea-config
```

验证组织存在：

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 无法启动

症状：

act_runner daemon --config ...
# 进程立即退出或报错

原因：

act_runner 未安装
配置文件错误
端口被占用（cache service）

诊断步骤：

检查 act_runner：
```
which act_runner
act_runner --version
```

验证配置文件：

cat ~/.config/gitea/runners/runner-name/config.yaml

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

解决方案：

安装 act_runner：
```
brew install act_runner
```
修复配置文件（确保路径正确）

更改端口（如果 9000 被占用）：

vim ~/.config/gitea/runners/runner-name/config.yaml
# 修改 port: 9001

3. Runner 已注册但不在线

症状：

Gitea 中看不到 Runner
Workflow 无法分配到 Runner

原因：

Runner 进程未运行
网络连接问题
Labels 不匹配

诊断步骤：

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

查看 Runner 日志：

tail -f ~/.config/gitea/runners/runner-name/runner.log

测试 Gitea 连接：

source ~/.config/gitea/config.env
curl -s "$GITEA_URL/api/v1/version"

解决方案：

启动 Runner：

act_runner daemon --config ~/.config/gitea/runners/runner-name/config.yaml

检查网络和防火墙设置
验证 Labels 匹配

4. Labels 不匹配

症状：

Workflow 一直 pending，不执行

原因：

Workflow 的 runs-on 与 Runner labels 不匹配

诊断步骤：

检查 Runner labels：

/gitea-list-runners
# 或
cat ~/.config/gitea/runners/runner-name/.runner | jq '.labels'

检查 Workflow：

jobs:
  build:
    runs-on: darwin-arm64  # 这个 label 必须存在

解决方案：

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

Workflow 问题

1. Workflow 不触发

症状：

推送代码后 Workflow 不执行

原因：

路径过滤不匹配
分支不匹配
Runner 不在线

诊断步骤：

检查触发条件：

on:
  push:
    paths:
      - 'backend/**'  # 确保修改的文件在此路径下

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

解决方案：

修改触发条件（删除或调整 paths）
确保 Runner 在线
检查 Gitea Actions 是否启用

2. Workflow 执行失败

症状：

Job failed

原因：

构建命令错误
依赖缺失
Secret 未配置

诊断步骤：

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

解决方案：

修复构建命令
安装缺失的依赖
配置必需的 Secrets

3. Cache 不生效

症状：

每次构建都重新下载依赖
构建时间没有减少

原因：

Cache key 每次都变化
Cache 目录不正确
Runner cache service 未启动

诊断步骤：

检查 cache key：

key: cache-${{ hashFiles('**/lockfile') }}
# 确保 lockfile 路径正确

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

解决方案：

修正 cache key 的 hash 文件路径
确保 Runner cache service 启用
检查 cache 目录权限

仓库操作问题

1. 创建仓库失败

症状：

❌ 仓库已存在
❌ Owner 不存在或无权限

原因：

仓库名冲突
组织不存在
Token 权限不足

诊断步骤：

检查仓库是否存在：

source ~/.config/gitea/config.env
curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/repos/owner/repo"

列出组织的所有仓库：

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

解决方案：

查看现有 remote：
```
git remote -v
```
更新 remote URL：
```
git remote set-url origin <new-url>
```

或删除后重新添加：

git remote remove origin
git remote add origin <new-url>

开发环境问题

1. Android SDK 未找到

症状：

ANDROID_HOME not set
SDK location not found

原因：

未安装 Android SDK
环境变量未配置
Runner 用户不同

诊断步骤：

检查环境变量：
```
echo $ANDROID_HOME
ls $ANDROID_HOME
```
检查 Runner 用户：
```
ps aux | grep act_runner
```

解决方案：

安装 Android SDK：

brew install --cask android-commandlinetools

配置环境变量（在 ~/.zshrc）：

export ANDROID_HOME=~/android-sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin

确保 Runner 以正确用户运行

2. JDK 版本错误

症状：

Android Gradle Plugin requires Java 17

原因：

JDK 版本过低
JAVA_HOME 指向错误版本

诊断步骤：

java -version
echo $JAVA_HOME

解决方案：

安装 JDK 17：
```
brew install openjdk@17
```

更新 JAVA_HOME：

export JAVA_HOME=/opt/homebrew/opt/openjdk@17
export PATH=$PATH:$JAVA_HOME/bin

API 调用问题

1. API 返回 404

原因：

Endpoint 错误
资源不存在
组织/仓库名错误

解决方案：

检查 API 路径
验证资源存在
参考 API 文档

2. API 返回 401

原因：

Token 无效
未提供 Authorization header

解决方案：

检查 Token
确保 header 格式正确：Authorization: token YOUR_TOKEN

3. API 返回 403

原因：

权限不足
Token 缺少必要权限

解决方案：

重新创建 Token，选择更多权限
联系管理员提升权限

性能问题

1. 构建速度慢

原因：

未使用缓存
依赖下载慢
Runner 性能不足

解决方案：

启用缓存：

- uses: https://github.com/actions/cache@v3
  with:
    path: ~/.cache
    key: cache-${{ hashFiles('**/lockfile') }}

使用镜像源（如 Go proxy、npm registry）
升级 Runner 硬件

2. Cache 占用空间大

原因：

长时间未清理
多个 Runner 共享 cache

解决方案：

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

设置 crontab 自动清理：

crontab -e
# 添加: 0 3 * * 0 ~/.config/gitea/cleanup-cache.sh

诊断工具

快速诊断脚本

#!/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 并执行：

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

获取帮助

如果问题仍未解决：

查看日志：
- Runner 日志：~/.config/gitea/runners/runner-name/runner.log
- Gitea UI 中的 Workflow 运行日志
检查文档：
联系支持：
- Gitea 官方文档：https://docs.gitea.com/
- Gitea 社区论坛：https://discourse.gitea.io/

版本

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

11 KiB Raw Blame History Unescape Escape

Gitea 故障排查

配置问题

1. 配置文件不存在

2. Token 无效或已过期

3. 连接 Gitea 失败

4. 权限不足

Runner 问题

1. Runner 创建失败

2. Runner 无法启动

3. Runner 已注册但不在线

4. Labels 不匹配

Workflow 问题

1. Workflow 不触发

2. Workflow 执行失败

3. Cache 不生效

仓库操作问题

1. 创建仓库失败

2. Git Remote 添加失败

开发环境问题

1. Android SDK 未找到

2. JDK 版本错误

API 调用问题

1. API 返回 404

2. API 返回 401

3. API 返回 403

性能问题

1. 构建速度慢

2. Cache 占用空间大

诊断工具

快速诊断脚本

获取帮助

版本

11 KiB

Raw Blame History