Hoppscotch自托管部署中的服务连接问题分析与解决

问题背景

在Kubernetes环境中使用Helm Chart部署Hoppscotch时，开发团队遇到了后端服务不可用的问题。具体表现为：前端应用可以正常访问，但管理界面显示空白页面，后端服务返回503错误状态码。

环境配置

部署采用了以下关键配置：

• 使用Helm Chart进行部署
• 通过ConfigMap管理环境变量
• 数据库使用PostgreSQL
• 认证服务配置了Google OAuth
• 邮件服务配置了SMTP
• 使用Nginx Ingress Controller处理入口流量

问题排查过程

开发团队首先检查了环境变量配置，确认所有URL和凭证设置正确。特别是以下关键配置项：

• 前后端分离部署，使用不同子域名
• 正确配置了GraphQL端点
• WebSocket连接使用wss协议
• 设置了跨域白名单

进一步检查发现，虽然服务部署成功，但后端服务实际上无法被正确访问。通过检查Kubernetes服务定义，发现了潜在问题。

根本原因

问题出在Service资源的定义上。原始配置中，服务端口定义存在缺陷：

• 服务端口命名为http-app
• 但目标端口也使用了相同的名称http-app
• 这种配置在某些Kubernetes环境中可能导致端口映射失效

解决方案

团队修改了Service资源的定义，确保端口映射正确。关键修改点包括：

• 明确定义服务端口为3000
• 正确指定目标端口
• 确保协议类型为TCP

修改后的Service配置示例：

apiVersion: v1
kind: Service
metadata:
  name: hoppscotch-service
spec:
  type: ClusterIP
  ports:
    - port: 3000
      targetPort: 3000
      protocol: TCP
      name: http
  selector:
    app: hoppscotch

经验总结

在Kubernetes环境中部署复杂应用时，需要注意以下几点：

1. 服务发现机制：确保Service和Pod之间的标签选择器匹配
2. 端口映射：明确数字端口比使用命名端口更可靠
3. 健康检查：配置适当的就绪和存活探针
4. 逐步验证：先验证基础服务连通性，再测试高级功能

通过这次问题解决，团队加深了对Kubernetes服务发现机制的理解，为今后类似项目的部署积累了宝贵经验。