Docker监控服务部署

Docker监控服务部署记录

背景

为XScholar文献下载系统搭建监控告警体系，需要部署Prometheus、AlertManager、Grafana等监控服务。项目已有Prometheus和Grafana在运行，需要在此基础上新增AlertManager服务。

初始环境状态

已有服务

• Prometheus (端口9090)
• Grafana (端口3000)
• Node Exporter (端口9100)
• XScholar应用 (端口10089，已暴露actuator/prometheus端点)

已有配置文件

# 现有的docker-compose.yml
version: '3.8'
services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    # ... 其他配置

需求分析

目标

1. 新增AlertManager服务用于告警路由
2. 配置Prometheus告警规则
3. 实现钉钉机器人告警推送
4. 保持现有服务正常运行

技术选型

• AlertManager: 官方推荐的告警管理组件
• 钉钉机器人: 企业内部沟通工具，支持Webhook
• Docker Compose: 统一容器编排管理

部署过程记录

第一步：扩展Docker Compose配置

遇到的问题

初始配置中没有AlertManager服务，需要在不影响现有服务的情况下添加。

解决方案

在现有docker-compose.yml基础上添加AlertManager服务：

# 新增的AlertManager服务配置
alertmanager:
  image: prom/alertmanager:latest
  container_name: alertmanager
  ports:
    - "9093:9093"
  volumes:
    - ./alertmanager.yml:/etc/alertmanager/alertmanager.yml
    - alertmanager_data:/alertmanager
  command:
    - '--config.file=/etc/alertmanager/alertmanager.yml'
    - '--storage.path=/alertmanager'
  restart: unless-stopped
  networks:
    - monitoring

# 在volumes部分新增
volumes:
  prometheus_data:
  grafana_data:
  alertmanager_data:  # 新增

关键配置点

1. 端口映射: 9093是AlertManager的标准端口
2. 数据持久化: 使用Docker卷保存AlertManager数据
3. 网络配置: 与其他服务使用同一monitoring网络
4. 配置文件挂载: 外部配置文件便于修改

第二步：配置Prometheus告警规则

遇到的问题

原有Prometheus配置中没有rule_files和alerting配置。

解决方案

修改prometheus.yml添加告警相关配置：

global:
  scrape_interval: 15s
  evaluation_interval: 15s

# 新增：告警规则文件配置
rule_files:
  - "prometheus-alerts.yml"

# 新增：AlertManager配置
alerting:
  alertmanagers:
    - static_configs:
        - targets:
          - alertmanager:9093

scrape_configs:
  # ... 保持原有配置不变

关键点

1. evaluation_interval: 告警规则评估间隔
2. targets配置: 使用容器名称alertmanager，利用Docker网络自动解析
3. rule_files路径: 相对于容器内/etc/prometheus/目录

第三步：创建AlertManager配置

核心配置文件

# alertmanager.yml
global:
  resolve_timeout: 5m

route:
  group_by: ['alertname', 'severity']
  group_wait: 10s
  group_interval: 10s
  repeat_interval: 1h
  receiver: 'dingtalk-webhook'
  routes:
    # 严重告警立即发送
    - match:
        severity: critical
      receiver: 'dingtalk-webhook'
      group_wait: 5s
      repeat_interval: 30m

receivers:
  - name: 'dingtalk-webhook'
    webhook_configs:
      - url: 'http://host.docker.internal:8060/dingtalk/webhook'
        send_resolved: true

设计思路

1. 告警分组: 按告警名称和严重程度分组，避免告警风暴
2. 差异化处理: critical告警5秒内发送，warning告警30秒后发送
3. 重复抑制: critical告警30分钟重复一次，warning告警2小时重复一次

第四步：Docker Compose版本兼容性问题

遇到的问题

$ docker-compose version
docker: 'compose' is not a docker command.

$ docker-compose
-bash: /usr/local/bin/docker-compose: Permission denied

问题分析

1. Docker版本27.5.1较新，默认使用docker compose而非docker-compose
2. 旧版docker-compose二进制文件权限问题

解决方案

# 方案1：修复权限
sudo chmod +x /usr/local/bin/docker-compose

# 方案2：使用新版命令（推荐）
docker compose up -d
docker compose down

经验总结

• Docker新版本推荐使用docker compose命令
• 注意检查docker-compose文件的执行权限
• 建议统一使用新版本命令避免兼容性问题

第五步：配置文件编码问题

遇到的严重问题

level=ERROR msg="loading groups failed" err="yaml: invalid Unicode character"

问题根因

告警规则文件中包含Unicode特殊字符（表情符号），导致Prometheus无法解析。

错误示例

# 问题配置 - 包含表情符号
- alert: XScholarServiceDown
  annotations:
    summary: "🔴 服务宕机告警"  # 🔴 导致解析错误

解决方案

# 正确配置 - 纯ASCII字符
- alert: XScholarServiceDown
  annotations:
    summary: "Service Down Alert"  # 移除特殊字符

预防措施

1. 配置文件规范: 避免在YAML文件中使用特殊Unicode字符
2. 验证工具 : 使用yamllint或Python验证YAML语法
3. 编码标准: 统一使用UTF-8编码，但内容限制ASCII字符

# YAML语法验证
python3 -c "import yaml; yaml.safe_load(open('prometheus-alerts.yml'))"

最终配置结构

prometheus/
├── docker-compose.yml          # 容器编排配置
├── prometheus.yml              # Prometheus主配置
├── prometheus-alerts.yml       # 告警规则定义
├── alertmanager.yml           # AlertManager配置
└── dingtalk-webhook.py        # 钉钉集成服务

部署验证

服务启动验证

# 启动所有服务
docker compose up -d

# 检查服务状态
docker compose ps

# 验证服务可访问性
curl http://localhost:9090/api/v1/status/config    # Prometheus
curl http://localhost:9093/api/v1/status           # AlertManager

配置验证

1. Prometheus: 访问http://localhost:9090/rules 查看规则加载状态
2. AlertManager: 访问http://localhost:9093 查看配置状态
3. Targets: 访问http://localhost:9090/targets 确认所有目标UP状态

踩坑总结

主要难点

1. Docker Compose版本兼容性: 新旧版本命令差异
2. 配置文件编码: Unicode字符导致解析失败
3. 网络配置: 容器间通信和主机通信的地址配置
4. 权限问题: Docker相关文件的执行权限

关键经验

1. 渐进式部署: 先确保基础服务正常，再逐步添加新组件
2. 配置验证: 每次修改后立即验证，避免问题累积
3. 日志观察: 重点关注容器启动日志，快速定位问题
4. 版本兼容: 注意Docker和相关工具的版本兼容性

最佳实践

1. 文件组织: 统一目录结构，便于维护
2. 权限管理: 确保配置文件有正确的读写权限
3. 备份策略: 修改前备份重要配置文件
4. 文档记录: 详细记录每个配置项的作用和修改原因

下一步

基础监控服务部署完成后，下一阶段将重点关注：

1. Spring Boot应用的Prometheus集成配置
2. 业务相关监控指标的设计和实现
3. 具体告警规则的优化配置

这个阶段的重点是建立稳定的基础设施，为后续的应用监控和业务告警奠定基础。