Nezha 管理后台帮助文档

本文档面向 Nezha 管理后台使用者，覆盖后台页面的主要功能、常见操作流程、字段说明和注意事项。管理后台默认入口为：

/dashboard

用户面板默认入口为：

/

1. 后台概览

Nezha 后台用于管理服务器监控、服务监控、告警通知、计划任务、DDNS、NAT、用户、在线会话、WAF 拦截记录和系统配置。

后台主要菜单包括：

2. 登录与账号

2.1 默认账号

首次运行后，如果数据库中没有用户，系统会自动创建默认管理员账号：

用户名：admin
密码：admin

首次登录后建议立即进入 个人信息 修改用户名和密码。

2.2 登录方式

进入 /dashboard/login 后可以使用：

• 用户名 + 密码登录
• 已配置的 OAuth2 登录，例如 GitHub

如果系统配置了 OAuth2 提供商，登录页会显示对应的 OAuth2 登录按钮。

2.3 退出登录

点击右上角头像，选择 Logout 即可退出当前账号。

3. 权限说明

后台存在普通用户和管理员两类角色。

管理员可以：

• 查看和管理全部服务器、服务、任务、通知、分组和配置
• 创建、删除用户
• 查看在线用户并封禁 IP
• 查看和解除 WAF 拦截
• 修改系统设置
• 重试服务器转移任务

普通用户可以：

• 查看自己有权限的服务器、服务、任务和分组
• 管理自己创建或拥有的资源
• 修改自己的个人资料
• 查看自己相关的服务器转移任务

注意：部分列表会按权限过滤。普通用户看不到无权限的服务器或服务。

4. 服务器管理

路径：

/dashboard

服务器页面展示所有已接入的 Agent。表格中主要字段包括：

4.1 添加服务器

服务器不是在后台手动创建，而是通过安装 Agent 接入。

操作步骤：

1. 进入 服务器 页面。
2. 点击右上角 Install Commands。
3. 选择目标系统：Linux、macOS 或 Windows。
4. 系统会复制安装命令到剪贴板。
5. 到目标服务器执行该命令。
6. Agent 成功连接后，会自动出现在服务器列表中。

安装命令依赖系统设置中的：

• install_host：Dashboard 原始连接地址
• tls：是否使用 TLS
• 当前用户的 agent_secret

如果复制命令时报 InstallHostRequired 或 AgentSecretRequired，先检查系统设置和当前账号信息。

4.2 编辑服务器

点击服务器行右侧编辑按钮，可以修改：

公开备注支持两种模式：

• Custom Fields：通过表单填写套餐、流量、账单周期、IP 类型等结构化信息
• Raw Text：直接填写文本或 JSON

结构化公开备注适合在用户面板展示服务器套餐、到期时间、流量规格等信息。

4.3 终端

服务器行右侧更多菜单中选择 Terminal，会打开：

/dashboard/terminal/:id

功能：

• 通过 WebSocket 连接 Agent 终端
• 支持全屏
• 终端会话关闭后显示 Session completed

注意：

• 服务器必须在线
• Agent 需要允许远程命令执行
• 如果服务器不存在或未连接，会提示服务器不可用

4.4 文件管理器

在终端页面右上角点击文件夹按钮，可打开文件管理器。

文件管理器支持：

• 查看当前目录文件和文件夹
• 点击文件夹进入子目录
• 刷新目录
• 复制当前路径
• 跳转到指定路径
• 下载文件
• 上传文件

注意：

• 文件管理器依赖 Agent 在线连接
• 上传和下载通过 WebSocket 传输
• 大文件会分块传输

4.5 Agent 配置

服务器行右侧更多菜单中选择 Config，可以读取和修改单台 Agent 配置。

可配置项包括：

提交后，后台会把配置下发到目标服务器。返回结果会区分：

• Success：下发成功
• Failure：下发失败
• Offline：服务器离线

4.6 批量修改 Agent 配置

勾选多个服务器后，点击顶部配置按钮可以批量下发配置。

操作方式：

1. 勾选服务器。
2. 点击批量配置按钮。
3. 输入配置项名称，例如 disable_command_execute。
4. 输入配置值，例如 true。
5. 添加到待提交配置。
6. 点击提交。

适合批量开启或关闭 Agent 功能。

4.7 强制更新 Agent

勾选一个或多个服务器后，点击顶部更新按钮，可以向在线 Agent 下发强制更新任务。

注意：

• 离线服务器不会执行
• 如果 Agent 禁用了强制更新，会返回失败
• 普通用户只能操作自己有权限的服务器

4.8 批量转移服务器

勾选服务器后，点击批量转移按钮，可以将服务器归属转移给其他用户。

转移任务会进入 转移 页面跟踪状态。可能出现：

• 已提交等待确认
• 已完成
• 失败
• 超时
• 已取消

4.9 删除服务器

勾选服务器后点击删除按钮，或在单行操作中删除。删除后该服务器记录会从后台移除。

建议仅在确认 Agent 不再使用时删除。

5. 服务监控

路径：

/dashboard/service

服务监控用于定期检测 HTTP、TCP、Ping 等目标是否可用，并可触发通知和任务。

列表字段包括：

5.1 创建服务监控

操作步骤：

1. 进入 服务 页面。
2. 点击右上角新增按钮。
3. 填写名称、目标、类型、检测间隔等信息。
4. 选择覆盖范围和服务器。
5. 根据需要选择通知分组。
6. 点击提交。

主要字段：

Target 示例：

HTTP：https://example.com
Ping：example.com
TCP：example.com:443

5.2 编辑和删除服务监控

• 点击单行编辑按钮修改服务监控。
• 勾选多行后点击删除按钮批量删除。
• 删除后相关历史展示可能不再关联到该监控项。

6. 计划任务

路径：

/dashboard/cron

计划任务用于在指定服务器上按 Cron 表达式执行任务，也可以手动触发。

列表字段包括：

6.1 创建任务

操作步骤：

1. 进入 任务 页面。
2. 点击新增按钮。
3. 填写任务名称。
4. 选择任务类型。
5. 填写 Cron 表达式。
6. 填写命令。
7. 选择覆盖范围和服务器。
8. 选择通知分组。
9. 按需开启成功通知。
10. 提交保存。

Cron 表达式示例：

0 0 3 * * *

表示每天凌晨 3 点执行。

6.2 手动执行任务

任务列表每行有播放按钮，点击后立即触发该任务。

注意：

• 手动执行仍受服务器在线状态、权限和 Agent 配置影响。
• 如果 Agent 禁用了命令执行，任务可能失败。

6.3 任务触发联动

服务监控和告警规则中可以填写：

• TasksToTriggerOnAlert
• TasksToTriggerAfterRecovery

填写计划任务 ID 后，告警或恢复时会触发对应任务。

多个任务 ID 使用英文逗号分隔：

1,2,3

7. 通知通道

路径：

/dashboard/notification

通知通道用于配置告警消息发送目标，例如 Webhook、消息机器人或其他通知服务。

列表字段包括：

7.1 创建通知通道

操作步骤：

1. 进入 通知 页面。
2. 确保当前在 Notifier 标签。
3. 点击新增按钮。
4. 填写名称和通知 URL。
5. 根据需要设置 TLS 校验、测试消息等选项。
6. 保存。

建议先创建通知通道，再创建通知分组和告警规则。

通知通道常见字段如下：

Request Body 支持模板变量，常见变量包括：

#NEZHA#
#SERVER.NAME#
#SERVER.IP#
#SERVER.IPV4#
#SERVER.IPV6#
#SERVER.CPU#
#SERVER.MEM#
#SERVER.SWAP#
#SERVER.DISK#
#SERVER.NETINSPEED#
#SERVER.NETOUTSPEED#
#SERVER.TRANSFERIN#
#SERVER.TRANSFEROUT#
#SERVER.LOAD1#
#SERVER.LOAD5#
#SERVER.LOAD15#
#SERVER.TCPCONNCOUNT#
#SERVER.UDPCONNCOUNT#

如果通知平台要求自定义 JSON、Header 或请求方法，可以直接在这里调整。

7.2 通知 URL

通知 URL 通常由目标通知平台提供。请按对应平台要求填写完整地址和参数。

如果通知发送失败，优先检查：

• URL 是否正确
• 网络是否可达
• TLS 证书是否可信
• 通知平台 Token 是否有效

8. 告警规则

路径：

/dashboard/alert-rule

告警规则用于根据服务器指标触发通知和任务。

支持的规则类型包括：

8.1 创建告警规则

操作步骤：

1. 进入 通知 菜单。
2. 切换到 AlertRule 标签。
3. 点击新增按钮。
4. 填写规则名称。
5. 添加一个或多个规则项。
6. 选择通知分组。
7. 设置触发模式。
8. 可选填写告警和恢复时触发的任务 ID。
9. 勾选启用。
10. 提交保存。

8.2 规则项字段

示例规则 JSON：

[
  {
    "type": "cpu",
    "max": 90,
    "duration": 10,
    "cover": 0
  }
]

周期流量示例：

[
  {
    "type": "transfer_all_cycle",
    "max": 1073741824000,
    "duration": 10,
    "cover": 0,
    "cycle_start": "2026-01-01T00:00:00+08:00",
    "cycle_interval": 1,
    "cycle_unit": "month"
  }
]

8.3 高级 JSON

告警规则页面同时提供结构化编辑器和 AdvancedJSON。如果结构化编辑无法满足需求，可以直接编辑 JSON。

注意：

• JSON 必须是数组。
• 字段名必须与后端规则字段一致。
• 无效 JSON 无法提交。

9. DDNS

路径：

/dashboard/ddns

DDNS 用于把服务器上报 IP 自动同步到 DNS 解析记录。

列表字段包括：

9.1 创建 DDNS 配置

操作步骤：

1. 进入 DDNS 页面。
2. 点击新增按钮。
3. 填写名称。
4. 选择 Provider。
5. 填写域名，多个域名用英文逗号分隔。
6. 填写凭据。
7. 设置最大重试次数。
8. 按需启用 IPv4 和 IPv6。
9. 保存。

9.2 Provider 凭据

不同 Provider 需要的凭据不同。后台提供两个通用凭据字段：

• Credential 1
• Credential 2

通常对应 Token ID、Access Key、Secret Key 等。

9.3 Webhook DDNS

如果使用 Webhook 类型 DDNS，可以配置：

Webhook 模板可使用变量，例如：

{
  "ip": "#ip#",
  "domain": "#domain#"
}

9.4 在服务器中启用 DDNS

DDNS 配置创建后，还需要到服务器编辑页：

1. 开启 EnableDDNS。
2. 在 DDNSProfiles 中填写 DDNS 配置 ID。
3. 保存。

10. NAT

路径：

/dashboard/nat

NAT 用于通过 Dashboard 暴露 Agent 所在内网中的服务。

列表字段包括：

10.1 创建 NAT

操作步骤：

1. 进入 NAT 页面。
2. 点击新增按钮。
3. 填写名称。
4. 填写服务器 ID。
5. 填写本地服务地址，例如 192.168.1.1:80。
6. 填写绑定域名，例如 router.example.com。
7. 勾选启用。
8. 保存。

注意：

• 绑定域名需要解析到 Dashboard 所在服务器。
• Agent 必须在线。
• 如果 Agent 配置禁用了 NAT，该功能不可用。

11. 分组管理

路径：

/dashboard/server-group

服务器分组用于组织服务器列表，也会影响用户面板展示。

11.1 服务器分组

操作步骤：

1. 进入 分组 页面。
2. 确认当前在 Server 标签。
3. 点击新增按钮。
4. 填写分组名称。
5. 选择服务器。
6. 保存。

列表字段：

11.2 通知分组

路径：

/dashboard/notification-group

通知分组用于把多个通知通道组合起来，供服务监控、告警规则、任务等引用。

操作步骤：

1. 进入 分组 页面。
2. 切换到 Notification 标签。
3. 点击新增按钮。
4. 填写分组名称。
5. 选择通知通道。
6. 保存。

列表字段：

12. 服务器转移

路径：

/dashboard/transfer

服务器转移页面用于查看服务器归属变更任务。

列表字段包括：

状态包括：

• Pending：等待处理
• Verified：已验证完成
• Failed：失败
• Timeout：超时
• Cancelled：已取消

12.1 取消转移

当状态为 Pending 时：

• 管理员可以取消任意待处理转移。
• 普通用户只能取消自己作为转出方的待处理转移。

12.2 重试转移

当状态为 Failed、Timeout 或 Cancelled 时：

• 仅管理员可以重试。

页面会通过 WebSocket 实时接收转移状态更新，并在断线后自动重连。

13. 个人信息

路径：

/dashboard/profile

个人信息页展示：

• 当前用户名
• 登录 IP
• 账号拥有的服务器数量
• 服务器分组数量
• OAuth2 绑定状态

13.1 修改个人资料

点击 UpdateProfile 可以修改：

注意：

• 原密码长度要求 5 到 72。
• 新密码长度要求 8 到 72。
• 开启 RejectPassword 前，请确认已经绑定可用的 OAuth2 登录方式，否则可能无法登录。

13.2 OAuth2 绑定

如果系统配置了 OAuth2 提供商，个人信息页会显示绑定区域。

操作：

• 点击 Bind 绑定账号。
• 点击 Unbind 解绑账号。

14. 系统设置

路径：

/dashboard/settings

系统设置仅管理员可访问。

可配置项包括：

14.1 站点名称和语言

SiteName 会影响页面标题和用户面板显示。

Language 会影响后台默认语言。如果用户本地已经选择语言，本地设置可能优先生效。

14.2 用户面板主题

Theme 用于选择用户面板模板。系统会列出可用模板，并标识：

• Official：官方模板
• Community：社区模板

社区模板可能存在兼容性或安全风险，启用前应确认来源可信。

14.3 自定义代码

CustomCodes 注入用户面板。

CustomCodesDashboard 注入管理后台。

可以用于添加统计脚本、自定义样式或扩展脚本。

注意：

• 自定义代码会在页面加载时执行。
• 不要粘贴不可信脚本。
• 错误脚本可能导致页面异常。

14.4 DashboardOriginalHost

该字段用于生成 Agent 安装命令。

示例：

example.com:8008

如果启用了 TLS，通常使用 HTTPS/WSS 对应地址。

14.5 真实 IP 设置

WebRealIPHeader 和 AgentRealIPHeader 用于在反向代理后获取真实 IP。

常见值：

CF-Connecting-IP
X-Forwarded-For
X-Real-IP

如果勾选 UseDirectConnectingIP，会使用直连 IP，不读取代理头。

14.6 IP 变更通知

IP 变更通知用于服务器 IP 变化时发送告警。

字段说明：

15. 用户管理

路径：

/dashboard/settings/user

用户管理仅管理员可访问。

列表字段包括：

15.1 创建用户

操作步骤：

1. 进入 设置。
2. 切换到 User 标签。
3. 点击新增按钮。
4. 填写用户名。
5. 填写密码。
6. 选择角色。
7. 保存。

角色说明：

• Admin：管理员
• User：普通用户

15.2 删除用户

勾选用户后点击删除按钮，或在单行操作中删除。

注意：

• 删除用户可能影响其拥有的服务器和资源归属。
• 删除前应先确认服务器是否需要转移给其他用户。

16. 在线用户

路径：

/dashboard/settings/online-user

在线用户页面展示当前在线会话。

列表字段包括：

16.1 封禁在线用户

管理员可以：

• 单行封禁指定 IP
• 勾选多行批量封禁 IP

封禁后，对应 IP 会进入 WAF 拦截记录。

普通用户不可执行封禁操作。

17. WAF

路径：

/dashboard/settings/waf

WAF 页面展示被系统拦截的 IP。

列表字段包括：

17.1 解除拦截

管理员可以：

• 单行删除 WAF 记录
• 勾选多行批量删除 WAF 记录

删除记录后，对应 IP 不再因该 WAF 记录被拦截。

18. 顶栏和通用操作

18.1 返回首页

顶栏中的 BackToHome 会返回用户面板 /。

18.2 主题切换

顶栏中的主题按钮可切换：

• 浅色
• 深色
• 跟随系统

18.3 头像菜单

点击头像可进入：

• Profile：个人信息
• Settings：系统设置，管理员可见
• Logout：退出登录

18.4 表格通用操作

多数后台表格都有：

• 勾选框：选择单行或多行
• 新增按钮：创建资源
• 编辑按钮：修改资源
• 删除按钮：删除单行或批量删除
• 复制按钮：复制 ID、URL、命令或 JSON

19. 推荐配置流程

19.1 首次部署后

建议按以下顺序配置：

1. 登录默认管理员账号。
2. 进入 个人信息 修改用户名和密码。
3. 进入 设置 配置 SiteName、DashboardOriginalHost 和 ConfigTLS。
4. 返回 服务器 页面复制 Agent 安装命令。
5. 在目标服务器安装 Agent。
6. 创建服务器分组。
7. 创建通知通道。
8. 创建通知分组。
9. 创建服务监控。
10. 创建告警规则。

19.2 配置告警通知

推荐流程：

1. 在 通知 页面创建通知通道。
2. 在 分组 -> Notification 创建通知分组。
3. 在 告警规则 创建告警规则并选择通知分组。
4. 如需服务状态监控，在 服务 中创建监控并选择通知分组。

19.3 配置 DDNS

推荐流程：

1. 在 DDNS 页面创建 DDNS 配置。
2. 在 服务器 页面编辑目标服务器。
3. 开启 EnableDDNS。
4. 填写 DDNSProfiles。
5. 保存并等待下一次 IP 上报或 DDNS 更新。

19.4 配置 NAT

推荐流程：

1. 确保目标 Agent 在线。
2. 确保 Agent 未禁用 NAT。
3. 为绑定域名添加 DNS 解析到 Dashboard。
4. 在 NAT 页面创建 NAT 配置。
5. 启用 NAT 配置。
6. 通过绑定域名访问内网服务。

20. 常见问题

20.1 安装命令无法复制

检查：

• 设置 -> DashboardOriginalHost 是否为空
• 当前账号是否有 agent_secret
• 浏览器是否允许剪贴板权限

20.2 Agent 接入后不显示

检查：

• Agent 是否运行成功
• NZ_SERVER 是否指向正确 Dashboard
• NZ_CLIENT_SECRET 是否正确
• Dashboard 端口是否开放
• 如果启用 TLS，NZ_TLS 是否与实际访问协议一致

20.3 终端打不开

检查：

• 服务器是否在线
• Agent 是否允许命令执行
• 浏览器控制台是否有 WebSocket 错误
• 反向代理是否支持 WebSocket

20.4 文件管理器无法上传或下载

检查：

• 服务器是否在线
• 目标路径是否有权限
• 反向代理是否支持 WebSocket
• 浏览器是否阻止下载

20.5 通知没有发送

检查：

• 通知通道 URL 是否正确
• 通知分组是否包含该通知通道
• 告警规则或服务监控是否引用了正确的通知分组
• TLS 校验是否导致失败
• 目标通知平台是否限制频率或 Token 已失效

20.6 DDNS 不更新

检查：

• DDNS 配置是否启用 IPv4 或 IPv6
• 域名是否填写正确
• Provider 凭据是否正确
• 服务器是否开启 EnableDDNS
• 服务器是否关联正确的 DDNS 配置 ID
• 自定义 DNS 是否可用

20.7 NAT 访问失败

检查：

• 绑定域名是否解析到 Dashboard
• NAT 配置是否启用
• Server ID 是否正确
• 本地服务地址是否能被 Agent 访问
• Agent 是否在线
• Agent 配置是否禁用了 NAT

20.8 普通用户看不到某些资源

这是权限过滤结果。普通用户只能看到自己有权限的服务器、服务、分组和相关记录。需要管理员确认资源归属或权限设置。

21. 安全建议

• 首次登录后立即修改默认密码。
• 不要将 agent_secret 泄露给不可信人员。
• 只给必要人员管理员权限。
• 启用反向代理时正确配置真实 IP 请求头。
• 自定义代码只使用可信来源。
• 谨慎开启远程终端和文件管理能力。
• 对公开访问的 Dashboard 建议启用 HTTPS。
• 使用 WAF 和在线用户页面定期检查异常访问。