graphiteapp/graphite-statsd

Graphite & Statsd Docker 镜像文档

!Docker Pulls !Docker Size

镜像概述和主要用途

本镜像为 Graphite 和 Statsd 的官方 Docker 镜像，基于 https://github.com/hopsoft/docker-graphite-statsd 和 https://github.com/obfuscurity/synthesize 项目构建。主要用途是提供快速部署方案，帮助用户在几分钟内搭建起完整的指标收集与可视化系统，无需手动配置复杂的 Graphite 和 Statsd 环境。

标签与架构

• 开发版本：已弃用原开发仓库（graphiteapp/docker-graphite-statsd），不稳定构建请使用稳定仓库的 master 标签（graphiteapp/graphite-statsd:master）。
• 多架构支持：从 1.1.7-1 版本开始支持 arm/arm64 架构；从 1.1.7-6 版本开始提供 x64 架构的 -pypy 版本（针对性能优化，详情见 https://github.com/graphite-project/docker-graphite-statsd/pull/151%EF%BC%89%E3%80%82

核心功能和特性

包含组件

• Nginx：反向代理 Graphite 仪表盘
• Graphite：前端指标可视化仪表盘
• Carbon：后端指标接收与存储服务（包含 carbon-cache、carbon-aggregator）
• Statsd：UDP 协议的指标聚合代理
• 可选组件：Redis（用于 TagDB）、Collectd（系统指标收集）

关键特性

• 快速部署：一键启动完整的 Graphite & Statsd 环境
• 灵活配置：通过环境变量调整性能参数和功能开关
• 多架构支持：x64、arm、arm64 架构兼容，提供 PyPy 优化版本
• 数据持久化：支持挂载卷存储配置、指标数据和日志
• 服务监控：使用 runit 管理进程，支持优雅启停和日志轮转

使用场景和适用范围

适用场景

• 开发/测试环境的指标收集与调试
• 中小型生产环境的系统/应用指标监控
• 需要快速搭建可视化监控平台的场景
• 对指标存储和查询性能有基础需求的场景

不适用场景

• 超大规模集群监控（建议使用分布式部署方案）
• 对组件独立扩展有强需求的场景（建议拆分部署各组件）

使用方法和配置说明

快速开始

通过以下命令一键启动容器：

sh
docker run -d \
  --name graphite \
  --restart=always \
  -p 80:80 \
  -p 2003-2004:2003-2004 \
  -p 2023-2024:2023-2024 \
  -p 8125:8125/udp \
  -p 8126:8126 \
  graphiteapp/graphite-statsd

参数说明：

• --name graphite：指定容器名称为 graphite
• --restart=always：容器退出时自动重启
• -p：端口映射（详见下文“端口映射”）
• 可根据需求调整端口映射（如主机端口冲突时）

端口映射

卷挂载

默认情况下，容器会自动创建***卷存储以下数据。建议显式挂载主机目录以实现持久化：

挂载示例：

sh
docker run -d \
  --name graphite \
  -v /host/graphite/conf:/opt/graphite/conf \
  -v /host/graphite/storage:/opt/graphite/storage \
  -v /host/statsd/config:/opt/statsd/config \
  graphiteapp/graphite-statsd

开始使用 Graphite & Statsd

发送测试指标数据

通过以下命令向 Statsd 发送随机指标：

sh
while true; do echo -n "example:$((RANDOM % 100))|c" | nc -w 1 -u 127.0.0.1 8125; done

（example 为指标名，c 表示计数器类型，数值为 0-99 随机数）

可视化指标数据

访问 Graphite 仪表盘查看指标：

• 仪表盘：http://localhost/dashboard
• 指标查询：http://localhost/render?from=-10mins&until=now&target=stats.example

安全设置：Django Admin

默认 Django 管理员账户存在安全风险，需立即修改：

• 默认用户名：root
• 默认密码：root
• 默认***：root.graphite@mailinator.com

修改步骤：

1. 访问 http://localhost/account/login 登录
2. 进入 http://localhost/admin/auth/user/1/ 修改用户信息

配置参数说明

基础参数

Graphite-web 配置

Carbon 配置

TagDB 配置

TagDB 用于存储指标标签信息，默认使用 SQLite，可切换为 Redis：

其他功能开关

修改配置文件

若需调整高级配置（如 storage-schemas.conf）：

1. 停止容器：docker stop graphite
2. 查看容器卷路径：docker inspect graphite（在 Mounts 中找到对应卷的 Source 路径）
3. 修改主机上的配置文件（如 /var/lib/docker/volumes/xxx/_data/storage-schemas.conf）
4. 重启容器：docker start graphite

注意：修改 storage-schemas.conf 后，需删除旧的 whisper 文件（/opt/graphite/storage/whisper/ 目录下）以应用新的数据保留策略。

高级部署方案

Docker Compose 部署

创建 docker-compose.yml 文件：

yaml
version: '3'
services:
  graphite:
    image: graphiteapp/graphite-statsd
    container_name: graphite
    restart: always
    ports:
      - "80:80"
      - "2003-2004:2003-2004"
      - "8125:8125/udp"
      - "8126:8126"
    volumes:
      - ./graphite/conf:/opt/graphite/conf
      - ./graphite/storage:/opt/graphite/storage
    environment:
      - GRAPHITE_TIME_ZONE=Asia/Shanghai
      - GRAPHITE_WSGI_PROCESSES=8

启动：docker-compose up -d

Kubernetes 部署

推荐使用第三方 Helm Chart：https://github.com/kiwigrid/helm-charts/tree/master/charts/graphite

实验性功能

go-carbon

设置 GOCARBON=1 启用 https://github.com/lomik/go-carbon%EF%BC%88Carbon 的 Go 语言实现，性能更优）。若需启用 carbonserver，设置 GRAPHITE_CLUSTER_SERVERS="127.0.0.1:8000"。

Brubeck

设置 BRUBECK=1 启用 https://github.com/github/brubeck%EF%BC%88Statsd 替代方案，支持更多协议，但配置格式与原生 Statsd 不兼容）。

附加说明

关于 root 进程

容器使用 runit 作为 init 系统管理多进程，需 root 权限运行。这符合 Docker 多进程容器最佳实践，但不完全遵循“单进程容器”理念。若需无 root 运行，建议拆分部署各组件。

Statsd 与 Carbon 配置兼容性

确保 Statsd 刷新间隔（flushInterval）不小于 Carbon 最小数据保留粒度。例如，Statsd 配置 flushInterval: 10000（10 秒）时，storage-schemas.conf 中保留策略需设置为 10s:12h 或更大粒度。

附加阅读

• Graphite 官方文档
• https://github.com/etsy/statsd/wiki
• Carbon 配置指南
• Docker 多进程容器管理