使用 OneUptime Docker Agent 一键采集 Docker 主机指标、容器日志并接入 OneUptime 可观测性平台
【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime
本篇技术指南以 OneUptime 开源仓库中的 Docker 主机遥测接入文档（App/FeatureSet/Docs/Content/es/telemetry/docker-host.md）为核心，围绕官方预配置镜像oneuptime/docker-agent展开：你将掌握它的部署前提、单命令快速启动与 Docker Compose 两种安装方式、全部环境变量的含义与默认值、内部采集管线（CPU/内存/网络/块 I/O 指标、容器日志与资源清单快照）的底层实现，以及升级、卸载与常见故障排查的完整实战方案。读完即可在数分钟内让一台 Docker 主机以指标与日志的形式出现在 OneUptime 面板的Docker区域中。
一、Docker Agent 是什么
OneUptime Docker Agent 是一个预配置的 OpenTelemetry Collector 容器镜像。它不需要你手写任何 Collector 配置——镜像内已内置一套针对 Docker 场景调优好的otel-collector-config.yaml，你只需要传入几个环境变量并运行一条命令，它就会：
- 自动发现宿主机上的每一个容器；
- 采集每个容器的 CPU、内存、网络、块 I/O（Block I/O）指标以及容器日志；
- 通过 OTLP（OpenTelemetry Protocol）协议将全部数据转发到 OneUptime。
从仓库结构看，该 Agent 的完整实现集中在 DockerAgent 目录，包含镜像构建文件 Dockerfile.tpl、采集配置 otel-collector-config.yaml、Compose 示例 docker-compose.yml、入口脚本 entrypoint.sh、资源清单轮询脚本 inventory-snapshot.sh，以及交互式安装脚本 install.sh 与 systemd 单元文件 oneuptime-docker-agent.service。
镜像的构建底座
从 Dockerfile.tpl 可以看出镜像的关键设计决策：
- 基础镜像：
otel/opentelemetry-collector-contrib:0.154.0，即 OpenTelemetry Collector Contrib 发行版，内置docker_stats、filelog等大量社区接收器； - 内置配置：构建时把 otel-collector-config.yaml 拷贝到
/etc/otelcol-contrib/config.yaml，Collector 启动时通过${env:...}占位符解析环境变量； - 以 root 运行：
USER 0:0，因为基础镜像默认的非 root 用户（UID 10001）在大多数宿主机上无权访问 Docker socket 与容器日志目录； - 默认值固化：
ENV DOCKER_HOST_NAME=docker-host、ENV DOCKER_API_VERSION=1.44均作为镜像默认值注入，可在运行时覆盖。
容器内的进程模型
entrypoint.sh 揭示了 Agent 运行时的进程拓扑：
/usr/local/bin/oneuptime-docker-inventory.sh & exec /otelcol-contrib --config=/etc/otelcol-contrib/config.yaml即：后台启动资源清单快照轮询器（best-effort，失败不影响 Agent 存活），前台执行 OTel Collector（受监督进程，若它退出则容器重启）。这正是“一条命令、一个容器、全部采集”的实现基础。
二、部署前提
在运行 Agent 前，请确认满足以下条件：
- Docker Engine 20.10+；
- 宿主机上可访问
/var/run/docker.sock（Agent 通过它调用 Docker Engine API）； - 一个OneUptime 遥测摄取 Token（Telemetry Ingestion Token）——在 OneUptime 面板中通过项目设置 → Telemetry 和 APM → 摄取密钥（Ingestion Keys）创建并复制其值；
- （采集日志时需要）容器使用
json-file日志驱动：这是 Docker 的默认驱动。Agent 通过 filelog 接收器追踪/var/lib/docker/containers/*/*-json.log文件，无法解析local（二进制 protobuf）或其他远程驱动（journald、syslog、fluentd、gelf等）产生的日志。
三、快速开始：单命令部署
将YOUR_ONEUPTIME_URL、YOUR_TELEMETRY_INGESTION_TOKEN以及主机名替换为你的环境值。主机名（DOCKER_HOST_NAME）是这台 Docker 主机在 OneUptime 中显示的名称——请选择类似prod-docker-01这样的稳定命名。
docker run -d \ --name oneuptime-docker-agent \ --user 0:0 \ --restart unless-stopped \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -v /var/lib/docker/containers:/var/lib/docker/containers:ro \ -e ONEUPTIME_URL="YOUR_ONEUPTIME_URL" \ -e ONEUPTIME_SERVICE_TOKEN="YOUR_TELEMETRY_INGESTION_TOKEN" \ -e DOCKER_HOST_NAME="my-docker-host" \ oneuptime/docker-agent:release对几个关键参数的解释：
--user 0:0：以 root 身份运行，才能读取 Docker socket 与/var/lib/docker/containers下的日志文件；-v /var/run/docker.sock:/var/run/docker.sock:ro：只读挂载 Docker 控制 socket，供docker_stats接收器与资源清单轮询器调用 Docker Engine API；-v /var/lib/docker/containers:/var/lib/docker/containers:ro：只读挂载容器日志目录，供 filelog 接收器读取*-json.log文件；--restart unless-stopped：确保守护进程退出后自动拉起。
完成以上步骤即可：一旦 Agent 建立连接，你的 Docker 主机就会自动出现在 OneUptime 面板的Docker区域中，无需手动注册主机。
四、Docker Compose 部署方式
如果你更习惯 Docker Compose，可将以下内容写入docker-compose.yml：
services: oneuptime-docker-agent: image: oneuptime/docker-agent:release container_name: oneuptime-docker-agent user: "0:0" restart: unless-stopped volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - /var/lib/docker/containers:/var/lib/docker/containers:ro environment: - ONEUPTIME_URL=YOUR_ONEUPTIME_URL - ONEUPTIME_SERVICE_TOKEN=YOUR_TELEMETRY_INGESTION_TOKEN - DOCKER_HOST_NAME=my-docker-host logging: driver: json-file options: max-size: "10m" max-file: "3"启动：
docker compose up -d仓库自带的 docker-compose.yml 与官方文档保持一致的形态，但它更进一步示范了如何通过.env文件注入环境变量：
environment: - ONEUPTIME_URL=${ONEUPTIME_URL} - ONEUPTIME_SERVICE_TOKEN=${ONEUPTIME_SERVICE_TOKEN} - DOCKER_HOST_NAME=${DOCKER_HOST_NAME:-docker-host} - DOCKER_API_VERSION=${DOCKER_API_VERSION-1.44}注意两个容易踩坑的细节（详见该文件注释）：
DOCKER_HOST_NAME使用${VAR:-default}形式：变量未设置时回落到docker-host；DOCKER_API_VERSION特意使用${VAR-default}而非${VAR:-default}——冒号形式会把显式设置为空字符串的值替换成默认值，从而吞掉“空字符串 = 自动协商 API 版本”这个逃生通道。
Compose 文件中同时为 Agent 自身配置了json-file日志驱动与轮转策略（max-size: "10m"、max-file: "3"），避免 Agent 自身日志无限增长。
五、环境变量详解
| 变量 | 是否必填 | 说明 |
|---|---|---|
ONEUPTIME_URL | 是 | 你的 OneUptime 实例地址（例如https://oneuptime.com，或自托管实例地址） |
ONEUPTIME_SERVICE_TOKEN | 是 | 来自项目设置 → Telemetry 和 APM → 摄取密钥的遥测摄取 Token |
DOCKER_HOST_NAME | 否 | 该主机的友好名称，默认值为docker-host；请配置为每台主机稳定不变的名称（例如prod-docker-01） |
DOCKER_API_VERSION | 否 | Agent 使用的 Docker Engine API 版本，默认值为1.44；在 daemon 较旧的主机上调低它，或设为空字符串让 SDK 自动协商（见“故障排查”） |
这 4 个变量在 Dockerfile.tpl 与 otel-collector-config.yaml 中的流向非常清晰：
DOCKER_HOST_NAME通过 resource processor 写入host.name资源属性（otel-collector-config.yaml 中的resourcedetection/resource处理器）；DOCKER_API_VERSION注入docker_stats接收器的api_version字段；ONEUPTIME_URL拼接出 OTLP HTTP exporter 的端点${env:ONEUPTIME_URL}/otlp；ONEUPTIME_SERVICE_TOKEN以x-oneuptime-service-token请求头随数据发送。
镜像 Tag 选择
关于镜像的可用 Tag（见 DockerAgent/README.md）：
| Tag | 说明 |
|---|---|
oneuptime/docker-agent:release | 最新稳定版（社区版） |
oneuptime/docker-agent:enterprise-release | 最新稳定版（企业版） |
oneuptime/docker-agent:<version> | 固定版本，例如10.0.31 |
ghcr.io/oneuptime/docker-agent:release | 同一镜像在 GHCR 的镜像副本 |
六、验证安装
确认 Agent 正在运行：
docker ps --filter name=oneuptime-docker-agent查看 Agent 日志：
docker logs -f oneuptime-docker-agent在日志中寻找以下启动就绪标志：
"Everything is ready. Begin running and processing data."出现该信息后，大约一分钟内，主机就会出现在 OneUptime 面板中，指标与日志开始持续流动。
七、Agent 内部实现：采集了什么、如何采集
官方文档给出了“采集了什么”的分类清单，而仓库中的 otel-collector-config.yaml 则完整揭示了“如何采集”的底层实现。以下将两者结合展开。
7.1 采集内容总览
| 类别 | 数据 |
|---|---|
| CPU 指标 | 总用量、使用百分比、限流（throttling）时间（按容器） |
| 内存指标 | 使用量、限额、百分比、RSS、缓存（按容器） |
| 网络指标 | 接收/发送的字节数与包数（按容器） |
| 块 I/O 指标 | 读/写的字节数与操作次数（按容器） |
| 容器信息 | 运行时长（uptime）、重启次数、进程数 |
| 容器日志 | 所有容器的 stdout/stderr 日志 |
配合 Docker Monitor 文档 中列出的具体指标名，可在告警查询中直接使用：
- CPU：
container.cpu.utilization（100% 表示整整一个 CPU 核心）、container.cpu.usage.total、container.cpu.throttling_data.throttled_time、container.cpu.throttling_data.throttled_periods； - 内存：
container.memory.usage.total、container.memory.usage.limit、container.memory.percent； - 网络：
container.network.io.usage.rx_bytes、container.network.io.usage.tx_bytes； - 块 I/O：
container.blockio.io_service_bytes_recursive.read、container.blockio.io_service_bytes_recursive.write； - 容器信息：
container.uptime、container.restarts、container.pids.count。
7.2 指标管线：docker_stats 接收器
receivers: docker_stats: endpoint: unix:///var/run/docker.sock api_version: "${env:DOCKER_API_VERSION}" collection_interval: 30s metrics: container.cpu.utilization: enabled: true container.cpu.throttling_data.throttled_periods: enabled: true container.cpu.throttling_data.throttled_time: enabled: true container.memory.percent: enabled: true container.pids.count: enabled: true container.restarts: enabled: true container.uptime: enabled: true要点：
docker_stats接收器通过 Unix socket 调用 Docker Engine API，每 30 秒抓取一轮指标；container.restarts、container.uptime、container.pids.count、container.cpu.utilization、container.cpu.throttling_data.*、container.memory.percent这些指标在 contrib 版docker_stats接收器中默认关闭，必须在配置中显式开启——OneUptime 的 Docker Monitor 告警模板恰好依赖这些指标（重启、运行时长、进程数、CPU 限流），所以这份内置配置特意全部开启；api_version直接取自环境变量，这是“旧 daemon 上可调低版本而不替换配置”的实现入口（详见故障排查）。
7.3 日志管线：filelog 接收器与多操作符处理链
filelog: include: - /var/lib/docker/containers/*/*-json.log exclude: - /var/lib/docker/containers/${env:HOSTNAME}*/*-json.log start_at: end include_file_path: true operators: - type: json_parser # 解析 Docker json-file 日志信封 - type: regex_parser # 从文件路径提取 container_id - type: move # container_id -> resource["container.id"] - type: move # log -> body - type: move # stream -> attributes["log.iostream"] - type: recombine # 多行栈帧重组合并为单条记录 - type: router / regex_parser / add / severity_parser # 严重级别推导 - type: remove这段配置（otel-collector-config.yaml）体现了大量工程细节：
- 排除自采自收的反馈回路：
exclude用${env:HOSTNAME}前缀（容器内HOSTNAME默认是 12 位短容器 ID）排除 Agent 自身容器的日志，避免 Collector 摄取并导出自己的采集/导出堆栈信息； - 容器 ID 关联：从日志文件路径正则提取容器 ID 并提升为
resource["container.id"]，从而在 OneUptime 日志页与docker_stats指标之间建立关联； - 多行日志重组：Docker 的 json-file 驱动按行写 JSON 信封，一条多行堆栈（如 Node.js 错误的多行
at ...帧）会被拆成多条记录。recombine操作符把“以空白或右括号/大括号/圆括号开头”的行视为上一行的延续，重新合并成一条完整记录，并用source_identifier防止不同容器的记录被错误合并； - 严重级别（severity）推导：Docker 的 json-file 驱动本身不记录严重级别，而 OTel 日志记录要求
severity_number/severity_text供下游视图过滤。该配置实现了一套“尽力而为”的推导：- 识别行首前言位置的级别关键字（如
[ERROR]、Monolog 的app.INFO:、2026-08-31 07:25:04 INFO ...、Python logging 的- myapp - INFO -、logfmt 的level=error）或任意位置的 level 字段（level、lvl、severity、levelname、log.level等），只相信位于级别真实位置的单词，普通句子中顺带出现的 “error”/“panic” 不会被误判； - 未识别到级别关键字时回落到流判定：
stderr → ERROR、stdout → INFO； - 最后通过
severity_parser把文本级别映射为 OTel 的severity_number，并补充了notice、alert、emerg、emergency、crit、critical、panic等 PSR-3/syslog 级别映射（默认 preset 不认识这些词）。该逻辑在仓库的 Tests/Ops 下有专门测试用例钉死（含“必须不匹配”的语料）。
- 识别行首前言位置的级别关键字（如
7.4 资源清单管线：inventory-snapshot 轮询器
除了指标与日志，Agent 还会周期性地向 OneUptime 上报容器/镜像/网络/卷的清单快照。inventory-snapshot.sh 的实现要点：
- 通过 Unix socket 调用 Docker Engine API，抓取四类资源：
/containers/json?all=true（含 exited/paused 容器）、/images/json、/networks、/volumes； - 每条资源写成一行 JSON 信封：
{"oneuptime.docker.kind":"Container","data":{...}}，写入/var/log/oneuptime-docker-inventory.log； - 每次先写
.tmp再原子 rename，保证 Collector 永远读不到半写文件； - 默认每 300 秒（
DOCKER_INVENTORY_INTERVAL_SECONDS）轮询一次；API 版本跟随DOCKER_API_VERSION——若显式设为空串（“让服务端决定”），脚本会退化为不带/v<version>前缀的未版本化路径请求，等价于使用 daemon 当前最高版本。
该日志文件由独立的filelog/inventory接收器读取（start_at: beginning+ 30 秒轮询），走独立的logs/inventory管线，避免被“丢弃自采集日志”的过滤器（基于 body 匹配 Collector 错误串）误伤。
7.5 处理器与导出器
processors: resource: attributes: - key: container.runtime value: "docker" - key: host.name value: "${env:DOCKER_HOST_NAME}" - key: oneuptime.agent.version value: "${env:APP_VERSION}" resourcedetection: detectors: [env, system] batch: timeout: 10s send_batch_size: 1024 memory_limiter: check_interval: 5s limit_mib: 512 spike_limit_mib: 128 exporters: otlphttp: endpoint: "${env:ONEUPTIME_URL}/otlp" headers: x-oneuptime-service-token: "${env:ONEUPTIME_SERVICE_TOKEN}" service: pipelines: metrics: receivers: [docker_stats] processors: [memory_limiter, resourcedetection, resource, batch] exporters: [otlphttp] logs: receivers: [filelog] processors: [memory_limiter, filter/drop_self_logs, resourcedetection, resource, batch] exporters: [otlphttp] logs/inventory: receivers: [filelog/inventory] processors: [memory_limiter, resourcedetection, resource, batch] exporters: [otlphttp]值得注意的设计：
- 资源打标：每个数据点都被打上
container.runtime=docker、host.name=${DOCKER_HOST_NAME}、oneuptime.agent.version=${APP_VERSION}三个资源属性。其中host.name是 OneUptime Docker 主机页面的过滤键——主机的hostIdentifier直接取自该值； - 三条管线分离：指标、容器日志、清单快照互不干扰，
filter/drop_self_logs只作用于容器日志管线； - 内存保护：
memory_limiter限制 Collector 自身内存占用（上限 512 MiB、尖峰 128 MiB），batch以 10 秒/1024 条批量导出以提高吞吐。
八、自托管 OneUptime 场景
如果你在自托管 OneUptime，只需将ONEUPTIME_URL配置为你自己的实例：
-e ONEUPTIME_URL="https://your-oneuptime-host.example.com"如果实例仅支持 HTTP，使用http://并带上对应端口即可。Agent 会将数据 POST 到{ONEUPTIME_URL}/otlp，因此务必保证该端点可达且公网/内网路由正确。
九、升级与卸载 Agent
升级
docker pull oneuptime/docker-agent:release docker rm -f oneuptime-docker-agent # 重新执行上面的 docker run 命令或使用 Docker Compose：
docker compose pull docker compose up -d卸载
docker rm -f oneuptime-docker-agent如果使用的是 Docker Compose：
docker compose down另外，仓库还提供了两套便捷部署路径：交互式安装脚本 install.sh（自动检查 Docker 与 daemon 状态、交互式收集 URL/Token/主机名、执行docker run）以及 systemd 单元文件 oneuptime-docker-agent.service（docker compose pull+up --remove-orphans，失败自动重启），适合需要开机自启与进程托管的服务器场景。
十、常见问题排查
10.1 Docker socket 权限被拒绝
Agent 容器必须以 root 运行（--user 0:0）才能访问/var/run/docker.sock。请确认docker run命令中包含--user 0:0标志（或 Compose 中的user: "0:0"）。
10.2 Agent 反复重启，报错 “client version is too new”
典型报错：
Error: cannot start pipelines: failed to start "docker_stats" receiver: Error response from daemon: client version 1.44 is too new. Maximum supported API version is 1.41原因：daemon 会拒绝比自己最高支持版本更新的客户端，docker_stats接收器启动失败，整个 Collector 随之退出，容器陷入重启循环。解决方式：
- 查询 daemon 支持的 API 版本：
docker version --format '{{ .Server.APIVersion }}'- 把得到的值（如
1.41）传给 Agent：
docker run -d ... -e DOCKER_API_VERSION=1.41 ...或在 Compose 中设置DOCKER_API_VERSION。由于新 daemon 仍然向下兼容旧 API 版本，这个设置即使日后 daemon 升级也依然有效，可按自己的节奏移除。
如果不想手动查版本号，可以把DOCKER_API_VERSION设为空字符串。此时 Agent 会请求 Docker SDK 与 daemon 自动协商版本（一次HEAD /_ping，随后采用 daemon 自身的最高版本），新旧 daemon 都能适配：
docker run -d ... -e DOCKER_API_VERSION= ...仓库注释中特别解释了为什么空字符串能生效：confmap 只有在变量未设置时才应用:-默认值，而显式传入空串不会被默认值覆盖，因此-e DOCKER_API_VERSION=可以安全地触达自动协商分支。
10.3 Agent 显示为离线/未连接
- 确认 Agent 在运行：
docker ps --filter name=oneuptime-docker-agent； - 检查 Agent 日志中的错误：
docker logs oneuptime-docker-agent | grep -i error； - 核对 OneUptime URL 与服务 Token 是否正确；
- 确认 Docker 主机网络可以访问 OneUptime 实例。
10.4 没有指标上报
- 验证 Docker socket 在 Agent 内部可访问：
docker exec oneuptime-docker-agent ls -la /var/run/docker.sock； - 查看 Collector 日志中的导出错误：
docker logs oneuptime-docker-agent | tail -100； - 确保服务 Token 有效且未过期。
10.5 主机名显示为容器 ID
请设置DOCKER_HOST_NAME环境变量为描述性名称，并重新创建容器。因为 OneUptime 的 Docker 主机页面按resource.host.name == hostIdentifier过滤，且该值取自DOCKER_HOST_NAME——如果主机自动注册后再修改该值，OneUptime 会以新名称再建一行主机记录（DockerAgent/README.md 对此有专门说明）。
10.6 有指标但没有容器日志
如果指标正常、日志页却是空的，最常见的原因是容器未使用json-file日志驱动。排查步骤：
# 1. 检查 filelog 接收器是否在追踪日志文件 docker logs oneuptime-docker-agent 2>&1 | grep -E "Started watching file|no files match" # 2. 查看容器实际使用的日志驱动 docker inspect <container> --format '{{.HostConfig.LogConfig.Type}}' # 3. 检查接收器期望的日志文件是否存在 docker run --rm --volumes-from oneuptime-docker-agent alpine:3.19 \ sh -c 'ls /var/lib/docker/containers/*/*-json.log 2>&1 | head'若第 1 步显示no files match the configured criteria，或第 3 步找不到文件，说明容器没有使用json-file驱动。可在 Compose 中为每个服务显式声明logging块：
services: my-app: image: my-app:latest logging: driver: "json-file" options: max-size: "100m" max-file: "5"或在/etc/docker/daemon.json中修改 daemon 全局默认（影响之后创建的所有容器）：
{ "log-driver": "json-file", "log-opts": { "max-size": "100m", "max-file": "5" } }修改后需要重新创建（而非仅重启）受影响的容器——日志驱动在容器创建时即被绑定：
# Compose 场景 docker compose up -d --force-recreate <service> # 纯 docker 场景 docker rm -f <container> docker run ... <image>十一、下一步：用 Docker Monitor 配置告警
Agent 负责“采集与上报”，告警则由 OneUptime 的Docker Monitor完成。在 Docker Monitor 文档 中你可以看到完整的告警配置指南：选择 Docker 主机与资源范围（Host 整体或按容器名/镜像筛选）、配置指标查询（指标名 + 聚合方式 Avg/Sum/Max/Min + 过滤器 + Group By）、选择滚动时间窗口（过去 1/5/10/15/30/60 分钟），并基于container.cpu.utilization、container.memory.percent、container.restarts等指标设置 CPU 过高、内存过高、容器重启循环等监控条件，实现对容器工作负载的自动化告警。
如果你的监控对象不是单机 Docker，官方还提供了对应方案：
- Kubernetes 集群：使用 OneUptime Kubernetes Agent；
- 非容器化主机（Linux/macOS/Windows 的 VM 与物理机）：使用 Host OpenTelemetry Collector。
结语
OneUptime Docker Agent 的价值在于“零配置接入”：预调优的 Collector 配置、对旧 daemon 的版本兼容设计、自排除反馈回路的日志采集、多行重组与严重级别推导、原子写入的资源清单快照，以及三条隔离的 OTLP 管线，都封装在一个镜像一条命令里。从部署到告警的完整链路中，DockerAgent 目录下的源码与配置是理解其内部行为的最佳参考，而 docker-host.md（及英文版 docker-host.md）则始终是安装、升级与排障的首选官方手册。
【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
