new-api/.agents/skills/cmd-debug-prod/SKILL.md

allowed-tools	description	name
Bash(wsl -- *)	Command: debug-prod (imported from Claude Code)	cmd-debug-prod

线上排查命令

用户要求排查线上问题。根据 $ARGUMENTS 确定目标服务器，然后根据问题类型选择合适的操作。

参数

$ARGUMENTS 中可能传入：

• (空) — 默认排查国外服务器（OV，主节点）
• cn — 只排查国内服务器
• ov — 只排查国外服务器
• all — 排查两台服务器

如果用户没有明确指定，默认排查 OV 服务器（因为 MySQL 主库在 OV）。

---

服务器配置

节点	SSH	docker-compose 目录	new-api 容器名	MySQL 容器名
🇨🇳 国内 CN	root@123.57.74.135	/root/new-api/	cn-new-api	ov-mysql
🌏 国外 OV	root@139.180.189.205	/root/new-api/new-api/	ov-new-api	mysql

重要：两台服务器的 MySQL 实际都在 OV（国外节点）。CN 的 SQL_DSN 指向 ov-mysql:3306。所以查数据库统一用 OV 的 MySQL 容器 mysql。

MySQL 连接：docker exec mysql mysql -uroot -pLanqi123456 new-api -e "SQL语句"

---

所有命令执行方式

必须通过 WSL 执行（SSH 密钥在 WSL 中）：

# 单条命令
wsl -- bash -c "ssh root@HOST '命令'"

# 多条命令（引号嵌套复杂时用 heredoc）
wsl -- bash -c "ssh root@HOST 'cmd1 && cmd2 && cmd3'"

---

操作指南

根据用户描述的问题，选择合适的排查步骤。不要一次性执行所有操作，应该根据问题逐步排查。

1. 服务状态检查

# 查看所有容器状态
wsl -- bash -c "ssh root@HOST 'cd COMPOSE_DIR && docker compose ps'"

# 健康检查
wsl -- bash -c "ssh root@HOST 'curl -s http://localhost:3000/api/status'"

# 系统资源（CPU/内存/磁盘）
wsl -- bash -c "ssh root@HOST 'free -h && df -h / && docker stats --no-stream'"

2. 应用日志

# 最近 N 行容器日志
wsl -- bash -c "ssh root@HOST 'docker logs --tail 100 CONTAINER_NAME'"

# 实时跟踪日志（带超时，避免阻塞）
wsl -- bash -c "ssh root@HOST 'timeout 5 docker logs --tail 50 --since 5m CONTAINER_NAME'"

# 搜索特定关键词（如错误、某用户、某模型）
wsl -- bash -c "ssh root@HOST 'docker logs --tail 500 CONTAINER_NAME 2>&1 | grep -i KEYWORD'"

# 应用日志文件（oneapi-*.log）
wsl -- bash -c "ssh root@HOST 'ls -lt COMPOSE_DIR/logs/ | head -5'"
wsl -- bash -c "ssh root@HOST 'tail -100 COMPOSE_DIR/logs/oneapi-XXXX.log'"

3. MySQL 查询

连接方式（在 OV 服务器上执行）：

wsl -- bash -c "ssh root@139.180.189.205 'docker exec mysql mysql -uroot -pLanqi123456 new-api -e \"SQL语句\"'"

注意：SQL 语句中的双引号需要用 \" 转义。

常用查询模板：

-- 查用户信息
SELECT id, username, email, role, status, quota, used_quota, \`group\`, aff_code FROM users WHERE username = 'XXX';

-- 查用户最近的请求日志
SELECT id, created_at, type, model_name, quota, channel_id, content FROM logs WHERE user_id = XXX ORDER BY created_at DESC LIMIT 20;

-- 查某时间段内的错误日志
SELECT id, created_at, type, content, model_name FROM logs WHERE created_at >= '2026-04-16 00:00:00' AND type = 2 ORDER BY created_at DESC LIMIT 50;

-- 查渠道状态和余额
SELECT id, name, type, status, balance, used_quota, models, \`group\`, priority FROM channels WHERE status != 3;

-- 查某渠道的最近请求
SELECT id, created_at, model_name, quota, content FROM logs WHERE channel_id = XXX ORDER BY created_at DESC LIMIT 20;

-- 查 Token 信息
SELECT id, name, \`key\`, status, remain_quota, used_quota, expired_time FROM tokens WHERE user_id = XXX;

-- 查最近的充值/支付记录
SELECT id, user_id, amount, money, trade_no, status, created_at FROM topups ORDER BY created_at DESC LIMIT 20;

-- 查订阅订单
SELECT id, user_id, plan_id, status, amount, created_at FROM subscription_orders ORDER BY created_at DESC LIMIT 20;

-- 查同步记录（主从同步问题）
SELECT * FROM pending_sync_records ORDER BY id DESC LIMIT 20;
SELECT * FROM quota_sync_logs ORDER BY id DESC LIMIT 20;

-- 查 Midjourney 任务状态
SELECT id, user_id, action, status, progress, fail_reason, created_at FROM midjourneys ORDER BY created_at DESC LIMIT 20;

-- 查系统配置
SELECT \`key\`, value FROM options WHERE \`key\` IN ('ServerAddress', 'TopUpLink', 'QuotaForNewUser', 'QuotaForInviter', 'QuotaForInvitee');

日志类型 (type 字段)：

• 1 — 消耗 (consume)
• 2 — 充值 (recharge/topup)
• 3 — 管理员操作
• 4 — 系统

4. Relay 抓包日志（请求体/响应体完整记录）

对开启了 capture_relay 的用户，系统会将完整的请求体和响应体写入容器内文件。适用于需要查看客户端实际发送的请求体内容的场景（如验证字段是否正确、排查请求格式问题）。

文件路径（容器内）：/data/data/relay-capture/{YYYY-MM-DD}/{requestID}.log

# 列出某天的抓包文件（最新 20 个）
wsl -- bash -c 'ssh root@HOST "docker exec CONTAINER_NAME ls -lt /data/data/relay-capture/2026-05-14/ | head -20"'

# 查看特定请求的抓包内容（requestID 从日志错误行中获取）
wsl -- bash -c 'ssh root@HOST "docker exec CONTAINER_NAME cat /data/data/relay-capture/2026-05-14/REQUEST_ID.log"'

# 文件很大时，只看请求头 + 请求体前 2000 字节
wsl -- bash -c 'ssh root@HOST "docker exec CONTAINER_NAME head -c 2000 /data/data/relay-capture/2026-05-14/REQUEST_ID.log"'

抓包文件格式：

=== REQUEST 2026-05-14T09:09:51.80665026Z ===
POST /v1/chat/completions
user_id: 44
X-Forwarded-For: 184.73.225.134
User-Agent: Cursor/1.0
Content-Type: application/json
...

{"stream":true,"model":"openai/gpt-5.4","messages":[...]}

=== RESPONSE ===
{"error":{"message":"field messages is required",...}}

=== END duration_ms=6 ===

使用场景：

• 客户端发送了错误格式的请求体（如用 input 代替 messages）
• 需要确认请求头、User-Agent、请求体字段
• 排查特定 request ID 的完整请求/响应链路

注意：

• 只有开启了 capture_relay 的用户才有抓包文件，未开启的用户查不到
• 请求体可能很大（100KB+），建议先用 head -c 限制输出大小
• 抓包文件名即 request ID，可从容器的 [ERR] 日志行中提取

5. 容器内操作

# 进入容器执行命令（如检查网络连通性）
wsl -- bash -c "ssh root@HOST 'docker exec CONTAINER_NAME wget -qO- http://localhost:3000/api/status'"

# 重启某个服务（谨慎操作，先确认用户意图）
wsl -- bash -c "ssh root@HOST 'cd COMPOSE_DIR && docker compose restart new-api'"

---

排查流程建议

1. 先问清楚问题：什么现象？什么时候开始的？影响哪些用户？
2. 服务状态 → 检查容器是否正常运行
3. 应用日志 → 搜索错误关键词、时间范围
4. 数据库查询 → 根据日志中的线索查相关数据
5. Relay 抓包 → 如果日志中只有错误摘要但看不清请求体细节，检查用户是否开启了 capture_relay，若有则读取抓包文件查看完整请求/响应
6. 综合分析 → 给出问题原因和修复建议

注意事项

• 不要执行任何写入操作（INSERT/UPDATE/DELETE），除非用户明确要求
• MySQL 查询要加 LIMIT，避免返回过多数据
• 查询时间范围要合理，不要全表扫描
• 如果发现需要重启服务，先告知用户再操作
• 所有输出向用户展示时，用中文解释含义