Hiddify Next 是一款开源的多平台通用代理客户端，旨在帮助用户在受互联网审查的地区自由访问网络服务。它基于 Sing-Box 构建，支持超过 20 种协议，兼容 Android、iOS、Windows、macOS 和 Linux 等操作系统。Hiddify Next 最近更名为 HiddifyApp 了，本文中 Hiddify Next 和 HiddifyApp 会交替使用，他们所指的都是同一个软件。

本教程详细讲解了如何在 debian 系列和 redhat 系列 Linux 操作系统上安装并配置 v2rayA 这款科学上网、魔法上网软件。

本教程详细讲解了如何在 Windows 操作系统上安装并配置 v2rayA 这款科学上网软件。

1. 前言

v2rayN 是 Windows 平台上一款基于 v2ray 核心的简洁好用、功能强大的 v2ray 客户端，用于科学上网和保护用户隐私。支持 Vmess、Socks5、VLESS、Trojan、Hysteria2、Shadowsocks（不支持 ssr）等多种协议，也支持服务器订阅，支持规则分流。对于新手们来说使用非常的方便快捷，在本篇教程我们教大家如何配置使用 v2rayN，来快速实现代理上网的功能。

v2rayNG 是一款专为 Android 设计的 V2Ray 客户端应用程序，它提供了一个简洁易用的图形用户界面，使用户能够方便地在移动设备上配置和使用V2Ray代理服务。
支持多种传输协议和网络协议，包括 VMess、VLESS、Shadowsocks、Socks 等，能够帮助用户绕过网络封锁，保护隐私和安全，提升网络访问体验。用户可以根据自己的需求选择合适的协议和代理方式来进行网络代理。适用于安卓手机及支持部分基于安卓系统的电视（TV）或者电视盒子。

本文将详细讲述如何在 Android 系统上快速安装、配置和使用 v2rayNG 这款科学上网应用。

Hiddify Next 是一款开源的多平台通用代理客户端，旨在帮助用户在受互联网审查的地区自由访问网络服务。它基于 Sing-Box 构建，支持超过 20 种协议，兼容 Android、iOS、Windows、macOS 和 Linux 等操作系统。Hiddify Next 最近更名为 HiddifyApp 了，本文中 Hiddify Next 和 HiddifyApp 会交替使用，他们所指的都是同一个软件。本文主要讲述如何在 MacOS 操作系统上安装并配置HiddifyApp。

Hiddify Next 是一款开源的多平台通用代理客户端，旨在帮助用户在受互联网审查的地区自由访问网络服务。它基于 Sing-Box 构建，支持超过 20 种协议，兼容 Android、iOS、Windows、macOS 和 Linux 等操作系统。Hiddify Next 最近更名为 HiddifyApp 了，本文中 Hiddify Next 和 HiddifyApp 会交替使用，他们所指的都是同一个软件。本文主要讲述如何在 Linux 操作系统上安装并配置HiddifyApp。

Hiddify Next 是一款开源的多平台通用代理客户端，旨在帮助用户在受互联网审查的地区自由访问网络服务。它基于 Sing-Box 构建，支持超过 20 种协议，兼容 Android、iOS、Windows、macOS 和 Linux 等操作系统。Hiddify Next 最近更名为 HiddifyApp 了，本文中 Hiddify Next 和 HiddifyApp 会交替使用，他们所指的都是同一个软件。本文是 HiddifyApp 系列教程之一，重点讲述如何在 Windows 上安装 HiddifyApp。

根据 Github 影响力,是否在积极维护以及实际使用体验筛选出 16 款精致的 Hexo 主题。欢迎评论区留言，告诉大家你最喜欢的主题。

1. 前言

关于如何对 Tauri 项目进行打包和发布, 在 Tauri 的官方网站实际上只做了基本的介绍. 而且由于 Tauri 或者说是 Rust 对跨平台编译以及打包支持得不是很好.

所以到底如何在 Github.com 以外得平台进行编译打包, 讲得不够详细. 本人希望搜索到能对这方面有所补充的博客文章, 但是也没有找到. 包括一些英文方面的资料以及视频教程都不理想。 网上关于 Tauri 的 devops 自动化编译打包部署方面都是照本宣科, 按照官方的介绍使用 github action 进行配置. 而这些内容对于企业开发或者非开源项目来说帮助非常有限.

1. 第一章: Rust 简介

1.1. 为什么要用 Rust

Rust 是一种令人兴奋的新编程语言, 它可以让每一个人编写可靠且高效的软件.
它可以用来替换 C/C++, Rust 和他们具有同样的性能, 但是很多常见的 bug 在编译时就可以被消灭.
Rust 是一种通用的编程语言, 但是它更善于以下场景:
需要运行时的速度
需要内存安全
更好的利用多处理器

VMess 协议是由 V2Ray （科学上网软件）创立并使用于 V2Ray 的加密传输协议，如同 Shadowsocks 一样为了对抗审查的深度包检测而研发的。在 V2Ray 上客户端与服务器的通信主要是通过 VMess 协议通信。

本文中采用Vultr VPS，一款性能优越、配置的VPS, 其拥有广泛的数据中心分布、丰富的功能和便捷的支付方式，成为众多用户的首选。无论是个人学习、小型项目还是大型企业应用，Vultr VPS 都能提供稳定可靠的服务支持。

拥有一台Vultr VPS可以做很多事情，例如：

• Vultr + Code-server 自建 Cloud IDE
• Vultr 部署 Wordpress 博客
• Vultr 上快速搭建 kubernetes 集群

更多玩法等待您来解锁。

本文主要讲解在 Vultr VPS上，如何使用自动化脚本和手动两种方式，安装并配置一台 v2ray 服务器（也称为 vmess server）。以及如何通过v2rayA, v2rayN, v2RayNG连接 v2ray 服务器并访问google和chatGPT。

1.1 Docker Compose 是什么？

Docker Compose 是用于定义和运行多容器 Docker 应用的工具。它通过一个声明式的 YAML 文件（通常命名为 compose.yaml 或 docker-compose.yml），描述应用由哪些服务（services）、网络（networks）、卷（volumes）等组成，然后用一条命令即可创建、启动、停止或销毁整套环境。

它本身并不替代 Docker Engine，而是构建在 Docker Engine 之上，负责编排多个容器之间的依赖、网络连通性和生命周期管理。对于单机开发、测试和轻量运维场景，Compose 是最常见的多容器管理方式。

更完整的背景可参考官方文档：History and development of Docker Compose。

Docker 是现代软件开发和运维中不可或缺的工具之一。它通过容器化技术，为开发者和运维人员提供了一个轻量级、高效且灵活的解决方案。无论是构建、测试还是部署应用程序，Docker 都能显著简化流程并提升效率。在本篇文章中，我们将详细介绍如何在 RHEL 系列 系统上安装和配置 Docker，帮助您快速上手并充分利用其强大的功能。

一、前言

如果你同时管理着几台、十几台甚至更多 VPS，最头疼的往往不是“机器挂了”，而是“挂了却不知道”。打开一堆终端、一个个 htop 或 uptime，效率低下；等到发现某个站点打不开，可能已经过去好几个小时。有没有一个轻量、集中的方式，把所有服务器的状态、流量、可用性都放在一个页面里看？这就是哪吒监控（Nezha）要解决的问题。

1.1 Nezha 是什么

Nezha（哪吒监控）是一个轻量的服务器与服务监控工具。它由两部分组成：面板（Dashboard）负责展示数据、管理节点和发送告警；Agent 安装在被监控的机器上，负责采集系统信息并上报。整体设计简洁，部署门槛不高，适合个人站长和运维新手使用。

1.2 v2 版本的主要特点

v2 是一次较大的重构版本，与 v1 在架构和通信方式上都有明显变化。主要特点包括：

• 整体架构重构，面板与 Agent 的职责划分更清晰。
• 面板与 Agent 之间改用 gRPC 通信，后续配置反向代理时需要注意对 gRPC 的支持（具体写法后文会讲）。
• 界面和交互有所改进，日常查看状态更顺手。
• 功能上对告警、服务探测等能力做了调整与增强。
• 安装与配置流程相对 v1 有所简化，但与 v1 不兼容。

需要特别提醒：v2 与 v1 不能原地升级。已有 v1 环境的读者，请先阅读本教程中关于迁移的章节，再决定如何处理旧数据与旧节点。

1.3 适用场景

• 多台 VPS 需要统一查看 CPU、内存、磁盘、流量等基础状态。
• 希望对 HTTP/HTTPS 服务做简单可用性探测。
• 需要在服务器离线或关键指标异常时及时收到通知。
• 个人或小团队希望用一套轻量工具完成基础运维监控，而不想引入过重的监控体系。

1.4 本文将完成什么

本教程将按以下顺序带你完成一次完整部署：

1. 部署 Nezha v2 面板
2. 配置反向代理与 HTTPS
3. 在被监控机器上安装 Agent
4. 配置通知与告警

1.5 阅读提示

本文测试环境为：Debian 12 / Nezha v2.x.x / 测试时间 2026-10（具体版本号与官方文档为准）。文中出现的 your.domain.com、your-email@example.com 等均为占位符，请替换为你自己的域名和邮箱。命令与配置以实际环境为准，遇到差异时请优先参考官方文档。

接下来我们先从准备工作开始。

二、准备工作

正式动手前，先把环境和前置条件理顺。准备得越扎实，后面安装、反代、上线 Agent 就越少踩坑。本章只做准备工作，不涉及具体安装命令。

2.1 环境要求

面板服务器

面板（Dashboard）需要一台能从公网访问的服务器。推荐使用较新的稳定发行版，例如 Debian 12 或 Ubuntu 22.04 LTS。内存与磁盘没有特别严苛的硬性门槛，普通轻量 VPS 即可满足个人或少量节点的使用，具体建议以官方文档（nezha.wiki）为准。

必须具备公网 IP，否则外部无法访问面板，Agent 也无法正常上报。若服务器在内网或仅有私有 IP，需要额外做端口映射或隧道，本教程默认你使用带公网 IP 的 VPS。

被监控机器（Agent 端）

Agent 支持在多种系统和架构上运行。官方文档覆盖的主要平台如下（以实际发布和支持情况为准）：

更多特殊环境（如 OpenWrt、群晖等）可参考官方文档的对应章节。架构与系统支持列表以 nezha.wiki 最新说明为准。

典型拓扑

面板和 Agent 不必在同一台机器上。常见做法是：

• 一台专门的 VPS 跑面板（带域名、反向代理和 HTTPS）
• 其他需要监控的 VPS / 机器只安装 Agent，向面板上报数据

也可以把面板和一台 Agent 装在同一台机器上，适合节点很少的情况。

2.2 域名准备与 DNS 解析

虽然可以直接用 IP + 端口访问面板，但强烈建议使用域名，原因很简单：

• 方便配置 HTTPS（证书通常按域名签发）
• 反向代理时更清晰
• 以后更换服务器 IP 时，只需改 DNS，已安装的 Agent 不用批量改配置

在域名服务商处添加一条 A 记录（IPv4）或 AAAA 记录（IPv6），指向你的面板服务器公网 IP。示例：

• 主机记录：dashboard（或你喜欢的子域名）
• 记录类型：A
• 记录值：your_server_ip

最终完整域名形如 dashboard.your.domain.com。

添加后等待生效，可用以下命令验证：

1
2
3

ping dashboard.your.domain.com
# 或
dig +short dashboard.your.domain.com

预期结果是解析到你填写的服务器 IP。若长时间不生效，检查是否有本地 DNS 缓存，或换一个公共 DNS（如 1.1.1.1）再试。

提示：解析刚改完时，不同地区生效时间可能不一致，耐心等几分钟到十几分钟再继续。

2.3 端口规划与防火墙

哪吒 v2 面板默认将 Web 访问与 Agent 通信放在同一端口上（官方文档中的默认值为 8008，具体以你安装时选择或官方最新说明为准）。反向代理后通常只对外暴露 80/443。

建议关注的端口如下：

放行示例（按你实际使用的防火墙工具选择）：

ufw（Debian/Ubuntu 常见）：

1
2
3
4
5
6
7

sudo ufw allow 22/tcp          # SSH，按实际端口修改
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8008/tcp        # 若暂时直连面板端口，按实际端口修改
sudo ufw enable
sudo ufw reload
sudo ufw status

firewalld（部分 CentOS/RHEL 系）：

1
2
3
4
5

sudo firewall-cmd --permanent --add-port=22/tcp
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=8008/tcp   # 按实际端口修改
sudo firewall-cmd --reload

注意：云服务商控制台的安全组 / 防火墙规则也必须同步放行对应端口，否则系统防火墙开了，外面仍然进不来。这是最常见的踩坑点之一。

2.4 是否使用 Cloudflare / CDN

v2 面板与 Agent 通过 gRPC 通信。CDN（尤其是 Cloudflare 的代理模式）对 gRPC 和长连接的支持并不总是开箱即用，容易导致 Agent 上线异常或数据上报不稳定。

给新手的建议：

• 第一次部署时，先把域名设为 仅 DNS 解析（灰云），不开启代理。
• 确认面板能正常访问、Agent 能稳定上线后，再考虑是否启用 CDN 以及如何正确配置 gRPC 相关规则。
• 详细的反向代理与 CDN 配置会在第四章展开。

如果暂时只用 IP 访问也可以，但后续申请证书和更换服务器会麻烦一些，仍建议尽早准备域名。

2.5 准备清单（Checklist）

进入下一章前，请确认以下事项都已完成：

• 面板服务器已准备好，有公网 IP，系统为较新的 Debian / Ubuntu 等
• 域名已添加 A/AAAA 记录，指向面板服务器 IP
• 用 ping 或 dig 验证解析正确
• 系统防火墙已放行必要端口
• 云服务商安全组已同步放行对应端口
• （可选）决定是否暂时关闭 CDN 代理，仅使用 DNS 解析

三、安装面板

准备工作完成后，就可以开始安装哪吒监控的面板（Dashboard）了。本章只覆盖面板本身的安装与验证，反向代理、HTTPS 和 Agent 安装会放到后面章节。

3.1 安装方式选择

目前常见有两种安装方式，可根据自己的使用习惯选择：

建议：第一次接触哪吒的读者优先用官方一键脚本, ；已经习惯用 Docker 管理服务的，可以选择 Docker 方式。

3.2 方式一：官方一键脚本安装

安装前检查

确认当前用户有 root 权限（或可使用 sudo），并确保 curl 或 wget 可用以及 unzip 可用：

1
2
3
4
5
6
7
8

whoami
# 预期输出 root，或后续命令前加 sudo

curl --version
# 或
wget --version

unzip --version

执行安装

官方安装命令请以 nezha.wiki - 安装 Dashboard 当前文档为准。通用形式如下：

1

curl -L https://raw.githubusercontent.com/nezhahq/scripts/refs/heads/main/install.sh -o nezha.sh && chmod +x nezha.sh && sudo ./nezha.sh

若服务器位于中国大陆，官方通常会提供镜像地址，可按文档说明加上对应环境变量后执行（具体命令以官方页面为准）。

脚本运行后会进入交互菜单，常见选项含义与建议如下（实际提示可能随版本略有调整，以屏幕显示为准）：

输入完成后，脚本会拉取镜像或下载二进制并启动服务。安装成功后，终端一般会提示可通过 http://你的IP:端口 访问。

是否希望通过 TLS 连接 Agent，这个选项决定生成的 Agent 安装命令里是否启用 TLS（加密通信）

• 选 Y：Agent 会通过 TLS 连接面板（对应配置里的 tls: true）。适用于面板前面已经有 HTTPS 反向代理、或使用 CDN 终结 TLS 的情况。
• 选 N：明文连接（tls: false）。适用于直接用 IP:端口 或还没上 HTTPS 的情况
• 安装面板时建议直接选 N, 因为现在还只是临时用 IP + 端口访问，还没配域名和 HTTPS。选错了会导致后面 Agent 连不上。以后随时可以在面板「系统设置」里改。

注意：

• 安装过程需要 root 权限。端口请与第二章防火墙、安全组规划保持一致，避免装完却访问不了。
• 端口默认常见为 8008

3.3 方式二：Docker / Docker Compose 部署

前置条件

先确认 Docker 与 Compose 已安装，安装过程可参考安装并配置docker-compose：

安装完成后检查docker 和 docker compose:

1
2

docker --version
docker compose version

能正常输出版本号即可。

示例 Compose 框架

官方一键脚本内部也会生成 Compose 文件。若你希望手动管理，可参考以下框架（镜像名、版本标签、端口与路径均请以官方文档为准，以下为示意）：

1
2
3
4
5
6
7
8
9
10
11
12
13

# docker-compose.yml 示例框架【待核实具体镜像与路径】
services:
  dashboard:
    # image: ghcr.io/nezhahq/nezha            # 使用最新版本
    image: ghcr.io/nezhahq/nezha:<版本标签>   # 使用指定版本
    container_name: nezha-dashboard
    restart: always
    ports:
      - "8008:8008"                 # 主机端口:容器端口，按实际修改
    volumes:
      - ./data:/dashboard/data      # 数据目录，务必持久化
    # 其他配置项以官方示例为准

数据目录（如 ./data 或官方默认的 /opt/nezha/dashboard/data）非常重要，后续备份、升级都依赖它，请务必挂载到宿主机持久化位置。
如果不了解 如何配置 nezha docker compose 文件，可以使用官方脚本以docker compose安装一次然后查看官方配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

$ docker compose ls
NAME                STATUS              CONFIG FILES
dashboard           running(1)          /opt/nezha/dashboard/docker-compose.yaml

$ cat  /opt/nezha/dashboard/docker-compose.yaml
services:
  dashboard:
    image: ghcr.io/nezhahq/nezha
    container_name: nezha-dashboard
    restart: always
    volumes:
      - ./data:/dashboard/data
    ports:
      - 8008:8008

常用操作

1
2
3
4
5
6
7
8
9
10

# 启动
docker compose up -d

# 停止
docker compose down

# 查看日志
docker compose logs -f
# 或
docker logs -f nezha-dashboard

提示：手动维护 Compose 时，建议把文件和数据目录放在固定路径（如 /opt/nezha/dashboard），方便以后升级和备份。

3.4 检查服务是否正常运行

查看服务状态

一键脚本（独立安装方式）：

1
2

systemctl status nezha-dashboard
# 或官方脚本生成的具体服务名，以实际为准

预期：状态为 active (running)。

Docker 方式：

1

docker ps | grep nezha

预期：容器处于 Up 状态。

查看日志

1
2
3
4
5

# systemd
journalctl -u nezha-dashboard -f --no-pager

# Docker
docker logs -f nezha-dashboard

日志中不应出现持续报错或反复重启的信息。

检查端口监听

1
2
3

ss -tlnp | grep 8008
# 或
netstat -tlnp | grep 8008

预期：对应端口处于 LISTEN 状态。

3.5 首次访问面板

在尚未配置反向代理前，可通过 IP 临时访问：

1

http://your_server_ip:面板端口

后台管理路径一般为 /dashboard，完整地址示例：

1

http://your_server_ip:8008/dashboard

首次登录的默认账号密码，官方文档目前写明默认用户名和密码均为 admin。

登录成功后，请立刻修改默认密码：

1. 点击右上角头像
2. 进入个人信息 / 更新个人资料
3. 设置一个足够强的新密码（建议长度 ≥ 18，包含大小写、数字和符号）

注意：面板权限较高，默认弱密码非常危险。在公网环境下，务必第一时间改密，且不要把面板端口长期直接暴露在公网，后续应通过反向代理 + HTTPS 访问。

3.6 常见问题速查

• 端口被占用：安装时报端口已使用。用 ss -tlnp 查看占用进程，换一个端口或释放原端口。详细处理见第十章。
• 镜像拉取失败：网络问题或镜像源不可达。检查网络、尝试官方提供的国内镜像，或手动拉取后再启动。
• 服务启动后无法访问：防火墙/安全组未放行，或服务实际未监听。对照第二章检查端口与安全组，并查看日志。
• 页面能打开但登录异常：确认访问的是正确路径（通常含 /dashboard），并核对是否使用了最新默认凭据。

四、配置反向代理与 HTTPS

面板已经能通过 IP 临时访问，但生产环境更推荐用域名 + HTTPS。本章重点是把反向代理配好，让浏览器访问和 Agent 的 gRPC 通信都能正确转发。这一步最容易踩坑，请按顺序仔细操作。

4.1 为什么需要反向代理

反向代理主要解决三件事：

1. 域名访问：用 https://your.domain.com 代替 http://IP:端口，更规范也更安全。
2. HTTPS 加密：浏览器与面板之间的流量加密，避免明文传输。
3. gRPC 转发：v2 的面板与 Agent 通过 gRPC 通信，反向代理必须正确转发这类流量，否则 Agent 无法上线。

简单拓扑如下：

1
2
3
4
5
6
7

浏览器 / Agent
      │
      ▼
反向代理（监听 80/443）
      │
      ▼
本机面板（默认常见端口 8008）

Agent 最终连接的地址（域名或 IP + 端口）需要与你在面板里设置的「Agent 对接地址」保持一致。

4.2 方案选择

建议：想少折腾就选 Caddy；服务器上已经跑着 Nginx，或习惯用它的，继续用 Nginx 即可。

4.3 方案一：Nginx 反向代理

安装 Nginx 与申请证书

以常见方式为例（具体命令以你系统包管理器为准）：

1
2
3
4
5
6
7

# Debian / Ubuntu 示例
sudo apt update
sudo apt install -y nginx

# 使用 certbot 申请证书（需域名已解析且 80 端口可访问）
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your.domain.com

证书路径通常类似 /etc/letsencrypt/live/your.domain.com/fullchain.pem 和 privkey.pem。也可用 acme.sh，按官方文档操作即可。

注意：申请证书前请确认域名已正确解析到服务器，且防火墙/安全组已放行 80 端口。

完整配置示例

创建或编辑站点配置（路径因发行版而异，常见为 /etc/nginx/conf.d/nezha.conf）。以下示例基于官方文档结构，请把域名、证书路径、上游端口替换为你的实际值：

如果是 Debian或者 Ubuntu 在使用Certbot生成证书时，其会在/etc/nginx/sites-available/default 下生成一段默认配置，这个会影响我们真正需要为your.domain.com的设置，建议将这段配置删除。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

# 80 跳转 HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name your.domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    # Nginx > 1.25.1 时可改用：http2 on;

    server_name your.domain.com;

    ssl_certificate     /path/to/fullchain.pem;   # 替换为实际证书路径
    ssl_certificate_key /path/to/privkey.pem;     # 替换为实际私钥路径
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_session_timeout 1d;
    ssl_session_cache   shared:SSL:10m;
    ssl_stapling on;

    # 如使用 Cloudflare 等 CDN，可按官方文档开启 real_ip 相关配置
    # underscores_in_headers on;

    # gRPC 转发（关键！）
    location ^~ /proto.NezhaService/ {
        grpc_set_header Host $host;
        # 若 Nginx 是最外层，可用下面这行获取真实 IP
        # grpc_set_header nz-realip $remote_addr;
        grpc_read_timeout 600s;
        grpc_send_timeout 600s;
        grpc_socket_keepalive on;
        client_max_body_size 10m;
        grpc_buffer_size 4m;
        grpc_pass grpc://dashboard;
    }

    # WebSocket（终端、文件、实时数据等）
    location ~* ^/api/v1/ws/(server|terminal|file)(.*)$ {
        proxy_set_header Host $host;
        proxy_set_header Origin https://$host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_pass http://127.0.0.1:8008;
    }

    # 普通网页
    location / {
        proxy_set_header Host $host;
        # proxy_set_header X-Forwarded-Proto $scheme;  # 最外层时可开启
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size 256k;
        proxy_max_temp_file_size 0;
        proxy_pass http://127.0.0.1:8008;
    }
}

upstream dashboard {
    server 127.0.0.1:8008;   # 与面板实际监听端口一致
    keepalive 512;
}

关键说明：

• listen … http2：gRPC 依赖 HTTP/2，必须开启。
• location ^~ /proto.NezhaService/：官方定义的 gRPC 路径，使用 grpc_pass 转发。
• WebSocket location：保证终端、文件管理、实时状态更新正常。
• upstream：把请求转到本机面板端口。

提示：修改前先备份原配置。改完务必先检查再重载。

检查与重载

1

sudo nginx -t

• 预期输出类似：syntax is ok / test is successful。

注意：在Debian或者 Ubuntu操作系统下Certbot生成证书时在/etc/nginx/sites-available/default生成的一段配置对整体配置的影响。

重载nginx服务

1
2
3

sudo systemctl reload nginx
# 或
sudo nginx -s reload

4.4 方案二：Caddy 反向代理

Caddy 能自动申请并续期证书，配置更简洁。

安装

请按 Caddy 官方文档安装。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 安装所需的依赖软件包
# debian-keyring / debian-archive-keyring: Debian 官方密钥环,用于校验软件包签名
# apt-transport-https: 允许 apt 通过 HTTPS 访问软件源
# curl: 用于下载文件
sudo apt install --yes debian-keyring debian-archive-keyring apt-transport-https curl

# 导入 Caddy 软件源的 GPG 公钥
# 下载公钥后用 gpg --dearmor 转换为二进制格式,保存到系统密钥环目录
# (-1 强制使用 TLS 1.x;-s 静默模式;-L 跟随重定向;-f 请求失败时不输出错误页)
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

# 将 Caddy 软件源添加到 apt 的源列表中
# tee 会把下载到的源配置内容写入 /etc/apt/sources.list.d/caddy-stable.list
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# 给密钥文件和源列表文件添加"其他用户可读"权限(o+r)
# 否则 apt 在以非 root 的内部用户身份运行时,可能因权限不足而无法读取
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list

# 刷新软件包索引,使 apt 识别新添加的 Caddy 软件源
sudo apt update

# 安装 Caddy
sudo apt install caddy

安装完成后,Caddy 会自动注册为 systemd 服务,可以用 systemctl status caddy 查看运行状态。

安装完成后确认：

1
2
3
4
5
6
7

# 查看版本
caddy version

# 查看运行状态
systemctl status caddy

Caddyfile 示例

编辑 Caddyfile（常见路径 /etc/caddy/Caddyfile），内容示例如下（基于官方文档结构）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

your.domain.com {
        @grpcProto {
                path /proto.NezhaService/*
        }

        reverse_proxy @grpcProto {
                header_up Host {host}
                # 最外层时可使用：
                # header_up nz-realip {remote_host}
                transport http {
                        versions h2c
                        read_buffer 4096
                }
                to localhost:8008  # 上游端口以实际为准
        }

        reverse_proxy {
                header_up Host {host}
                header_up Origin https://{host}
                # 最外层时可使用：
                # header_up nz-realip {remote_host}
                transport http {
                        read_buffer 16384
                }
                to localhost:8008  # 上游端口以实际为准
        }
}

说明：

• @grpcProto 匹配官方 gRPC 路径，使用 h2c（明文 HTTP/2）转发到本机面板。
• 其余流量走普通反向代理。
• 前提：域名已正确解析，80/443 可从公网访问，Caddy 才能自动申请证书。

校验与重载

1
2
3

caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
# 或按你的安装方式使用 caddy reload

4.5 使用 Cloudflare 时的注意事项

若域名接入 Cloudflare：

• Cloudflare代理模式会对 gRPC 有影响。需要在 Cloudflare 后台开启 gRPC 支持（具体开关名称与路径以 Cloudflare 当前界面为准）。
• Agent 使用的端口必须在 Cloudflare 支持代理的端口范围内，否则建议改用仅 DNS。

两种常见策略：

1. Agent 通信使用仅 DNS模式：面板访问域名可以使用代理模式，Agent 对接地址用另一个仅 DNS 解析的域名或直接 IP，稳定性更高。
2. 统一代理模式：开启 gRPC，并确保使用 Cloudflare 支持的端口，同时 SSL/TLS 加密模式建议选「完全（严格）」。

注意：SSL/TLS 模式选「灵活」容易导致证书或回源异常，生产环境不推荐。

4.6 回到面板修改相关设置

反代与 HTTPS 生效后，请登录面板，把对外相关地址改为域名形式：

• Agent 对接地址（例如 your.domain.com:443）
• 其他与对外访问相关的设置项

详细操作见第五章。同时建议：

• 防火墙只保留 80/443（以及 SSH），把原来临时开放的面板端口对公网关闭。
• 确认面板实际只监听本机（或通过反代访问），不再直接暴露例如8008。

4.7 验证配置是否成功

浏览器验证：

访问 https://your.domain.com，应能看到登录页，地址栏显示锁图标，证书有效。

命令验证：

1

curl -I https://your.domain.com

预期返回 HTTP/2 200 或 HTTP/1.1 200 等成功状态。

1

echo | openssl s_client -connect your.domain.com:443 -servername your.domain.com 2>/dev/null | openssl x509 -noout -dates

可查看证书有效期。

gRPC 验证：

此时还无法完整验证 gRPC。需在第六章安装 Agent 后，观察服务器是否正常上线。如果 Agent 一直离线，优先回头检查反代中的 gRPC location 与 grpc_pass / h2c 配置。

4.8 常见问题速查

• 证书申请失败：域名未解析、80 端口不通或被占用。检查解析与防火墙后重试。
• 502 Bad Gateway：上游面板未运行，或端口写错。用 ss -tlnp 确认面板监听端口。
• 页面能开但实时数据不更新：WebSocket 未正确转发。检查对应 location 与 Upgrade 头。
• Agent 连不上：gRPC 路径或 grpc_pass / h2c 配置有问题。对照官方示例排查。
• 使用 Cloudflare 后连接异常：未开 gRPC、端口不支持或 SSL 模式不正确。详见第十章。

五、面板基础设置

面板已经能通过 https://your.domain.com 正常访问，反向代理与 gRPC 转发也在上一章配好了。这一章我们把后台里和「能不能顺利装 Agent、前台长什么样、怎么安全登录」直接相关的基础项一次理清楚。

其中最关键的是 Agent 对接地址：它会直接决定第六章生成的安装命令里写什么地址。地址写错，Agent 就连不上。

5.1 认识后台界面

登录后进入的是管理后台（路径一般为 /dashboard）。左侧是功能菜单，右上角头像可进入个人信息、系统设置等。

常见菜单与本教程对应关系如下：

先有个整体印象即可，后面按需深入。

5.2 系统设置（本章重点）

路径：右上角头像 → 系统设置。

与部署、Agent 上线直接相关的项建议先核对一遍：

操作建议：

1. 把 Agent 对接地址 改成你实际给 Agent 用的域名或 IP + 端口，并与第四章的反向代理、gRPC 转发保持一致。
2. 若使用 Cloudflare 橙云（代理开启），请确认所用端口在 Cloudflare 支持范围内，并参考第四章 4.5 的说明；Agent 通信域名一般不建议强依赖 CDN，具体以你实际方案为准。
3. 保存后，到 服务器 页再点一次「安装命令」，看生成的命令里 NZ_SERVER（或同类参数）是否已是新地址。

注意

• Agent 对接地址填错：安装命令里的地址会错，Agent 无法上线或一直离线。
• TLS 开关与真实连接方式不一致：Agent 可能按 TLS 去连明文端口（或反过来），同样连不上。
• 修改后若界面仍像旧值，可强制刷新浏览器缓存，或重新打开系统设置页确认。

时区等更多项若在界面中有单独选项，以当前版本界面为准；部分项仅存在于配置文件（如 location，默认多为 Asia/Shanghai），修改配置文件后需重启 Dashboard 才生效，详见官方配置文档。

5.3 前台主题与展示设置

• 前台：未登录或访客看到的公开展示页，用来看服务器状态、服务探测结果等。
• 后台：登录后的管理界面，用于配置、安装命令、用户与权限等。

在系统设置中可以：

• 修改 站点名称（影响前台标题等展示）；
• 选择 主题（用户前端模板）；内置主题由官方维护，社区主题请确认来源可信且与当前 Dashboard 版本兼容；
• 使用 自定义代码（用户前端 / 管理前端分开），例如改 Logo、背景、外链等。可用的全局变量与写法以官方文档「设置」页为准。

提示
公开展示页会暴露服务器名称、在线状态等信息。若不想把所有机器都公开展示，可在后续服务器管理中控制展示范围，或结合官方「强制验证」等能力（若你版本支持）限制未登录访问，具体以 nezha.wiki 为准。

5.4 （可选）OAuth2 登录配置

OAuth2 可以用 GitHub 等第三方账号登录，减少弱密码风险。哪吒支持为已有本地账户绑定第三方账号。

配置需要改 Dashboard 配置文件（常见路径示例：/opt/nezha/dashboard/data/config.yaml，以你实际安装方式为准），改完后重启面板。

以 GitHub 为例，流程如下。

1. 在 GitHub 创建 OAuth 应用

1. 打开 GitHub Developer Settings → OAuth Apps → New OAuth App。
2. 填写：
   • Application name：随意
   • Homepage URL：面板访问地址，例如 https://your.domain.com
   • Authorization callback URL：https://your.domain.com/api/v1/oauth2/callback（官方说明只检测前缀，路径以官方文档为准）
3. 创建后保存 Client ID 与 Client secrets。

2. 在面板配置文件中填写

参考官方示例结构：

1
2
3
4
5
6
7
8
9
10

dashboard_host: "your.domain.com"
oauth2:
  GitHub:
    client_id: "your_client_id"
    client_secret: "your_client_secret"
    endpoint:
      auth_url: "https://github.com/login/oauth/authorize"
      token_url: "https://github.com/login/oauth/access_token"
    user_info_url: "https://api.github.com/user"
    user_id_path: "id"

保存后重启 Dashboard。

3. 在后台绑定并验证

登录后台 → 右上角头像 → 个人信息 → 在 OAuth2 相关区域点击对应提供方的「绑定」，完成授权后，登录页会出现 OAuth 登录入口。

注意

• 启用或绑定前，务必保留一种可用的登录方式（本地密码或其它已绑定方式），避免把自己锁在外面。
• 若开启「禁止密码登录」，需先完成至少一种 OAuth2 绑定；只剩一个绑定时不能删掉最后一个绑定。
• Client Secret 不要截图、不要提交到公开仓库。

5.5 用户与权限管理

路径：系统设置 → 用户管理（需管理员权限）。

• 新建用户：由管理员在此添加。
• 权限（以官方文档为准）：
  • 管理员：可访问几乎全部资源，并可修改系统设置；
  • 普通用户：只能管理自己的资源，不能改系统设置，只能改自己的用户信息。
• 每个用户有独立的 Agent 连接密钥；安装命令里会带上当前用户对应的密钥。用户被删除后，其密钥失效，关联服务器也会被删除。

个人站长实用建议：

• 日常查看状态用普通权限账号；
• 改系统设置、装 Agent、改关键配置时再用管理员账号；
• 密码保持足够强度，并考虑启用 OAuth2。

修改自己的密码：头像 → 个人信息 → 更新个人资料（第四章若已改过可跳过）。

5.6 常见问题速查

• Agent 安装命令里的地址不对
  多半是系统设置里「Agent 对接地址」未填或未保存。到系统设置核对后重新复制安装命令。详见第十章。

• 修改设置后不生效
  先确认已点保存；浏览器强刷；若改的是配置文件项，需重启 Dashboard。详见第十章。

• OAuth2 登录回调报错
  检查 GitHub（或其它提供方）的回调 URL 是否与面板公网域名一致，以及 dashboard_host / 配置是否正确，并已重启面板。详见第十章。

• 前台页面显示异常
  先排除自定义代码或社区主题兼容问题，可临时切回默认主题对比。详见第十章。

面板侧地址与展示相关设置已经就绪，接下来就可以进入第六章，安装 Agent 并把第一台服务器接入上线。

六、安装 Agent 并添加服务器

面板侧地址与反向代理已经就绪，这一章把第一台被监控机器真正接上线。装成功后，你就能在后台和前台看到实时的 CPU、内存、磁盘和网络数据——这也是检验第四、五章配置是否正确的关键一步。

6.1 Agent 工作原理简述

Agent（探针程序）安装在你要监控的那台机器上，由它主动连接面板，并周期上报系统状态。面板根据安装命令里的连接密钥（与当前登录用户绑定）识别是谁的 Agent；连接成功后，后台会出现对应的服务器记录。

Agent 连接的目标，就是第五章在系统设置里填写的 Agent 对接地址（域名或 IP + 端口）。这个地址或端口写错、TLS 开关与实际不一致、gRPC 没正确转发，都会表现为一直离线。

6.2 在面板中获取安装命令

v2 推荐流程是：先确认 Agent 对接地址已保存，再到服务器页复制一键安装命令；Agent 连上后，列表里会出现新服务器，再编辑名称、分组等即可。

1. 登录后台，进入 服务器 页面。
2. 点击 安装命令（或同类入口），选择目标系统（Linux / Windows / macOS 等）。
3. 安装命令会自动复制到剪贴板。命令中会包含对接地址、是否使用 TLS，以及当前用户的连接密钥等信息。

上线后，可在列表中点击编辑，为服务器设置名称、分组、备注（私有备注仅登录用户可见，公开备注游客也可能看到）等，具体字段以你当前版本界面为准。

【此处插入截图：添加服务器页面（密钥已打码）】

注意

• 安装命令里含有专属连接密钥，不要截图发到群聊、论坛或公开仓库。
• 每个用户有自己的连接密钥；同一用户下多台机器各自执行一次安装即可，不要把「一整条命令」当成万能密钥随意转发。
• 若复制安装命令时提示未指定安装主机，请回到第五章核对 Agent 对接地址 是否已填写并保存。

6.3 在 Linux 上安装 Agent

安装前建议先做这几项检查：

• 系统与架构是否在官方支持范围内（以 Agent 安装文档 为准）。
• 被控机能访问面板域名，例如：

1

curl -I https://your.domain.com

能返回正常 HTTP 状态即可（示例结果因环境而异）。

• 系统时间大致正确（偏差过大可能导致证书校验或数据异常），可用 date 查看；需要同步时按你发行版使用 ntp / chrony / timedatectl 等工具。

安装步骤：

1. 在被控端用 root 或具备 sudo 的用户登录。
2. 粘贴并执行面板生成的安装命令（整段以你面板里复制的为准，不要手抄或改参数）：

1
2

# 将下面整行替换为面板「安装命令」复制出的内容
<面板生成的安装命令>

3. 安装脚本会下载 Agent、写入配置并注册为系统服务。常见结果是出现 nezha-agent 相关服务；安装目录常见为 /opt/nezha/agent/（以你机器上实际结果为准【待核实】）。

查看服务是否在跑：

1

sudo systemctl status nezha-agent

预期：状态为 active (running)（示例，实际以你环境为准）。

查看最近日志（排查离线时很有用）：

1

sudo journalctl -u nezha-agent -n 50 --no-pager

提示
若服务起不来或一直连不上面板，按顺序排查：先看 Agent 日志 → 在本机测能否访问 your.domain.com → 回查第四章 gRPC / 反向代理 → 回查第五章 Agent 对接地址与 TLS 开关。

6.4 在 Windows 与 macOS 上安装 Agent

Windows

1. 以 管理员身份 打开 PowerShell。
2. 粘贴并执行面板为 Windows 生成的安装命令（整段以面板复制内容为准）：

1
2

# 将下面整行替换为面板「安装命令」复制出的内容
<面板生成的 Windows 安装命令>

3. 若提示更改执行策略，按提示输入 Y 确认（以官方说明为准）。
4. 安装完成后，回到面板「服务器」页查看是否上线。也可在安装目录用内置服务管理命令管理服务（路径与命令以实际安装结果与官方文档为准）。

macOS

在面板选择 macOS 对应的安装命令，在终端中执行（整段以面板复制内容为准）。若系统弹出权限或安全相关提示，按本机策略允许即可。细节以官方文档为准。

本节 Windows / macOS 流程基于官方文档整理；若你环境与文档示例不一致，以面板生成的命令和 nezha.wiki 为准。

6.5 验证服务器已上线

安装完成后稍等几秒到一两分钟，刷新面板：

1. 后台 → 服务器：应出现新记录，状态为在线；可点编辑改成易记的名称。
2. 打开该服务器详情或前台展示页：CPU、内存、磁盘、网络等数据应持续刷新。

【此处插入截图：服务器在线状态与实时数据】

若离线，不要急着重装：先在被控端看 systemctl status 与 journalctl，再按 6.3 的排查顺序往回查网络与第四、五章配置。

6.6 Agent 的配置、升级与卸载

配置

一键安装后，Agent 会在本机生成配置文件（常见路径示例：/opt/nezha/agent/config.yml，以实际为准【待核实】）。也可在后台服务器列表中通过编辑配置下发部分选项。常见相关项包括连接地址 server、密钥 client_secret、是否 TLS、是否自动更新等，完整字段见官方 Agent 配置。

升级

默认情况下 Agent 会自动更新。若关闭了自动更新，可在后台对指定服务器执行 强制更新（若同时禁用了强制更新，则该操作无效）。也可按官方文档手动替换二进制后重启服务。

卸载（Linux 常见写法，以官方文档为准）

1
2
3
4

cd /opt/nezha/agent/   # 目录以实际安装位置为准
sudo ./nezha-agent service uninstall
# 如需清理文件，再删除对应安装目录，例如：
# sudo rm -rf /opt/nezha/agent/

Windows 可在安装目录执行类似的 nezha-agent.exe service uninstall（以实际程序名为准）。

注意
卸载本机 Agent 后，面板里的服务器记录不会自动消失，需要你在后台手动删除；否则会留下一条离线记录。

6.7 批量添加多台服务器的建议

• 先在一台机器上完整跑通：安装 → 在线 → 数据刷新正常，再复制同一套流程到其它机器。
• 每台机器各自在面板复制一次安装命令并在本机执行，不要多机共用同一条已跑过的历史命令当「模板乱贴」。
• 命名建议带用途或地区，例如 hk-web-01、jp-db-02，并善用分组，方便前台按组浏览。
• 需要「重装并继承原记录」时，可按官方说明在安装命令中附带该服务器的 UUID（见官方 Agent 文档中的 UUID 相关说明），并先卸掉旧 Agent，避免重复注册。

6.8 常见问题速查

• Agent 一直离线
  优先看本机日志，再测能否访问面板域名；仍不行则回查第四章 gRPC/反代与第五章 Agent 对接地址、TLS。详见第十章。

• 安装命令执行失败
  多为网络拉不下脚本、权限不足或系统架构不匹配。检查网络与 root/管理员权限。详见第十章。

• 数据异常或时间相关报错
  检查被控端系统时间是否同步。详见第十章。

• 重复安装出现多条记录
  同一台机多次安装且未带原 UUID 时可能产生新记录；卸掉多余 Agent，面板侧删除多余条目。详见第十章。

• 走了 Cloudflare 橙云后连不上
  Agent 通信对 CDN/代理较敏感，需确认端口与协议是否被支持，并对照第四章 4.5。详见第十章。

基础监控链路已经打通。下一章我们配置服务探测、通知与告警，让面板不只是「能看」，还能在出问题时主动提醒你。