一个用于容器化运行哪吒监控 Agent 的 Docker Compose 示例项目。
本项目不是 Nezha 官方项目,也不提供 Dashboard 或 Agent 的二进制分发;它只是把官方 Agent 二进制运行方式整理成可复制的 Compose 部署模板,方便已经部署好 Nezha Dashboard 的用户用容器方式运行 Agent。
这是一个个人自用项目存档,主要用于记录和复用自己验证过的 Agent 容器化部署方式。项目内容以“能稳定复现个人部署经验”为目标,不承诺覆盖所有环境,也不代表 Nezha 官方推荐方案。
本项目的文档整理、README 表达和部分模板拆分经过 AI 辅助完成;核心部署思路来自个人实际排查和服务器验证。AI 生成内容可能存在表述不严谨或遗漏,使用前请结合自己的 Dashboard、反向代理和服务器环境自行确认。
如果你需要权威说明,请优先参考 Nezha 官方文档和官方仓库。
- 使用官方
nezhahq/agent发布的 Agent 二进制 - 不依赖第三方 Agent 镜像
- 支持直接粘贴 Dashboard 面板生成的官方 Agent 安装命令
- 支持
.env参数方式部署 - 自动生成 Agent
config.yml - 前台运行 Agent,便于
docker compose logs排查
推荐新手使用方式一:直接粘贴官方安装命令。
如果你更希望把参数放在 .env 中管理,可以使用方式二。
编辑 docker-compose.yml,把 Dashboard 面板「服务器 → 安装命令」复制出来的整条命令粘贴到 INSTALL_CMD 下方:
INSTALL_CMD: |
curl -L https://raw.githubusercontent.com/nezhahq/scripts/main/agent/install.sh -o agent.sh && chmod +x agent.sh && env NZ_SERVER=nezha.example.com:443 NZ_TLS=true NZ_CLIENT_SECRET=YOUR_CLIENT_SECRET ./agent.sh启动:
docker compose up -d查看日志:
docker compose logs -f nezha-agent复制示例环境文件:
cp .env.example .env编辑 .env:
COMPOSE_PROJECT_NAME=zhane-agent-compose
NZ_SERVER=nezha.example.com:443
NZ_TLS=true
NZ_CLIENT_SECRET=YOUR_CLIENT_SECRET
# NZ_UUID=启动 .env 版本:
docker compose -f docker-compose.env.yml up -d查看日志:
docker compose -f docker-compose.env.yml logs -f zhane-agent如果 Dashboard 通过 HTTPS 443 暴露,例如:
https://nezha.example.com
Agent 参数通常应为:
NZ_SERVER=nezha.example.com:443
NZ_TLS=true
443 + NZ_TLS=false 是常见错误组合,会导致 Agent 握手失败。
如果 Dashboard 页面能打开但 Agent 不上线,通常需要确认反向代理是否正确转发 gRPC。见 docs/reverse-proxy-nginx.md。
# 方式一:启动
docker compose up -d
# 方式一:查看日志
docker compose logs -f nezha-agent
# 方式一:重建并拉取最新 Agent
docker compose up -d --force-recreate
# 方式一:停止并删除容器
docker compose down# 方式二:启动
docker compose -f docker-compose.env.yml up -d
# 方式二:查看日志
docker compose -f docker-compose.env.yml logs -f zhane-agent
# 方式二:重建并拉取最新 Agent
docker compose -f docker-compose.env.yml up -d --force-recreate
# 方式二:停止并删除容器
docker compose -f docker-compose.env.yml down不要把真实的 NZ_CLIENT_SECRET 提交到公开仓库。
公开发布时请确认:
docker-compose.yml中仍是NZ_CLIENT_SECRET=YOUR_CLIENT_SECRET.env没有被提交.env.example中只有示例值
如果密钥已经泄露,建议在 Dashboard 中重置连接密钥并重新生成安装命令。
项目名使用 zhane-agent-compose,避免与 Nezha 官方项目、镜像或仓库名称混淆。本文档中的 Nezha / 哪吒仅用于说明本项目适配的上游监控系统。
暂未指定开源许可证。发布到 GitHub 前请根据你的授权意图选择合适的 License。