常见问题
本章主要讲述有关 MSST-Net 的常见问题。
安装与启动
安装客户端后，控制器无法检测到核心？
请检查以下几点：
- 确认客户端核心（
msst-net-client-core）正在运行 - 若配置了系统服务，检查服务状态：bash
sudo systemctl status msst-net - 检查核心进程是否正常启动，查看日志获取错误信息
客户端启动后，未生成设备 ID？
设备 ID 在首次启动时自动生成，通常存储在数据目录（~/MSST-Net/）下的 identity.json 文件中。
若该文件不存在，核心会在启动时自动创建。若仍未生成，请检查核心是否有写入该目录的权限。
连接问题
为什么无法连接到对端设备？
请按以下顺序排查：
- 确认两台设备均已上线：在控制器中查看对端设备的在线状态
- 确认路由中继正常：查看控制器中的连接状态，确认已连接到中继服务器
- 检查防火墙规则：确认目标端口有对应的允许规则，或等待交互式授权弹出
为什么直连没有建立，一直走中继？
直连需要满足以下条件：
- 对端的端点信息已获取
- 连续收到 10 次以上探测回包
- P2P 路径延迟不超过中继路径的 80%
若网络环境（如严格 NAT、对称 NAT）无法穿透，直连可能永远无法建立，流量会始终通过中继转发。这是正常现象，不影响正常使用。
连接延迟很高怎么办？
- 检查当前路径模式：若为直连（Direct），延迟高可能是网络本身问题
- 若为中继模式，可在网络设置中选择距离更近的中继节点（首选中继）
- 检查本机网络质量，排查本机 ISP 或 Wi-Fi 问题
防火墙与授权
为什么连接对端时弹出了授权请求？
当有设备尝试访问本机某端口，且没有匹配的防火墙规则时，系统会触发交互式授权请求。
这是正常的安全机制。你可以选择：
- 允许一次：临时放行，10 分钟后失效
- 始终允许：永久放行，自动创建规则
- 拒绝：拒绝本次或永久拒绝
详见：《交互式授权》
为什么没有弹出授权请求，对端直接连接失败了？
交互式授权只对特定来源的设备触发，陌生设备（既不是本账号设备、也不是近期联系过的设备、也未在规则中引用）的连接请求会被静默丢弃。
若需要允许某陌生设备访问，请先手动创建防火墙规则，或确保两台设备曾在同一房间中。
ping 对端没有响应？
ICMP ping（ping 命令）默认被拒绝。
若需要允许 ping，请在控制器的防火墙设置中启用 ICMP 回显请求（Ping）选项。
标识符与主机名
如何修改设备的显示名称？
在控制器的设置页面，可以修改：
- 设备显示名称（在界面上展示的名字）
- 设备助记符（用于规则引用和 ezPlay 主机名）
修改助记符后，ezPlay 主机名会随之更新。
已认证用户可以修改用户助记符吗？
若已完成接入认证（OIDC 认证），用户助记符由认证账号的用户名派生，由协调器控制，本地修改不会生效。
若尚未认证（免认证模式），可以在控制器中自由修改用户助记符。
ezPlay 主机名解析失败？
请检查以下几点：
- 确认客户端核心正在运行（ezPlay 解析在本地完成）
- 确认目标设备在线，且与本机处于同一网络（大内网或房间）
- ezPlay 主机名仅在 MSST-Net 虚拟网络内有效，不能从公网解析
房间模式
游戏的局域网联机选项搜不到房间？
- 确认两台设备已在同一 MSST-Net 房间内
- 局域网发现功能仅在桌面端（Windows / Linux / macOS）支持，Android 不支持
- 确认游戏使用的是发现支持的协议（Minecraft Java LAN 广播、mDNS 等）
- 部分游戏可能需要手动输入 IP 而非自动发现
离开房间后，虚拟 IP 还有效吗？
有效。设备的虚拟 IP 是由设备 ID 确定性推导的固定地址，与是否在房间内无关，始终有效。
离开房间只是停止局域网发现广播代理，并不影响虚拟 IP 连接。
数据与隐私
设备数据存储在哪里？
客户端数据默认存储在用户主目录下的 MSST-Net 文件夹中：
- Windows / Linux / macOS：
~/MSST-Net/ - 容器部署：
/var/lib/msst/
该目录包含设备身份信息、密钥、配置文件及防火墙规则等。
私钥文件可以迁移吗？
可以。将 ~/MSST-Net/private.key 和 ~/MSST-Net/identity.json 复制到新设备的相同目录，重启核心后即可恢复设备身份。
注意：私钥文件请妥善保管，切勿泄露。泄露私钥将导致他人冒充你的设备。