터널링 운영

이 문서는 패널의 「터널링 운영」을 소개합니다. 공인 IP가 없는 서버를 패널에 연결하는 기능입니다.

한 문장으로

공인 IP가 없는 기기(내부망 머신, NAT 뒤 기기, 안드로이드 폰)는 외부에서 「먼저 접속해 들어갈」 수 없습니다. 터널링 운영은 이런 기기가 먼저 「바깥으로 접속해 나오게」 해 패널 서버에 연결하고, 이후에는 일반 서버처럼 조작할 수 있게 합니다.

기능 소개

공인망으로 도달할 수 있는 주소가 전혀 없는 기기(내부망 머신, NAT 뒤 기기, Android 폰 등)는 직접 SSH 연결할 수 없습니다. 터널링 운영은 리버스 터널을 통해 이런 기기가 먼저 패널 서버에 연결하게 하고, 이후 일반 서버처럼 조작할 수 있게 합니다.

원리

• 패널 서버(공인 IP 보유)가 터널 서비스를 실행합니다
• 대상 기기에 경량 Agent를 설치해 먼저 패널 서버로 「발신」 연결합니다
• 연결이 수립되면 패널이 이 터널을 통해 대상 기기로 역방향 SSH를 수행할 수 있습니다

> 쉽게 말하면: 대상 기기가 패널 서버로 「먼저 전화를 거는」 것이고, 통화가 연결되면 패널이 이 「전용선」을 통해 거꾸로 제어할 수 있습니다.

적용 시나리오

• 집의 내부망 기기(라즈베리파이, NAS, 소프트 라우터) 관리
• 공인 IP가 없는 저렴한 VPS(NAT 서버) 관리
• Android 폰(Termux 환경) 관리

사용 방법(3단계)

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를 사용합니다

>

> 설치 위치: Linux는 기본적으로 /opt/sshe-agent에 설치되며(/opt가 없거나 쓸 수 없으면 스크립트가 자동으로 ~/sshe-agent로 폴백하며 오류를 내지 않음), Termux는 ~/sshe-agent를 사용합니다(Termux 시작 시 함께 실행).

>

> 비밀번호 없는 연결: 설치가 끝나면 패널이 미리 주입한 키로 해당 기기에 비밀번호 없이 연결하므로 매번 비밀번호를 입력할 필요가 없습니다.

Agent가 지원하는 환경

> ⚠️ macOS는 아직 지원하지 않습니다: macOS는 버전별 SSH 인증 차이가 커서 버전 간 안정적인 연결을 보장할 수 없으므로, 이 버전에서는 macOS의 터널링 연결을 제공하지 않습니다. Linux / Termux 기기로 터널링 운영에 연결하세요.

Agent 온라인 상태

• 온라인: 터널 연결이 정상이며 언제든 조작할 수 있습니다
• 오프라인: 기기가 끊긴 상태입니다(전원 꺼짐, 네트워크 단절, Agent 중지). 오프라인 기록은 일정 기간 보관되고 재연결 시 자동으로 온라인으로 복구됩니다

> 📌 서버 카드 판정: 터널링 기기의 「온라인/오프라인」은 Agent 하트비트로 결정됩니다. Agent가 온라인이 되면 터널을 통해 SSH 채널을 동적으로 수립해 실제 상태 데이터(부하/메모리/디스크/가동 시간/배터리/온도)를 수집하며, 일반 서버와 동일합니다.

주의 사항

1. Agent는 패널이 대상 기기에 설치해야 하는 유일한 프로그램입니다(「흔적 없음」 이념의 예외). 공인 IP가 없는 기기는 먼저 접속될 수 없어 스스로 밖으로 접속할 수밖에 없기 때문입니다.

2. Agent가 차지하는 리소스는 극히 작습니다(Python 프로세스 하나 + 긴 연결 하나).

3. Agent는 암호화 터널로 전송하므로 통신이 안전합니다.

4. 기기 IP가 바뀌거나 Agent가 무효화되면 설치 스크립트를 다시 실행하면 복구됩니다.

포트 터널링과의 관계

터널링 운영은 「기기를 연결해 들이는」 역할을 하고, 포트 터널링은 「기기의 앱 포트를 공인망에 노출하는」 역할을 합니다. 둘을 함께 사용합니다: 먼저 터널링 운영으로 공인 IP 없는 기기를 연결한 뒤, 포트 터널링으로 그 앱(예: Navidrome, Nextcloud)을 패널 서버의 공인 포트에 매핑합니다.