Nezha 安装部署指南

目标：给出 Nezha dashboard 的 Docker Compose 与二进制 systemd 两种部署全流程，并用官方脚本完成 agent 安装接入；所有命令与输出均为真实执行照录。实测环境：dashboard v2.3.18（ghcr.io 镜像 + 官方 release 二进制两种方式部署）、agent v2.3.5（官方安装脚本安装），Ubuntu 22.04 服务器 ×2，Docker 28.3.3。部署架构介绍见《Nezha 介绍与选型指南》。

一、部署规划

Nezha 只需两个角色：dashboard（中心面板） 和 agent（探针）。开始前先确认三件事：

一台中心服务器：跑 dashboard，开放一个 TCP 端口（默认 8008，本文实测改用 13903，容器方案用 13930）；
被监控机器：安装 agent，只需能出站访问 dashboard 的端口，无需开放任何入站端口；
agent 接入密钥：dashboard 配置文件 config.yaml 中的 agent_secret_key，agent 安装时通过环境变量传入。

下表是本次实测的部署参数（后文所有命令以此为准，替换成你自己的值即可）：

项目	值
dashboard 服务器内网 IP	172.30.0.2
dashboard 端口	8008（宿主映射 13903 / 13930）
agent_secret_key	`nX3qmk2cXMKuCY0SCO2N3g8bLdun25gF`
dashboard 实测版本	v2.3.18
agent 实测版本	v2.3.5（agent 独立发版，最新即 v2.3.5）
数据目录	/opt/data/nezha（宿主）

版本说明：dashboard 与 agent 各自独立发版，截至实测日，dashboard 最新为 v2.3.18，agent 最新为 v2.3.5，两者版本号不同属正常现象。

二、方案 A：Docker Compose 部署 dashboard（推荐）

2.1 官方镜像与脚本说明

官方镜像：ghcr.io/nezhahq/nezha，latest 标签即当前稳定版（实测拉取后验证运行版本为 v2.3.18，镜像大小 66.2MB）；
官方安装脚本（https://raw.githubusercontent.com/nezhahq/scripts/main/install.sh）本质上是交互式地帮你装 Docker 并生成类似的 compose 文件；本文直接手写 compose，过程透明可控。

2.2 编排文件

在宿主机创建部署目录与编排文件：

mkdir -p /opt/data/nezha/compose/data
cat > /opt/data/nezha/compose/docker-compose.yml <<'EOF'
services:
  dashboard:
    image: ghcr.io/nezhahq/nezha:latest
    container_name: nezha-dashboard-compose
    restart: always
    ports:
      - "13930:8008"
    volumes:
      - ./data:/dashboard/data
EOF

逐段解析：

片段	说明
`image: ghcr.io/nezhahq/nezha:latest`	官方镜像。生产建议锁定具体版本标签，避免 `latest` 随升级变动
`container_name`	固定容器名，便于 `docker logs` / `docker exec` 定位
`restart: always`	宿主机重启或进程异常退出后自动拉起
`ports: "13930:8008"`	宿主 13930 → 容器 8008。8008 端口同时承载 HTTP 面板与 agent 的 gRPC，agent 侧必须直连此端口的容器侧（或映射后的宿主侧）
`volumes: ./data:/dashboard/data`	关键挂载：配置 `config.yaml`、数据库 `sqlite.db`、主题与静态资源全部在容器内 `/dashboard/data`，必须持久化到宿主

2.3 启动与首次初始化（实测输出）

$ docker compose -f /opt/data/nezha/compose/docker-compose.yml up -d
[+] Running 8/8
 ✔ dashboard Pulled                                                                    5.9s
   ✔ 33557d5d1548 Pull complete                                                        1.1s
   ✔ 257c808d3b19 Pull complete                                                        1.3s
   ✔ 6e6dd00c9be7 Pull complete                                                        1.9s
   ✔ f6a20b98df66 Pull complete                                                        2.0s
   ✔ 4f4fb700ef54 Pull complete                                                        2.0s
   ✔ 372a0a235e35 Pull complete                                                        2.1s
   ✔ b6a0a644d6e8 Pull complete                                                        2.4s
[+] Running 2/2
 ✔ Network compose_default  Created                                                     0.1s
 ✔ Container nezha-dashboard-compose  Started                                           0.5s

首次启动日志（照录）：

$ docker logs nezha-dashboard-compose
NEZHA@2026-10-18 04:30:43>> Checking for disk usage..
NEZHA@2026-10-18 04:30:43>> Listening for http on 0.0.0.0:8008

数据目录自动生成（照录）：

$ ls -la /opt/data/nezha/compose/data/
-rw-r--r-- 1 root root  1023 Oct 18 04:30 config.yaml
-rw-r--r-- 1 root root 86016 Oct 18 04:30 sqlite.db
drwxr-xr-x 2 root root   4096 Oct 18 04:30 theme

2.4 默认账号验证（实测输出）

全新初始化的 dashboard 默认管理员账号为 admin / admin（首次登录后立即改密）：

$ curl -s -X POST http://localhost:13930/api/v1/login \
    -H 'Content-Type: application/json' \
    -d '{"username":"admin","password":"admin"}'
{"success":true,"data":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjo..."}}

2.5 数据持久化实测

实测方法：修改 config.yaml 中的站点名（site_name: Nezha Compose Demo），重启服务后通过管理 API 验证配置仍在、版本号正确：

$ grep site_name /opt/data/nezha/compose/data/config.yaml
site_name: Nezha Compose Demo

$ docker compose -f /opt/data/nezha/compose/docker-compose.yml restart
[+] Running 1/1
 ✔ Container nezha-dashboard-compose  Started                                           0.5s

$ TOKEN=$(curl -s -X POST http://localhost:13930/api/v1/login \
    -H 'Content-Type: application/json' \
    -d '{"username":"admin","password":"admin"}' \
    | python3 -c "import sys,json;print(json.load(sys.stdin)['data']['token'])")
$ curl -s http://localhost:13930/api/v1/setting -H "Authorization: Bearer $TOKEN"
{"success":true,"data":{"version":"2.3.18","site_name":"Nezha Compose Demo",...}}

down 后 up 重建，配置与数据库同样保留（数据在宿主 ./data 目录）。结论：只要保留 ./data 挂载目录，镜像重建/升级不丢数据。

三、方案 B：二进制 + systemd 部署 dashboard

适合不使用 Docker 的机器。以下在一台全新 Ubuntu 22.04 服务器上 0→1 实测。

3.1 安装依赖与下载发行包

$ apt-get update && apt-get install -y curl unzip
$ mkdir -p /opt/nezha/dashboard && cd /opt/nezha/dashboard
$ curl -sL -o app.zip \
    https://github.com/nezhahq/nezha/releases/download/v2.3.18/dashboard-linux-amd64.zip
$ unzip -qo app.zip && mv dashboard-linux-amd64 app && rm app.zip && chmod +x app
$ ./app -v
version: v2.3.18

3.2 最小配置文件

在 /opt/nezha/dashboard/data/config.yaml 写入最小配置即可启动，其余项由服务首次启动时自动补全默认值：

debug: false
listen_port: 8008
language: zh_CN
site_name: "Nezha Standalone Demo"
install_host: "nezha-standalone:8008"
tls: false

参数	说明
`listen_port`	HTTP 面板与 agent gRPC 共用的监听端口
`language`	面板语言，`zh_CN` 中文
`site_name`	站点名称，显示在面板标题
`install_host`	agent 一键安装命令中展示的接入地址（仅展示用途）
`tls`	面板是否启用 TLS（通常交给反向代理处理，此处 false）

首次启动后，服务会把完整配置写回该文件（实测自动补全为 1422 字节，新增 agent_secret_key、jwt_secret_key 等并自动生成密钥），完整字段说明见《Nezha v2.3.18 配置参数详解》。

3.3 systemd 服务单元（官方模板）

官方脚本仓库提供了现成的服务单元（services/nezha-dashboard.service），实测经 gitee 镜像拉取：

$ curl -sL -o /etc/systemd/system/nezha-dashboard.service \
    https://gitee.com/naibahq/scripts/raw/main/services/nezha-dashboard.service
$ systemctl daemon-reload
$ systemctl enable --now nezha-dashboard

单元文件内容（照录，二进制路径按实际调整）：

[Unit]
Description=Nezha dashboard Service
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/nezha/dashboard
ExecStart=/opt/nezha/dashboard/app
Restart=on-failure
RestartSec=10s
LimitNOFILE=infinity

[Install]
WantedBy=multi-user.target

3.4 启动验证（实测输出）

$ systemctl is-active nezha-dashboard
active
$ ss -tlnp | grep 8008
LISTEN 0 4096 *:8008  *:*  users:(("app",pid=1234,fd=5))
$ curl -s -X POST http://127.0.0.1:8008/api/v1/login \
    -H 'Content-Type: application/json' -d '{"username":"admin","password":"admin"}'
{"success":true,"data":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}

3.5 卸载（实测）

systemctl disable --now nezha-dashboard
rm -f /etc/systemd/system/nezha-dashboard.service && systemctl daemon-reload
rm -rf /opt/nezha/dashboard

四、Agent 安装（官方脚本实测）

4.1 前置检查

在要被监控的机器上确认能连通 dashboard 的端口（实测走容器内网 172.30.0.2:8008）：

$ timeout 3 bash -c "echo > /dev/tcp/172.30.0.2/8008" && echo "grpc-port 8008 reachable"
grpc-port 8008 reachable

注意：v2 面板与 agent 通过 HTTP/2 复用同一端口，用 TCP 连通性检查即可，不必区分端口。

4.2 官方脚本与参数说明

下载官方安装脚本（来自 nezhahq/scripts 仓库 agent/install.sh）：

$ curl -L https://raw.githubusercontent.com/nezhahq/scripts/main/agent/install.sh -o agent.sh
$ chmod +x agent.sh

脚本通过环境变量传参，执行前设置：

环境变量	必填	说明
`NZ_SERVER`	是	dashboard 接入地址，`IP或域名:端口`，如 `172.30.0.2:8008`；启用 `NZ_TLS` 时为域名+443 形式
`NZ_TLS`	否	是否对 dashboard 使用 TLS（经反代+HTTPS 暴露时置 `true`），默认 `false`
`NZ_CLIENT_SECRET`	是	dashboard `config.yaml` 中的 `agent_secret_key`，agent 与面板的握手凭据
`NZ_VER`	否	指定 agent 版本（如 `v2.3.5`），缺省安装最新版

4.3 执行安装（完整输出照录）

$ export NZ_SERVER=172.30.0.2:8008 NZ_TLS=false NZ_CLIENT_SECRET=nX3qmk2cXMKuCY0SCO2N3g8bLdun25gF
$ ./agent.sh

实测完整输出：

> Install nezha-agent
[Info] nezha-agent v2.3.5 开始安装
[Info] 正在下载 nezha-agent-linux-amd64.zip
################################################################ 100.0%
[Info] 解压 nezha-agent-linux-amd64.zip
Archive:  nezha-agent.zip
  inflating: nezha-agent-linux-amd64
[Info] 配置 nezha-agent
[Info] 创建 systemd 服务
[Info] nezha-agent v2.3.5 安装成功
[Info] systemctl status nezha-agent 查看服务状态

脚本实际做了四件事：从 GitHub release 下载对应平台二进制包并解压到 /opt/nezha/agent/；将 NZ_SERVER/NZ_TLS/NZ_CLIENT_SECRET 写入 /opt/nezha/agent/config.yml；注册并启动 nezha-agent.service（systemd 托管）。

4.4 服务状态与版本（实测输出）

$ systemctl is-active nezha-agent
active
$ /opt/nezha/agent/nezha-agent -v
version: v2.3.5

4.5 agent 配置文件（照录）

/opt/nezha/agent/config.yml 安装后自动生成：

client_secret: nX3qmk2cXMKuCY0SCO2N3g8bLdun25gF
debug: false
disable_auto_update: false
disable_command_execute: false
disable_force_update: false
disable_nat: false
disable_send_query: false
gpu: false
insecure_tls: false
ip_report_period: 1800
report_delay: 3
self_update_period: 0
server: 172.30.0.2:8008
skip_connection_count: false
skip_procs_count: false
temperature: false
tls: false
use_atomgit_to_upgrade: false
use_gitee_to_upgrade: false
use_ipv6_country_code: false
uuid: 6186c917-4a13-722f-77be-9e9cc619d89e

关键项：server 与 tls 对应安装时的 NZ_SERVER/NZ_TLS；client_secret 对应 NZ_CLIENT_SECRET；uuid 是该 agent 的身份标识（迁移/重装时保持不变则 dashboard 中仍是同一台机器）；report_delay: 3 为上报间隔秒数。逐项调优见《Nezha v2.3.18 配置参数详解》。

4.6 接入验证（实测输出）

在 dashboard 管理界面「服务器」页应立即出现该机器；用 API 验证（照录）：

$ curl -s 'http://localhost:13903/api/v1/server?page=1&page_size=10' \
    -H "Authorization: Bearer $TOKEN"
{"success":true,"data":[
  {"id":1,"name":"nezha-agent-server","uuid":"6186c917-...","last_active":"2026-10-18T03:59:31Z",
   "state":{"cpu":11.2,"mem_used":9872609280,"disk_used":26735454208,
            "net_out_transfer":2237105,"net_in_transfer":1557834,...},
   "host":{"cpu_name":"Virtual CPU (12 vcores)","mem_total":33607307264,
           "os":"Ubuntu 22.04.5 LTS","kernel_version":"5.15.0-152-generic",...},
   "geo_ip":{"ip":"172.30.0.3","country_code":"AU",...}}]}

state 中 CPU/内存/磁盘/流量为实时真实值，last_active 持续刷新即说明心跳正常。

五、部署后必做三件事

立即修改默认口令：默认 admin/admin 人尽皆知，公网面板不改密等于裸奔（面板右上角 Profile → 修改密码）；
反代 + HTTPS：用 Nginx/Caddy 反代 8008 端口并配 TLS，反代需支持 WebSocket/HTTP/2 透传；agent 侧 NZ_TLS=true 重新接入；
记录 agent_secret_key：后续每台新机器装 agent 都要用它，泄露需在配置中更换。

六、参考链接

Dashboard 发行包（v2.3.18 下载核实）：https://github.com/nezhahq/nezha/releases
Agent 发行包（v2.3.5 与安装脚本核实）：https://github.com/nezhahq/agent/releases
站内延伸：《Nezha v2.3.18 配置参数详解》——dashboard config.yaml 与 agent config.yml 逐项说明，改值重启实测验证。