kjake/pfmon-docker

pfMon Docker镜像文档

1. 镜像概述和主要用途

pfMon 是一个用于简化 InfluxDB 和 Grafana 部署的 Docker 项目，旨在帮助 pfSense 防火墙用户快速搭建监控系统。通过集成 InfluxDB（时序数据库）和 Grafana（可视化平台），pfMon 能够收集 pfSense 上的 Telegraf 统计数据，并提供开箱即用的灵活仪表板，实现对网络状态的实时监控。

2. 核心功能和特性

• 集成组件：预配置 InfluxDB 和 Grafana，无需单独部署和配置两个服务
• 数据收集：支持收集 pfSense 系统指标、pfBlockerNG 日志、网关状态、HAProxy 状态及 Ping 测试数据
• 预设仪表板：Grafana 内置针对 pfSense 监控的预设仪表板，无需手动创建
• 灵活配置：支持自定义 InfluxDB 连接参数、Telegraf 输入配置，适配不同网络环境

3. 使用场景和适用范围

• 适用用户：使用 pfSense 防火墙（2.4.x 版本测试通过）并需要监控网络状态的管理员
• 监控目标：网络吞吐量、pfBlockerNG 拦截日志、网关可用性、DNS 解析性能、外部 Ping 延迟
• 部署环境：Docker 环境（支持 Docker Compose 部署）

4. 详细使用方法和配置说明

4.1 部署容器（InfluxDB + Grafana）

4.1.1 准备 docker-compose.yml

使用以下配置文件部署 InfluxDB 和 Grafana 容器（默认映射 Grafana 端口 4000，InfluxDB 端口 8088，非默认端口以避免冲突）：

yaml
version: '2'
services:
  db:
    image: influxdb
    container_name: influxdb-pfmon
    restart: always
    ports:
      - "8088:8086"  # InfluxDB 端口映射（宿主机:容器）
    networks:
      - default
    volumes:
      - ./influxdb:/var/lib/influxdb  # 持久化 InfluxDB 数据
    environment:
      - INFLUXDB_ADMIN_USER=admin      # InfluxDB 管理员用户名
      - INFLUXDB_ADMIN_PASSWORD=password  # InfluxDB 管理员密码
      - INFLUXDB_DB=speedtest          # 初始数据库名（待优化）
  web:
    image: kjake/pfmon-docker:latest
    container_name: pfweb
    restart: always
    ports:
      - "4000:3000"  # Grafana 端口映射（宿主机:容器）
    networks:
      - default
    volumes:
      - ./config:/var/lib/grafana     # 持久化 Grafana 配置
    user: "472"      # Grafana 运行用户 ID
    environment:
      - GF_INSTALL_PLUGINS=https://packages.hiveeyes.org/grafana/grafana-map-panel/grafana-map-panel-0.9.0.zip;grafana-map-panel  # 安装地图插件
      - GF_SERVER_ROOT_URL=http://localhost  # Grafana 访问 URL
      - GF_SERVER_HTTP_PORT=3000             # Grafana 容器内端口
      - GF_AUTH_ANONYMOUS_ENABLED=true       # 启用匿名访问
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Viewer    # 匿名用户角色（只读）
      # 可选 HTTPS 配置（取消注释并替换证书路径）
      # - GF_SERVER_CERT_FILE=/tmp/crt
      # - GF_SERVER_CERT_KEY=/tmp/key
      # - GF_SERVER_PROTOCOL=https
networks:
  default:
    driver: bridge

4.1.2 启动容器

在 docker-compose.yml 所在目录执行以下命令启动容器：

bash
docker-compose up -d

4.2 pfSense 配置（Telegraf 安装与配置）

4.2.1 安装 Telegraf

1. 登录 pfSense 管理界面，进入 系统 > 包管理器
2. 搜索并安装 Telegraf 包

4.2.2 配置 gateways.py 脚本（网关状态收集）

1. 下载 gateways.py 脚本：访问 https://gist.github.com/fastjack/a0feb792a9655da7aa3e2a7a1d9f812f 并保存文件
2. 上传脚本至 pfSense：进入 诊断 > 命令提示符，通过 "上传文件" 功能上传 gateways.py 至 /tmp 目录
3. 移动并授权脚本：在 诊断 > 命令提示符 的 "执行 Shell 命令" 中依次运行：

bash
mv /tmp/gateways.py /usr/local/bin/gateways.py
chmod +x /usr/local/bin/gateways.py

4.2.3 配置 Telegraf 发送数据至 InfluxDB

1. 进入 pfSense 服务 > Telegraf，启用 Telegraf 服务
2. 基础配置：
   • 服务器：输入 InfluxDB 容器地址 http://<docker宿主机IP>:8088（替换 <docker宿主机IP> 为实际宿主机 IP）
   • 数据库：输入 speedtest（当前版本固定，待优化）
   • 用户名/密码：使用 docker-compose.yml 中配置的 INFLUXDB_ADMIN_USER 和 INFLUXDB_ADMIN_PASSWORD
3. 功能模块启用：
   • 若使用 HAProxy，勾选 "启用 HAProxy" 并配置非默认端口（如有）
   • 勾选 "启用 Ping" 并设置目标为 8.8.8.8（Google DNS，用于网络连通性测试）
4. 高级配置：在 "Telegraf 额外配置" 中粘贴以下内容，用于收集网关状态和 pfBlockerNG 日志：

ini
[[inputs.exec]]
        commands = ["/usr/local/bin/gateways.py"]  # 执行网关状态脚本
        timeout = "5s"
        data_format = "influx"

[[inputs.logparser]]
  files = ["/var/log/pfblockerng/dnsbl.log"]  # pfBlockerNG DNS 拦截日志
  from_beginning=true
  [inputs.logparser.grok]
    measurement = "dnsbl_log"
    patterns = ["^%{WORD:BlockType}-%{WORD:BlockSubType},%{SYSLOGTIMESTAMP:timestamp:ts-syslog},%{IPORHOST:destination:tag},%{IPORHOST:source:tag},%{GREEDYDATA:call},%{WORD:BlockMethod},%{WORD:BlockList},%{IPORHOST:tld:tag},%{WORD:DefinedList:tag},%{GREEDYDATA:hitormiss}"]
    timezone = "Local"
    [inputs.logparser.tags]
      value = "1"

[[inputs.logparser]]
    files = ["/var/log/pfblockerng/ip_block.log"]  # pfBlockerNG IP 拦截日志
    from_beginning=true
    [inputs.logparser.grok]
        measurement = "ip_block_log"
        patterns = ["^%{SYSLOGTIMESTAMP:timestamp:ts-syslog},%{NUMBER:TrackerID},%{GREEDYDATA:Interface},%{WORD:InterfaceName},%{WORD:action},%{NUMBER:IPVersion},%{NUMBER:ProtocolID},%{GREEDYDATA:Protocol},%{IPORHOST:SrcIP:tag},%{IPORHOST:DstIP:tag},%{NUMBER:SrcPort},%{NUMBER:DstPort},%{WORD:Dir},%{WORD:GeoIP:tag},%{GREEDYDATA:AliasName},%{GREEDYDATA:IPEvaluated},%{GREEDYDATA:FeedName:tag},%{HOSTNAME:ResolvedHostname},%{HOSTNAME:ClientHostname},%{GREEDYDATA:ASN},%{GREEDYDATA:DuplicateEventStatus}"]
        timezone = "Local"

5. 保存配置并重启 Telegraf 服务

5. 配置参数说明

5.1 InfluxDB 容器环境变量

5.2 Grafana 容器环境变量

6. 验证部署

1. 访问 Grafana：打开浏览器，访问 http://<docker宿主机IP>:4000，进入 Grafana 界面（***访问已启用，无需登录）
2. 查看仪表板：在 Grafana 左侧菜单选择 "Dashboards > Home"，选择 pfMon 预设仪表板
3. 确认数据：检查仪表板是否显示 pfSense 系统指标、pfBlockerNG 日志等数据（数据延迟约 10-30 秒）

7. 注意事项

• pfSense 版本限制：仅在 pfSense 2.4.x 版本测试通过，其他版本可能存在兼容性问题
• 数据库名问题：当前版本 Telegraf 配置中数据库名固定为 speedtest，未来版本将优化为可配置
• 端口冲突：若宿主机 4000/8088 端口已被占用，需修改 docker-compose.yml 中的端口映射（如 4001:3000）
• 数据持久化：确保 ./influxdb 和 ./config 目录权限正确，避免容器启动失败