部署与快速上手

部署方式怎么选

Prometheus 是一个单二进制程序（Go 写的，无外部依赖），怎么跑都行。常见三条路：

方式	适合场景	优点	缺点
二进制	裸机/虚机上的生产部署	直接、透明，systemd 托管	要手动管安装、升级、服务单元
Docker	学习、本地验证、小环境	一条命令起，环境干净	要处理好配置和数据卷的挂载
Kubernetes	生产主力，监控 K8s 本身	服务发现、配置管理全自动	需要理解 operator / Helm 体系

K8s 上一般不手撸 Deployment，而是用 kube-prometheus-stack（Helm）或 Prometheus Operator——那套东西分量大，第 7 篇专门讲。学习阶段用 Docker 最快，本篇也以 Docker 为主线，二进制方式顺带一提。

版本口径

当前主流是 Prometheus 2.5x 系列和 3.x 系列，本篇的配置写法两边通用。3.x 主要变化在 UI 重写、UTF-8 指标名支持、移除一些废弃特性，入门层面体感差别不大。

二进制与 Docker 跑起来

二进制方式（以 Linux 为例）：先下载对应平台的压缩包，解压即用。两个官方下载地址：

• 官方下载页：prometheus.io/download（Prometheus 和各 Exporter 都在这一页）
• GitHub Releases：prometheus/prometheus/releases（版本更新最快，有完整变更日志）

# 以 linux-amd64 为例（macOS Apple Silicon 选 darwin-arm64）
curl -LO https://github.com/prometheus/prometheus/releases/download/v3.5.0/prometheus-3.5.0.linux-amd64.tar.gz

tar xf prometheus-3.5.0.linux-amd64.tar.gz
cd prometheus-3.5.0.linux-amd64
./prometheus --config.file=prometheus.yml

版本号替换

命令里的 v3.5.0 换成 Releases 页里的最新版本号即可；linux-amd64 按你的平台换成 darwin-arm64（macOS M 系）、linux-arm64 等。

Docker 方式（推荐学习用）：先准备一份配置文件（下一节细讲），然后挂载启动：

# 准备配置目录
mkdir -p ~/prometheus
# 把下面「最小配置示例」存为 ~/prometheus/prometheus.yml

docker run -d \
  --name prometheus \
  -p 9090:9090 \
  -v ~/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml \
  -v ~/prometheus/data:/prometheus \
  prom/prometheus:v3.5.0

参数说明：

• -p 9090:9090：Web UI 和 API 都走 9090 端口。
• 第一个 -v：把宿主机上的配置文件挂到容器里的默认配置路径。
• 第二个 -v：把数据目录挂出来，容器删了数据还在。

启动后浏览器打开 http://localhost:9090，能看到 Prometheus 的 UI（3.x 是新版的 Mantine UI，2.x 是老版界面，功能位置略有差异）就算成功。

prometheus.yml 结构

Prometheus 的全部行为都由这一个 YAML 文件驱动，顶层分四段：

# 全局默认，可被局部覆盖
global:
  scrape_interval: 15s        # 抓取间隔：多久去目标拉一次
  evaluation_interval: 15s    # 评估间隔：多久算一遍告警/记录规则
  scrape_timeout: 10s         # 单次抓取超时，必须小于 scrape_interval

# 告警与记录规则文件，下一篇细讲
rule_files:
  - "rules/*.yml"

# 告警往哪推：Alertmanager 地址
alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - "alertmanager:9093"

# 抓谁：抓取目标配置，最核心的一段
scrape_configs:
  - job_name: "prometheus"
    static_configs:
      - targets: ["localhost:9090"]

四段职责：

• global：全局默认值。scrape_interval 决定数据粒度（15s 是官方默认和生态惯例）；evaluation_interval 决定告警规则多久评估一次。每个 job 里可以单独覆盖这些值。
• rule_files：加载告警规则和记录规则的 YAML 文件列表，支持 glob。没有规则可以先留空或删掉这段。
• alerting：配置 Alertmanager 地址，Server 评估出告警后往这里推。没配就单纯不告警，不影响采集。
• scrape_configs：抓取目标列表，每一项是一个 job——一组同类目标。job 里用 static_configs 写死地址，或用各种 *_sd_configs 做服务发现。配置层级、标签重写、认证等高级玩法后面篇章展开。

提示

改完配置想验证语法，用镜像里自带的 promtool：docker exec prometheus promtool check config /etc/prometheus/prometheus.yml。写错 YAML 直接 reload 失败但进程不会挂，这个命令能提前兜底。

第一个抓取目标

上面最小配置里的 job_name: "prometheus" 让 Server 抓取自己——它自己也暴露 /metrics，这是监控 Prometheus 自身健康的基础。

再加点实际的：跑一个 Node Exporter（主机指标导出器），把它也抓进来。

先启动 Node Exporter：

docker run -d \
  --name node-exporter \
  --net="host" \
  --pid="host" \
  -v "/:/host:ro,rslave" \
  prom/node-exporter:v1.9.1 \
  --path.rootfs=/host

macOS 的注意

--net="host" 在 macOS 的 Docker Desktop 上不生效（容器跑在虚拟机里）。macOS 上换个方式：两个容器都接默认网桥，Prometheus 抓取目标写 host.docker.internal:9100，见下文「常见问题」。

然后在 prometheus.yml 的 scrape_configs 里追加一个 job：

scrape_configs:
  - job_name: "prometheus"
    static_configs:
      - targets: ["localhost:9090"]

  - job_name: "node"
    static_configs:
      - targets: ["localhost:9100"]

重新加载配置（方法见「热更新配置」一节），然后打开 UI 的 Status → Targets 页面（2.x 老 UI 在顶部菜单，3.x 新 UI 在左侧导航）。两个 target 的 State 都应该是绿色的 UP：

Endpoint                        State    Labels                Last Scrape   Error
http://localhost:9090/metrics   UP       instance=localhost:9090  4s ago
http://localhost:9100/metrics   UP       instance=localhost:9100  2s ago

如果 State 是红色的 DOWN，Error 列会写明原因（连接拒绝、超时、404 等），按提示排查即可——这就是拉模型「目标健康自明」的直接体现。

自动生成的标签

抓取时 Prometheus 会自动给每个目标打上 job 和 instance 两个标签：job 来自 job_name，instance 来自目标地址。之后查数据、写告警，基本都靠这两个标签圈定范围。

第一次查询

打开 UI 的查询页面（首页即是），输入表达式回车。先试两个最有代表性的：

up

up 是每次抓取自动生成的指标：抓成功记 1，失败记 0。当前应该看到两条值为 1 的序列，分别对应 prometheus 和 node 两个 job。

再看抓取耗时：

scrape_duration_seconds

它记录每次抓取花了多长时间。目标变多、指标变多之后，盯紧它配合 scrape_timeout 调优抓取性能。

切换到 Table / Graph 两个视图对比：Table 显示表达式在「这一时刻」的值（instant vector），Graph 显示一段时间内的曲线（range vector）。日常调试先用 Table 确认序列存在、标签对，再切 Graph 看趋势。

Console 模板

菜单里还有个 Consoles 功能，可以用 HTML + Go template 写自定义展示页面。这是个历史遗留能力，正经画图请直接用 Grafana，Console 模板知道有这回事就行。

热更新配置

改完 prometheus.yml 不用重启进程，两种方式热加载：

# 方式一：给进程发 SIGHUP 信号
kill -HUP $(pidof prometheus)
# Docker 场景
docker kill --signal=SIGHUP prometheus

# 方式二：HTTP API，需启动时加 --web.enable-lifecycle
docker run -d ... prom/prometheus:v3.5.0 \
  --config.file=/etc/prometheus/prometheus.yml \
  --web.enable-lifecycle

# 然后改完配置执行
curl -X POST http://localhost:9090/-/reload

lifecycle 接口的安全

--web.enable-lifecycle 会同时开放 /-/quit（远程关闭进程），裸奔在公网等于把命门交出去。开它之前务必配上认证或只监听内网地址。

什么时候必须重启而不是热更新：启动命令行参数（--storage.tsdb.*、--web.* 这类）只有重启才生效；而 prometheus.yml 里的所有内容（抓取目标、规则、告警路由）都可以热加载。

常见问题

端口冲突

9090 被占用时换宿主机映射端口即可，容器内不用动：

docker run -d --name prometheus -p 19090:9090 -v ... prom/prometheus:v3.5.0

容器里的 Prometheus 抓不到宿主机

这是 Docker 部署最常见的坑：容器里的 localhost 指容器自己，不是宿主机。

• macOS / Windows（Docker Desktop）：用内置域名 host.docker.internal 指代宿主机。抓宿主机上的 Node Exporter 就写 host.docker.internal:9100。
• Linux：host.docker.internal 默认不存在，要么启动时加 --add-host=host.docker.internal:host-gateway，要么容器用 --net="host" 直接用宿主机网络栈。

Web UI 时间显示不对

UI 图表默认按浏览器本地时区渲染，但 Prometheus 内部的告警评估、时间戳全部用 UTC。如果对图表和告警时间（比如静默窗口、for 时长），记住一个是本地时区、一个是 UTC，差 8 小时不是 bug。

小结

• 部署三选一：二进制透明、Docker 快、K8s 交给 operator（第 7 篇）；学习用 Docker 一条命令起步。
• prometheus.yml 四段：global 定默认节奏、rule_files 载规则、alerting 指告警出口、scrape_configs 定抓谁。
• 抓自己 + 抓 Node Exporter 是最小上手组合，Status → Targets 页面看 UP/DOWN 验证抓取。
• 查询先跑 up 和 scrape_duration_seconds 找感觉，Table 看值、Graph 看趋势。
• 改配置用 kill -HUP 或开 lifecycle 后 POST /-/reload 热加载；启动参数变更才需要重启。

跑起来只是开始。下一篇深入 scrape_configs：静态配置之外的服务发现、标签重写，以及多环境目标的组织方式。