哪吒面板(Nezha)在Kubernetes中配置Ingress代理GRPC服务的解决方案

问题背景

在使用Kubernetes环境部署哪吒面板(Nezha)时，许多用户选择通过Ingress控制器来暴露服务。当配置Nginx Ingress代理哪吒面板的GRPC服务时，可能会遇到Agent无法连接的问题，具体表现为Agent日志中出现"客户端认证失败"的错误。

问题分析

通过分析问题现象，我们发现：

1. 前端页面可以正常访问，WebSocket和终端功能也正常工作
2. 当Agent直接连接独立端口时能够正常连接
3. 问题仅出现在通过Ingress代理GRPC服务时

这表明HTTP和WebSocket代理配置正确，问题出在GRPC代理的特殊配置上。

解决方案

关键在于Nginx Ingress需要特殊配置来处理GRPC请求的头信息。在Ingress资源中添加以下注解即可解决问题：

nginx.ingress.kubernetes.io/server-snippet: underscores_in_headers on;

这个配置允许Nginx处理包含下划线的HTTP头信息，而GRPC协议通常会使用这类头信息进行通信。

完整配置示例

以下是经过验证可用的完整Ingress配置示例：

HTTP和WebSocket代理配置

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/tls-acme: 'true'
    nginx.ingress.kubernetes.io/proxy-body-size: 4G
    nginx.ingress.kubernetes.io/proxy-request-buffering: 'off'
  name: nezha
  namespace: default
spec:
  ingressClassName: nginx
  rules:
    - host: nz.example.com
      http:
        paths:
          - backend:
              service:
                name: nezha
                port:
                  number: 80
            path: /
            pathType: ImplementationSpecific
  tls:
    - hosts:
        - nz.example.com
      secretName: nz.example.com-tls

GRPC代理配置

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: GRPC
    nginx.ingress.kubernetes.io/configuration-snippet: grpc_socket_keepalive on;
    nginx.ingress.kubernetes.io/proxy-body-size: 4G
    nginx.ingress.kubernetes.io/proxy-request-buffering: 'off'
    nginx.ingress.kubernetes.io/server-snippet: underscores_in_headers on;
  name: nezha-grpc
  namespace: default
spec:
  ingressClassName: nginx
  rules:
    - host: nz.example.com
      http:
        paths:
          - backend:
              service:
                name: nezha
                port:
                  number: 80
            path: /proto.NezhaService
            pathType: ImplementationSpecific
  tls:
    - hosts:
        - nz.example.com
      secretName: nz.example.com-tls

技术原理

GRPC协议基于HTTP/2，使用特殊的头信息进行通信。Nginx默认会忽略包含下划线的头信息，这是出于安全考虑。哪吒面板的Agent在与服务端通信时使用了这类头信息，因此需要明确配置Nginx允许处理这些头信息。

underscores_in_headers on指令告诉Nginx不要忽略包含下划线的头信息，从而确保GRPC通信能够正常进行。

验证方法

部署配置后，可以通过以下方式验证：

1. 检查Agent日志，不应再出现"客户端认证失败"的错误
2. 在前端面板中查看服务器状态，应能看到Agent正常上报的信息
3. 使用终端功能测试与服务器的连接

总结

在Kubernetes环境中通过Ingress代理哪吒面板服务时，GRPC代理需要特殊配置。添加underscores_in_headers on注解是解决Agent连接问题的关键。这一解决方案不仅适用于哪吒面板，对于其他需要通过Ingress代理GRPC服务的应用也有参考价值。