【教程8】搭建完成：全链路测试与排错指南 — 确保一切正常运转

lpf2026

教程5-7完成之后，你的中转站应该已经可以通过域名访问了。但能访问不代表能用——本文教你如何系统性地测试每一个环节，并解决可能遇到的问题。

一、全链路测试清单

测试项	命令/方法	期望结果
Web 页面可访问	浏览器访问域名	显示 New API 页面
HTTPS 正常	浏览器地址栏	🔒 锁图标
用户注册	注册新账号	注册成功，收到确认
API 调用	curl 测试	返回正常 JSON 响应
额度扣减	发请求后查看余额	余额正确减少
日志记录	管理面板日志	有请求记录

二、curl 测试 API 接口

这是最重要的测试，模拟真实用户调用你的 API：

2.1 测试 /v1/models 接口（列出可用模型）

1. curl -H "Authorization: Bearer YOUR_API_KEY" \
2.      -H "Content-Type: application/json" \
3.      https://api.yourdomain.com/v1/models

复制代码

2.2 测试聊天补全（Chat Completions）

1. curl -X POST https://api.yourdomain.com/v1/chat/completions \
2.   -H "Authorization: Bearer YOUR_API_KEY" \
3.   -H "Content-Type: application/json" \
4.   -d '{
5.     "model": "gpt-5-mini",
6.     "messages": [
7.       {"role": "user", "content": "Say hello in one sentence."}
8.     ],
9.     "max_tokens": 50
10.   }'

复制代码

2.3 测试流式响应（SSE）

1. curl -X POST https://api.yourdomain.com/v1/chat/completions \
2.   -H "Authorization: Bearer YOUR_API_KEY" \
3.   -H "Content-Type: application/json" \
4.   -H "Accept: text/event-stream" \
5.   -d '{
6.     "model": "gpt-5-mini",
7.     "messages": [
8.       {"role": "user", "content": "Count from 1 to 5 slowly."}
9.     ],
10.     "stream": true
11.   }'

复制代码

期望看到逐字输出的 SSE 格式响应。

三、常见错误码及排查

错误码	含义	排查方向
401 Unauthorized	API Key 无效	检查Key是否正确；用户是否有额度
403 Forbidden	权限不足	用户分组权限设置
404 Not Found	接口路径错误	检查域名和路径是否正确
429 Too Many Requests	请求频率过高	限流配置（Nginx/New API）
500 Internal Server Error	服务器内部错误	查看 New API 日志
502 Bad Gateway	Nginx 无法连接后端	New API 容器是否在运行
503 Service Unavailable	服务暂时不可用	上游 API 不通或超时

四、查看日志排查问题

1. # New API 日志（最重要）
2. cd /opt/new-api
3. docker compose logs -f new-api --tail=100
5. # Nginx 访问日志
6. sudo tail -f /var/log/nginx/access.log
8. # Nginx 错误日志
9. sudo tail -f /var/log/nginx/error.log
11. # 系统日志
12. sudo tail -f /var/log/syslog | grep -i error

复制代码

五、数据库直连测试

1. # 测试 MySQL 连接
2. docker exec -it newapi-mysql mysql -uroot -p
4. # 查看数据
5. USE new_api;
6. SELECT COUNT(*) FROM users;        -- 用户数
7. SELECT COUNT(*) FROM channels;      -- 渠道数
8. SELECT COUNT(*) FROM logs;          -- 日志数
9. SELECT SUM(quota) FROM users;       -- 总充值额度
10. EXIT;

复制代码

六、性能基准测试（可选）

使用简单的 bash 脚本测试吞吐量：

1. #!/bin/bash
2. # 简单性能测试 - 发送10个请求，记录耗时
4. API_URL="https://api.yourdomain.com/v1/chat/completions"
5. API_KEY="YOUR_API_KEY"
7. for i in {1..10}; do
8.   start=$(date +%s%N)
9.   curl -s -X POST "$API_URL" \
10.     -H "Authorization: Bearer $API_KEY" \
11.     -H "Content-Type: application/json" \
12.     -d '{"model":"gpt-5-mini","messages":[{"role":"user","content":"Hi"}]}' \
13.     -o /dev/null -w "%{http_code} "
14.   end=$(date +%s%N)
15.   echo "Request $i: $(( (end-start) / 1000000 ))ms"
16. done

复制代码

七、部署检查清单（Checklist）

检查项	通过标准
Docker 各容器正常运行	docker compose ps 全绿，无 restart
Nginx 配置无语法错误	nginx -t 返回 successful
SSL 证书有效	浏览器 🔒 图标，证书未过期
HTTP → HTTPS 自动跳转	访问 http://域名 自动跳转 https
管理面板可登录	输入管理员账号密码成功进入
渠道测试通过	管理面板 → 渠道 → 测试 → 连通
用户可自助注册	用隐私窗口注册新用户
API Key 可用	curl 测试返回 200 + 正确响应
额度扣减准确	调用前后对比用户余额
防火墙仅开放必要端口	ufw status 只有 22/80/443

八、如果一切正常……

恭喜！你的 API 中转站已经可以运行了。接下来：

• 教程9：接入更多上游渠道，配置负载均衡
  
• 教程10：制定定价策略，管理用户
  
• 教程11：对接支付系统，开始赚钱
  
• 教程12：推广获客，让用户知道你的站
  

参考来源：New API GitHub Issues 常见问题汇总；OpenAI API 文档；Nginx 官方文档