Hysteria2-LuoPo 详细教程：从零部署、客户端导入、更新与故障排查

Hysteria2-LuoPo 详细教程：从零部署、客户端导入、更新与故障排查

Hysteria2 性能很好，但第一次部署时，证书、YAML、systemd 权限、客户端参数和防火墙往往会一起出现。一个小字段写错，就可能变成服务启动失败、客户端连接超时，或者看似连上却无法解析域名。

为了解决这些重复问题，我们制作了 Hysteria2-LuoPo 管理面板。它是一个面向 Linux VPS 的纯 Bash 菜单脚本，可以完成 Hysteria2 内核安装、节点配置、客户端配置导出、服务管理、诊断、备份和更新。

本文以 v26.8.11 为例，从一台新 VPS 开始，完整演示部署和日常维护过程。

本文仅用于介绍开源软件的部署与运维。请遵守服务器所在地和使用所在地的法律法规，并遵守云服务商的服务条款。

项目地址

一、这个项目解决了什么问题

Hysteria2-LuoPo 将常见运维流程集中到了一个菜单中：

  • 安装或更新 Hysteria2 内核；
  • 使用 CA 域名证书或自签证书创建节点；
  • 自动生成随机认证密码；
  • 输出 hysteria2:// 分享链接；
  • 输出 v2rayN / NekoRay 使用的 YAML 片段；
  • 输出 Sing-box Outbound 和完整配置模板；
  • 启动、停止、重启并检查服务状态；
  • 查看实时日志；
  • 检查内核、配置、证书、端口和公网 IP；
  • 创建手动备份并恢复最近备份；
  • 配置失败或恢复失败时自动回滚；
  • 单独更新面板脚本，避免和内核更新混淆。

它比较适合下面几类用户：

  1. 不熟悉 YAML 和 systemd 的 Linux 新手；
  2. 需要在多台 VPS 上重复部署的用户；
  3. 希望保留完整诊断与回滚能力的轻量运维用户；
  4. 想基于纯 Bash 项目继续二次开发的维护者。

二、部署前准备

1. 一台可用的 Linux VPS

脚本需要：

  • root 权限；
  • 可用的 systemd；
  • apt-get、dnf 或 yum 其中一种包管理器；
  • 能访问 GitHub Raw 和 Hysteria2 官方安装地址；
  • 一个公网 IPv4 或可用的公网网络环境。

常见的 Debian、Ubuntu、Rocky Linux、AlmaLinux 等 systemd 发行版通常都能满足这些条件。容器内部、OpenVZ 特殊模板或没有 systemd 的精简系统不适合直接运行本面板。

2. 检查 VPS 时间

TLS 对系统时间比较敏感，建议先确认时间同步正常：

1
timedatectl status

如果时间明显不正确，应先修复 NTP 或系统时区，再继续部署。

3. 准备防火墙和安全组

Hysteria2 基于 QUIC，节点监听端口使用 UDP。假设准备使用 45625 端口，需要在云厂商安全组和 VPS 防火墙中放行：

1
2
3
协议：UDP
端口：45625
来源：按自己的安全策略设置

使用 UFW 时可以执行：

1
2
ufw allow 45625/udp
ufw status

使用 firewalld 时可以执行：

1
2
3
firewall-cmd --permanent --add-port=45625/udp
firewall-cmd --reload
firewall-cmd --list-ports

如果选择 CA 域名证书模式，还应根据证书申请环境允许 TCP 80 和 443：

1
2
ufw allow 80/tcp
ufw allow 443/tcp

VPS 系统防火墙和云厂商安全组是两层配置。只改其中一层，客户端仍可能超时。

4. CA 模式需要提前准备域名

如果准备使用 CA 模式，请先在 DNS 服务商处添加域名解析：

1
2
3
类型：A
主机记录：hy2（示例）
记录值：你的 VPS 公网 IPv4

例如最终使用 hy2.example.com。等待解析生效后，可以在本地检查：

1
nslookup hy2.example.com

解析结果必须指向当前 VPS。

三、安装 Hysteria2-LuoPo 面板

1. 登录 VPS

在电脑终端中执行：

1
ssh root@你的VPS公网IP

例如：

1
ssh [email protected]

2. 执行官方仓库安装命令

1
bash <(curl -fsSL https://raw.githubusercontent.com/LuoPoJunZi/hysteria2-luopo/main/install.sh)

安装器会完成以下工作：

  1. 检查是否使用 root 运行；
  2. 检测 apt-get、dnf 或 yum；
  3. 安装 curl、wget、openssl 等基础依赖；
  4. 从 GitHub 官方仓库下载 hy2.sh；
  5. 检查脚本标识、版本格式和 Bash 语法；
  6. 将面板安装到 /usr/local/bin/hy2；
  7. 自动打开管理面板。

安装完成后，以后只需要输入：

1
hy2

即可重新打开面板。

四、认识主菜单

当前 v26.8.11 的主菜单如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
=====================================================
  Hysteria2-LuoPo 管理面板 v26.8.11 |  快捷启动: hy2
=====================================================
  内核版本: v2.12.1    服务状态: 运行中
-----------------------------------------------------
  节点核心管理
    (1)  一键安装/更新 Hysteria2 内核
    (2)  配置 Hysteria2 节点 (CA / 自签)
    (3)  查看客户端配置与分享链接

  服务运行控制
    (4)  启动 / 停止 / 重启 / 状态
    (5)  查看实时运行日志
    (6)  完全卸载清理
    (7)  查看常用指令速查
    (8)  查看 Sing-box 完整模板
    (9)  一键环境诊断
    (10) 查看最近诊断报告
    (11) 配置备份与恢复
    (12) 更新管理面板脚本
    (0)  退出面板
=====================================================
 => 请选择操作 [0-12]:

这里有一个很重要的区别：

  • 菜单 1 更新的是 Hysteria2 内核；
  • 菜单 12 更新的是 Hysteria2-LuoPo 管理面板。

只更新其中一个，不代表另一个也已经更新。

五、安装或更新 Hysteria2 内核

第一次进入面板时，顶部通常显示“内核版本：未安装”。输入：

1
1

面板会下载 Hysteria2 官方安装脚本，先检查文件和 Bash 语法，再执行安装，并设置 hysteria-server.service 开机自启。

安装完成后，面板会显示实际内核版本。当前建议使用 Hysteria2 v2.12.1 或更高版本；菜单 9 会检查版本，发现过旧时给出更新建议。

也可以手动确认：

1
2
hysteria version
systemctl is-enabled hysteria-server.service

六、创建 Hysteria2 节点

安装内核后，在主菜单输入：

1
2

配置过程会依次询问端口、密码、伪装网址、带宽和证书模式。

1. 设置监听端口

默认端口是 443，也可以使用其他 1-65535 之间的端口：

1
=> 请设置监听端口 (默认 443): 45625

请记住：这里填写的是 UDP 端口，必须和云安全组、防火墙中的放行端口一致。

如果不确定端口是否被占用，可以先检查：

1
ss -lunp | grep ':45625'

没有输出通常表示当前没有 UDP 程序监听该端口。

2. 设置认证密码

脚本会使用 OpenSSL 自动生成 32 位十六进制随机密码：

1
=> 请设置认证密码 (默认随机: 此处会显示随机值):

直接按回车即可使用随机密码，也可以输入自己的密码。建议使用自动生成的随机密码，不要使用生日、手机号或常见单词。

3. 设置伪装网址

默认值是：

1
https://bing.com

输入必须以 http:// 或 https:// 开头。一般直接使用默认值即可。

4. 设置带宽

默认值为：

1
2
上行：20 Mbps
下行：100 Mbps

建议根据 VPS 的真实带宽填写，不要为了追求数字而设置得远高于线路能力。例如，VPS 标称上行约 50 Mbps、下行约 200 Mbps，可以填写：

1
2
上行：50
下行：200

这些参数会用于客户端配置生成。

5. 选择证书模式

面板提供两种模式：

1
2
(1) CA 域名证书
(2) 自签证书

下面分别说明。

七、CA 域名证书模式

什么时候选择 CA

满足以下条件时，推荐使用 CA 模式：

  • 已有域名；
  • 域名已经解析到 VPS；
  • TCP 80/443 没有被上游网络阻断；
  • 希望客户端使用标准证书验证。

配置步骤

证书模式选择 1，然后输入域名和邮箱：

1
2
[*] 请输入已解析到本机的域名: hy2.example.com
[*] 请输入邮箱: [email protected]

配置完成后：

  • SNI 使用输入的域名；
  • 客户端不需要 insecure；
  • Hysteria2 服务负责自动申请和使用 CA 证书。

CA 模式常见失败原因

  1. 域名 A/AAAA 记录没有指向当前 VPS；
  2. DNS 仍在传播中；
  3. TCP 80/443 被安全组、防火墙或运营商拦截；
  4. 域名同时存在错误的 AAAA 记录；
  5. VPS 时间不正确；
  6. 证书签发机构暂时无法访问。

遇到失败时，优先执行菜单 5 查看日志，再执行菜单 9 生成诊断报告。

八、自签证书模式

什么时候选择自签

没有域名、希望快速通过 IP 建立连接时，可以选择自签模式。

证书模式输入：

1
2

然后选择一个 SNI：

1
2
3
4
5
6
(1) bing.com
(2) www.cloudflare.com
(3) www.apple.com
(4) www.microsoft.com
(5) www.amazon.com
(0) 手动输入域名

直接按回车会使用 bing.com。

自签模式为什么不能只写 insecure

过去一些客户端仅使用 insecure=true 跳过证书验证，这样虽然容易连接，但无法确认对端证书是否仍是你服务器上的那一张。

当前脚本会同时生成不同客户端需要的证书固定参数：

  • 原生 Hysteria2：insecure=1 + pinSHA256；
  • v2rayN / Xray：使用 pcs 映射为 pinnedPeerCertSha256；
  • Sing-box 1.13+：insecure: true + certificate_public_key_sha256。

脚本不会重新加入已经移除的 allowInsecure 参数。如果无法读取证书指纹或公钥指纹，面板会直接拒绝导出不安全的客户端配置。

重新生成自签证书后，证书固定值会变化。所有客户端都必须重新导入节点，否则会因为指纹不匹配而连接失败。

九、检查节点是否启动成功

配置完成后，脚本会自动重启服务。如果服务无法保持运行，会尝试恢复配置前的文件，避免错误配置直接覆盖原来的可用节点。

可以手动检查：

1
systemctl status hysteria-server.service --no-pager -l

确认 UDP 端口正在监听：

1
ss -lunp | grep ':45625'

查看最近 100 行日志：

1
journalctl -u hysteria-server.service --no-pager -n 100

如果状态是 active (running)，并且目标 UDP 端口正在监听，服务端基本配置已经完成。

十、导出客户端配置

回到主菜单输入：

1
3

面板会显示：

  • 服务器 IP；
  • UDP 端口；
  • 认证密码；
  • SNI；
  • 证书验证模式；
  • 上下行带宽；
  • hysteria2:// 分享链接；
  • Sing-box Outbound JSON；
  • v2rayN / NekoRay YAML 片段。

这些内容包含认证密码，不要发到公开群聊、论坛、Issue 或博客截图中。本文所有示例都使用保留地址和占位值。

十一、Windows 客户端导入

方案 A：使用 hysteria2:// 链接

从菜单 3 复制完整链接，格式大致如下：

1
hysteria2://密码@203.0.113.10:45625/?sni=bing.com&insecure=1&pinSHA256=证书指纹&pcs=证书指纹#Hysteria2-LuoPo

在 v2rayN、NekoBox 或其他支持 Hysteria2 URI 的客户端中，选择“从剪贴板导入”。

自签节点建议：

  • v2rayN 使用 7.24.4 或更高版本；
  • Xray-core 使用 26.2.6 或更高版本；
  • 不要手动删除 pinSHA256 或 pcs；
  • 如果客户端支持原生 Hysteria2 内核，也可以优先用原生内核测试。

CA 节点的链接不会加入 insecure，由客户端按标准证书链验证。

方案 B：使用 YAML 片段

面板还会输出类似下面的配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
server: '203.0.113.10:45625'
auth: '请替换为自己的密码'
bandwidth:
  up: 50 mbps
  down: 200 mbps
tls:
  sni: 'bing.com'
  insecure: true
  pinSHA256: 请使用面板实际输出的证书指纹
socks5:
  listen: 127.0.0.1:1080
http:
  listen: 127.0.0.1:8080

这个片段适合原生 Hysteria2 或支持自定义 Hysteria2 YAML 的客户端。不要直接照抄示例中的 IP、密码和指纹。

十二、Android / iOS 的 Sing-box 配置

当前自签配置要求 Sing-box 1.13.0 或更高版本。

方案 A：复制 Outbound

菜单 3 会输出 Hysteria2 Outbound：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "type": "hysteria2",
  "tag": "proxy",
  "server": "203.0.113.10",
  "server_port": 45625,
  "up_mbps": 50,
  "down_mbps": 200,
  "password": "请使用面板实际输出的密码",
  "tls": {
    "enabled": true,
    "server_name": "bing.com",
    "insecure": true,
    "certificate_public_key_sha256": [
      "请使用面板实际输出的公钥指纹"
    ]
  }
}

这个片段适合合并到已有 Sing-box 配置。需要注意，它只是一个 outbound，不是完整配置文件。

方案 B：使用完整模板

如果要在 Sing-box Android 客户端中新建一份完整配置，推荐回到主菜单输入：

1
8

复制从第一个 { 到最后一个 } 的全部内容，再在客户端中创建本地配置并粘贴。

完整模板已经包含：

  • TUN inbound；
  • Hysteria2 proxy outbound；
  • direct outbound；
  • 新版 DNS server 格式；
  • default_domain_resolver；
  • 国内域名/IP 和广告规则集；
  • 远程 DNS 与规则集通过 proxy 获取；
  • 自签模式的证书公钥固定。

当前稳定模板继续使用 download_detour。sing-box 1.14 的替代字段 http_client 尚未进入稳定版，因此不要提前手工替换。

Sing-box 启动后无法解析域名

如果节点能启动，但 YouTube、X、IP.sb 等网站提示 DNS 解析失败，请检查：

  1. 是否使用了菜单 8 输出的完整模板；
  2. 远程 DNS cf 是否设置为通过 proxy；
  3. route.default_domain_resolver 是否指向 cf；
  4. 规则集下载是否通过 proxy；
  5. 是否误把本地 DNS 写成 detour: direct。

旧配置中的下面写法可能触发错误，应删除：

1
2
3
4
5
6
{
  "type": "udp",
  "tag": "local",
  "server": "223.5.5.5",
  "detour": "direct"
}

正确的本地 DNS server 不需要把 detour 指向一个空的 direct outbound。

十三、一键诊断和日志

菜单 9：一键环境诊断

输入 9 后，面板会检查：

  • Hysteria2 内核是否安装；
  • 内核版本是否低于建议版本；
  • systemd 服务是否开机自启；
  • 服务当前是否运行；
  • config.yaml 是否存在；
  • meta.info 是否存在且可以安全解析；
  • UDP 监听端口；
  • 当前使用 CA 还是自签模式；
  • 自签证书和私钥是否存在；
  • 公网 IP 是否能获取；
  • 当前公网 IP 是否和节点元数据一致。

结果分为：

  • OK：检查正常；
  • WARN：暂不一定阻断，但建议处理；
  • FAIL：会影响节点运行或配置导出。

诊断末尾会给出“结论、建议、命令”，并生成报告：

1
2
/tmp/hy2-diagnose-YYYYMMDD-HHMMSS.log
/tmp/hy2-diagnose-latest.log

菜单 10：查看最近报告

输入 10 可以直接查看 /tmp/hy2-diagnose-latest.log，适合在问题发生后重新回看诊断结果。

菜单 5：实时日志

输入 5 会跟踪最近日志。手动命令是：

1
journalctl -u hysteria-server.service --no-pager -n 100 -f

按 Ctrl+C 退出日志跟踪。

十四、服务管理

主菜单输入 4 后，可以选择：

1
2
3
4
5
(1) 启动服务
(2) 停止服务
(3) 重启服务
(4) 查看状态
(0) 返回主菜单

对应的 systemd 命令分别是：

1
2
3
4
systemctl start hysteria-server.service
systemctl stop hysteria-server.service
systemctl restart hysteria-server.service
systemctl status hysteria-server.service --no-pager -l

十五、配置备份与恢复

修改端口、密码、证书模式或 SNI 前，建议先创建手动备份。

主菜单输入 11：

1
2
3
4
(1) 创建手动备份
(2) 恢复最近手动备份
(3) 查看手动备份列表
(0) 返回主菜单

备份目录位于：

1
/etc/hysteria/backup/manual-时间戳.随机字符/

备份会保存：

  • config.yaml；
  • meta.info；
  • 自签模式下的 server.crt；
  • 自签模式下的 server.key。

恢复前，脚本会先保存当前运行配置。如果恢复文件失败或恢复后服务无法启动，脚本会尝试回滚到恢复操作之前的状态。

菜单 6 的完全卸载会删除 /etc/hysteria，其中也包括备份目录。重要备份请另外保存到安全位置。

十六、如何更新项目

更新 Hysteria2 内核

打开面板：

1
hy2

选择菜单 1。更新完成后会显示当前内核版本。

更新 Hysteria2-LuoPo 面板

打开面板后选择菜单 12。面板会：

  1. 从 GitHub 下载最新 hy2.sh；
  2. 检查脚本内容、版本号和 Bash 语法；
  3. 备份当前 /usr/local/bin/hy2；
  4. 用新脚本原子替换旧脚本。

更新结束后退出面板，再执行：

1
hy2

顶部即可看到新的面板版本。

如果面板自身无法打开，也可以重新运行安装命令：

1
bash <(curl -fsSL https://raw.githubusercontent.com/LuoPoJunZi/hysteria2-luopo/main/install.sh)

该命令会更新面板，不会主动删除现有 /etc/hysteria 节点配置。

十七、重要文件和路径

路径 用途
/usr/local/bin/hy2 Hysteria2-LuoPo 管理面板
/usr/local/bin/hysteria Hysteria2 内核
/etc/hysteria/config.yaml 服务端主配置
/etc/hysteria/meta.info 生成客户端配置所需的节点元数据
/etc/hysteria/server.crt 自签证书
/etc/hysteria/server.key 自签私钥
/etc/hysteria/backup/ 手动备份目录
/etc/systemd/system/hysteria-server.service systemd 服务文件
/tmp/hy2-diagnose-latest.log 最近一次诊断报告

不要手工公开 meta.info、server.key 或包含密码的客户端配置。

十八、常见问题排查

1. 客户端连接超时

按顺序检查：

  1. 云安全组是否放行节点 UDP 端口；
  2. VPS 防火墙是否放行同一个 UDP 端口；
  3. systemctl status 是否显示服务运行；
  4. ss -lunp 是否能看到端口监听；
  5. 客户端 IP、端口、密码和 SNI 是否与菜单 3 一致；
  6. 自签配置是否保留完整证书固定参数；
  7. VPS 所在网络是否限制 UDP/QUIC。

建议命令：

1
2
3
systemctl status hysteria-server.service --no-pager -l
ss -lunp
journalctl -u hysteria-server.service --no-pager -n 100

2. 服务提示端口被占用

1
ss -lntup | grep ':45625'

找到占用进程后，可以更换 Hysteria2 端口，或者停止确认无用的占用程序。不要在不了解进程用途时直接结束系统服务。

3. config.yaml: permission denied

脚本会根据 systemd 实际运行用户动态设置权限。如果仍然出现错误，执行：

1
2
3
systemctl show -p User,Group hysteria-server.service
namei -l /etc/hysteria/config.yaml
ls -la /etc/hysteria

然后重新进入菜单 2 生成配置，让脚本重新收敛权限。

4. CA 证书申请失败

检查域名解析：

1
getent ahosts hy2.example.com

检查 80/443 防火墙、安全组和其他 Web 服务占用情况：

1
ss -lntup | grep -E ':(80|443) '

然后查看日志中的 acme、timeout、dns 或 no such host 信息。

5. 自签节点更新后突然不能连接

如果重新执行了菜单 2 的自签配置，服务器可能生成了新证书。此时旧客户端保存的证书固定值已经失效。

解决方法：

  1. 执行菜单 3；
  2. 重新复制分享链接或 Outbound；
  3. 删除客户端旧节点并重新导入；
  4. 不要继续使用旧的 pinSHA256、pcs 或 certificate_public_key_sha256。

6. 手机休眠或切换网络后容易断联

先在菜单顶部查看 Hysteria2 内核版本，再执行菜单 9。低于 v2.12.1 时，通过菜单 1 更新内核，以获得移动端快速重连和小 MTU 环境稳定性修复。

同时检查手机系统是否限制 Sing-box 或其他客户端的后台运行、电池使用和 VPN 权限。

7. 菜单 3 无法导出自签配置

这是安全保护，不建议绕过。通常表示：

  • server.crt 缺失；
  • 证书文件损坏；
  • OpenSSL 无法读取证书；
  • 证书公钥指纹计算失败。

通过菜单 11 先备份，再使用菜单 2 重新配置自签节点。随后重新导入所有客户端。

十九、安全使用建议

  1. 长期使用优先选择 CA 域名证书模式；
  2. 自签模式必须保留客户端证书固定参数；
  3. 不要把菜单 3 的完整输出发布到公开页面；
  4. 不要公开 /etc/hysteria/server.key；
  5. 修改配置前先使用菜单 11 创建备份；
  6. 定期使用菜单 1 更新 Hysteria2 内核；
  7. 定期使用菜单 12 更新管理面板；
  8. 从 Release 下载文件时，可使用同版本的 SHA256SUMS 检查完整性；
  9. 遇到问题时先保存诊断报告，但分享前应检查其中的 IP 和环境信息；
  10. 不要把陌生脚本直接覆盖到 /usr/local/bin/hy2。

二十、完全卸载

主菜单输入 6，确认后会删除：

  • Hysteria2 服务；
  • /usr/local/bin/hysteria；
  • /etc/hysteria 及其中的配置、证书和备份；
  • /etc/systemd/system/hysteria-server.service；
  • /usr/local/bin/hy2 面板命令。

这个操作不可逆。确定不再使用前，请先导出需要保留的配置和备份。

二十一、给开发者的说明

项目保持单文件面板体验，核心入口是 hy2.sh。仓库提供统一验证命令：

1
2
3
4
git clone https://github.com/LuoPoJunZi/hysteria2-luopo.git
cd hysteria2-luopo
chmod +x scripts/verify.sh
./scripts/verify.sh

验证内容包括：

  • Bash 语法；
  • 文本和换行规范；
  • ShellCheck；
  • 菜单与 README 同步；
  • 版本号同步；
  • Release 包防污染；
  • Smoke E2E；
  • Bats 单元测试；
  • 交互配置流程回放。

推送到 main 后，GitHub Actions 会先执行完整验证，再按 hy2.sh 中的日期版本号自动创建正式 Release。Release 标题只使用版本号，正文从 CHANGELOG.md 提取“主要变化”。

结语

Hysteria2-LuoPo 的目标不是隐藏所有技术细节，而是把最容易出错的步骤做成可靠、可检查、能回滚的流程。

对于第一次部署的用户，最短操作路线只有四步：

1
2
3
4
菜单 1：安装内核
菜单 2：配置节点
菜单 3：导出客户端配置
菜单 9：执行诊断

完成后，再根据自己的客户端选择 hysteria2:// 链接、YAML 片段、Sing-box Outbound 或完整模板。遇到问题时，不要急着反复重装，先看服务状态、UDP 端口和诊断报告，通常能更快找到真正原因。

项目仍在持续维护。欢迎通过 GitHub Issues 提交可复现的问题、客户端报错截图和脱敏后的诊断信息。