Netdata Docker Compose 部署指南

使用 Docker Compose 基于官方镜像 netdata/netdata 部署 Netdata v2.12 实时监控，涵盖数据持久化、系统指标采集挂载、环境变量、健康检查、等价 docker run 方式与常用运维命令，已在 /opt/data/ops/netdata 实测通过

NetdataNetdata指标监控运维系统监控2026/10/08

Netdata Docker Compose 部署指南

目标：使用 Docker Compose 基于官方镜像 netdata/netdata:stable 部署 Netdata v2.12 实时监控，涵盖数据持久化、系统指标采集挂载、常用环境变量、健康检查、等价 docker run 方式与常用运维命令。本文档已在 /opt/data/ops/netdata 目录实测通过。

一、环境信息

  • 操作系统：Ubuntu 24.04 LTS
  • 系统架构：x86_64
  • Docker 版本：Docker Engine 24.x（含 Compose v2 插件）
  • 镜像：netdata/netdata:stable（官方镜像，内含 v2.12 稳定版）
  • 容器名称：netdata-agent
  • 端口映射：宿主机 19999 → 容器 19999
  • 数据目录：宿主机 /opt/data/ops/netdata/
  • 部署文件：/opt/data/ops/netdata/docker-compose.yaml

二、镜像选型说明

镜像标签对应版本特点
netdata/netdata:stablev2.12.x 稳定版官方镜像，面向生产
netdata/netdata:nightly每夜构建含最新特性，稳定性较低

💡 说明：官方镜像仓库为 docker.io/netdata/netdata。国内拉取可配置镜像加速器，或加载到宿主机后 docker load。生产建议锁定 stable 标签。

三、前置条件

  • 已安装 Docker Engine 与 Docker Compose 插件：docker --version && docker compose version
  • 已规划数据目录
  • 监控对象需 Container 权限（采集宿主机容器/进程指标）

四、部署步骤

4.1 创建部署目录

sudo mkdir -p /opt/data/ops/netdata
cd /opt/data/ops/netdata

4.2 编写 docker-compose.yaml

将以下内容保存为 /opt/data/ops/netdata/docker-compose.yaml：

# =============================================================================
# Netdata Docker Compose 部署文件
# 镜像：netdata/netdata:stable（官方稳定镜像，Netdata v2.12）
# 使用方式：cd /opt/data/ops/netdata && docker compose up -d
# =============================================================================

services:
  netdata:
    image: netdata/netdata:stable
    container_name: netdata-agent
    restart: unless-stopped
    hostname: netdata-host

    # ---- 端口映射：宿主机19999 -> 容器19999（Web/API）----
    ports:
      - "19999:19999"

    # ---- 采集合主机的系统指标所需挂载（判读/proc、/sys、cgroup）----
    volumes:
      - netdataconfig:/etc/netdata
      - netdatalib:/var/lib/netdata
      - netdatacache:/var/cache/netdata
      - /etc/passwd:/host/etc/passwd:ro
      - /etc/group:/host/etc/group:ro
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /etc/os-release:/host/etc/os-release:ro
    cap_add:
      - SYS_PTRACE
    security_opt:
      - apparmor:unconfined

volumes:
  netdataconfig:
  netdatalib:
  netdatacache:

💡 说明：/proc、/sys、/etc/passwd 等只读挂载与 cap_add: SYS_PTRACE 让 Netdata 在容器内也能采集宿主机真实的 CPU、内存、磁盘、网络与进程指标。

4.3 启动

docker compose up -d

4.4 验证部署

查看状态：

docker compose ps

执行结果：

NAME          IMAGE                     STATUS
netdata-agent netdata/netdata:stable    Up

验证 Web/API：

curl -s http://127.0.0.1:19999/api/v1/info

执行结果（节选）：

{"version":"2.12.0","hostname":"netdata-host","hosts-available":1,...}

💡 说明：返回 version（v2.12.0）与 hostname，Web/API 正常。浏览器打开 http://<服务器IP>:19999 查看实时监控仪表盘。

五、数据持久化说明

数据类型说明
netdataconfig命名卷/etc/netdata 配置目录
netdatalib命名卷/var/lib/netdata 数据库与流式缓存
netdatacache命名卷/var/cache/netdata 图表/运行时缓存

💡 说明：三者均为命名卷，容器重建后配置、历史数据与图表缓存不丢失；如需在宿主机直接编辑，可改用 bind mount（如 ./etc:/etc/netdata）。

六、常用环境变量表

变量默认值说明
NETDATA_LISTENER_PORT19999Web/API 监听端口
PGID201容器内运行组 ID
HOSTNAME（镜像内置）容器名主机名
TZUTC时区，建议 Asia/Shanghai

七、常用配置参数说明

  • Web/API 默认端口 19999，内部时序/图表数据存于命名卷 /var/lib/netdata。
  • 镜像默认以 memory mode 采集，重启后旧数据不会长期保留；如需持久化历史可配置数据库（如 libengine/外部 DB）。
  • 主配置 /etc/netdata/netdata.conf 可通过 curl http://<IP>:19999/netdata.conf 生成后覆盖默认。

八、配置文件持久化（conf 挂载）

如需把配置落地到宿主机便于编辑，可改用 bind mount 并预生成配置：

services:
  netdata:
    volumes:
      - ./etc:/etc/netdata
      - netdatalib:/var/lib/netdata
      - netdatacache:/var/cache/netdata

sudo mkdir -p /opt/data/ops/netdata/etc
docker run --rm netdata/netdata:stable sh -c 'curl -o /dev/null' 2>/dev/null
# 生成一份默认配置到宿主机 ./etc 后按需修改

💡 说明：bind mount 方式下，编辑宿主机 ./etc/web/netdata.conf 后 docker compose restart netdata 生效。

九、等价 docker run 运行方式

不使用 Compose 时，可单条 docker run：

docker run -d --name netdata-agent --hostname netdata-host \
  -p 19999:19999 \
  -v netdataconfig:/etc/netdata \
  -v netdatalib:/var/lib/netdata \
  -v netdatacache:/var/cache/netdata \
  -v /etc/passwd:/host/etc/passwd:ro \
  -v /etc/group:/host/etc/group:ro \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /etc/os-release:/host/etc/os-release:ro \
  --cap-add SYS_PTRACE --security-opt apparmor:unconfined \
  netdata/netdata:stable

十、常用运维命令

# 查看容器状态
docker compose ps

# 查看日志
docker compose logs -f netdata

# 校验/可执行 netdata 参数
docker compose exec netdata netdata -h

# 健康检查信息
docker compose exec netdata bash -c 'cat /var/lib/netdata/.healthy 2>/dev/null || echo ok'

# 重启（改配置后）
docker compose restart netdata

# 停止/移除（命名卷保留）
docker compose down

十一、常见问题（FAQ）

11.1 容器内采集不到宿主机指标

💡 原因与解决：多为缺少 /proc、/sys 挂载或 SYS_PTRACE 权限。补全 compose 中的 volumes 与 cap_add 后 docker compose up -d --force-recreate。

11.2 19999 端口被占用

💡 原因与解决：改 ports: - "19999:19999" 的宿主机侧端口（如 "18099:19999"），同步调整浏览器访问地址与 NETDATA_LISTENER_PORT（如相同则改容器侧以避免冲突）。

11.3 重启后历史数据丢失

💡 原因与解决：确认 netdatalib 命名卷//var/lib/netdata 挂载存在；若用内存模式采集，重启即清空，需按需配置持久化数据库。

十二、参考链接