强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

Prometheus 完全指南 / 02 - 安装与部署

02 - 安装与部署

2.1 获取 Prometheus

Prometheus 提供多种安装方式,本章将介绍二进制安装、Docker 部署以及配置文件详解。

版本选择

安装方式适用场景维护成本
二进制安装开发/测试环境
Docker快速启动、CI/CD
Kubernetes Operator生产环境/K8s 集群中高
包管理器(apt/yum)系统级部署

2.2 二进制安装

下载与安装

# 设置版本变量
PROMETHEUS_VERSION="2.52.0"

# 下载二进制包
wget https://github.com/prometheus/prometheus/releases/download/v${PROMETHEUS_VERSION}/prometheus-${PROMETHEUS_VERSION}.linux-amd64.tar.gz

# 解压
tar xvfz prometheus-${PROMETHEUS_VERSION}.linux-amd64.tar.gz
cd prometheus-${PROMETHEUS_VERSION}.linux-amd64

# 查看目录结构
ls -la
# prometheus           # 主程序
# promtool             # 规则校验/调试工具
# prometheus.yml       # 默认配置文件
# consoles/            # 内置 Console 模板
# console_libraries/   # Console 库文件
# LICENSE
# NOTICE

安装到系统路径

# 复制二进制文件
sudo cp prometheus /usr/local/bin/
sudo cp promtool /usr/local/bin/

# 创建配置和数据目录
sudo mkdir -p /etc/prometheus
sudo mkdir -p /var/lib/prometheus

# 复制配置文件
sudo cp prometheus.yml /etc/prometheus/

# 复制控制台模板(可选)
sudo cp -r consoles /etc/prometheus/
sudo cp -r console_libraries /etc/prometheus/

# 验证安装
prometheus --version
# prometheus, version 2.52.0 (branch: HEAD, revision: xxx)

创建系统用户

# 创建专用用户(无需登录)
sudo useradd --no-create-home --shell /bin/false prometheus

# 设置目录权限
sudo chown -R prometheus:prometheus /etc/prometheus
sudo chown -R prometheus:prometheus /var/lib/prometheus
sudo chown prometheus:prometheus /usr/local/bin/prometheus
sudo chown prometheus:prometheus /usr/local/bin/promtool

创建 Systemd 服务

# /etc/systemd/system/prometheus.service
[Unit]
Description=Prometheus Monitoring System
Documentation=https://prometheus.io/docs/
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=prometheus
Group=prometheus
ExecReload=/bin/kill -HUP $MAINPID
ExecStart=/usr/local/bin/prometheus \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.path=/var/lib/prometheus/ \
  --web.console.templates=/etc/prometheus/consoles \
  --web.console.libraries=/etc/prometheus/console_libraries \
  --web.listen-address=0.0.0.0:9090 \
  --web.enable-lifecycle \
  --storage.tsdb.retention.time=15d \
  --storage.tsdb.retention.size=0
SyslogIdentifier=prometheus
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

启动服务

# 重载 systemd 配置
sudo systemctl daemon-reload

# 启动 Prometheus
sudo systemctl start prometheus

# 设置开机自启
sudo systemctl enable prometheus

# 查看状态
sudo systemctl status prometheus

# 查看日志
sudo journalctl -u prometheus -f

验证安装

# 检查端口监听
ss -tlnp | grep 9090

# 访问 Web UI
curl http://localhost:9090/-/healthy
# Prometheus Server is Healthy.

# 访问 Web 界面
# 浏览器打开 http://localhost:9090

常用启动参数

参数默认值说明
--config.fileprometheus.yml配置文件路径
--storage.tsdb.pathdata/数据存储路径
--storage.tsdb.retention.time15d数据保留时间
--storage.tsdb.retention.size0(无限制)数据保留大小
--web.listen-address0.0.0.0:9090监听地址
--web.enable-lifecyclefalse启用 API 热重载
--web.enable-admin-apifalse启用管理 API
--log.levelinfo日志级别

注意:生产环境中建议设置 --storage.tsdb.retention.time--storage.tsdb.retention.size 中至少一个,避免磁盘被撑满。


2.3 Docker 部署

快速启动

# 使用 Docker 运行 Prometheus
docker run -d \
  --name=prometheus \
  -p 9090:9090 \
  -v /etc/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml \
  -v prometheus_data:/prometheus \
  prom/prometheus:v2.52.0

# 带自定义参数
docker run -d \
  --name=prometheus \
  -p 9090:9090 \
  -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \
  -v prometheus_data:/prometheus \
  prom/prometheus:v2.52.0 \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.retention.time=30d \
  --web.enable-lifecycle

Docker Compose 部署

# docker-compose.yml
version: '3.8'

services:
  prometheus:
    image: prom/prometheus:v2.52.0
    container_name: prometheus
    restart: unless-stopped
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./rules:/etc/prometheus/rules:ro
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.retention.time=30d'
      - '--storage.tsdb.retention.size=10GB'
      - '--web.enable-lifecycle'
      - '--web.enable-admin-api'
    networks:
      - monitoring

  node-exporter:
    image: prom/node-exporter:v1.7.0
    container_name: node-exporter
    restart: unless-stopped
    ports:
      - "9100:9100"
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro
    command:
      - '--path.procfs=/host/proc'
      - '--path.sysfs=/host/sys'
      - '--path.rootfs=/rootfs'
      - '--collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host|etc)($$|/)'
    networks:
      - monitoring

volumes:
  prometheus_data:

networks:
  monitoring:
    driver: bridge

运行 Docker Compose

# 创建配置文件后启动
docker compose up -d

# 查看运行状态
docker compose ps

# 查看日志
docker compose logs -f prometheus

# 验证
curl http://localhost:9090/-/healthy

2.4 配置文件详解

Prometheus 使用 YAML 格式的配置文件,默认路径为 prometheus.yml

完整配置示例

# /etc/prometheus/prometheus.yml
# 全局配置
global:
  scrape_interval: 15s          # 默认抓取间隔
  scrape_timeout: 10s           # 抓取超时时间
  evaluation_interval: 15s      # 规则评估间隔
  external_labels:              # 联邦和远程写入时附加的标签
    cluster: 'production'
    region: 'cn-east'

# 告警规则文件
rule_files:
  - /etc/prometheus/rules/*.yml

# Alertmanager 配置
alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - 'alertmanager:9093'
      timeout: 10s

# 抓取配置
scrape_configs:
  # 抓取 Prometheus 自身
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']
        labels:
          env: 'production'

  # 抓取 Node Exporter
  - job_name: 'node'
    scrape_interval: 30s
    static_configs:
      - targets:
          - 'node1:9100'
          - 'node2:9100'
          - 'node3:9100'
    relabel_configs:
      - source_labels: [__address__]
        regex: '(.+):9100'
        target_label: instance
        replacement: '${1}'

  # 抓取自定义应用
  - job_name: 'my-app'
    metrics_path: '/actuator/prometheus'
    scheme: 'https'
    tls_config:
      insecure_skip_verify: true
    basic_auth:
      username: 'prometheus'
      password_file: '/etc/prometheus/app_password'
    static_configs:
      - targets: ['app1:8443', 'app2:8443']

全局配置说明

字段类型默认值说明
scrape_intervalduration15s全局抓取间隔
scrape_timeoutduration10s抓取超时(不能大于 scrape_interval)
evaluation_intervalduration15s规则评估间隔
external_labelsmap{}外部标签(用于联邦/远程写入)

scrape_configs 配置详解

scrape_configs:
  - job_name: <string>                    # 必填:作业名称
    honor_labels: false                   # 是否保留目标自身的标签
    honor_timestamps: true                # 是否保留目标自身的时间戳
    params:                               # URL 查询参数
      <map[string][]string>
    scrape_interval: <duration>           # 作业级别抓取间隔(覆盖全局)
    scrape_timeout: <duration>            # 作业级别抓取超时
    metrics_path: <string>                # 指标路径(默认 /metrics)
    scheme: <string>                      # 协议(默认 http)
    basic_auth:                           # Basic 认证
      username: <string>
      password: <secret>
    bearer_token: <secret>                # Bearer Token 认证
    bearer_token_file: <string>           # Bearer Token 文件
    tls_config:                           # TLS 配置
      ca_file: <string>
      cert_file: <string>
      key_file: <string>
      insecure_skip_verify: <boolean>
    static_configs:                       # 静态配置
      - targets: ['host:port']
        labels:
          key: value
    relabel_configs:                      # 重新标记配置
      - ...

重载配置

Prometheus 支持两种方式重载配置,无需重启:

# 方式一:发送 SIGHUP 信号
kill -HUP $(pgrep prometheus)

# 方式二:使用 HTTP API(需启用 --web.enable-lifecycle)
curl -X POST http://localhost:9090/-/reload

# 验证配置语法
promtool check config /etc/prometheus/prometheus.yml

2.5 promtool 工具

promtool 是 Prometheus 自带的命令行工具,用于规则校验、调试查询等。

# 检查配置文件语法
promtool check config /etc/prometheus/prometheus.yml

# 检查规则文件
promtool check rules /etc/prometheus/rules/alerts.yml

# 查询 Prometheus(调试用)
promtool query instant http://localhost:9090 'up'

# 查询时间范围
promtool query range http://localhost:9090 \
  'rate(http_requests_total[5m])' \
  --start=$(date -d '1 hour ago' +%s) \
  --end=$(date +%s) \
  --step=15s

# 测试告警规则
promtool test rules test_rules.yml

告警规则测试文件

# test_rules.yml
rule_files:
  - /etc/prometheus/rules/alerts.yml

evaluation_interval: 1m

tests:
  - interval: 1m
    input_series:
      - series: 'up{job="my-app"}'
        values: '1 1 1 0 0 0'
    alert_rule_test:
      - eval_time: 3m
        alertname: InstanceDown
        exp_alerts: []
      - eval_time: 6m
        alertname: InstanceDown
        exp_alerts:
          - exp_labels:
              job: my-app

2.6 环境变量替换

Prometheus 配置文件支持环境变量替换(自 2.48+ 版本实验性支持),或者使用模板引擎如 envsubst

# 使用 envsubst 替换环境变量
export PROM_LISTEN_ADDRESS="0.0.0.0:9091"
export PROM_RETENTION="30d"

cat prometheus.yml.template | envsubst > prometheus.yml
# prometheus.yml.template
global:
  scrape_interval: 15s

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

2.7 数据目录管理

目录结构

/var/lib/prometheus/
├── chunks_head/          # 内存映射的数据块
│   ├── 000001
│   └── 000002
├── wal/                  # Write-Ahead Log
│   ├── 00000001
│   └── 00000002
├── queries.active        # 活跃查询
└── lock                  # 文件锁

磁盘容量估算

磁盘空间 = 每个样本字节数 × 采集频率 × 时间序列数 × 保留时间
参数典型值
每个样本~1-2 字节(压缩后)
采集间隔15s
时间序列10,000
保留时间15 天

估算:2 bytes × (86400/15) × 10000 × 15 ≈ 17.3 GB

注意:实际占用会因压缩率、标签数量等因素浮动,建议预留 20-30% 额外空间。

管理数据保留

# 查看当前数据大小
du -sh /var/lib/prometheus/

# 按时间保留(启动参数)
--storage.tsdb.retention.time=30d

# 按大小保留(启动参数)
--storage.tsdb.retention.size=50GB

# 两者同时配置时,任一条件满足即触发清理

2.8 安全加固

启用 TLS

# web.yml - Prometheus Web 配置
tls_server_config:
  cert_file: /etc/prometheus/tls/server.crt
  key_file: /etc/prometheus/tls/server.key

basic_auth_users:
  admin: $2y$10$hash_of_password
# 生成密码哈希
htpasswd -nBC 10 "" | tr -d ':\n'

# 使用 web 配置启动
prometheus \
  --config.file=/etc/prometheus/prometheus.yml \
  --web.config.file=/etc/prometheus/web.yml

限制网络访问

# 只监听本地
--web.listen-address=127.0.0.1:9090

# 使用防火墙
sudo ufw allow from 10.0.0.0/8 to any port 9090

2.9 本章小结

安装方式命令适用场景
二进制prometheus --config.file=...开发测试
Dockerdocker run prom/prometheus快速启动
Composedocker compose up -d多服务编排
Systemdsystemctl start prometheus生产部署

扩展阅读


上一章01 - Prometheus 简介 下一章03 - 架构与原理