Prometheus服务发现实战：从文件到K8s的监控配置指南

做监控时间长了，你大概率经历过这样的场景：新服务要上线，你提前把IP写进prometheus.yml，reload，然后盯着Targets页面变成绿色。等业务规模一上来，扩容变成家常便饭，你会发现每天都在反复改IP、删IP，改到怀疑人生。Prometheus服务发现机制，专门解决这样一类问题——让监控系统自己去发现该抓谁，而不是你手动告诉它该抓谁。它也是Prometheus能在动态基础设施里站稳脚跟的关键设计。这篇文章从原理讲到实操，覆盖文件、DNS、Consul、Kubernetes这几类最主流的服务发现方式，也包含大量我实际踩坑后的配置示例，适合正在给Prometheus做动态监控、或者想把监控能力接到自己业务系统中的朋友。

1. 服务发现到底解决了什么问题

1.1 静态配置的瓶颈在哪

在没有服务发现的年代，大家做监控采集最常用的方式就是改配置文件。在prometheus.yml里把targets一个一个列出来，把服务IP和端口写死。比如要监控一批机器，就在static_configs下写入几十个IP；要监控一个Redis集群，就把每个节点的IP:9121写进去。这套玩法在小规模、少变更的场景下没有问题，但一旦系统进入微服务化、容器化，节点频繁上下线，每天花大量时间改文件、触发reload、检查Targets页面就成了常识。

举个实际场景。我维护过一个业务集群，高峰期会做自动扩容，扩容脚本创建完实例之后，应用进程大约需要3分钟才能对外提供服务。如果用静态配置，你必须在扩容之前把新IP加进Prometheus配置，否则新实例会处于监控盲区。等缩容开始，实例被销毁，静态配置里的旧IP会变成永久DOWN的Target，长期挂在Targets页面里。这两个问题，一个叫“监控盲区”，一个叫“僵尸Target”，根子都在于静态配置无法跟随实例生命周期变化。

1.2 Prometheus服务发现的执行流程

服务发现的核心思路，是把“目标列表”从配置文件里的固定值，变成Prometheus周期性扫描外部数据源后得到的动态结果。每个scrape_config下面，既可以写targets，也可以写各类服务发现配置。Prometheus在启动时会初始化所有的scrape_config，同时开启对应服务发现器的定时刷新任务，把发现的每个目标转换成一个内部目标对象，再经过一系列relabel规则处理后，才进入实际抓取环节。

这里要理解一个点：服务发现不是只在启动时执行一次，而是周期性执行的。比如Consul SD默认每30秒刷新一次，文件SD默认间隔在5分钟左右（新版本还有文件监听优化），Kubernetes SD则通过watch机制减少延迟。你不需要死记每个数据源的刷新间隔，但一定要知道Prometheus抓取的是“内存里的目标列表”，服务发现更新的就是这张表。服务发现只负责找到目标，目标是否存活、抓取是否成功，仍然是scrape阶段的事。

另一个关键概念是relabel。服务发现器产生的原始目标，会带上一堆以__meta_开头、以下划线包裹的临时标签，比如__address__表示要抓取的地址，__meta_*里面是各类元数据。relabel规则可以对这些临时标签做筛选、改名、覆盖地址，最后生成真正要抓取的target。后面所有实战配置，本质上都是在操作这些标签。

2. 主流服务发现方式与选型分析

2.1 静态配置：固定节点的兜底方案

静态配置不需要额外组件，适合节点数量少、变更频率极低的场景。我的建议是，即使上了服务发现，也不要把static_configs完全删掉。一些基础组件（Prometheus自身、告警管理器、关键数据库）用静态配置反而最稳。因为这些组件不经常变，如果也交给SD，反而会给监控链路引入不必要的依赖，一旦发现源挂了，你可能连自监控都丢掉。

static_configs和SD配置可以写在同一个scrape_config里，Prometheus会自动合并两组目标，不用拆成多个job。不过要注意，静态配置的目标也没有自动摘除能力，目标下线后如果不再需要，还是要手动把IP从配置里移除，否则会一直留在Targets列表里。

2.2 文件服务发现：最灵活的自研系统对接方式

file_sd_configs是个人系统和Prometheus对接时最常用、成本最低的方式。它只需要提供一个JSON或YAML文件，Prometheus会周期扫描并动态读取，把文件里的targets加入目标列表。文件不要求一定放在Prometheus机器本地，只要是Prometheus进程能读到的路径就行。你可以由一个cron脚本、后端服务甚至配置管理工具来更新它。

一个最简配置：

yaml复制scrape_configs:
  - job_name: 'mybackend'
    file_sd_configs:
      - files:
          - /etc/prometheus/targets/*.json
        refresh_interval: 30s

对应JSON文件：

json复制[
  {
    "targets": ["10.0.0.11:8080", "10.0.0.12:8080"],
    "labels": {
      "env": "prod",
      "service": "mybackend"
    }
  }
]

新增节点只需要更新这个文件，Prometheus会在下个刷新周期把新target加进来，不需要reload，也不需要重启进程。这套方案非常适合那些想接监控、又不想把业务系统直接耦合进Prometheus配置管理的团队。

2.3 DNS服务发现：适合固定服务名、动态IP的场景

dns_sd_configs利用DNS的SRV记录来发现目标。当系统里IP会变化、但服务名固定的时候很实用。比如你用Consul的DNS功能，或者Kubernetes headless Service，SRV记录天然存在，Prometheus定期解析即可。

yaml复制scrape_configs:
  - job_name: 'redis-node'
    dns_sd_configs:
      - names:
          - _redis._tcp.example.com
        port: 9121

每条SRV记录会生成一个目标。这类SD的优点是零部署成本，不需要额外组件；缺点是SRV记录里的元信息很少，你没法用它来区分环境、区域等标签，做精细化路由会比较吃力。

2.4 Consul服务发现：传统微服务架构的标配

Consul服务发现是生产环境里非常常见的选择。Consul本身承担服务注册中心职责，Prometheus只需要轮询Consul的Catalog API，就能拿到所有注册服务的节点列表。配合Consul的健康检查，还能自动剔除不健康的节点。

典型配置：

yaml复制scrape_configs:
  - job_name: 'consul-services'
    consul_sd_configs:
      - server: 'consul.example.com:8500'
        services: ['api-server', 'redis-exporter']
    relabel_configs:
      - source_labels: [__meta_consul_service]
        target_label: service
      - source_labels: [__meta_consul_node]
        target_label: instance

Consul注册时会带大量元数据标签，比如数据中心、服务ID、服务地址、服务端口，甚至自定义标签，这些都能拿来做relabel。这里有个很常见的坑：如果你注册的service是Redis本身，但Prometheus要抓取的是redis_exporter暴露出的指标，那么配置里的services应该写redis-exporter，或者让Consul的地址指向exporter监听端口。否则Prometheus会把目标地址指向Redis服务端口，抓取时只会得到一堆连接错误。

2.5 Kubernetes服务发现：容器化环境的事实标准

K8s的服务发现是Prometheus里最复杂、也最核心的一块。它通过访问Kubernetes API Server动态获取节点、Pod、Service、Endpoint等资源的信息，并转换成一组__meta_kubernetes_*标签。常用role包括node、pod、service、endpoints、ingress，每种role返回的资源类型不同，用途也不同。这一块在第4章里我会展开细讲，这里先记住一个结论：K8s场景下，单纯把每个Pod当成静态target来配置是走不通的，必须依赖SD加relabel。

2.6 各类服务发现方式选型对比

选型时有一个原则：能用业务侧已有数据源就尽量复用。已经有Consul就别另起一套文件SD，已经在K8s里跑服务就别再用静态IP方案。监控体系要跟着基础设施走，而不是反过来让基础设施迁就监控。

3. 实操：文件服务发现的完整落地

3.1 场景目标与目录规划

假设你有一套自研的业务后台，里面的计算任务会动态在多个节点启动和销毁，你想把它们纳入Prometheus监控，同时希望Prometheus部署后不频繁修改配置文件。用文件SD来对接是最直接的方案：业务系统在实例注册、注销时写一份目标文件，Prometheus自动读取。

目录规划建议：

code复制/etc/prometheus/
├── prometheus.yml
└── targets/
    ├── backend.json
    └── redis.json

主配置里增加文件SD：

yaml复制scrape_configs:
  - job_name: 'auto-backend'
    file_sd_configs:
      - files:
          - '/etc/prometheus/targets/*.json'
        refresh_interval: 30s

refresh_interval建议根据业务变更频率来定。如果是分钟级扩容，30秒比较合适；如果业务变更不频繁，默认5分钟也能接受。刷新越频繁，Prometheus对文件读取的压力越大，但正常情况下几十个文件、每秒读一次也不会有什么问题。

3.2 目标文件的格式与细节

文件SD支持JSON和YAML两种格式。JSON整体是一个数组，数组里的每个对象代表一组目标。每个对象包含targets数组和labels对象。这种“数组套对象”的结构让文件本身可以承载多组目标，每组带不同的标签。

json复制[
  {
    "targets": ["10.0.0.11:8080"],
    "labels": {
      "service": "backend-a",
      "env": "prod"
    }
  },
  {
    "targets": ["10.0.0.21:8080", "10.0.0.22:8080"],
    "labels": {
      "service": "backend-b",
      "env": "staging"
    }
  }
]

如果多个对象里的标签不同，最终目标集合就是所有对象目标并集的结果。同一个target出现在多组里时，后加载的组标签可能覆盖先加载的，所以尽量保持目标的唯一性，避免一个IP在多个文件里重复定义。

这里有个新手很容易踩的坑：文件内容不是数组。很多人会把JSON写成单个对象，比如{"targets": [...], "labels": {...}}，Prometheus解析时会直接报错，日志里提示JSON格式无效。写文件时必须保证顶层是数组。

3.3 结合relabel的进阶配置

文件SD产生的目标，默认__address__就是targets里写的host:port。但在实际场景里，目标地址可能不是最终抓取地址。比如业务注册的是10.0.0.11:8080，而监控指标在/metrics路径，或者8080是业务端口、指标端口是9100，这时候就需要用relabel来改写。

yaml复制scrape_configs:
  - job_name: 'auto-backend'
    file_sd_configs:
      - files:
          - '/etc/prometheus/targets/*.json'
    relabel_configs:
      - source_labels: [__address__]
        regex: '(.*):8080'
        replacement: '${1}:9100'
        target_label: __address__
      - source_labels: [__meta_filepath]
        regex: '.*/(.*)\.json'
        target_label: sd_file
        replacement: '$1'

第一段规则把原地址的8080端口替换成9100，这是很典型的“业务端口和指标端口分离”的处理方式。第二段规则从文件路径里提取文件名做标签，方便后续告警时定位目标来源。文件SD提供的元标签不多，__meta_filepath是其中比较常用的一条，但默认并不一定会出现在目标标签中，需要自己通过relabel转出来。

3.4 自研系统与文件SD对接的三种路径

文件SD对接自研系统，最核心的问题是谁来写文件、怎么保证文件可靠。

第一种路径：由业务后端在实例注册、心跳上报时，把当前存活实例列表一次性写成JSON。写入时先用临时文件名，再rename覆盖目标文件，这样Prometheus在任意时刻读取，看到的都是一个完整文件，而不是写到一半的半个JSON。这是我在实际项目里最推荐的方式。

第二种路径：写一个cron脚本，定时执行服务发现命令，再把结果输出到JSON文件。适合业务系统比较老旧、没法快速改代码的情况。脚本逻辑很简单：查数据库、调接口、拿到节点列表、生成JSON、原子覆盖。

第三种路径：把目标文件放到共享存储或配置中心，由运维通过配置管理工具分发。这种方式适合多个Prometheus实例共享一份目标列表的场景，但要额外保证所有Prometheus都能读到同一份文件。

不管哪种路径，都要注意文件权限。Prometheus进程运行用户必须对目标目录有读权限，否则Prometheus会一直打日志告诉你文件读取失败，但Targets页面不会有明显报错，排查起来很费劲。

4. Kubernetes环境下的服务发现实战

4.1 k8s服务发现常用role与作用

K8s服务发现的特殊之处在于，它不只是找到“一个IP”，而是要区分role，因为监控目标可能是Node、Pod、Service、Endpoint或Ingress。

role: node返回集群所有节点，常用来采集node-exporter指标。role: pod返回所有Pod，适合业务应用直接暴露metrics端口的场景。role: service返回所有Service对象，适合通过Service访问metrics接口的场景。role: endpoints返回Service关联的Endpoints对象，每个Endpoint对应一个目标，适合需要做负载均衡的场景。role: ingress返回Ingress对象，多用于HTTP层监控。

每种role会携带不同的__meta_kubernetes_*标签，这些标签是relabel配置的基础。比如Pod角色会带__meta_kubernetes_namespace、__meta_kubernetes_pod_name、__meta_kubernetes_pod_label_*、__meta_kubernetes_pod_annotation_*等，信息量非常丰富。

4.2 用node role采集node-exporter

这是K8s监控告警体系里最基础的需求：采集每个节点的CPU、内存、磁盘等指标。完整配置如下：

yaml复制scrape_configs:
  - job_name: 'node-exporter'
    kubernetes_sd_configs:
      - role: node
    relabel_configs:
      - action: labelmap
        regex: __meta_kubernetes_node_label_(.+)
      - source_labels: [__address__]
        regex: '(.*):10250'
        replacement: '${1}:9100'
        target_label: __address__

这段配置最关键的地方是把默认的抓取地址从kubelet端口（10250）替换成node-exporter端口（9100）。第一次配K8s监控的人，十有八九在这里翻车：node角色已经发现了所有节点，但抓取一直失败，因为kubelet的10250端口不是metrics接口，而是API端口。所以必须用relabel把__address__的端口替换成9100。

labelmap的作用是把Node上的标签，比如kubernetes.io/hostname，映射成监控指标里的标签。这样后面在Alertmanager里按节点名做告警路由、或者在大盘里按节点筛指标，就能直接用这些标签。

这里要注意RBAC权限。Prometheus的ServiceAccount要有对nodes资源的get、list、watch权限，否则服务发现会持续报403。这个问题非常常见，配置正确却看不到任何目标，八成就是RBAC没做对。

4.3 通过annotation自动发现Pod指标接口

如果业务Pod已经暴露了metrics端口，但没有固定的Service，用role: pod配合annotation来过滤最灵活。业内通用的约定是三个注解：prometheus.io/scrape、prometheus.io/path、prometheus.io/port。

yaml复制scrape_configs:
  - job_name: 'kubernetes-pods'
    kubernetes_sd_configs:
      - role: pod
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
        action: keep
        regex: 'true'
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
        replacement: '$1'
        target_label: __metrics_path__
      - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
        regex: '([^:]+)(?::\d+)?;(\d+)'
        replacement: '$1:$2'
        target_label: __address__
      - action: labelmap
        regex: __meta_kubernetes_pod_label_(.+)
      - source_labels: [__meta_kubernetes_namespace]
        target_label: namespace
      - source_labels: [__meta_kubernetes_pod_name]
        target_label: pod

这段配置做的事情是：先保留带prometheus.io/scrape: "true"注解的Pod，再用注解里的path替换默认metrics路径，把Pod IP和注解里的端口拼成新的抓取地址，最后把Pod的标签和相关元信息转成最终标签。

这套annotation约定在生产环境很实用。只需要让业务团队在Pod模板里统一加上这几个注解，新增服务的监控接入就不需要运维再改Prometheus配置。这里隐含的管理思路是：把监控接入的入口下沉到业务侧，运维只维护一套通用的发现规则。

4.4 Kubernetes环境下的抓取地址问题

K8s环境下，Prometheus抓取Pod的地址是Pod IP，但这里有个网络连通性问题：如果你的Prometheus部署在集群外，或者Prometheus Pod没有和业务Pod在同一网络平面，Pod IP可能完全访问不通。这时候有两个方向：一是把Prometheus部署成DaemonSet并使用hostNetwork，让它能访问节点网络；二是通过NodePort或Service把metrics端口暴露出来，再在relabel阶段把地址改成NodeIP加NodePort。

这两种方案各有代价。hostNetwork会占用节点端口，并且多个Prometheus副本可能端口冲突；NodePort方案会额外暴露端口，需要网络策略配合。实际项目中，我遇到过最多的情况是“Targets出现在列表里、但抓取超时”，排查下来基本都卡在这个环节。所以，如果你的Prometheus不是跑在K8s集群内部，就不要直接用Pod角色的Pod IP当抓取地址。

5. 常见问题与排查技巧实录

5.1 文件发现不生效或目标迟迟不更新

表现：改了JSON文件，Prometheus很久才更新，或者根本不更新。

排查第一步看refresh_interval，文件SD默认刷新间隔是5分钟，如果你改完文件等1分钟就急着刷新页面，那大概率还在间隔内。第二步看文件路径是否在配置里正确通配，Prometheus对路径错误不会在启动时硬报错，它会在日志里持续记录读取失败，你可以用promtool check config校验配置，再查看Prometheus日志确认有没有解析错误。第三步看文件内容是否为合法JSON数组，单个对象会导致解析失败。

5.2 目标出现在Targets里但状态是DOWN

目标能出现，说明服务发现问题解决了，剩下的问题在抓取链路。

最常见原因有三个：端口替换错了，__address__没有指向exporter端口；目标机的防火墙或云安全组没有放行对应端口；抓取路径不对，比如Exporter的metrics路径不是默认的/metrics。排查方法很直接：从Targets页面复制Endpoint地址，手动用curl请求这个地址。如果curl有响应数据，问题在Prometheus配置，重点检查relabel是否改错了地址；如果curl不通，问题在目标机网络或服务本身。

5.3 relabel之后目标全部消失

这种情况经常出现在刚写relabel规则时。action: keep加错了regex，把全部目标都过滤掉了。

排查思路是：先临时去掉relabel配置，看目标能否正常出现，确认是relabel的问题后，再逐条加入规则观察变化。另外要注意，relabel后的目标在Targets页面只能看到最终标签，看不到__meta_*临时标签，所以没法依赖页面直接判断。这里有个小技巧：用Prometheus自带的promtool check config验证配置，它对标签字段、正则语法错误能及时发现。

5.4 Kubernetes环境发现到目标但抓取失败

K8s里抓取失败，除了网络问题，还有一个高频原因是RBAC权限不足。你在Targets页面看到的可能是“server returned HTTP status 403 Forbidden”，或者服务发现阶段就报错导致列表为空。先检查Prometheus的ServiceAccount有没有对应资源的get、list、watch权限。权限配好之后，再看网络连通性，尤其是前面说的Pod IP访问问题。

5.5 多套SD源同时发现同一个目标

如果一个目标被多个服务发现源命中，Prometheus会合并目标列表，每个源带来的标签可能不一样。比如文件SD带来的env=prod，Consul SD也带来了env=dev，后者会覆盖前者，最终标签以先到先得还是后到覆盖，取决于实际合并顺序，这种不确定性很容易影响告警路由。

我的习惯是：一个scrape_config里尽量只使用一类SD。如果确实需要多类SD混合，要在relabel阶段给每类源打上唯一标签，比如sd_source: "consul"或者sd_source: "file"，后续告警路由、去重都能有据可依。

5.6 常见问题速查表

6. 服务发现配置的几条个人经验

配置服务发现的路上，有几条经验是踩过坑之后才总结出来的。第一条，不要一开始就上最复杂的方式。如果你的业务还没到K8s那种规模，文件SD已经完全够用，没必要为了“自动化”而引入Consul或K8s SD，复杂度会成倍增加。第二条，任何SD配置上线前，都用promtool check config过一遍，再把抓取间隔调短到5秒观察Targets页面，确认目标列表符合预期再恢复正常刷新周期。第三条，始终给目标打上业务标签，比如service、env，这会在后续配置告警、做聚合时会省下大量时间。

还有一点，服务发现不是一次性配置完就结束的。目标列表会随着业务系统动态变化，你需要定期检查Targets页面，关注是否有意外出现的新目标、是否有长期DOWN的僵尸目标。Prometheus本身提供了一个健康度指标可以跟踪，把服务发现的状态也纳入监控，这才是完整的监控体系。

最后再分享一个我在生产环境中的心得：接一套自定义指标到Prometheus时，不要只考虑“怎么配抓取”，还要考虑“目标从哪来、生命周期怎么变化、下线后怎么摘除”。服务发现机制的价值，就是让这些事从手工操作变成自动化流程。你在Prometheus配置上做的每一项选择，本质上都是在定义监控体系的扩展边界。按这个思路去设计，后面接redis集群、接GPU缓存命中率这类自定义指标，都会顺畅很多。