穿透运维

本文介绍面板的「穿透运维」——让没有公网 IP 的服务器接入面板。

功能简介

对于完全没有公网可达地址的设备（内网机器、NAT 后设备、Android 手机等），无法直接 SSH 连接。穿透运维通过反向隧道让这些设备主动连到面板服务器，之后你就能像操作普通服务器一样操作它们。

原理

• 面板服务器（有公网 IP）运行一个隧道服务
• 目标设备上装一个轻量 Agent，主动「拨出」连接到面板服务器
• 连接建立后，面板即可通过这条隧道反向 SSH 到目标设备

适用场景

• 管理家里的内网设备（树莓派、NAS、软路由）
• 管理没有公网 IP 的便宜 VPS（NAT 服务器）
• 管理 Android 手机（Termux 环境）

使用方法（三步）

1. 打开「穿透运维」，点击「一键安装脚本」，生成一条独立命令

2. 把命令贴到目标设备上跑一次（自动安装 Agent + 设置开机自启）

3. 约 10 秒后，面板自动出现该设备，即可 SSH 连接、使用全部功能

> 安装命令已刻意做短，方便在还没装好时手动打字：

> - Linux（curl）：curl -sSL http://服务器:5501/i/<令牌> | sudo bash

> - Termux：curl -sSL http://服务器:5501/t/<令牌> | bash

> - 已是 root 可去掉 sudo；Alpine 用 wget -qO- … | sudo bash，BSD 用 fetch -o - … | sudo bash

> 短路径 /i/（通用）和 /t/（Termux）会从安装令牌自动取出服务器地址，无需在命令里手填 IP。

>

> 安装位置：Linux 默认装 /opt/sshe-agent（/opt 缺失或不可写时脚本自动回退到 ~/sshe-agent，不会报错）；Termux 用 ~/sshe-agent（跟随 Termux 启动）。

>

> 连接免密：装完后面板会用预先注入的密钥免密连接该设备，无需每次输密码。

Agent 支持的环境

> ⚠️ macOS 暂不支持：macOS 各版本的 SSH 认证差异大（PAM / 签名算法等），无法保证跨版本稳定连接，故本版本移除 macOS 支持。请使用 Linux / Termux 设备接入穿透运维。

Agent 在线状态

• 在线：隧道连接正常，可随时操作
• 离线：设备断开（关机、网络断了、Agent 停了）。离线记录会保留一段时间，重连后自动恢复在线

> 📌 服务器卡片判定：穿透设备的「在线/离线」由 Agent 心跳 决定，不在线时直接判定离线，

> 避免每个健康检查干等 SSH 超时。Agent 在线后，会通过隧道动态建代理 SSH 采集真实健康数据

> （负载/内存/磁盘/运行时长/电池/温度），与普通服务器一致。仅当隧道 SSH 采集失败时才降级用 Agent

> 上报的概要兜底，且不因此误判离线。（旧 Agent 若不上报概要，降级态健康数据可能为 -，但卡片仍显示在线。）

注意事项

1. Agent 是面板唯一需要在目标设备上安装的程序（与「零足迹」理念的例外）。因为无公网 IP 的设备无法被主动连接，只能由它主动连出来。

2. Agent 占用的资源极小（一个 Python 进程 + 一条长连接）。

3. Agent 使用加密隧道传输，通信安全。

4. 如果设备 IP 变化或 Agent 失效，重新跑一次安装脚本即可恢复。

与端口穿透的关系

穿透运维负责「把设备接进来」，端口穿透 负责「把设备上的应用端口暴露到公网」。两者配合：先用穿透运维接入无公网设备，再用端口穿透把它的应用（如 Navidrome、Nextcloud）映射到面板服务器的公网端口。