# 常见问题排查

## 认证问题

### Q: 遇到 401 错误

**症状**: `[-1] 无效token` 或 `[-1] 请登录后再操作`

**原因**:
- Token 过期（7 天有效期）
- Token 存储损坏
- 网络问题导致 Token 未正确注入

**解决**:
```bash
# 重新登录
gitlink-cli auth login

# 或使用新 Token
gitlink-cli auth login --token
```

---

## 权限问题

### Q: 遇到 403 错误

**症状**: `[-1] 您没有权限进行该操作`

**原因**:
- 无仓库管理权限
- 无 Issue 编辑权限
- 无分支删除权限

**解决**:
```bash
# 检查当前用户权限
gitlink-cli user +me

# 确认仓库所有者
gitlink-cli repo +info --owner xxx --repo yyy

# 联系项目管理员申请权限
```

---

## Issue 操作问题

### Q: Issue 创建失败 - "Mysql2::Error: done_ratio cannot be null"

**原因**: 使用 Raw API 创建 Issue 时缺少 `done_ratio` 字段

**解决**:
```bash
# 使用 issue +create shortcut（已自动处理）
gitlink-cli issue +create -t "标题" -b "描述"

# 或使用 Raw API 时添加 done_ratio
gitlink-cli api POST /:owner/:repo/issues --body '{
  "subject": "标题",
  "description": "描述",
  "done_ratio": 0
}'
```

### Q: Issue 关闭失败 - "验证失败: 标题不能为空" 或描述被清空

**原因**: 更新 Issue 时缺少当前 `subject`，或没有保留当前 `description`

**解决**:
```bash
# 使用 issue +close shortcut（已自动处理）
gitlink-cli issue +close -i 123

# 或使用 Raw API 时先 GET 当前 Issue，再添加 subject 和 description
gitlink-cli api PUT /:owner/:repo/issues/123 --body '{
  "subject": "当前标题",
  "description": "当前描述",
  "status_id": 5
}'
```

---

## Release 操作问题

### Q: Release 查看返回 HTML 页面

**原因**: 使用了 tag_name 而非 version_id

**解决**:
```bash
# 先获取 version_id
gitlink-cli release +list --format json
# 从返回结果中找到 version_id 字段

# 使用 version_id 查看
gitlink-cli release +view -i <version_id>
```

---

## 分支操作问题

### Q: Branch 删除失败 - "分支不存在"

**原因**: GitLink API Bug - DELETE 端点实现有问题

**解决**:
```bash
# 暂无 CLI 解决方案
# 建议通过 Web UI 删除分支
# 或联系 GitLink 团队修复 API
```

---

## 网络问题

### Q: 请求超时或连接失败

**症状**: `request failed: context deadline exceeded`

**原因**:
- 网络连接不稳定
- GitLink 服务器响应慢
- 防火墙阻止

**解决**:
```bash
# 检查网络连接
ping www.gitlink.org.cn

# 启用调试模式查看详细信息
gitlink-cli user +me --debug

# 重试操作
```

---

## 调试技巧

### 启用调试输出

```bash
gitlink-cli <command> --debug
```

### 查看完整 API 请求

```bash
gitlink-cli api GET /users/me --debug
```

### 检查认证状态

```bash
gitlink-cli auth status
```

### 验证 API 连接

```bash
gitlink-cli user +me
```