chengmaandClaude Opus 4.8
42dd8a993f
- troubleshooting.md: 新增「⑤ cmhub 刷新别名/测试连接 notfound(404)」排障节，确认请求达标，给 curl 隔离法（models vs balance） - cmhub-integration-design.md: §4.1 补 Base URL 必须为网关根约束 + v3.4 核对记录 - 06-tasks.md: 新增 T-530（Base URL 规整 + 404 明确提示） Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
175 lines
7.7 KiB
Markdown
175 lines
7.7 KiB
Markdown
# 常见问题排查
|
||
|
||
> 本文只记录可复用的本地排障步骤。涉及 `config.json`、`config/ai_models.json`、`cmshopee.db`、`chrome_user_data_dir/`、`images/` 时，默认它们是本机敏感或业务数据，必须保持 gitignore，不把真实密码、API Key、Cookie、token 写入文档、日志或提交。
|
||
|
||
## 启动时报 “AI 模型 category 必须是 text 或 image”
|
||
|
||
### 现象
|
||
|
||
运行 `python main.py` / `python -m app` 启动 GUI 时，弹出或输出：
|
||
|
||
```text
|
||
AI 模型 category 必须是 text 或 image
|
||
```
|
||
|
||
### 原因
|
||
|
||
`config/ai_models.json` 是本地 AI 模型清单，里面每个模型都必须有合法的 `category`：
|
||
|
||
- `text`：标题生成模型，会出现在“标题大模型”下拉。
|
||
- `image`：封面生成模型，会出现在“图片大模型”下拉。
|
||
|
||
早期或手工维护过的 `config/ai_models.json` 可能缺少 `category`，或者填了中文、空值、旧字段，导致 `appconfig.load_ai_models_config()` 严格校验失败，GUI 启动被阻断。
|
||
|
||
### 不要这样做
|
||
|
||
- 不要删除 `config/ai_models.json` 来“重置”，否则会丢失本地明文 API Key 和模型配置。
|
||
- 不要把 `config/ai_models.json` 提交到 git。
|
||
- 不要把完整文件内容贴到聊天、文档或日志里；该文件含本地明文 API Key。
|
||
|
||
### 推荐修复
|
||
|
||
先只查看非敏感字段，确认哪些模型缺少 `category`：
|
||
|
||
```powershell
|
||
python -c "import json; p='config/ai_models.json'; data=json.load(open(p,encoding='utf-8')); [print({'index': i+1, 'name': m.get('name'), 'category': m.get('category'), 'api_type': m.get('api_type'), 'enabled': m.get('enabled'), 'has_api_key': bool(m.get('api_key'))}) for i,m in enumerate(data.get('models', []))]"
|
||
```
|
||
|
||
然后手工编辑 `config/ai_models.json`，只补这些字段：
|
||
|
||
```json
|
||
{
|
||
"name": "示例文本模型",
|
||
"category": "text",
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"name": "示例图片模型",
|
||
"category": "image",
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
如果要用脚本批量修复，只按模型名或 `api_type` 推断 `category`，并保留原有 `url`、`model`、`api_key`、`extra_body` 等字段。示例：
|
||
|
||
```powershell
|
||
python -c "import json; p='config/ai_models.json'; data=json.load(open(p,encoding='utf-8')); mapping={'你的文本模型名':'text','你的图片模型名':'image'}; changed=False
|
||
for m in data.get('models', []):
|
||
name=m.get('name')
|
||
if not m.get('category') and name in mapping:
|
||
m['category']=mapping[name]; changed=True
|
||
if m.get('enabled') is None:
|
||
m['enabled']=True; changed=True
|
||
open(p,'w',encoding='utf-8').write(json.dumps(data,ensure_ascii=False,indent=2)+'\n')
|
||
print('updated' if changed else 'unchanged')"
|
||
```
|
||
|
||
### 验证
|
||
|
||
验证时只输出模型名、类别、是否启用、是否存在 Key，不输出 Key 本身：
|
||
|
||
```powershell
|
||
python -c "import os,sys; sys.path.insert(0, os.getcwd()); from app import appconfig; print([(m['name'], m['category'], m['enabled'], m['api_key_set']) for m in appconfig.list_ai_models()])"
|
||
```
|
||
|
||
确认 `config/ai_models.json` 仍被忽略：
|
||
|
||
```powershell
|
||
git status --short --ignored config/ai_models.json
|
||
```
|
||
|
||
正常输出应包含：
|
||
|
||
```text
|
||
!! config/ai_models.json
|
||
```
|
||
|
||
最后重新启动：
|
||
|
||
```powershell
|
||
python main.py
|
||
```
|
||
|
||
## ⑤ 设置里测试连接提示 “HTTP 404”
|
||
|
||
### 现象
|
||
|
||
在⑤设置里填写文本大模型信息后，点击「测试连接」，结果显示：
|
||
|
||
```text
|
||
HTTP 404
|
||
```
|
||
|
||
### 原因
|
||
|
||
HTTP 404 表示服务端已响应，但当前请求 URL 路径不存在。旧代码会把「网址」字段原样作为 POST 地址；如果只填 OpenAI-compatible base URL，例如：
|
||
|
||
```text
|
||
https://api.vectorengine.ai/v1
|
||
```
|
||
|
||
程序会直接 POST 到 `/v1`，部分服务商会返回 404。当前代码已兼容 base URL：
|
||
|
||
- `api_type=chat` 或 `auto`：`/v1`、`/api/v1` 会自动补成 `/chat/completions`。
|
||
- `api_type=images_edits`：`/v1`、`/api/v1` 会自动补成 `/images/edits`。
|
||
- 已经填写完整 endpoint（如 `/v1/chat/completions`）时保持不变。
|
||
|
||
### 推荐修复
|
||
|
||
更新到包含该修复的代码后，保留当前配置即可；也可以手工把「网址」改成完整 endpoint：
|
||
|
||
```text
|
||
https://api.vectorengine.ai/v1/chat/completions
|
||
```
|
||
|
||
如果仍然 404，优先检查服务商文档要求的 endpoint 路径和 `api_type`，不要把 `config/ai_models.json` 或 API Key 贴到日志、文档或聊天里。
|
||
|
||
### 非敏感检查
|
||
|
||
只输出非密钥字段确认 URL 形态：
|
||
|
||
```powershell
|
||
python -c "import json; from urllib.parse import urlsplit,urlunsplit; p='config/ai_models.json'; data=json.load(open(p,encoding='utf-8')); [print({'name':m.get('name'),'category':m.get('category'),'api_type':m.get('api_type'),'url_without_query':urlunsplit((urlsplit(m.get('url','')).scheme,urlsplit(m.get('url','')).netloc,urlsplit(m.get('url','')).path,'','')),'has_api_key':bool(m.get('api_key'))}) for m in data.get('models', [])]"
|
||
```
|
||
## ⑤ cmhub「刷新别名 / 测试连接」提示 notfound / 404
|
||
|
||
### 现象
|
||
|
||
在⑤设置切到 cmhub 后端，手动填入 Base URL、API Key，点「刷新别名」或「测试连接」，提示 `notfound`（即 HTTP 404）。
|
||
|
||
### 原因
|
||
|
||
先明确：**cmshopee 的请求本身是达标的**——`GET {Base URL}/api/v1/models`，头 `Authorization: Bearer <key>`，与对接文档《cmhub-接口对接文档-桌面端生文生图》§4.4 和 cmhub 服务端路由 `path("v1/models", ModelsView)` 完全一致。404 表示服务端已响应但该路径不存在，原因在请求之外，通常是两类：
|
||
|
||
1. **Base URL 填了多余路径（手动填入最常见）**：Base URL 只能填**网关根**，例如 `https://cmhub.example.com`。当前 `appconfig.cmhub_request_url()` 是 `base_url.rstrip("/") + "/api/v1/models"`，**不会**替你去掉结尾的 `/api` 或 `/api/v1`；若你填成 `https://host/api/v1`，会拼成 `.../api/v1/api/v1/models` → 404。
|
||
2. **连的那台 cmhub 实例没有该路由**：`ModelsView` 在 cmhub 仓库代码里有，但**运行中的实例**若未重新部署/重启，`/api/v1/models`（较新接口）会 404，而 `/api/v1/balance`（较老接口）可能正常。
|
||
|
||
### 隔离方法（一条 curl 定位）
|
||
|
||
```bash
|
||
curl -i "https://<你的BaseURL>/api/v1/models" -H "Authorization: Bearer sk_cmhub_xxx"
|
||
curl -i "https://<你的BaseURL>/api/v1/balance" -H "Authorization: Bearer sk_cmhub_xxx"
|
||
```
|
||
|
||
- 两个都 404 → **Base URL 填错**，改成网关根（不带 `/api`、`/api/v1`）。
|
||
- balance 通、models 404 → **cmhub 实例未更新**，让部署方重启/重部署带上 `ModelsView`。
|
||
- models 通 → cmshopee 侧别的问题，回代码排查。
|
||
|
||
> 不要把 API Key 贴进日志、文档或聊天；curl 里的 `sk_cmhub_xxx` 是占位。
|
||
|
||
### 待改进（T-530）
|
||
|
||
`cmhub_request_url()` 目前不规整带 `/api`/`/api/v1` 的 Base URL，且 404 落到 `unknown` 后透传生涩英文原文。跟进任务 T-530 将：保存/请求前规整 Base URL 去掉多余 `/api(/v1)` 尾部；给 404 一个明确中文提示（“cmhub 接口不存在，检查 Base URL 或该实例是否已部署 /api/v1/models”）。
|
||
|
||
## AI生成：标题成功但图片生成失败，且看不到原因
|
||
|
||
当前代码会为 ② AI生成写两层日志：
|
||
|
||
- 页面右下「AI生成运行日志」显示最近一次 `run_type=generate` 的逐条事件，例如 `phase=cover step=cover_request result=failed detail=...`。
|
||
- 本地 `logs/cmshopee.log` 保存脱敏后的 traceback、任务 id、alias、item_id、phase 和 step，用于判断卡在模型配置、封面请求、图片解析、保存文件还是写库。
|
||
|
||
排查顺序：先看 ② 页面运行日志里的 `phase` / `step` / `detail`；如果只看到简短错误，再查看本地 `logs/cmshopee.log`。不要把 `config/ai_models.json` 或 API Key 发到聊天、文档或提交里。
|