hy2ctl 详细教程：从零部署 Hysteria2、客户端导入与运维排障

第一次部署 Hysteria2，最容易卡住的往往不是安装内核，而是证书、UDP 端口、systemd 权限和客户端配置没对上。

hy2ctl 把这些操作整理成一个纯 Bash 终端管理面板：安装内核、创建节点、导出配置、查看日志、诊断和备份恢复，都可以通过菜单完成。它原名 Hysteria2-LuoPo，项目名称已经更新，但 VPS 上的快捷命令仍然是 hy2。

2026-10-01 更新：本文按项目 main 分支的 v26.10.1 源码整理，更新了仓库地址、菜单编号、安装流程、默认参数和客户端兼容要求。正式发布版本以 Releases 为准；如果你使用旧版面板，请先看“旧版迁移与更新”一节。

本文仅介绍开源软件部署与运维，请遵守服务器所在地、使用所在地的适用规定及云服务商条款。

一、项目定位与使用入口

项目地址

• GitHub 仓库
• 版本发布与下载
• 更新记录
• 问题反馈
• 开发文档
• 开源许可证：当前文件为 GPL-3.0，许可说明以该文件为准。

先区分三个名称，避免把面板更新与内核更新混为一谈：

能做什么，不能替代什么

面板提供：

• 安装或更新 Hysteria2 内核、设置服务开机自启；
• 创建 CA 域名证书或自签证书节点；
• 自动生成认证密码，配置端口、SNI、伪装网址和客户端带宽参数；
• 导出 hysteria2:// 链接、原生 Hysteria2 YAML、Sing-box Outbound 和完整模板；
• 服务启停、实时日志、环境诊断和报告回看；
• 手动备份与恢复，配置启用失败时尝试自动回滚；
• 单独更新面板脚本。

它是单节点终端运维工具，不是浏览器控制台，也不是多用户计费系统。菜单配置、自动回滚和诊断不能替代云安全组设置、异机备份或客户端实际连接检查。

首次部署的最短路线：

1
2
3
4

运行安装器（自动安装面板与内核）
    → 菜单 1：配置节点
    → 菜单 2：导出客户端配置
    → 菜单 8：执行诊断

下面把每一步展开说明。

二、部署前准备

除了电脑上的 SSH 登录命令，本文 Shell 命令都在 Linux VPS 的 Bash 终端执行，不是在本地 Windows 的 Hexo 博客目录中执行。

1. 服务器与权限

需要：

• root 权限；
• 可用的 systemd；
• apt-get、dnf 或 yum 包管理器；
• 能访问 GitHub Raw 和 https://get.hy2.sh/；
• 客户端能够访问的公网地址，以及可用的 UDP 入站端口。

Debian、Ubuntu，以及使用 dnf/yum 的 systemd 发行版可按自己的环境部署。没有 systemd 的精简系统、受限制的容器环境，不能直接套用本教程。

NAT VPS 需要额外配置公网 UDP 端口映射；只有内网地址，或者只能使用 TCP 的环境，不满足默认部署方式。面板获取到了 IP，也不等于客户端一定能够从公网访问它。

2. 时间同步

TLS 证书依赖正确的系统时间：

1

timedatectl status

检查当前时间和同步状态。时间明显不正确时先修复时间同步；不是必须换成某个特定时区才能使用 TLS。

3. 云安全组与 VPS 防火墙

当前默认监听端口为 UDP 8443。本文也统一用这个端口举例；如果你选择其他端口，下面所有防火墙、命令和客户端示例都要对应替换。

云厂商安全组添加：

1
2
3

协议：UDP
端口：8443
来源：按实际客户端和安全策略设置

使用 UFW 的节点：

1
2

ufw allow 8443/udp
ufw status

使用 firewalld 的节点：

1
2
3

firewall-cmd --permanent --add-port=8443/udp
firewall-cmd --reload
firewall-cmd --list-ports

按自己正在使用的防火墙选择一种，不要为此同时启用两套，也不要在远程 SSH 中盲目重置规则。保留 SSH 管理端口。

CA 模式使用自动证书申请，还需按实际 ACME 挑战方式保证 TCP 80/443 可达。例如使用 UFW 时：

1
2

ufw allow 80/tcp
ufw allow 443/tcp

这些是证书挑战端口，与节点的 UDP 8443 不同。单纯放行 TCP 8443 不能让 Hysteria2 节点连通；只修改 VPS 防火墙、不修改云安全组，同样可能超时。

4. CA 模式的域名

使用 CA 模式前，把自己的域名解析到 VPS：

1
2
3
4

类型：A
主机记录：hy2
记录值：你的 VPS 公网 IPv4
示例域名：hy2.example.com

如果配置 AAAA 记录，IPv6 也必须正确指向并能到达这台 VPS；不用 IPv6 时不要保留错误的 AAAA 记录。使用 DNS 代理服务时，确认是否支持所需的 UDP/QUIC 通信，普通网页代理不能直接等同于节点代理。

从电脑或其他主机查看解析结果：

1

nslookup hy2.example.com

从 VPS 也可检查：

1

getent ahosts hy2.example.com

自签模式不要求你拥有域名，可以跳过域名解析步骤。

三、安装面板与 Hysteria2 内核

1. 登录 VPS

在电脑终端中执行，地址替换为自己的服务器：

1

ssh [email protected]

203.0.113.10 是文档示例地址，不能用于实际连接。使用普通用户登录时，先通过服务器允许的方式取得 root 权限，例如 sudo -i。

2. 使用当前仓库安装入口

项目当前的一键安装命令为：

1

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

如果希望先阅读安装器再执行，可使用下面的替代流程，不必把两种方式都运行一遍：

1
2
3

curl -fL -o /root/hy2ctl-install.sh https://raw.githubusercontent.com/LuoPoJunZi/hy2ctl/main/install.sh
less /root/hy2ctl-install.sh
bash /root/hy2ctl-install.sh

缺少 curl 时，先用本机包管理器安装它。安装器自身会继续下载面板及 Hysteria2 官方安装脚本，先阅读入口文件不等于对全部后续代码完成了审核；始终确认仓库来源。

安装器依次执行：

1. 检查 root 权限、基础命令和包管理器。
2. 安装 curl、wget、OpenSSL 等依赖。
3. 下载生成版 hy2.sh，检查脚本标识、版本格式和 Bash 语法。
4. 部署到 /usr/local/bin/hy2。
5. 自动安装或更新 Hysteria2 内核，并设置服务开机自启。
6. 成功后进入管理面板；内核安装失败时会停止进入面板。

结构与语法检查能够过滤错误下载内容，但不是代码签名验证。具体行为见 安装器源码。

3. 以后怎样打开

1

hy2

如果首次安装中途失败，先按终端报错处理网络、软件源或依赖问题。面板已部署但内核未安装时，可打开 hy2，使用“菜单 11 → 1”重新尝试，不必先执行完全卸载。

当前项目推荐 Hysteria2 2.12.3 或更高版本，可查看实际安装结果：

1
2

hysteria version
systemctl is-enabled hysteria-server.service

这只是版本和开机自启检查，首次安装后仍需要配置节点。推荐值来自 面板版本与默认值，不要把面板的日期版本号当成 Hysteria2 内核版本号。

四、认识当前主菜单

v26.10.1 的菜单示意如下，内核版本和服务状态以自己的节点为准：

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

=====================================================
  hy2ctl 管理面板 v26.10.1 | 快捷启动: hy2
=====================================================
  内核版本: v2.12.3    服务状态: 运行中
-----------------------------------------------------
  节点核心管理
    (1)  节点配置（CA / 自签）
    (2)  客户端配置与分享

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

首次安装不用再到菜单里单独安装内核。之后“菜单 11”的二级菜单才是更新入口：

1
2
3

(1) 安装/更新 Hysteria2 内核
(2) 更新 hy2ctl 管理面板
(0) 返回主菜单

更新面板不会自动等于更新内核，反过来也一样。菜单编号变动时，以 当前菜单源码 和实际界面为准。

五、创建节点：端口、密码和带宽

进入 菜单 1，按提示填写连接参数，再选择证书模式。配置会写入 /etc/hysteria/config.yaml，并生成客户端导出所需的 meta.info。

当前默认值

如果上一次已经配置了可用节点，先通过菜单 10 创建手动备份。重新走配置流程会重写相关参数；自签模式还会重新生成证书。

1. 监听端口

示例提示：

1

=> 请设置监听端口 (默认 8443):

回车使用默认值；改用其他端口时同步调整安全组、防火墙和客户端。

检查 UDP 占用：

1

ss -lunp 'sport = :8443'

没有监听条目不代表公网已放通，只说明当前没有查询到对应 UDP 监听。

2. 认证密码

直接回车使用随机密码即可。不建议使用生日、手机号或常见单词。密码会出现在导出的链接和客户端配置中，复制时注意剪贴板、终端录屏和截图。

3. 伪装网址与 SNI

伪装网址与证书 SNI 是不同参数：

• 伪装网址用于服务端的 masquerade 配置；
• SNI 用于 TLS 握手及相应验证流程；
• 选择 bing.com 等自签 SNI，不代表持有该网站的证书，也不代表获得第三方网络服务。

不了解具体用途时保持默认即可，不要认为修改一个域名就能保证任意网络下可用。

4. 带宽填写方向

面板把带宽保存到元数据，再写入客户端 YAML/JSON：

• up / up_mbps：客户端上传方向；
• down / down_mbps：客户端下载方向；
• 单位是 Mbps，不是下载软件显示的 MB/s。

这些值不是面板设置的 VPS 系统级限速，也不是保证能够达到的测速结果。按客户端到服务器的实际瓶颈填写，过高的值可能导致拥塞和不稳定；不要把 VPS 上行/下行方向直接原样对应到客户端。参考 Hysteria2 客户端带宽说明。

六、CA 与自签证书怎么选

1. CA 模式

在证书模式提示中选 1，输入域名及邮箱：

1
2

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

邮箱建议使用自己能接收通知的真实地址。确认域名解析、系统时间和 ACME 挑战入站可用后，Hysteria2 负责自动申请并管理证书，SNI 使用该域名。

CA 模式的分享链接不加入 insecure；客户端按标准证书链验证。连接地址可以是 IP，但证书验证所用的 SNI 仍要匹配自己的域名。

申请失败时依次检查：

1. A/AAAA 是否指向当前 VPS，DNS 是否生效。
2. 实际挑战所需的 TCP 80/443 是否被安全组、防火墙阻挡。
3. 是否有其他服务占用挑战端口。
4. VPS 时间、出站网络及 CA 可达性。
5. 菜单 4 的 ACME 日志和菜单 8 的诊断建议。

不要通过关闭证书验证掩盖 CA 模式的域名或证书错误。ACME 参数详见 Hysteria2 服务端配置。

2. 自签模式

在证书模式提示中回车或输入 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) 手动输入域名

不需要给这些预设域名做 DNS 解析；实际连接地址仍是自己的服务器 IP。

3. 自签不等于只开启 insecure

只跳过常规证书验证，不能确认对端就是自己的服务器。面板按客户端类型导出固定值：

证书指纹与公钥指纹不是同一个值，不能互相复制替换。面板不再输出旧的 allowInsecure；读取自签校验材料失败时会拒绝导出，而不是静默生成缺少固定值的配置。

重新生成自签证书后，所有客户端都需要重新导入节点。相关字段可对照 Hysteria2 TLS 与 Sing-box TLS。

七、确认服务状态并导出客户端配置

完成配置后，面板会重启服务，并观察两秒后的运行状态。启动失败或服务立即退出时，会尝试恢复变更前的配置、元数据、证书和私钥；回滚本身也可能失败，遇到失败提示必须继续查看日志。

手动查看：

1
2
3

systemctl status hysteria-server.service --no-pager -l
ss -lunp 'sport = :8443'
journalctl -u hysteria-server.service --no-pager -n 100

服务运行且端口监听，说明宿主机侧已经启动；不等于云安全组、客户端网络、证书固定和完整连接都已经通过。

进入 菜单 2，获取：

• 服务器地址、UDP 端口、认证密码和 SNI；
• 证书模式及客户端带宽值；
• hysteria2:// 分享链接；
• Sing-box Outbound JSON；
• 原生 Hysteria2 YAML 片段。

本文所有地址、密码和固定值都为示例。实际使用复制面板的完整输出，不要拿本文占位值连接，也不要把菜单 2 的输出发布到公开群聊、Issue 或博客截图中。

八、Windows 客户端：链接或 YAML

1. 先分清客户端与实际内核

图形客户端版本与它管理的内核版本不是一回事。本文按当前面板的兼容提示整理：

这些是项目给出的兼容下限，不是建议长期停留在旧版本。优先使用客户端官方仍维护的版本，并检查实际选中的内核。面板提示见 客户端兼容说明源码。

2. 使用分享链接

菜单 2 的自签链接格式示意：

1

hysteria2://密码@203.0.113.10:8443/?sni=bing.com&insecure=1&pinSHA256=证书指纹&pcs=证书指纹#hy2ctl

复制实际完整链接，在支持 Hysteria2 URI 的客户端中选择“从剪贴板导入”。

注意：

• 不要手工删除 pinSHA256 或 pcs。
• 使用 v2rayN/Xray 时，确认客户端正确映射证书固定字段。
• 并非所有支持 Hysteria2 的客户端都支持同样的 URI 扩展，导入后仍要看节点参数。
• CA 模式不添加 insecure，验证域名必须正确。
• IPv6 地址在 URI 中需要方括号，面板会按地址类型处理，不要随意删改。

原教程涉及 NekoRay/NekoBox 的导入方式保留为兼容说明，不把项目名称当作“当前仍受维护”的保证；具体导入能力以所用版本为准。

3. 使用原生 Hysteria2 YAML

菜单 2 会给出类似片段：

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

server: '203.0.113.10:8443'
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 配置，适用于原生内核或支持这种自定义配置的图形客户端，不是 Clash/Mihomo YAML，也不是 Sing-box JSON。

不要直接照抄示例 IP、密码和指纹。socks5/http 是客户端本机监听端口，和 VPS 的 UDP 8443 不同；客户端已有程序占用 1080/8080 时，需要调整本机监听端口。

九、Android / iOS：Sing-box 片段与完整模板

1. 已有配置：添加 Outbound

菜单 2 导出的片段类似：

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": 8443,
  "up_mbps": 50,
  "down_mbps": 200,
  "password": "请使用面板实际输出的密码",
  "tls": {
    "enabled": true,
    "server_name": "bing.com",
    "insecure": true,
    "certificate_public_key_sha256": [
      "请使用面板实际输出的公钥指纹"
    ]
  }
}

它只是一个出站对象，应合并到已有配置的 outbounds 数组，不是完整配置文件。合并时留意 proxy 标签冲突、DNS、路由以及规则下载的出站引用。

自签模式的公钥固定字段要求 Sing-box 1.13.0+。CA 模式以面板实际输出为准，不需要照抄上面的 insecure: true。

2. 新建配置：使用完整模板

进入 菜单 7，复制从第一个 { 到最后一个 } 的完整 JSON，在客户端新建本地配置并导入；不要把终端彩色提示、标题或分隔线一起复制。

当前完整模板要求 **Sing-box 1.14.0+**，包含：

• TUN 入站；
• Hysteria2 proxy 和 direct 出站；
• 新格式 DNS、route.default_domain_resolver；
• 国内域名/IP 与广告规则集；
• 通过代理下载远程规则集；
• 自签模式的证书公钥固定；
• 规则集缓存。

手机还需要授予客户端 VPN 权限；桌面端使用 TUN 时也需要对应系统权限。已有其他 VPN 时先确认冲突，不要把应用启动成功直接等同于接管了系统流量。

3. 旧模板与当前模板的区别

原文中“继续使用 download_detour、不要提前替换”的说明已经过时。当前项目通过：

• 顶层 http_clients 创建 rule-set-proxy；
• 在该 HTTP client 中使用 detour: proxy；
• 用 route.default_http_client 指定规则集下载入口。

这些字段属于当前完整模板的一部分，不能只改一个字段名、漏掉对应对象，也不能把 1.14 模板直接交给旧内核。新格式说明见 Sing-box 默认 HTTP client。

遇到 unknown field 或配置版本错误，先升级到支持的内核或选择与旧内核匹配的配置，不要把证书固定字段删掉来“修复”。

4. 节点能连接，但域名无法解析

依次检查：

1. 使用的是菜单 7 的当前完整模板，还是合并后缺少 DNS/路由的 Outbound。
2. 远程 DNS cf 是否通过 proxy，dns.final 和 route.default_domain_resolver 是否指向它。
3. route.default_http_client 指向的 HTTP client 是否存在、其 detour 是否为有效的 proxy。
4. 国内 DNS local 是否被错误配置为 detour: direct。
5. 远程规则集是否成功下载，设备自身网络是否可达服务器。

项目模板中，本地 DNS 使用如下对象，不额外指定 detour: direct：

1
2
3
4
5

{
  "type": "udp",
  "tag": "local",
  "server": "223.5.5.5"
}

旧写法可能触发 detour to an empty direct outbound makes no sense。不要删除远程 DNS 或公钥固定参数来绕过启动错误，优先重新导出完整模板。

当前模板的 DNS 策略为 ipv4_only，不是通用双栈分流方案；IPv6-only 或自定义双栈需求，应结合客户端环境调整，不要假定所有网络都能直接使用默认模板。

十、诊断、日志与服务管理

1. 菜单 8：环境诊断

检查内容包括：

• 内核是否安装、版本是否达到安全基线和项目推荐值；
• systemd 开机自启和当前状态；
• config.yaml、meta.info 是否存在且可解析；
• UDP 端口监听；
• CA/自签模式与自签证书、私钥文件；
• 公网 IP 探测结果与元数据地址是否一致。

结果分为 OK、WARN、FAIL，并给出“结论 → 建议 → 命令”。WARN 不一定只是小问题：低于内核安全基线的情况也会显示为 WARN，需要阅读具体说明。

当前面板将 Hysteria2 2.9.2 作为安全基线，推荐 2.12.3 或更高版本；这些值会随项目维护更新。内核 2.12.3 修复了 HTTP 代理明文传输约 10 秒断开，以及 Linux 端口跳跃规则误重定向出站 UDP 等问题，见 官方发布说明。

诊断不是公网端到端连接测试。公网探测失败后，面板可能退回本机地址，并明确提示“未确认公网可达”；NAT/内网节点不能把导出的私网地址直接当作公网连接地址。

2. 菜单 9：最近报告

当前诊断使用带随机后缀的独立文件，避免同秒覆盖：

1
2

/tmp/hy2-diagnose-YYYYMMDD-HHMMSS.随机字符.log
/tmp/hy2-diagnose-latest.log

第一条是本次报告，第二条是最近一次快捷路径。菜单 9 查看最近报告；最新路径更新失败时，应使用终端显示的本次文件路径。

报告仅允许运行用户读写，但“私有权限”不等于分享前已经脱敏。/tmp 也不是长期备份位置，需要保存的报告另行存放。

3. 菜单 4：实时日志

1

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

按 Ctrl+C 停止跟踪。只看最近记录、不跟踪：

1

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

4. 菜单 3：服务管理

子菜单提供启动、停止、重启和状态查看，对应命令：

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

这里是速查，按需执行一条，不是让你把启动、停止、重启全部连续执行。systemctl restart 返回成功也可能随后退出，仍需查看实际状态与日志。

十一、手动备份、自动快照与恢复

1. 手动备份入口

修改端口、密码、SNI 或证书模式前，进入 菜单 10：

1
2
3
4

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

备份目录：

1

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

备份保存 config.yaml、存在的 meta.info，以及自签模式的 server.crt、server.key。自签证书或私钥缺失时，面板会取消这次备份，而不是声称已有完整备份。

这不是整台 VPS 的备份，也不包含所有系统、云安全组、ACME 状态或客户端配置。重要备份应另存到安全位置，含私钥和密码的备份按敏感文件管理。

2. 自动快照不等于长期备份

配置变更和手动恢复前，当前版本会先保存四文件自动快照，并记录原本不存在的文件状态。快照完整后才更新 runtime.current 指针，失败时保留旧快照。

自动快照用于恢复本次操作前状态；后续操作可能替换它，不能当成无限版本历史。不要手工随意修改 runtime.current 或混合复制不同时间的证书、私钥和元数据。

3. 恢复最近手动备份

“菜单 10 → 2”恢复的是最近一份手动备份，不是任选历史版本的文件选择器。

恢复前先保存当前状态；恢复后重启服务并检查两秒后的状态，失败时尝试回滚到恢复前的文件。出现“自动回滚失败”时需要立即查看日志和配置，不能假设旧节点一定已经恢复。

如果恢复回旧证书或旧密码，客户端也必须使用对应的连接参数；文件恢复成功不等于客户端配置已经同步更新。

菜单 5 的完全卸载会删除整个 /etc/hysteria，包括这里的备份。卸载前先把需要保留的备份复制到该目录之外。

十二、旧版迁移与日常更新

1. 从 Hysteria2-LuoPo 旧版迁移

项目于 2026-08-31 更名为 hy2ctl。当前仍保留 hy2.sh 发布文件和 hy2 快捷命令，现有节点不需要仅因更名就重新配置证书。

旧版教程常见误区：

• 旧仓库 hysteria2-luopo 已不是本文使用的安装入口。
• 旧版“菜单 1 安装内核、菜单 2 配置节点”不能套到当前菜单。
• 旧版“菜单 12 更新面板”已经收纳进当前“菜单 11 → 2”。
• 新安装默认端口变为 8443、带宽变为 50/200 Mbps，不代表升级会把现有节点强制改成这些值。

迁移建议：

1. 在旧面板按功能名称找到“配置备份与恢复”，先备份；旧版编号可能不同。
2. 更新面板后退出，再运行 hy2，确认进入新的菜单界面。
3. 不需要变更节点时，不要为了升级说明而重新执行自签配置。
4. 按需更新内核，再重新导出需要更新的客户端模板。

变更依据见 项目更新记录。

2. 更新 Hysteria2 内核

使用“菜单 11 → 1”。更新的是通信程序，完成后查看 hysteria version、服务状态和客户端连接。

内核更新可能重启服务，维护前考虑短暂中断。配置自动回滚不是内核版本回滚，不能把更新内核与改 YAML 当作同一种保护范围。

3. 只更新面板

使用“菜单 11 → 2”，面板会：

1. 从当前项目下载 hy2.sh。
2. 检查脚本结构、版本格式和 Bash 语法。
3. 备份已有 /usr/local/bin/hy2。
4. 使用临时文件替换目标面板；写入失败时尝试恢复备份。

面板备份路径类似 /usr/local/bin/hy2.bak.时间戳.随机字符。更新后退出旧进程，再执行：

1

hy2

仅更新面板不主动重签节点证书，也不等于更新了 Hysteria2 内核。

4. 面板无法打开

先确认路径和错误信息；需要重新部署时可再次运行当前仓库安装器：

1

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

这不是“只更新面板”的命令：它还会自动安装或更新内核。安装器不主动删除现有节点配置，但维护前仍建议保存备份，不要用反复重装代替排障。

十三、重要文件与常见问题

1. 文件路径速查

服务单元可能被 drop-in 或发行版配置覆盖，查看实际定义使用：

1

systemctl cat hysteria-server.service

config.yaml、meta.info、私钥、客户端输出和备份都可能包含敏感信息，不要公开原文件。

2. 客户端连接超时

按顺序看：

1. 云安全组与 VPS 防火墙是否放行同一 UDP 端口。
2. 服务是否运行，监听地址和端口是否正确。
3. 客户端地址、端口、密码和 SNI 是否与菜单 2 对应。
4. 自签固定参数是否保留，实际客户端内核是否支持。
5. NAT 映射、公网地址或客户端 IPv4/IPv6 连通性是否正确。
6. 当前网络是否限制 UDP/QUIC。

1
2
3

systemctl status hysteria-server.service --no-pager -l
ss -lunp 'sport = :8443'
journalctl -u hysteria-server.service --no-pager -n 100

TCP 端口测试成功不能证明 UDP 节点连通，也不要只用 ping 结果下结论。

3. 端口被占用

1
2
3

ss -lunp 'sport = :8443'
ss -lntp 'sport = :80'
ss -lntp 'sport = :443'

第一条检查节点 UDP，后两条检查常见 ACME 挑战 TCP 端口。先确认占用服务用途，再决定换端口或调整服务，不要随意结束系统进程。

4. 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

先定位哪个目录或文件阻止访问，不要直接 chmod -R 777。重新通过菜单 1 生成配置可以重新应用面板权限逻辑，但会重写节点，自签时还会重签证书；先备份并准备重新导入客户端。

5. CA 申请失败

查看 DNS、错误 AAAA、挑战端口占用、系统时间及菜单 4 的日志。面板默认的自动申请依赖当前环境，不代表替你配置了 DNS 或云防火墙。

6. 自签节点突然不能连接

先确认是否重新配置、重签或恢复了旧证书。执行菜单 2，重新复制完整链接或 Outbound，更新客户端旧节点；pinSHA256、pcs、certificate_public_key_sha256 都应来自同一份当前证书。

仅升级面板通常不会重签证书，因此不要看到“更新后不能连”就直接认定是指纹变化，也要检查内核、端口和客户端导入结果。

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

通常是证书缺失、损坏，或者证书/公钥指纹读取失败。先用菜单 10 备份可用内容，检查证书文件；需要重签时再进入菜单 1。

不要删掉导出校验或只开启 insecure 来绕过保护。重签后重新导入所有客户端。

8. 手机休眠或切换网络后断联

检查内核版本，按菜单 8 建议通过菜单 11 更新；同时查看客户端的后台运行、电池限制和 VPN 权限。

Hysteria2 2.12.2 引入 quic.disableStatelessReset 兼容开关。面板不默认关闭 Stateless Reset，不建议把它当作通用“稳定性优化”；仅在确认特定环境冲突时按内核文档排查。

9. 提交 Issue 前准备什么

提供：

• 操作系统、面板版本、Hysteria2 内核版本；
• 客户端名称及实际内核版本；
• CA 或自签模式；
• 可复现步骤与报错；
• 脱敏的诊断报告、最近 20 行服务日志。

1

journalctl -u hysteria-server.service --no-pager -n 20

截图和报告先检查密码、私钥、完整分享链接、邮箱及不希望公开的 IP/域名。不能因为日志来自诊断菜单就默认已经脱敏。

十四、安全维护与完全卸载

日常维护建议：

• 长期使用优先考虑 CA 域名证书。
• 自签模式保留证书固定，不混用不同客户端的固定值。
• 改配置前创建手动备份，重要备份另存。
• 面板和内核分别更新，客户端内核也要保持受支持版本。
• 下载 Release 附件时，可以使用同版本 SHA256SUMS 检查完整性；校验摘要不等于证明下载来源可信。
• 不把未知脚本覆盖到 /usr/local/bin/hy2，不公开菜单 2 的完整输出。

完全卸载使用 菜单 5。确认后会停止并禁用服务，删除内核、节点配置目录、默认服务文件及面板命令。

卸载会删除 /etc/hysteria 中的配置、证书和备份，不能靠菜单恢复。先将需要保留的文件存到该目录之外，再确认；脚本未必会清理你手工配置的安全组、防火墙规则或其他外部服务，需要自行按实际配置处理。

十五、给开发者：模块化源码，单文件部署

当前仓库已经模块化。**不要手工修改生成版 hy2.sh**；业务逻辑在 src/ 中维护，通过构建生成供 VPS 安装的单文件。

主要目录：

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

src/
  bootstrap.sh       版本、路径和默认值
  core/              输入校验、编码、文件、网络与元数据
  hysteria/          安装、证书、配置、权限、快照与回滚
  clients/           分享链接、YAML 和 Sing-box 模板
  operations/        诊断、手动备份与恢复
  panel/             菜单、服务控制与面板更新
  main.sh            启动入口
scripts/             构建、验证和工程辅助工具
tests/               单元测试、回放与 VPS 验收清单
docs/                架构、开发和发布文档
hy2.sh               自动生成的单文件发布版
install.sh           安装入口

开发环境克隆并进入项目：

1
2

git clone https://github.com/LuoPoJunZi/hy2ctl.git
cd hy2ctl

修改对应模块后，再构建和检查：

1
2

bash scripts/build-panel.sh
bash scripts/verify.sh all

验证范围包括语法、ShellCheck、源码与生成版一致性、菜单/版本/入口同步、发布包检查、Bats、配置与导出回放、快照回滚及运行时边界等。测试依赖属于开发环境，不是 VPS 面板新增的运行依赖。

版本来源为 src/bootstrap.sh 的 sh_ver，采用日期版本号。发布工作流与附件校验见 发布文档；推送成功不等于 Release 成功，模拟测试通过也不能替代 独立 Linux VPS 验收。

结语

首次部署，记住当前流程：安装器自动部署面板与内核 → 菜单 1 配置 → 菜单 2 导出 → 菜单 8 诊断。

已有可用节点，先备份，再区分面板更新、内核更新和重新配置。遇到问题，先看服务状态、UDP 监听、证书固定和日志，不要反复卸载重装。

项目仍在维护。欢迎在 GitHub Issues 提交可复现的问题和脱敏后的诊断信息。