mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-04-26 04:13:28 +08:00
docs: add user manual documentation (#979)
* docs: add user manual documentation Add comprehensive user manual covering getting started, provider management, extensions (MCP/prompts/skills), proxy configuration, and FAQ sections. Includes screenshots and a README index. * fix(docs): align user manual with v3.10.3 codebase - Add OpenCode as 4th supported app throughout all docs - Fix proxy default port 15762 → 15721 - Update Claude presets (9 → 26), Codex (3 → 10), Gemini (3 → 7) - Add OpenCode presets (25 entries) - Fix timeout defaults and ranges (stream first byte 60s/90s, etc.) - Fix circuit breaker defaults with per-app values (Claude vs general) - Fix Skills support: all 4 apps, not just Claude/Codex - Remove non-existent Gemini authMode field - Fix prompt deletion behavior: enabled prompts cannot be deleted - Remove non-existent Legacy deeplink protocol, use V1 only - Fix DB table names (usage_logs → proxy_request_logs) and add missing tables - Fix migration version v3.8.0 → v3.7.0 - Add missing V1 deeplink parameters (config, configFormat, etc.) - Update doc version v3.9.1 → v3.10.3 - Add claude-opus-4-1 to pricing table - Fix recovery wait time range 10-300 → 0-300 --------- Co-authored-by: Jason <farion1231@gmail.com>
This commit is contained in:
Dex Miller
GitHub
220
docs/user-manual/5-faq/5.2-questions.md
Normal file
220
docs/user-manual/5-faq/5.2-questions.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# 5.2 常见问题 FAQ
|
||||
|
||||
## 安装问题
|
||||
|
||||
### macOS 提示「未知开发者」
|
||||
|
||||
**问题**：首次打开时提示「无法打开，因为它来自身份不明的开发者」
|
||||
|
||||
**解决方法一**：通过系统设置
|
||||
1. 关闭警告弹窗
|
||||
2. 打开「系统设置」→「隐私与安全性」
|
||||
3. 找到 CC Switch 相关提示
|
||||
4. 点击「仍要打开」
|
||||
5. 再次打开应用
|
||||
|
||||
**解决方法二**：通过终端命令（推荐）
|
||||
```bash
|
||||
sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/
|
||||
```
|
||||
|
||||
执行后即可正常打开应用。
|
||||
|
||||
### Windows 安装后无法启动
|
||||
|
||||
**可能原因**：
|
||||
- 缺少 WebView2 运行时
|
||||
- 杀毒软件拦截
|
||||
|
||||
**解决方法**：
|
||||
1. 安装 [Microsoft Edge WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
|
||||
2. 将 CC Switch 添加到杀毒软件白名单
|
||||
|
||||
### Linux 启动报错
|
||||
|
||||
**问题**：AppImage 无法启动
|
||||
|
||||
**解决方法**：
|
||||
```bash
|
||||
# 添加执行权限
|
||||
chmod +x CC-Switch-*.AppImage
|
||||
|
||||
# 如果仍然失败，尝试
|
||||
./CC-Switch-*.AppImage --no-sandbox
|
||||
```
|
||||
|
||||
## 供应商问题
|
||||
|
||||
### 切换供应商后不生效
|
||||
|
||||
**原因**：CLI 工具需要重新加载配置
|
||||
|
||||
**解决方法**：
|
||||
- Claude Code：关闭并重新打开终端，或重启 IDE
|
||||
- Codex：关闭并重新打开终端
|
||||
- Gemini：托盘切换可即时生效，无需重启
|
||||
|
||||
### API Key 无效
|
||||
|
||||
**检查步骤**：
|
||||
1. 确认 API Key 正确复制（无多余空格）
|
||||
2. 确认 API Key 未过期
|
||||
3. 确认端点地址正确
|
||||
4. 使用速度测试验证连接
|
||||
|
||||
### 如何恢复官方登录
|
||||
|
||||
**操作步骤**：
|
||||
1. 选择「官方登录」预设（Claude/Codex）或「Google 官方」预设（Gemini）
|
||||
2. 点击「启用」
|
||||
3. 重启对应的 CLI 工具
|
||||
4. 按照 CLI 工具的登录流程操作
|
||||
|
||||
## 代理问题
|
||||
|
||||
### 代理服务启动失败
|
||||
|
||||
**可能原因**：端口被占用
|
||||
|
||||
**解决方法**：
|
||||
1. 检查端口占用：
|
||||
```bash
|
||||
# macOS/Linux
|
||||
lsof -i :49152
|
||||
|
||||
# Windows
|
||||
netstat -ano | findstr :49152
|
||||
```
|
||||
2. 关闭占用端口的程序
|
||||
3. 或尝试修改配置恢复默认端口：
|
||||
- 打开「设置 → 代理服务」
|
||||
- 点击「恢复默认」按钮
|
||||
|
||||
### 代理模式下请求超时
|
||||
|
||||
**可能原因**：
|
||||
- 网络问题
|
||||
- 供应商服务器问题
|
||||
- 代理配置错误
|
||||
|
||||
**解决方法**：
|
||||
1. 检查网络连接
|
||||
2. 尝试直接访问供应商 API（关闭代理）
|
||||
3. 检查供应商配置是否正确
|
||||
|
||||
### 关闭代理后配置未恢复
|
||||
|
||||
**可能原因**：代理异常退出
|
||||
|
||||
**解决方法**：
|
||||
1. 编辑当前供应商
|
||||
2. 检查端点地址是否正确
|
||||
3. 保存以更新配置
|
||||
|
||||
## 故障转移问题
|
||||
|
||||
### 故障转移没有触发
|
||||
|
||||
**检查清单**：
|
||||
- [ ] 代理服务是否运行
|
||||
- [ ] 应用接管是否开启
|
||||
- [ ] 自动故障转移是否开启
|
||||
- [ ] 队列中是否有备用供应商
|
||||
|
||||
### 频繁触发故障转移
|
||||
|
||||
**可能原因**：
|
||||
- 主供应商不稳定
|
||||
- 熔断器阈值设置过低
|
||||
|
||||
**解决方法**：
|
||||
1. 检查主供应商状态
|
||||
2. 调高失败阈值（如从 3 改为 5）
|
||||
3. 考虑更换主供应商
|
||||
|
||||
### 所有供应商都熔断了
|
||||
|
||||
**解决方法**：
|
||||
1. 等待熔断时长到期（默认 60 秒）
|
||||
2. 或重启代理服务重置状态
|
||||
|
||||
## 数据问题
|
||||
|
||||
### 配置丢失
|
||||
|
||||
**可能原因**：
|
||||
- 配置目录被删除
|
||||
- 数据库损坏
|
||||
|
||||
**解决方法**：
|
||||
1. 检查 `~/.cc-switch/` 目录是否存在
|
||||
2. 从备份恢复：`~/.cc-switch/backups/`
|
||||
3. 或从之前导出的配置文件导入
|
||||
|
||||
### 导入配置失败
|
||||
|
||||
**可能原因**：
|
||||
- 文件格式错误
|
||||
- 版本不兼容
|
||||
|
||||
**解决方法**：
|
||||
1. 确认文件是 CC Switch 导出的 JSON 文件
|
||||
2. 检查文件内容是否完整
|
||||
3. 尝试用文本编辑器打开检查格式
|
||||
|
||||
### 用量统计数据为空
|
||||
|
||||
**检查清单**：
|
||||
- [ ] 代理服务是否运行
|
||||
- [ ] 应用接管是否开启
|
||||
- [ ] 日志记录是否开启
|
||||
- [ ] 是否有请求通过代理
|
||||
|
||||
## 其他问题
|
||||
|
||||
### 托盘图标不显示
|
||||
|
||||
**macOS**：
|
||||
- 检查系统设置中的菜单栏图标设置
|
||||
|
||||
**Windows**：
|
||||
- 检查任务栏设置，确保 CC Switch 图标未被隐藏
|
||||
|
||||
**Linux**：
|
||||
- 需要安装系统托盘支持（如 `libappindicator`）
|
||||
|
||||
### 界面显示异常
|
||||
|
||||
**解决方法**：
|
||||
1. 尝试切换主题（浅色/深色）
|
||||
2. 重启应用
|
||||
3. 删除 `~/.cc-switch/settings.json` 重置设置
|
||||
|
||||
### 更新失败
|
||||
|
||||
**解决方法**：
|
||||
1. 检查网络连接
|
||||
2. 手动下载最新版本安装
|
||||
3. 如使用 Homebrew：`brew upgrade --cask cc-switch`
|
||||
|
||||
## 获取帮助
|
||||
|
||||
### 提交 Issue
|
||||
|
||||
如果以上方法都无法解决问题：
|
||||
|
||||
1. 访问 [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
2. 搜索是否有类似问题
|
||||
3. 如果没有，创建新 Issue
|
||||
4. 提供以下信息：
|
||||
- 操作系统和版本
|
||||
- CC Switch 版本
|
||||
- 问题描述和复现步骤
|
||||
- 错误信息（如有）
|
||||
|
||||
### 日志文件
|
||||
|
||||
提交 Issue 时可附上日志文件：
|
||||
|
||||
- macOS/Linux：`~/.cc-switch/logs/`
|
||||
- Windows：`%APPDATA%\cc-switch\logs\`
|
||||
Reference in New Issue
Block a user