DM-ROW 接口文档

Appearance

服务发现机制 ​

**本文引用的文件** - [lemes-service-dm-common.yaml](file://lemes-cloud/src/devops/k8s/service/expose-port/lemes-service-dm-common.yaml) - [lemes-service-dm-device.yaml](file://lemes-cloud/src/devops/k8s/service/expose-port/lemes-service-dm-device.yaml) - [lemes-service-dm-store.yaml](file://lemes-cloud/src/devops/k8s/service/expose-port/lemes-service-dm-store.yaml) - [lemes-service-dm-workflow.yaml](file://lemes-cloud/src/devops/k8s/service/expose-port/lemes-service-dm-workflow.yaml) - [lemes-auth.yaml](file://lemes-cloud/src/devops/k8s/service/expose-port/lemes-auth.yaml) - [lemes-webservice.yaml](file://lemes-cloud/src/devops/k8s/service/expose-port/lemes-webservice.yaml) - [common.yaml](file://lemes-cloud/src/devops/k8s/service/base/common.yaml) - [auth.yaml](file://lemes-cloud/src/devops/k8s/service/base/auth.yaml) - [gateway.yaml](file://lemes-cloud/src/devops/k8s/service/base/gateway.yaml) - [lemes-web.yaml](file://lemes-cloud/src/devops/k8s/service/base/lemes-web.yaml) - [nacos.yaml](file://lemes-cloud/src/devops/k8s/service/base/nacos.yaml) - [redis.yaml](file://lemes-cloud/src/devops/k8s/service/base/redis.yaml)

目录 ​

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

引言 ​

本文件系统化梳理 DeviceMate 项目的 Kubernetes 服务发现机制，围绕 Service 资源类型（ClusterIP、NodePort、LoadBalancer、ExternalName）在本仓库中的实际使用进行说明；解释 Service 选择器（Label 匹配）、端口映射与会话亲和性策略；给出 Headless Service 配置（用于 StatefulSet）与服务网格集成（Istio 注入、流量管理、服务间认证）的参考路径；并总结命名规范、标签策略与网络策略集成的最佳实践，辅以具体 Service YAML 示例路径与故障排除建议。

项目结构 ​

本项目的服务发现相关配置主要集中在 lemes-cloud/src/devops/k8s/service 目录下，按“暴露端口”和“基础服务”两类组织：

  • 基础服务（base）：包含通用服务、认证、网关、Web、Nacos、Redis 等，多采用 ClusterIP 或 Headless（clusterIP: None），配合 Ingress 对外暴露。
  • 暴露端口（expose-port）：面向需要直接通过节点端口访问的服务，统一采用 NodePort 类型。

图表来源

章节来源

核心组件 ​

  • Service 类型与用途
    • ClusterIP：默认集群内访问，适合内部服务间通信。例如通用服务、认证服务、网关服务以及 Web 服务均采用 ClusterIP。
    • NodePort：对外暴露服务，通过节点 IP:nodePort 访问。DeviceMate 的各业务服务（dm-common/device/store/workflow）、认证与 Webservice 均采用 NodePort。
    • Headless（ClusterIP: None）：用于 StatefulSet 场景，暴露稳定网络标识，便于客户端直接连接 Pod。
    • LoadBalancer/ExternalName：未在本仓库中直接出现对应 YAML 示例，但可按标准配置接入云厂商负载均衡或外部服务别名。
  • 选择器与标签
    • 所有 Service 均通过 selector 与 Pod 模板中的 app 标签匹配，确保流量正确路由至后端 Pod。
  • 端口映射
    • Service 的 port/targetPort/nodePort 明确映射规则，便于跨环境一致访问。
  • 会话亲和性
    • 本仓库未显式配置 sessionAffinity，如需粘性会话可在 Service 层添加相应字段。

章节来源

架构总览 ​

DeviceMate 的服务发现遵循“内部 ClusterIP + 外部 NodePort/Ingress”的分层模式：

  • 内部服务（通用、认证、网关、业务模块）通过 ClusterIP 在集群内互相访问。
  • 需要对外暴露的服务通过 NodePort 或 Ingress 暴露，Web 服务通过 Ingress 绑定到 Headless Service。
  • StatefulSet 场景（Nacos、Redis）使用 Headless Service 提供稳定的 DNS 名称与 Pod 标识。

图表来源

详细组件分析 ​

Service 类型与使用场景 ​

  • ClusterIP
    • 适用：内部服务间调用，避免暴露到集群外。
    • 示例：通用服务、认证服务、网关服务、Web 服务（通过 Ingress 暴露）。
  • NodePort
    • 适用：需要从集群外直连访问的服务，或测试环境快速验证。
    • 示例：dm-common/device/store/workflow、auth、webservice。
  • Headless（ClusterIP: None）
    • 适用：StatefulSet 需要稳定的网络标识与 DNS 记录。
    • 示例：lemes-web 使用 Headless Service，结合 Ingress 暴露。
  • LoadBalancer/ExternalName
    • 适用：对接云厂商负载均衡或外部服务别名。
    • 说明：本仓库未提供对应 YAML 示例，可按标准字段配置。

章节来源

Service 选择器机制 ​

  • 标签匹配
    • Service.selector.app 与 Pod 模板 metadata.labels.app 必须一致，否则无法建立关联。
  • 端口映射
    • port：Service 暴露端口；targetPort：容器监听端口；nodePort：NodePort 类型的节点端口。
  • 会话亲和性
    • 本仓库未显式配置 sessionAffinity；如需粘性会话，可在 Service 中添加相应字段。

图表来源

章节来源

Headless Service 配置（StatefulSet） ​

  • 适用场景：StatefulSet 需要稳定的网络标识（稳定主机名、稳定存储）。
  • 配置要点：Service.spec.clusterIP 设为 None；StatefulSet.spec.serviceName 指向该 Service。
  • 示例路径：

图表来源

章节来源

服务网格集成方案（Istio） ​

  • Sidecar 注入
    • 可通过为命名空间或 Pod 添加注解实现自动注入 Envoy Sidecar。
    • 参考路径：Pod 模板中已存在 sidecar 卷与初始化容器，可作为注入 Sidecar 的前置条件。
  • 流量管理
    • 通过 DestinationRule、VirtualService、Gateway/Ingress 实现路由、熔断、超时、重试等策略。
  • 服务间认证
    • 通过 PeerAuthentication、AuthorizationPolicy 实现 mTLS 与访问控制。
  • 参考路径

章节来源

Service YAML 配置示例（路径） ​

依赖关系分析 ​

  • 服务间依赖
    • dm-common/device/store/workflow 通过 ClusterIP 由 common 服务提供通用能力。
    • 网关服务通过 ClusterIP 向外转发请求。
  • 外部依赖
    • Web 服务通过 Ingress 暴露，Headless Service 为 StatefulSet 提供稳定 DNS。
    • NodePort 服务直接暴露到宿主机，便于运维与测试。

图表来源

章节来源

性能考量 ​

  • 选择器匹配开销
    • 保持 selector 精准，避免过度宽泛导致匹配成本上升。
  • 端口映射一致性
    • 统一 port/targetPort/nodePort 命名与范围，减少运维复杂度。
  • Headless 与 StatefulSet
    • Headless 仅提供稳定 DNS，不引入额外代理开销；StatefulSet 的稳定性来自有序编号与持久卷。
  • 会话亲和性
    • 合理使用 sessionAffinity，避免热点后端过载。

故障排除指南 ​

  • 问题：Service 无法匹配到 Pod
  • 问题：NodePort 访问异常
  • 问题：Headless 无法解析到具体 Pod
    • 检查点：Service.clusterIP 是否为 None；StatefulSet.serviceName 是否指向该 Service；DNS 解析是否正常。
    • 参考路径：
  • 问题：Ingress 404 或 503
    • 检查点：Ingress 规则是否指向正确的 Service 名称与端口；Service 是否为 ClusterIP；后端 Pod 是否就绪。
    • 参考路径：

章节来源

结论 ​

DeviceMate 的服务发现机制以 ClusterIP 为核心，结合 Ingress 与 NodePort 实现内外部访问；Headless Service 为 StatefulSet 提供稳定网络标识。通过统一的标签策略与清晰的端口映射，系统实现了高内聚、低耦合的服务间通信。建议在生产环境中进一步完善服务网格策略（Istio）与网络策略，以提升可观测性与安全性。

附录 ​

  • 最佳实践清单
    • 命名规范
      • Service 名称：{业务模块}-svc；Deployment 名称：{业务模块}；Ingress 名称：{业务模块}-ig。
    • 标签策略
      • selector.app 与 Pod 标签 app 必须一致；为不同环境（dev/test/prod）设置额外标签区分。
    • 网络策略集成
      • 通过 NetworkPolicy 控制入站/出站流量，限制不必要的跨命名空间访问。
    • 会话亲和性
      • 仅在必要场景启用 sessionAffinity，避免后端负载不均。
    • 服务网格
      • 逐步引入 Istio，先在非关键链路验证流量治理策略，再推广到核心服务。