Plunk项目部署中fetch请求失败的排查与解决方案

Plunk是一个开源的开发者工具平台，在部署过程中可能会遇到后台服务fetch请求失败的问题。本文将深入分析该问题的成因并提供完整的解决方案。

问题现象

当Plunk后台服务启动约1分钟后，系统日志会出现以下错误信息：

TypeError: fetch failed
[cause]: ConnectTimeoutError: Connect Timeout Error
  code: 'UND_ERR_CONNECT_TIMEOUT'

该错误表明后台服务在尝试发起HTTP请求时遇到了连接超时问题。

根本原因分析

经过深入排查，发现该问题主要由以下两个因素共同导致：

1. 环境变量配置不当：特别是API_URI和NEXT_PUBLIC_API_URI的配置存在不一致性，且未正确包含协议头(https://)

2. 反向代理配置问题：当使用Traefik等反向代理时，如果没有正确处理API路径，会导致内部请求被错误重定向

完整解决方案

1. 环境变量正确配置

必须确保以下环境变量的正确性：

APP_URI=https://yourdomain.com
API_URI=http://localhost:4000  # 内部使用本地地址
NEXT_PUBLIC_API_URI=https://yourdomain.com/api  # 客户端使用公开地址

关键点说明：

• API_URI应该指向本地服务地址，因为这是后台服务内部使用的
• 所有公开URL必须包含https://协议头
• 内部和外部地址必须保持一致的功能路径

2. Traefik代理配置优化

对于使用Traefik作为反向代理的情况，需要特殊配置来处理API路径：

labels:
  - traefik.http.routers.plunk-api.rule=Host(`yourdomain.com`) && PathPrefix(`/api`)
  - traefik.http.routers.plunk-api.service=plunk-api
  - traefik.http.services.plunk-api.loadbalancer.server.port=4000
  - traefik.http.routers.plunk-web.rule=Host(`yourdomain.com`)
  - traefik.http.routers.plunk-web.service=plunk-web
  - traefik.http.services.plunk-web.loadbalancer.server.port=5000

这种配置实现了：

• 将/api路径的请求路由到4000端口(API服务)
• 其他请求路由到5000端口(前端服务)
• 避免了Nginx的不必要重定向

3. 验证步骤

部署后应进行以下验证：

1. 访问API端点验证：

curl https://yourdomain.com/api

预期返回：

{"code":404,"error":"Not Found","message":"Unknown route","time":1234567890}

2. 检查后台服务日志，确认定时任务能正常运行

3. 验证前端能正确调用API接口

深入技术原理

Plunk的后台服务会定期执行维护任务，如"Updating verified identities"。这些任务需要通过HTTP请求与自身API交互。当配置不正确时，会导致：

1. 请求被错误重定向
2. 形成请求循环
3. 最终因超时而失败

正确的配置应确保：

• 内部请求直接访问本地服务，避免经过反向代理
• 外部请求经过代理但路径处理正确
• 所有URL包含完整协议和路径

总结