17.2.7 常见安装问题与排查

本节聚焦 Prometheus 在安装与启动阶段的典型问题与快速排查方法，覆盖二进制、容器与系统服务化部署场景，确保能够定位配置错误、权限问题与运行异常，并提供可复现实验与练习。

文章图片

1. 无法启动或启动即退出#

  • 症状：进程闪退、systemctl status 显示 failed。
  • 排查步骤与命令：
# 1) 直接前台运行获取标准输出
/opt/prometheus/prometheus \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.path=/data/prometheus

# 2) systemd 日志
journalctl -u prometheus -n 200 --no-pager

# 3) 校验配置语法
/opt/prometheus/prometheus \
  --config.file=/etc/prometheus/prometheus.yml \
  --check-config
  • 命令解释：
  • --check-config：仅检查配置合法性，不启动服务。
  • --storage.tsdb.path：指定数据目录，权限不足会直接退出。
  • 常见原因：配置格式错误、启动参数拼写错误、数据目录不可写。
  • 快速修复示例：
# 修复数据目录权限
chown -R prometheus:prometheus /data/prometheus

2. 配置文件解析失败#

  • 症状：日志出现 error parsing config file。
  • 排查步骤：
# 使用最小可用配置验证
cat > /etc/prometheus/prometheus.yml <<'EOF'
global:
  scrape_interval: 15s
scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['127.0.0.1:9090']
EOF

/opt/prometheus/prometheus --config.file=/etc/prometheus/prometheus.yml --check-config
  • 关键点：
  • YAML 必须使用空格缩进，禁止 Tab。
  • scrape_configs 是必需段落。
  • 预期结果：输出 SUCCESS 表示语法通过。

3. 端口被占用#

  • 症状：listen tcp :9090: bind: address already in use
  • 排查与解决：
# 查占用进程
ss -lntp | grep 9090
lsof -i :9090

# 修改监听端口
/opt/prometheus/prometheus \
  --config.file=/etc/prometheus/prometheus.yml \
  --web.listen-address=:9091
  • 命令解释：--web.listen-address 可修改 UI/HTTP API 监听地址。

4. 无法写入数据目录#

  • 症状：open /path/to/data: permission denied
  • 排查与解决：
# 检查目录权限
ls -ld /data/prometheus

# 修复权限
chown -R prometheus:prometheus /data/prometheus
chmod 750 /data/prometheus
  • systemd 用户检查：
grep -E 'User=|Group=' /etc/systemd/system/prometheus.service

5. 访问 Web 界面失败#

  • 症状：无法访问 http://server:9090
  • 排查步骤：
# 本机监听检查
ss -lntp | grep 9090

# 防火墙检查
iptables -L -n | grep 9090
firewall-cmd --list-ports

# 容器部署端口映射
docker ps --format "table {{.Names}}\t{{.Ports}}"
  • 解决示例：
# 放通端口（firewalld）
firewall-cmd --add-port=9090/tcp --permanent
firewall-cmd --reload

6. 抓取目标显示 DOWN#

  • 症状：Targets 页面显示 Down。
  • 排查步骤：
# 验证目标 /metrics
curl -s http://node1:9100/metrics | head

# 查看 Targets 详细错误（在Web UI中）
# http://server:9090/targets
  • 修复示例：
# /etc/prometheus/prometheus.yml
scrape_configs:
  - job_name: 'node'
    static_configs:
      - targets: ['node1:9100','node2:9100']

7. 容器部署数据丢失#

  • 症状：重启容器后历史数据消失。
  • 原因：未挂载持久卷。
  • 解决示例：
docker run -d --name prom \
  -p 9090:9090 \
  -v /data/prom:/prometheus \
  -v /etc/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml \
  prom/prometheus:v2.49.1 \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.path=/prometheus

8. systemd 服务无效或环境变量不生效#

  • 症状：自定义参数未生效。
  • 排查与修复：
# 查看 ExecStart 参数
systemctl cat prometheus

# 修改 service 后重载
systemctl daemon-reload
systemctl restart prometheus
  • 环境变量示例：
# /etc/sysconfig/prometheus
PROM_OPTS="--web.listen-address=:9090 --storage.tsdb.retention.time=15d"

# /etc/systemd/system/prometheus.service
[Service]
EnvironmentFile=/etc/sysconfig/prometheus
ExecStart=/opt/prometheus/prometheus --config.file=/etc/prometheus/prometheus.yml $PROM_OPTS

9. 版本不兼容或二进制不可执行#

  • 症状：exec format error 或缺少依赖。
  • 排查与解决：
uname -m
file /opt/prometheus/prometheus

# 重新下载匹配架构
# amd64 示例
curl -LO https://github.com/prometheus/prometheus/releases/download/v2.49.1/prometheus-2.49.1.linux-amd64.tar.gz

10. TSDB 初始化异常或磁盘空间不足#

  • 症状：corruption、out of space
  • 排查与解决：
# 磁盘空间
df -h

# 降低保留时间
/opt/prometheus/prometheus \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.retention.time=7d
  • 说明：TSDB 启动时会进行 WAL/Block 校验，磁盘损坏或空间不足会阻止启动。

排错练习（动手）#

  1. 配置错误练习：把 prometheus.yml 的缩进改成 Tab，运行 --check-config 观察报错信息并修复。
  2. 端口冲突练习：启动一个 python -m http.server 9090，再启动 Prometheus，记录错误并改用 --web.listen-address=:9091。
  3. 权限问题练习：将数据目录权限改为只读，观察启动报错，再通过 chown 修复。

通过以上问题归类与排查手段，可快速定位安装阶段的主要故障点，为后续服务发现、告警规则与高可用部署奠定稳定基础。