DM-ROW 接口文档

Appearance

Ingress流量管理 ​

**本文引用的文件** - [baremetal-nginx-ingress.yaml](file://lemes-cloud/src/devops/k8s/baremetal-nginx-ingress.yaml) - [ingress-real-ip.yaml](file://lemes-cloud/src/devops/k8s/ingress-real-ip.yaml) - [gateway-ingress.yaml](file://lemes-cloud/src/devops/console/k8s/template/gateway-ingress.yaml) - [lemes-web.yaml](file://lemes-cloud/src/devops/console/k8s/template/lemes-web.yaml) - [seaweedfs-ingress.yaml](file://lemes-cloud/src/devops/k8s/service/base/seaweedfs-ingress.yaml) - [secret.yaml](file://lemes-cloud/src/devops/k8s/service/base/secret.yaml) - [baseUrl.js](file://app/devicemate-app/config/baseUrl.js) - [request.js](file://app/devicemate-app/config/request.js) - [vue.config.js](file://app/devicemate-app/vue.config.js)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

本文件面向DeviceMate项目的Ingress流量管理，系统性阐述Nginx Ingress控制器的安装与配置、IngressClass与注解策略、TLS证书管理（含Secret创建与证书链）、路由规则（路径/主机名/重写）、中间件能力（限流/认证/CORS）以及HTTPS最佳实践（证书部署、HTTP/2与安全头部）。同时提供可直接参考的Ingress YAML示例与性能优化建议，帮助运维与开发团队在生产环境中稳定、安全地交付流量。

项目结构 ​

DeviceMate的Ingress相关配置主要分布在以下位置：

  • 控制器安装与RBAC：lemes-cloud/src/devops/k8s/baremetal-nginx-ingress.yaml
  • 控制器运行参数与IngressClass：同上文件中的Deployment与args
  • 实际业务Ingress示例：lemes-cloud/src/devops/console/k8s/template/*.yaml
  • TLS证书Secret：lemes-cloud/src/devops/k8s/service/base/secret.yaml
  • 客户端访问入口与代理配置：app/devicemate-app/config/*.js 与 app/devicemate-app/vue.config.js

图示来源

章节来源

核心组件 ​

  • Nginx Ingress控制器
    • 通过Deployment运行，使用IngressClass“nginx”，并挂载证书Secret用于HTTPS。
    • 默认监听80/443端口，可通过NodePort对外暴露。
  • ConfigMap控制器配置
    • 启用转发头计算、允许snippet注解、使用X-Forwarded-For等，确保后端能正确识别客户端真实IP。
  • 业务Ingress
    • lemes-gateway-ig：将前缀“/lemes-api”转发至网关服务，并设置超时与上传大小限制。
    • lemes-web-ig：根路径“/”转发至Web服务。
    • lemes-seaweedfs-ig：将“/lemes-oss”前缀转发至网关，实现OSS访问代理。
  • TLS证书
    • 使用Secret存储tls.crt与tls.key，供Ingress控制器加载以启用HTTPS。

章节来源

架构总览 ​

下图展示从客户端到后端服务的完整流量路径，包括Ingress控制器、转发头处理与TLS终止：

图示来源

详细组件分析 ​

Nginx Ingress控制器安装与IngressClass ​

  • 安装要点
    • 创建命名空间、ServiceAccount、ClusterRole/Role与绑定。
    • 部署Service（NodePort暴露80/443）与Deployment（控制器镜像与args）。
    • args中指定IngressClass为“nginx”，并挂载Webhook证书Secret。
  • IngressClass
    • 通过Deployment的启动参数设置，确保Ingress资源仅被该控制器处理。
  • RBAC与准入控制
    • 允许控制器读取ConfigMap、Secret、Endpoints等；启用ValidatingWebhook以校验Ingress合法性。

图示来源

章节来源

负载均衡与转发头（真实IP） ​

  • 关键配置
    • 在ConfigMap中开启“use-forwarded-headers”、“compute-full-forwarded-for”、“forwarded-for-header”等，使控制器在请求头中注入或透传X-Forwarded-For。
    • 业务侧（如网关）据此解析真实客户端IP，便于审计与风控。
  • 影响范围
    • 所有经由该Ingress控制器的流量均受此影响。

图示来源

章节来源

路由规则与重写 ​

  • 前缀匹配
    • lemes-gateway-ig：将“/lemes-api”前缀转发至网关服务，适合API聚合场景。
    • lemes-web-ig：将“/”根路径转发至Web服务，适合静态站点或SPA。
    • lemes-seaweedfs-ig：将“/lemes-oss”前缀转发至网关，再由网关内部重写到具体OSS接口。
  • 重写规则
    • 通过注解设置“rewrite-target”，实现路径重写，常用于多服务共享同一前缀的场景。
  • 主机名匹配
    • 当前示例未配置host字段，若需按域名分发，可在Ingress.spec.rules[*].host中添加。

图示来源

章节来源

注解配置（超时/上传大小/重写） ​

  • 常用注解
    • 代理连接/发送/读取超时：提升长连接与大文件传输稳定性。
    • 代理body大小：避免上传过大导致失败。
    • rewrite-target：实现路径重写，常配合前缀路由使用。
  • 示例来源
    • 网关Ingress示例展示了上述注解的典型用法。

章节来源

TLS证书管理（Secret创建与证书链） ​

  • Secret结构
    • 类型为kubernetes.io/tls，包含tls.crt与tls.key两个密钥。
    • 可通过kubectl create secret tls命令或直接声明Secret资源创建。
  • 证书链与自动续期
    • 仓库中提供了Secret样例，但未包含自动签发/续期的Cert-Manager或类似机制配置。若需自动化，建议引入证书管理器并在Ingress中引用对应的证书资源。
  • Ingress与Secret关联
    • Ingress可引用TLS块中的secretName，控制器加载Secret以终止TLS。

图示来源

章节来源

中间件能力（限流/认证/CORS） ​

  • 限流
    • 可通过注解实现基于IP或路径的速率限制，建议结合IngressClass与第三方插件使用。
  • 认证
    • 支持Basic Auth或OIDC等认证方式，通常通过注解或专用Ingress扩展实现。
  • CORS
    • 可通过注解设置Access-Control-Allow-*头，或在后端服务统一处理。
  • 注意
    • 上述能力在当前仓库示例中未直接体现，建议结合业务需求在Ingress注解或后端服务中补充。

（本节为通用指导，不直接分析具体文件）

HTTPS配置指南（证书部署/HTTP/2/安全头部） ​

  • 证书部署
    • 使用kubernetes.io/tls类型的Secret，Ingress引用其secretName。
  • HTTP/2
    • 控制器默认启用HTTP/2，无需额外配置；如需禁用，可在ConfigMap中调整。
  • 安全头部
    • 可通过注解设置Security Headers（如Strict-Transport-Security、X-Content-Type-Options等），增强安全性。
  • 客户端访问
    • 前端通过相对路径访问后端API，开发环境使用本地代理将/lemes-api重写到后端。

章节来源

依赖关系分析 ​

  • 控制器依赖
    • ServiceAccount与RBAC赋予控制器读取集群资源的能力。
    • ConfigMap控制转发头与snippet注解等行为。
    • Secret提供TLS证书，用于HTTPS终止。
  • 业务依赖
    • Ingress依赖对应Service（如lemes-gateway-svc、lemes-web-svc）。
    • 前端通过相对路径与代理配置访问后端API。

图示来源

章节来源

性能考量 ​

  • 连接与超时
    • 对长连接或大文件场景，适当提高proxy-connect-timeout、proxy-send-timeout、proxy-read-timeout与proxy-body-size。
  • 负载均衡
    • 合理设置副本数与资源请求，避免单点瓶颈；必要时启用亲和性与拓扑感知。
  • 缓存与压缩
    • 启用gzip/deflate与静态资源缓存，减少带宽占用。
  • 健康检查
    • 配置liveness/readiness探针，确保快速剔除不健康实例。
  • 日志与监控
    • 开启访问日志与指标导出，结合Prometheus/Grafana进行观测。

（本节为通用指导，不直接分析具体文件）

故障排查指南 ​

  • 无法解析真实IP
    • 检查ConfigMap是否开启use-forwarded-headers与compute-full-forwarded-for。
  • 证书加载失败
    • 确认Secret类型为kubernetes.io/tls且包含tls.crt与tls.key；Ingress是否正确引用secretName。
  • 路由不生效
    • 确认IngressClass为nginx；检查Ingress注解语法与路径匹配规则。
  • 超时或上传失败
    • 检查proxy超时与body大小注解；确认后端服务处理能力。
  • 前端跨域问题
    • 在Ingress注解中设置CORS头，或在后端统一处理。

章节来源

结论 ​

DeviceMate的Ingress流量管理以Nginx Ingress为核心，通过明确的IngressClass、合理的注解配置与TLS Secret，实现了对多业务路径的统一接入与安全终止。结合转发头配置与后端服务，可有效支撑真实IP识别与API聚合。建议后续引入证书自动化与中间件能力（限流/认证/CORS），并持续优化超时与缓存策略，以满足生产环境的高可用与高性能要求。

附录 ​