naorlivne/alert_on_bad_air_quality

空气质量警报Docker镜像文档

镜像概述

空气质量警报Docker镜像是一个轻量级应用，旨在实时监测空气质量数据，当关键指标（如AQI、PM2.5、PM10等）超过预设阈值时，自动触发警报通知。该镜像适用于需要实时关注空气质量的场景，帮助用户及时了解环境质量变化并采取应对措施。

核心功能与特性

核心功能

• 实时空气质量监测：支持对接公开或私有空气质量API，获取实时AQI、PM2.5、PM10、二氧化硫、二氧化氮等指标数据。
• 自定义警报阈值：可配置各项指标的警报阈值，超过阈值时触发警报。
• 多渠道通知：支持通过邮件、短信、即时通讯工具（如Slack、***）等多种方式发送警报通知。
• 灵活的监测频率：可自定义监测间隔，平衡实时性与资源消耗。

特性

• 轻量级：基于Alpine Linux构建，镜像体积小，资源占用低。
• 易配置：通过环境变量即可完成核心参数配置，无需复杂的配置文件。
• 跨平台：支持x86_64、ARM等主流架构，可在服务器、边缘设备等多种环境运行。

使用场景与适用范围

适用场景

• 家庭环境：监测室内/室外空气质量，当PM2.5超标时提醒关闭窗户或开启空气净化器。
• 办公场所：保障员工健康，当空气质量不佳时通知行政部门采取通风或净化措施。
• 环境监测站点：作为简易监测终端，辅助环境数据采集与预警。
• 个人健康管理：对空气质量敏感人群（如哮喘患者）提供实时提醒。

适用人群

• 关注室内外空气质量的普通用户
• 企业行政与设施管理人员
• 环境监测与健康管理相关从业人员

使用方法与配置说明

前提条件

• 安装Docker Engine（20.10+）或Docker Desktop。
• （可选）若使用第三方空气质量API，需获取API密钥（如OpenWeatherMap、AQICN等）。
• （可选）若使用邮件/短信通知，需配置对应服务的账号信息（如SMTP服务器、短信API密钥）。

快速启动（Docker Run）

bash
docker run -d \
  --name air-quality-alert \
  --restart unless-stopped \
  -e MONITOR_INTERVAL=300 \          # 监测间隔（秒），默认300秒（5分钟）
  -e AQI_THRESHOLD=100 \              # AQI警报阈值，默认100（轻度污染）
  -e PM25_THRESHOLD=75 \              # PM2.5警报阈值（μg/m³），默认75
  -e PM10_THRESHOLD=150 \             # PM10警报阈值（μg/m³），默认150
  -e AIR_QUALITY_API_PROVIDER=aqicn \ # 空气质量API提供商，支持aqicn/openweathermap/custom
  -e API_KEY=your_api_key \           # 第三方API密钥（若使用需提供）
  -e CITY_ID=12345 \                  # 监测城市ID（根据API提供商要求配置）
  -e NOTIFICATION_METHOD=email \      # 通知方式，支持email/slack/telegram/sms，多方式用逗号分隔
  -e EMAIL_SMTP_SERVER=smtp.example.com \  # SMTP服务器地址（邮件通知时必填）
  -e EMAIL_SMTP_PORT=587 \            # SMTP端口（默认587）
  -e EMAIL_SMTP_USER=user@example.com \   # SMTP用户名
  -e EMAIL_SMTP_PASSWORD=your_email_password \  # SMTP密码/授权码
  -e EMAIL_RECIPIENTS=recipient1@example.com,recipient2@example.com \  # 收件人邮箱（逗号分隔）
  air-quality-alert:latest

环境变量配置详解

Docker Compose配置示例

yaml
version: '3.8'

services:
  air-quality-alert:
    image: docker.xuanyuan.run/air-quality-alert:latest
    container_name: air-quality-alert
    restart: unless-stopped
    environment:
      - MONITOR_INTERVAL=300
      - AQI_THRESHOLD=100
      - PM25_THRESHOLD=75
      - AIR_QUALITY_API_PROVIDER=aqicn
      - API_KEY=your_aqicn_api_key
      - CITY_ID=123456  # 替换为目标城市ID
      - NOTIFICATION_METHOD=email,telegram
      - EMAIL_SMTP_SERVER=smtp.qq.com
      - EMAIL_SMTP_PORT=587
      - EMAIL_SMTP_USER=your_qq_email@qq.com
      - EMAIL_SMTP_PASSWORD=your_smtp_auth_code
      - EMAIL_RECIPIENTS=user@example.com
      - TELEGRAM_BOT_TOKEN=your_telegram_bot_token  # Telegram通知必填
      - TELEGRAM_CHAT_ID=your_chat_id  # Telegram通知必填
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

日志与故障排查

容器日志可通过docker logs air-quality-alert查看，主要记录：

• 监测周期与数据获取状态
• 指标是否超标（如[INFO] Current AQI: 120 (Threshold: 100) - Alert triggered）
• 通知发送结果（成功/失败原因）

常见故障排查方向：

• 若无法获取数据：检查API密钥、城市ID是否正确，网络是否通畅。
• 若通知发送失败：检查通知方式配置（如SMTP服务器、端口、账号密码）是否正确。
• 若频繁触发警报：确认阈值设置是否合理（如AQI阈值是否过低）。

注意事项

• 第三方API可能存在调用限制或收费政策，使用前请查阅对应服务条款。
• 敏感信息（如API密钥、***密码）建议通过Docker Secrets或环境变量文件（.env）管理，避免直接暴露在命令行中。
• 长时间运行时建议配置--restart unless-stopped确保服务稳定性。