659 lines
16 KiB
Markdown
659 lines
16 KiB
Markdown
# Gitea 环境配置指南
|
||
|
||
首次使用 Gitea skill 前的完整配置指南。
|
||
|
||
## 概述
|
||
|
||
Gitea skill 需要配置连接信息才能与你的 Gitea 实例交互。配置信息存储在：
|
||
|
||
```
|
||
~/.config/gitea/config.env
|
||
```
|
||
|
||
## 配置目录结构
|
||
|
||
### macOS / Linux
|
||
```
|
||
~/.config/gitea/
|
||
├── config.env # 主配置文件（包含 URL、Token、默认组织等）
|
||
├── runners/ # Runner 配置目录
|
||
│ └── runner-*/ # 各个 runner 的独立目录
|
||
└── .gitignore # Git 忽略文件（保护敏感信息）
|
||
```
|
||
|
||
### Windows
|
||
```
|
||
%USERPROFILE%\.config\gitea\
|
||
├── config.env # 主配置文件（包含 URL、Token、默认组织等）
|
||
├── runners\ # Runner 配置目录
|
||
│ └── runner-*\ # 各个 runner 的独立目录
|
||
└── .gitignore # Git 忽略文件（保护敏感信息）
|
||
```
|
||
|
||
**Windows 用户提示**：
|
||
- 配置文件路径示例：`C:\Users\YourUsername\.config\gitea\config.env`
|
||
- 可以在 PowerShell 中使用 `$env:USERPROFILE` 变量
|
||
- 在 CMD 中使用 `%USERPROFILE%` 环境变量
|
||
|
||
## 快速配置
|
||
|
||
### 方法 1: 使用交互式向导（推荐）
|
||
|
||
运行配置命令：
|
||
|
||
```bash
|
||
/gitea-reset
|
||
```
|
||
|
||
按照提示输入信息即可。
|
||
|
||
### 方法 2: 自然语言请求
|
||
|
||
直接告诉 AI：
|
||
|
||
```
|
||
用户: 配置 gitea
|
||
用户: 初始化 gitea 连接
|
||
用户: 设置 gitea 环境
|
||
```
|
||
|
||
AI 会自动启动配置向导。
|
||
|
||
### 方法 3: 手动创建配置文件
|
||
|
||
如果你熟悉配置格式，可以手动创建：
|
||
|
||
**macOS / Linux**:
|
||
```bash
|
||
mkdir -p ~/.config/gitea/runners
|
||
cat > ~/.config/gitea/config.env << 'EOF'
|
||
GITEA_URL=https://git.digitevents.com
|
||
GITEA_TOKEN=your_personal_access_token
|
||
GITEA_DEFAULT_ORG=your_org_name
|
||
|
||
GITEA_RUNNER_CAPACITY=2
|
||
GITEA_RUNNER_TIMEOUT=3h
|
||
EOF
|
||
|
||
chmod 600 ~/.config/gitea/config.env
|
||
```
|
||
|
||
**Windows PowerShell**:
|
||
```powershell
|
||
# 创建目录
|
||
New-Item -Path "$env:USERPROFILE\.config\gitea\runners" -ItemType Directory -Force
|
||
|
||
# 创建配置文件
|
||
@"
|
||
GITEA_URL=https://git.digitevents.com
|
||
GITEA_TOKEN=your_personal_access_token
|
||
GITEA_DEFAULT_ORG=your_org_name
|
||
|
||
GITEA_RUNNER_CAPACITY=2
|
||
GITEA_RUNNER_TIMEOUT=3h
|
||
"@ | Out-File -FilePath "$env:USERPROFILE\.config\gitea\config.env" -Encoding utf8
|
||
|
||
# 设置文件权限（仅所有者可读）
|
||
$acl = Get-Acl "$env:USERPROFILE\.config\gitea\config.env"
|
||
$acl.SetAccessRuleProtection($true, $false)
|
||
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($env:USERNAME, "Read,Write", "Allow")
|
||
$acl.SetAccessRule($rule)
|
||
Set-Acl "$env:USERPROFILE\.config\gitea\config.env" $acl
|
||
```
|
||
|
||
**Windows CMD**:
|
||
```cmd
|
||
:: 创建目录
|
||
mkdir "%USERPROFILE%\.config\gitea\runners"
|
||
|
||
:: 创建配置文件
|
||
(
|
||
echo GITEA_URL=https://git.digitevents.com
|
||
echo GITEA_TOKEN=your_personal_access_token
|
||
echo GITEA_DEFAULT_ORG=your_org_name
|
||
echo.
|
||
echo GITEA_RUNNER_CAPACITY=2
|
||
echo GITEA_RUNNER_TIMEOUT=3h
|
||
) > "%USERPROFILE%\.config\gitea\config.env"
|
||
```
|
||
|
||
## 交互式配置流程
|
||
|
||
### 步骤 1: 输入 Gitea 实例地址
|
||
|
||
```
|
||
请输入 Gitea 实例地址 (例如: https://git.digitevents.com):
|
||
```
|
||
|
||
**要求**：
|
||
- 必须以 `http://` 或 `https://` 开头
|
||
- 不要包含尾随斜杠
|
||
- 确保可以从当前网络访问
|
||
|
||
**示例**：
|
||
```
|
||
✓ https://git.digitevents.com
|
||
✓ https://gitea.example.com
|
||
✗ git.digitevents.com (缺少协议)
|
||
✗ https://gitea.com/ (包含尾随斜杠)
|
||
```
|
||
|
||
### 步骤 2: 输入 Personal Access Token
|
||
|
||
```
|
||
请输入 Personal Access Token:
|
||
```
|
||
|
||
**获取 Token 的步骤**：
|
||
|
||
1. 登录 Gitea
|
||
2. 点击右上角头像 → **设置**
|
||
3. 左侧菜单选择 **应用** → **访问令牌**
|
||
4. 点击 **生成新令牌**
|
||
5. 设置令牌名称（如 `opencode-cli`）
|
||
6. 选择权限（见下方推荐权限）
|
||
7. 点击 **生成令牌**
|
||
8. 复制生成的 Token（只显示一次！）
|
||
|
||
**推荐权限**：
|
||
|
||
| 权限 | 用途 | 是否必需 |
|
||
|------|------|---------|
|
||
| `repo` | 创建和管理仓库 | ✅ 必需 |
|
||
| `admin:org` | 创建组织级 Runner | ✅ 推荐 |
|
||
| `write:runner` | 管理 Runner | ✅ 推荐 |
|
||
| `write:user` | 创建用户级 Variables | ✅ 推荐 |
|
||
| `admin:repo_hook` | 配置 Webhooks | ⚠️ 可选 |
|
||
| `write:issue` | 创建 Release | ⚠️ 可选 |
|
||
|
||
**安全提示**：
|
||
- Token 等同于密码，请妥善保管
|
||
- 不要在公开场合分享 Token
|
||
- 定期轮换 Token（建议每 3-6 个月）
|
||
- 使用最小权限原则
|
||
|
||
### 步骤 3: 测试连接
|
||
|
||
```
|
||
正在测试连接...
|
||
✓ 连接成功！
|
||
```
|
||
|
||
系统会调用 Gitea API 验证：
|
||
- URL 是否可访问
|
||
- Token 是否有效
|
||
- 网络是否正常
|
||
|
||
**如果失败**：
|
||
- 检查 URL 是否正确
|
||
- 检查 Token 是否复制完整
|
||
- 检查网络连接
|
||
- 检查防火墙设置
|
||
|
||
### 步骤 4: 验证 Token 权限
|
||
|
||
```
|
||
正在检查 Token 权限...
|
||
✓ repo (仓库管理)
|
||
✓ admin:org (组织管理)
|
||
✓ write:runner (Runner 管理)
|
||
⚠ 缺少 admin:repo_hook 权限（可能影响 Webhook 配置）
|
||
```
|
||
|
||
系统会测试 Token 的实际权限，并给出建议。
|
||
|
||
**权限不足时**：
|
||
- 如果缺少必需权限，建议重新创建 Token
|
||
- 如果只缺少可选权限，可以继续使用
|
||
- 后续需要时可以更新 Token
|
||
|
||
### 步骤 5: 输入默认组织（可选）
|
||
|
||
```
|
||
请输入默认组织名称 (可选，回车跳过):
|
||
```
|
||
|
||
**作用**：
|
||
- 创建仓库时，如果不指定 owner，使用此默认组织
|
||
- 创建组织级 Runner 时使用
|
||
- 可以随时使用 `/gitea-switch-org` 切换
|
||
|
||
**示例**：
|
||
```
|
||
ai → 创建仓库时使用 ai/repo-name
|
||
my-team → 创建仓库时使用 my-team/repo-name
|
||
(留空) → 创建仓库时使用当前登录用户
|
||
```
|
||
|
||
**注意**：留空是完全可以的，系统会自动使用当前登录用户创建个人仓库。
|
||
|
||
### 步骤 6: 输入 Gitea 用户名（用于 Actions Variables）
|
||
|
||
```
|
||
请输入 Gitea 用户名 (将创建为用户级 variable):
|
||
```
|
||
|
||
**作用**：
|
||
- 此用户名将自动注册到 Gitea 用户级 variables（变量名：`USERNAME`）
|
||
- 可在所有个人仓库的 Actions workflow 中通过 `${{ vars.USERNAME }}` 使用
|
||
- 用于需要 Git 操作的 workflow（如推送代码、创建 tag 等）
|
||
|
||
**示例**：
|
||
```
|
||
your_username → 在 workflow 中可使用 ${{ vars.USERNAME }}
|
||
john → 你的 Gitea 登录用户名
|
||
```
|
||
|
||
**重要说明**：
|
||
- Gitea 不允许 variable 名称以 `GITEA_` 或 `GITHUB_` 开头
|
||
- 因此配置项 `GITEA_USERNAME` 会被注册为 `USERNAME` variable
|
||
- 如果此 variable 已存在于 Gitea 服务器，系统会自动更新为新值
|
||
|
||
### 步骤 7: 输入 Gitea 密码（用于 Actions）
|
||
|
||
```
|
||
请输入 Gitea 密码:
|
||
```
|
||
|
||
**作用**：
|
||
- 密码将存储在本地配置文件 `config.env` 中（权限 600）
|
||
- 用于需要认证的 Git 操作
|
||
- 也可以选择在 workflow 中使用 Secret 方式（需要手动创建）
|
||
|
||
**安全说明**：
|
||
- ✅ 配置文件权限为 600（仅所有者可读写）
|
||
- ✅ `.gitignore` 自动排除配置文件
|
||
- ⚠️ 不建议在公共环境使用明文密码
|
||
- 💡 建议使用 Personal Access Token 替代密码
|
||
|
||
**留空说明**：如果不需要在 workflow 中进行 Git 推送操作，可以留空。
|
||
|
||
### 步骤 8: 输入 Actions 通知 Webhook URL（可选）
|
||
|
||
```
|
||
请输入 Actions 通知 Webhook URL (可选，回车跳过):
|
||
```
|
||
|
||
**作用**：
|
||
- 用于 workflow 完成后发送通知到第三方平台（如飞书、钉钉、企业微信等）
|
||
- 此 URL 将自动注册到 Gitea 用户级 variables（变量名：`WEBHOOK_URL`）
|
||
- 可在 workflow 中通过 `${{ vars.WEBHOOK_URL }}` 使用
|
||
|
||
**示例**：
|
||
```
|
||
https://www.feishu.cn/flow/api/trigger-webhook/xxx (飞书)
|
||
https://oapi.dingtalk.com/robot/send?access_token=xxx (钉钉)
|
||
https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx (企业微信)
|
||
```
|
||
|
||
**使用方式**：
|
||
```yaml
|
||
- name: 发送通知
|
||
run: |
|
||
curl -X POST "${{ vars.WEBHOOK_URL }}" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"msg_type":"text","content":{"text":"构建完成"}}'
|
||
```
|
||
|
||
**说明**：
|
||
- 留空则不创建 `WEBHOOK_URL` variable
|
||
- 如果此 variable 已存在于 Gitea 服务器，系统会更新为新值
|
||
|
||
### 步骤 9: 注册用户级 Variables
|
||
|
||
```
|
||
正在检查并注册用户级 Variables...
|
||
检查 USERNAME...
|
||
✓ USERNAME 已创建
|
||
检查 WEBHOOK_URL...
|
||
✓ WEBHOOK_URL 已创建
|
||
```
|
||
|
||
系统会自动调用 Gitea API 创建以下用户级 variables：
|
||
|
||
| Variable 名称 | 来源配置 | 说明 |
|
||
|--------------|---------|------|
|
||
| `USERNAME` | `GITEA_USERNAME` | Gitea 用户名 |
|
||
| `WEBHOOK_URL` | `GITEA_WEBHOOK_URL` | Actions 通知 Webhook |
|
||
|
||
**重要**：Gitea 不允许 variable 名称以 `GITEA_` 或 `GITHUB_` 开头，所以 `GITEA_USERNAME` 配置项会被注册为 `USERNAME` variable。
|
||
|
||
**API 端点**：
|
||
```
|
||
POST /api/v1/user/actions/variables/{variable_name}
|
||
```
|
||
|
||
**在 Workflow 中使用**：
|
||
```yaml
|
||
steps:
|
||
- name: 使用 Variables
|
||
run: |
|
||
echo "用户名: ${{ vars.USERNAME }}"
|
||
echo "Webhook: ${{ vars.WEBHOOK_URL }}"
|
||
```
|
||
|
||
**查看已创建的 Variables**：
|
||
- 访问：`https://git.digitevents.com/user/settings/actions/variables`
|
||
- 或使用命令：`/gitea-list-variables`
|
||
|
||
### 步骤 10: 保存配置
|
||
|
||
```
|
||
✓ 配置已保存
|
||
配置文件: ~/.config/gitea/config.env
|
||
Runner 目录: ~/.config/gitea/runners
|
||
```
|
||
|
||
配置文件内容：
|
||
|
||
```bash
|
||
# Gitea Configuration
|
||
# Generated at 2026-01-12 22:30:00
|
||
|
||
GITEA_URL=https://git.digitevents.com
|
||
GITEA_TOKEN=git_xxxxxxxxxxxxxxxxxxxx
|
||
GITEA_DEFAULT_ORG=ai
|
||
|
||
# Gitea 仓库认证信息（用于 Actions）
|
||
GITEA_USERNAME=your_username
|
||
GITEA_PASSWORD=your_password_here
|
||
|
||
# Actions 通知 Webhook（可选）
|
||
GITEA_WEBHOOK_URL=https://www.feishu.cn/flow/api/trigger-webhook/xxx
|
||
|
||
# Runner Default Settings
|
||
GITEA_RUNNER_CAPACITY=2
|
||
GITEA_RUNNER_TIMEOUT=3h
|
||
|
||
# Optional: Override auto-detected labels
|
||
# GITEA_RUNNER_LABELS=custom-label-1:host,custom-label-2:host
|
||
```
|
||
|
||
## 配置验证
|
||
|
||
配置完成后，验证配置是否正确：
|
||
|
||
```bash
|
||
/gitea-config
|
||
```
|
||
|
||
应该看到：
|
||
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
当前 Gitea 配置
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
URL: https://git.digitevents.com
|
||
默认组织: ai
|
||
Token 状态: ✓ 有效 (用户: your_username)
|
||
配置文件: ~/.config/gitea/config.env
|
||
```
|
||
|
||
## 配置文件说明
|
||
|
||
### 必需配置项
|
||
|
||
| 配置项 | 说明 | 示例 |
|
||
|--------|------|------|
|
||
| `GITEA_URL` | Gitea 实例地址 | `https://git.digitevents.com` |
|
||
| `GITEA_TOKEN` | Personal Access Token | `git_xxxxxxxxxx` |
|
||
|
||
### 推荐配置项（用于 Actions）
|
||
|
||
| 配置项 | 说明 | 示例 | 自动创建为 Variable |
|
||
|--------|------|------|-------------------|
|
||
| `GITEA_USERNAME` | Gitea 用户名 | `your_username` | ✅ 是 → `USERNAME` |
|
||
| `GITEA_PASSWORD` | Gitea 密码 | `your_password` | ❌ 否（仅本地使用） |
|
||
| `GITEA_WEBHOOK_URL` | Actions 通知 Webhook | `https://...` | ✅ 是 → `WEBHOOK_URL` |
|
||
|
||
**说明**：
|
||
- 标记为 ✅ 的配置项会在初始化时自动创建为 Gitea 用户级 variables
|
||
- 这些 variables 可在所有个人仓库的 Actions workflow 中使用
|
||
- 使用方式：`${{ vars.USERNAME }}`、`${{ vars.WEBHOOK_URL }}`
|
||
- **注意**：Gitea 不允许 variable 名称以 `GITEA_` 或 `GITHUB_` 开头，所以会自动转换名称
|
||
|
||
### 可选配置项
|
||
|
||
| 配置项 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `GITEA_DEFAULT_ORG` | 默认组织名称 | 无 |
|
||
| `GITEA_RUNNER_CAPACITY` | Runner 并发任务数 | `2` |
|
||
| `GITEA_RUNNER_TIMEOUT` | Runner 任务超时时间 | `3h` |
|
||
| `GITEA_RUNNER_LABELS` | 覆盖自动检测的 labels | 自动检测 |
|
||
|
||
### 自定义 Runner Labels
|
||
|
||
如果自动检测的 labels 不符合需求，可以手动覆盖：
|
||
|
||
```bash
|
||
# 编辑配置文件
|
||
vim ~/.config/gitea/config.env
|
||
|
||
# 取消注释并修改
|
||
GITEA_RUNNER_LABELS=self-hosted:host,linux:host,x64:host,custom:host
|
||
```
|
||
|
||
创建新 Runner 时会优先使用此配置。
|
||
|
||
## 配置管理
|
||
|
||
### 查看当前配置
|
||
|
||
```bash
|
||
/gitea-config
|
||
```
|
||
|
||
显示：
|
||
- Gitea URL
|
||
- 默认组织
|
||
- Token 状态和关联用户
|
||
- 已配置的 Runner 数量
|
||
- 配置文件路径
|
||
|
||
### 切换默认组织
|
||
|
||
```bash
|
||
/gitea-switch-org new-org-name
|
||
```
|
||
|
||
### 重置配置
|
||
|
||
```bash
|
||
/gitea-reset
|
||
```
|
||
|
||
会重新启动配置向导，覆盖现有配置。
|
||
|
||
**警告**：重置配置不会影响已创建的 Runner，但 Runner 会继续使用旧的注册信息。
|
||
|
||
### 更新配置
|
||
|
||
#### 方法 1: 使用命令（推荐）
|
||
|
||
```bash
|
||
/gitea-reset # 完整重置
|
||
/gitea-switch-org my-org # 只切换组织
|
||
```
|
||
|
||
#### 方法 2: 手动编辑
|
||
|
||
```bash
|
||
vim ~/.config/gitea/config.env
|
||
```
|
||
|
||
修改后无需重启，下次使用时自动生效。
|
||
|
||
## 多环境配置
|
||
|
||
如果需要管理多个 Gitea 实例，推荐做法：
|
||
|
||
### 方法 1: 使用不同的配置文件
|
||
|
||
```bash
|
||
# 开发环境
|
||
cp ~/.config/gitea/config.env ~/.config/gitea/config.dev.env
|
||
|
||
# 生产环境
|
||
cp ~/.config/gitea/config.env ~/.config/gitea/config.prod.env
|
||
|
||
# 使用时手动切换
|
||
cp ~/.config/gitea/config.prod.env ~/.config/gitea/config.env
|
||
```
|
||
|
||
### 方法 2: 创建切换脚本
|
||
|
||
```bash
|
||
# ~/.config/gitea/switch-env.sh
|
||
#!/bin/bash
|
||
|
||
case "$1" in
|
||
dev)
|
||
cp ~/.config/gitea/config.dev.env ~/.config/gitea/config.env
|
||
echo "✓ 切换到开发环境"
|
||
;;
|
||
prod)
|
||
cp ~/.config/gitea/config.prod.env ~/.config/gitea/config.env
|
||
echo "✓ 切换到生产环境"
|
||
;;
|
||
*)
|
||
echo "用法: $0 {dev|prod}"
|
||
exit 1
|
||
;;
|
||
esac
|
||
```
|
||
|
||
使用：
|
||
```bash
|
||
bash ~/.config/gitea/switch-env.sh dev
|
||
```
|
||
|
||
## 安全最佳实践
|
||
|
||
### 1. 文件权限
|
||
|
||
确保配置文件只有所有者可读写：
|
||
|
||
```bash
|
||
chmod 600 ~/.config/gitea/config.env
|
||
```
|
||
|
||
### 2. Token 安全
|
||
|
||
- ✅ 使用最小权限原则
|
||
- ✅ 定期轮换 Token
|
||
- ✅ 不要将 Token 提交到 Git
|
||
- ✅ 使用 `.gitignore` 排除配置文件
|
||
- ❌ 不要在公开场合分享 Token
|
||
- ❌ 不要使用永不过期的 Token
|
||
|
||
### 3. 配置备份
|
||
|
||
定期备份配置（移除 Token 后）：
|
||
|
||
```bash
|
||
# 创建备份（移除敏感信息）
|
||
grep -v "GITEA_TOKEN" ~/.config/gitea/config.env > ~/gitea-config-backup.env
|
||
```
|
||
|
||
### 4. .gitignore 配置
|
||
|
||
自动生成的 `.gitignore` 文件：
|
||
|
||
```
|
||
# ~/.config/gitea/.gitignore
|
||
config.env
|
||
runners/*/.runner
|
||
runners/*/.env
|
||
```
|
||
|
||
确保敏感文件不会被意外提交。
|
||
|
||
## 故障排查
|
||
|
||
### 连接失败
|
||
|
||
**症状**：
|
||
```
|
||
❌ 连接失败 (HTTP 404)
|
||
请检查 URL 和 Token 是否正确
|
||
```
|
||
|
||
**解决方案**：
|
||
1. 检查 URL 是否正确（不要包含 `/api/v1`）
|
||
2. 检查网络连接
|
||
3. 尝试在浏览器中访问 URL
|
||
4. 检查防火墙设置
|
||
|
||
### Token 无效
|
||
|
||
**症状**：
|
||
```
|
||
❌ 连接失败 (HTTP 401)
|
||
```
|
||
|
||
**解决方案**：
|
||
1. Token 可能已过期，重新生成
|
||
2. Token 可能被撤销，检查 Gitea 设置
|
||
3. Token 复制不完整，重新复制
|
||
4. 确认 Token 有足够的权限
|
||
|
||
### 权限不足
|
||
|
||
**症状**：
|
||
```
|
||
⚠ 缺少 admin:org 权限（可能影响组织 Runner 创建）
|
||
```
|
||
|
||
**解决方案**：
|
||
1. 重新创建 Token，选择更多权限
|
||
2. 联系 Gitea 管理员提升权限
|
||
3. 使用个人 Runner 而非组织 Runner
|
||
|
||
### 配置文件损坏
|
||
|
||
**症状**：
|
||
```
|
||
❌ 配置文件不完整，请运行 /gitea-reset 重新配置
|
||
```
|
||
|
||
**解决方案**：
|
||
```bash
|
||
/gitea-reset
|
||
```
|
||
|
||
## 下一步
|
||
|
||
配置完成后，你可以：
|
||
|
||
1. **创建第一个 Runner**（自动后台启动）：
|
||
```
|
||
用户: 创建一个 runner
|
||
```
|
||
- 默认创建全局 Runner（可用于所有组织和仓库）
|
||
- 如果 Token 没有管理员权限，自动降级到组织 Runner
|
||
- 创建后 Runner 会自动在后台运行
|
||
|
||
2. **创建仓库**：
|
||
```bash
|
||
/gitea-create-repo my-project
|
||
```
|
||
|
||
3. **生成 Workflow**：
|
||
```
|
||
用户: 为我的项目生成 workflow
|
||
```
|
||
|
||
4. **查看配置**：
|
||
```bash
|
||
/gitea-config
|
||
```
|
||
|
||
---
|
||
|
||
**相关文档**：
|
||
- [Runner 管理](./runner-management.md)
|
||
- [Workflow 生成器](./workflow-generator.md)
|
||
- [仓库操作](./repository-operations.md)
|
||
- [API 参考](./api-reference.md)
|