flashcatcloud/categraf_ent

Categraf 企业版 Docker 镜像文档

镜像概述和主要用途

Categraf 企业版是一款高性能、多用途的监控数据采集器，专为企业级监控场景设计。该 Docker 镜像封装了 Categraf 企业版核心组件，提供了便捷的部署方式，适用于各类云环境、容器平台及物理机环境。

主要用途包括：

• 系统和应用指标采集
• 日志数据收集与解析
• 分布式追踪数据采集
• 自定义业务指标上报
• 监控数据聚合与转发

核心功能和特性

企业级特性

• 多租户隔离机制，支持复杂组织架构
• 增强的数据加密传输与存储
• 高级数据采样与聚合功能
• 企业级技术支持与服务保障
• 专属监控插件与集成能力

通用功能

• 丰富的内置采集插件（超过 100+）
• 轻量级设计，资源占用低
• 支持 Prometheus、InfluxDB、OpenTSDB 等多种数据输出
• 灵活的配置方式，支持动态 reload
• 高可用性设计，支持集群部署
• 自动发现与服务发现能力
• 自定义采集规则与指标计算

使用场景和适用范围

适用场景

• 企业级监控平台构建
• 混合云环境统一监控
• DevOps 与 SRE 日常监控
• 大规模容器集群监控
• 微服务架构可观测性建设
• IT 基础设施与业务系统一体化监控

适用范围

• 中小型企业监控系统
• 大型企业分布式监控架构
• 云原生应用监控
• Kubernetes 集群监控
• 传统数据中心监控现代化改造

快速开始

基本使用

使用默认配置启动容器：

bash
docker run -d --name categraf-enterprise \
  --net=host \
  --restart=always \
  registry.example.com/categraf-enterprise:latest

注意：--net=host 模式用于让容器直接使用主机网络，便于采集主机指标，非必需，根据实际需求选择。

详细配置说明

配置文件挂载

推荐使用外部配置文件进行自定义配置：

bash
docker run -d --name categraf-enterprise \
  --restart=always \
  -v /path/to/conf:/etc/categraf \
  -v /path/to/data:/var/lib/categraf \
  registry.example.com/categraf-enterprise:latest

配置文件目录结构：

/path/to/conf/
├── categraf.conf       # 主配置文件
├── conf.d/             # 插件配置目录
│   ├── cpu.conf
│   ├── mem.conf
│   ├── disk.conf
│   └── ...
└── enterprise.conf     # 企业版专属配置

环境变量配置

支持通过环境变量调整核心配置：

命令行参数

支持通过命令行参数覆盖配置：

bash
docker run -d --name categraf-enterprise \
  registry.example.com/categraf-enterprise:latest \
  --log.level=debug \
  --configs.dir=/etc/categraf/conf.d \
  --enterprise.license=/etc/categraf/license.key

常用命令行参数：

• --config: 指定主配置文件路径
• --configs.dir: 指定插件配置目录
• --test: 测试配置有效性
• --dry-run: 模拟运行，不实际采集数据
• --version: 显示版本信息
• --help: 显示帮助信息

Docker 部署方案

Docker Run 命令示例

1. 基础监控（主机网络模式）

bash
docker run -d --name categraf-enterprise \
  --net=host \
  --pid=host \
  --restart=always \
  -v /:/rootfs:ro \
  -v /var/run:/var/run:ro \
  -v /sys:/sys:ro \
  -v /proc:/proc:ro \
  -v /path/to/conf:/etc/categraf \
  -e CATEGRAF_LOG_LEVEL=info \
  -e CATEGRAF_OUTPUT_PROMETHEUS_REMOTE_WRITE_URL="http://prometheus:9090/api/v1/write" \
  registry.example.com/categraf-enterprise:latest

2. 容器监控（非主机网络模式）

bash
docker run -d --name categraf-enterprise \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /path/to/conf:/etc/categraf \
  -e CATEGRAF_LOG_LEVEL=info \
  -e CATEGRAF_CLUSTER_NAME="prod-cluster" \
  -p 9273:9273 \
  registry.example.com/categraf-enterprise:latest \
  --configs.dir=/etc/categraf/conf.d

Docker Compose 配置示例

yaml
version: '3.8'

services:
  categraf:
    image: registry.example.com/categraf-enterprise:latest
    container_name: categraf-enterprise
    restart: always
    network_mode: "host"
    pid: "host"
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /proc:/proc:ro
      - ./conf:/etc/categraf
      - ./data:/var/lib/categraf
      - ./license:/etc/categraf/license
    environment:
      - CATEGRAF_LOG_LEVEL=info
      - CATEGRAF_TENANT_ID=company-a
      - CATEGRAF_CLUSTER_NAME=prod-k8s-cluster
      - CATEGRAF_METRICS_INTERVAL=10s
      - CATEGRAF_OUTPUT_PROMETHEUS_REMOTE_WRITE_URL="http://prometheus:9090/api/v1/write"
    command:
      - --config=/etc/categraf/categraf.conf
      - --enterprise.license=/etc/categraf/license/enterprise.lic

插件配置

Categraf 企业版提供丰富的插件，可通过配置文件启用和定制：

bash
# 进入容器查看插件列表
docker exec -it categraf-enterprise categraf --list-plugins

# 查看特定插件帮助
docker exec -it categraf-enterprise categraf --plugin-help cpu

常用插件配置示例（在 conf.d/ 目录下创建对应配置文件）：

CPU 监控插件

toml
[[instances]]
  percpu = true
  totalcpu = true
  collect_cpu_time = false
  report_active = false
  core_tags = false

磁盘监控插件

toml
[[instances]]
  mount_points = ["/"]
  ignore_fs = ["tmpfs", "devtmpfs", "devfs", "overlay", "aufs", "squashfs"]
  fs_types = []

企业版数据库监控插件

toml
[[instances]]
  address = "sqlserver://username:password@localhost:1433?database=master"
  interval = "30s"
  collection_query_files = ["/etc/categraf/enterprise/queries/mssql"]
  tls_skip_verify = false
  timeout = "10s"
  
  [instances.tags]
    service = "mssql"
    env = "production"

数据输出配置

支持多种数据输出目标，配置示例：

Prometheus 远程写入

toml
[[outputs.prometheus_remote_write]]
  url = "http://prometheus:9090/api/v1/write"
  basic_auth_user = "user"
  basic_auth_pass = "pass"
  timeout = "10s"
  interval = "15s"
  version = "v2"
  send_batches = true
  batch_size = 10000
  
  [outputs.prometheus_remote_write.headers]
    X-Scope-OrgID = "company-a"

企业版时序数据库输出

toml
[[outputs.enterprise_tsdb]]
  url = "https://tsdb.example.com:8443/write"
  token = "${ENTERPRISE_TSDB_TOKEN}"
  tls_ca_file = "/etc/categraf/certs/ca.pem"
  tls_cert_file = "/etc/categraf/certs/client.pem"
  tls_key_file = "/etc/categraf/certs/client-key.pem"
  timeout = "20s"
  retry_interval = "30s"
  max_retry_times = 3
  
  [outputs.enterprise_tsdb.tags]
    cluster = "${CATEGRAF_CLUSTER_NAME}"
    region = "cn-north-1"

企业版专属功能

多租户配置

toml
[enterprise.tenant]
  id = "${CATEGRAF_TENANT_ID}"
  [enterprise.tenant.labels]
    department = "IT"
    business_unit = "operations"

高级采样配置

toml
[enterprise.sampling]
  [enterprise.sampling.rules]
    [[enterprise.sampling.rules.rule]]
      metric_name = "http_requests_total"
      rate = 0.5
      [enterprise.sampling.rules.rule.labels]
        service = "api-server"
        
    [[enterprise.sampling.rules.rule]]
      metric_name = "db_query_duration_seconds"
      rate = 0.1
      [enterprise.sampling.rules.rule.labels]
        db_type = "mysql"

维护与升级

查看日志

bash
docker logs -f categraf-enterprise

# 查看特定时间段日志
docker logs --since 30m categraf-enterprise

升级镜像

bash
# 拉取新版本镜像
docker pull registry.example.com/categraf-enterprise:latest

# 停止并删除当前容器
docker stop categraf-enterprise && docker rm categraf-enterprise

# 使用新镜像启动
docker run -d --name categraf-enterprise [原有参数] registry.example.com/categraf-enterprise:latest

健康检查

bash
# 容器内健康检查
docker exec -it categraf-enterprise curl -f http://localhost:9273/health || echo "Unhealthy"

# 或通过 Docker 健康检查机制（在 docker run 时添加 --health-cmd 参数）

注意事项

1. 企业版授权：需确保已获得有效的企业版授权证书，并正确挂载或配置
2. 资源限制：根据采集规模调整容器资源限制，建议至少分配 1 CPU 核心和 512MB 内存
3. 网络策略：确保容器能够访问需要监控的目标服务及输出目标
4. 数据安全：生产环境中应启用 TLS 加密传输，并保护敏感配置信息
5. 持久化：配置文件和数据目录建议使用外部挂载，确保升级时数据不丢失

常见问题

Q: 如何获取企业版授权？

A: 请联系 *** 获取企业版授权及报价信息。

Q: 容器启动后无指标输出如何排查？

A: 1. 检查日志确认是否有错误信息；2. 验证授权是否有效；3. 检查输出目标配置是否正确；4. 确认插件是否正确启用。

Q: 如何实现配置的动态更新？

A: Categraf 支持配置文件的动态 reload，修改配置后可通过 docker kill -SIGHUP categraf-enterprise 发送重载信号。

Q: 是否支持 Kubernetes 环境部署？

A: 是的，企业版提供专用的 Helm Chart，支持在 Kubernetes 环境中大规模部署和管理。