qcc-debug

name	qcc-debug
description	Use for debugging, troubleshooting, and diagnosing issues in qcc_plus project

QCC Plus 调试排查手册

请求类问题

400 错误

检查项	解决方案
USER_HASH	检查是否匹配账号
预热	尝试 NO_WARMUP=1 跳过预热
系统提示	确认使用精简系统提示 MINIMAL_SYSTEM=1

工具定义格式错误 (tools.*.custom)

• v3.0.1+ 自动清理工具定义中的非标准字段（如 custom、input_examples）
• 代理会自动移除 Anthropic API 不支持的字段，保留 name/description/input_schema
• 如需查看清理日志，检查代理服务器输出

节点/连接类问题

代理连接失败

检查项	解决方案
上游地址	检查 UPSTREAM_BASE_URL 配置
网络	确认网络连通性
重试	查看 PROXY_RETRY_MAX 重试配置

MySQL 连接问题

检查项	解决方案
DSN 格式	检查 PROXY_MYSQL_DSN 格式
服务状态	确认 MySQL 服务运行状态
网络	检查防火墙和端口配置

CI/CD 类问题

健康检查超时

检查项	解决方案
版本	v1.0.1+ 已增强健康检查：10s 初始等待 + 6 次重试
端口	检查服务器端口和防火墙配置
日志	查看部署日志：docker logs qcc_test-proxy-1

日志位置

组件	日志命令
Docker 容器	docker logs <container_name>
代理服务器	标准输出
健康检查	代理服务器日志中的 [health] 标签

测试环境参数

参数	值
重试次数	PROXY_RETRY_MAX=3
单次超时	12/6/3s（递减）
总超时	RETRY_TOTAL_TIMEOUT_SEC=25
重试状态码	RETRY_ON_STATUS=502,503,504
健康检查模式	PROXY_HEALTH_CHECK_MODE=cli
失败阈值	PROXY_FAIL_THRESHOLD=3
探活间隔	PROXY_HEALTH_INTERVAL_SEC=30

熔断器配置

参数	值
窗口	120s
失败率	0.8
连续失败	10 次
冷却时间	60s
半开探测	5 次

常见踩坑

前端页面 CSS 硬编码颜色

• 现象：新页面在深色主题下显示异常
• 原因：直接使用硬编码颜色值而非 CSS 变量
• 解决：使用 CSS 变量（var(--bg)、var(--text)、var(--border)）
• 预防：开发新页面时禁止使用硬编码颜色

Codex 执行卡住无响应

• 现象：codex exec 运行超过 30 分钟无输出
• 原因：网络问题或 API 超时
• 解决：使用 KillShell 终止后重试，或设置 timeout
• 预防：对于简单分析任务，直接用 Claude 而非 Codex

Shell 转义问题导致 Codex 失败

• 现象：直接传递含特殊字符的 prompt 导致命令解析错误
• 原因：Shell 对引号、换行等字符的转义处理
• 解决：写入临时文件后用 cat file | codex exec
• 预防：始终使用临时文件方式调用 Codex