Twikoo 502 错误排查指南

建站
Twikoo, 502, 故障排查
0 字 / 约 0 分钟

Twikoo 502 错误排查指南 ​

错误现象 ​

  • 浏览器控制台显示：POST https://chiplayout.net/twikoo/ 502 (Bad Gateway)
  • 评论框无法加载或提交失败
  • 页面显示"评论服务暂时不可用"提示

502 错误原因 ​

502 Bad Gateway 表示 Nginx 作为反向代理，无法从上游服务器（Twikoo 后端）获取有效响应。常见原因：

  1. Twikoo 后端服务未运行
  2. Nginx 代理配置错误
  3. 服务端口不正确或不可访问
  4. 防火墙阻止连接

排查步骤 ​

1. 检查 Twikoo 服务状态 ​

bash
# 如果使用 PM2
pm2 status
pm2 logs twikoo

# 如果使用 Docker
docker ps | grep twikoo
docker logs <容器ID或名称>

# 如果使用 systemd
systemctl status twikoo
journalctl -u twikoo -n 50

2. 检查服务端口 ​

bash
# 检查 Twikoo 服务是否在监听端口（默认 8080）
netstat -tlnp | grep 8080
# 或
ss -tlnp | grep 8080

# 测试本地连接
curl http://127.0.0.1:8080/version

3. 检查 Nginx 配置 ​

检查 /etc/nginx/sites-available/ 或 /etc/nginx/conf.d/ 中的配置文件：

nginx
# 正确的配置示例
location /twikoo/ {
    proxy_pass http://127.0.0.1:8080/;  # 注意末尾的斜杠
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # 超时设置
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
    
    # CORS 设置（如果需要）
    add_header 'Access-Control-Allow-Origin' '$http_origin' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
    add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization' always;
    
    # 处理 OPTIONS 预检请求
    if ($request_method = 'OPTIONS') {
        return 204;
    }
}

常见配置错误：

  • ❌ proxy_pass http://127.0.0.1:8080; （缺少末尾斜杠）

  • ✅ proxy_pass http://127.0.0.1:8080/; （正确）

  • ❌ proxy_pass http://localhost:8080/; （可能解析失败）

  • ✅ proxy_pass http://127.0.0.1:8080/; （使用 IP 地址）

4. 测试服务端点 ​

在服务器上执行：

bash
# 测试 Twikoo 版本接口
curl http://127.0.0.1:8080/version

# 测试评论接口
curl -X POST http://127.0.0.1:8080/ \
  -H "Content-Type: application/json" \
  -d '{"action":"getComments","url":"/test"}'

5. 检查 Nginx 错误日志 ​

bash
# 查看 Nginx 错误日志
tail -f /var/log/nginx/error.log

# 或特定站点的错误日志
tail -f /var/log/nginx/chiplayout.net_error.log

常见错误信息：

  • connect() failed (111: Connection refused) - 后端服务未运行
  • connect() failed (113: No route to host) - 防火墙问题
  • upstream timed out - 服务响应超时

6. 检查防火墙 ​

bash
# Ubuntu/Debian
sudo ufw status
sudo ufw allow 8080/tcp

# CentOS/RHEL
sudo firewall-cmd --list-ports
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload

修复方案 ​

方案 1: 重启 Twikoo 服务 ​

bash
# PM2
pm2 restart twikoo

# Docker
docker restart <容器名称>

# systemd
sudo systemctl restart twikoo

方案 2: 修复 Nginx 配置 ​

  1. 编辑 Nginx 配置文件
  2. 确保 proxy_pass 指向正确的地址和端口
  3. 检查末尾斜杠是否正确
  4. 重新加载配置：
bash
sudo nginx -t  # 测试配置
sudo nginx -s reload  # 重新加载

方案 3: 检查服务启动命令 ​

确保 Twikoo 服务正确启动：

bash
# PM2 启动示例
pm2 start node_modules/twikoo/bin/twikoo.js -- server --port 8080

# 或使用配置文件
pm2 start ecosystem.config.js

方案 4: 验证服务可访问性 ​

bash
# 从服务器本地测试
curl http://127.0.0.1:8080/version

# 如果失败，检查服务是否监听正确端口
netstat -tlnp | grep 8080

前端诊断功能 ​

组件版本 v1.5.0 已添加诊断功能：

  1. 服务健康检查：初始化前检查服务是否可用
  2. 自动重试：502 错误时自动重试（最多3次）
  3. 诊断信息：显示详细错误信息和排查步骤
  4. 手动重试：用户可以手动触发重试

验证修复 ​

修复后，在浏览器控制台执行：

javascript
// 检查服务版本
fetch('https://chiplayout.net/twikoo/version')
  .then(r => r.text())
  .then(console.log)

// 应该返回版本号，而不是 502

预防措施 ​

  1. 监控服务状态：使用 PM2 监控或 systemd 自动重启
  2. 日志监控：定期检查 Nginx 和 Twikoo 日志
  3. 健康检查：设置定期健康检查脚本
  4. 备份配置：保存正确的 Nginx 配置备份

相关文档 ​