문서

빠른 시작 + 부분별, 기기별 기능 설명 (계속 업데이트 중)

SSH Everywhere 아키텍처와 기술 스택

> 이 문서는 SSH Everywhere의 전체 아키텍처와 사용된 프로토콜, 기술 스택을 쉬운 말로 설명합니다. 「이게 도대체 어떻게 동작하는가」를 알고 싶은 독자를 위한 글이며, 기술 배경 지식이 없어도 이해할 수 있습니다.

---

한 문장으로 이해하는 전체 프로젝트

SSH Everywhere는 올인원 서버/기기 원격 운영 패널로, 1Panel / BT Panel에 대응합니다. 핵심 역량은 이것입니다: 여러분의 기기가 네트워크 어디에 있든 — 공인 IP가 있든, 공인 IP가 없든(NAT 뒤), 아니면 안드로이드 폰이든 — 이 하나의 패널에서 SSH를 쓰듯 관리할 수 있습니다.

패널 자체는 공인 IP가 있는 서버에 배포되며(0.0.0.0:5501 리스닝) 여러분은 브라우저로 패널에 접속하고, 패널은 다시 다양한 「연결 방식」으로 각 대상 기기에 도달합니다.

---

전체 아키텍처 (그림 한 장으로 이해)

┌─────────────────────────────────────────────────────────────┐
│  브라우저 프런트엔드 (단일 페이지 앱, 데스크톱 OS 모사)          │
│  데스크톱 창 · 작업 표시줄 · 시작 메뉴 · 카드 대시보드            │
│  · 실제 터미널 · 아이콘 라이브러리 · 순수 바닐라 JS (프레임워크 없음) │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTP REST + SocketIO
┌──────────────────────────┴──────────────────────────────────┐
│  패널 백엔드 (Flask + Flask-SocketIO, Python)                 │
│  메인 프로그램 · 리버스 터널 서버 · SocketIO 서버 · 파일 전송     │
│  크래시 보호 · 사이트 관리 · 백업 · SQLite 데이터베이스           │
└───┬───────────────┬──────────────────┬──────────────────────┘
    │ SSH           │ 리버스 터널       │ SocketIO
    │ 직접 연결/터널 경유 │ (0.0.0.0:4433)   │ (HTTP 경유)
    ▼                ▼                  ▼
┌──────────┐  ┌──────────────┐  ┌─────────────────┐
│ 공인 IP   │  │ 공인 IP 없는  │  │ 안드로이드 폰     │
│ 서버      │  │ Linux/NAS/   │  │ (Termux)        │
│          │  │ 라즈베리파이 등 │  │                 │
└──────────┘  └──────────────┘  └─────────────────┘

---

네 가지 연결 방식 (프로토콜)

SSH Everywhere는 내부적으로 4가지 프로토콜을 사용하며, 각기 역할이 나뉘어 서로 다른 유형의 기기를 담당합니다:

1. SSH — 주력 채널

용도: 모든 「일반 Linux 서버」를 관리하는 핵심 기능.

  • 시스템 관리 (개요, 프로세스, 예약 작업, 방화벽, Docker, 사이트, 미러, 크래시 보호)
  • 터미널 (대화형 shell)
  • 파일 관리 (업로드/다운로드/편집/압축)
  • 상태 점검 (CPU/메모리/디스크/온도)
  • 명령 실행

연결 방식:

  • 공인 IP 있음: 패널이 host:port로 직접 연결
  • 공인 IP 없음: 패널이 먼저 리버스 터널로 로컬 프록시 포트를 만든 뒤 SSH로 접속

> 다시 말해 리버스 터널의 본질은 「SSH를 공인 IP가 없는 기기로 배달하는 것」이며, 그래서 SSH가 최종적으로 안착하는 프로토콜입니다.

2. 리버스 터널 프로토콜 — 터널링 채널

용도: 「공인 IP가 없는 기기」를 패널이 닿을 수 있게 합니다. 기기 쪽이 먼저 패널로 「연결을 걸어」 리버스 TCP 상시 연결을 맺으면, 패널이 이 터널로 명령을 내리고 포트를 전달합니다.

특징: TCP 상시 연결 + 암호화(AES-256-GCM), 서버는 0.0.0.0:4433 리스닝.

대표 시나리오:

  • 공인 IP 없는 Linux 서버의 SSH 터널링 운영 (터널 안에서 다시 SSH 실행)
  • 포트 터널링: 기기의 서비스 포트(예: 8090)를 패널의 공인 포트로 매핑

> 헷갈리기 쉬운 개념: 포트 포워딩 vs 포트 터널링

>

> | | 포트 포워딩 | 포트 터널링 |

> |---|---|---|

> | 대상 기기 | 공인 IP가 있는 서버 | 공인 IP가 없는 터널링 기기 |

> | 구현 방식 | 시스템 방화벽 DNAT, 대상 서버 본체에서 수행 | 리버스 터널 경유 |

> | 데이터 흐름 | 접속자 → 대상 공인 IP → 대상 포트 | 접속자 → 패널 공인 포트 → 리버스 터널 → 기기 포트 |

> | 기기 온라인 필요 | 불필요 | 필요 (기기가 Agent를 계속 온라인 유지) |

>

> 한마디로: 「포워딩」은 공인 IP가 있는 서버용, 「터널링」은 공인 IP가 없는 기기용입니다.

3. SocketIO — 안드로이드 폰 전용 채널

용도: 안드로이드 폰의 Termux 관리. 모바일 네트워크의 NAT가 자주 바뀌어 SSH가 불안정하므로, 안정적인 SocketIO 롱폴링 채널을 사용합니다(실기기에서 검증된 성숙한 방식).

폰에서 실행되는 Agent가 SocketIO로 제공하는 것:

  • 시스템 관리 (개요/프로세스/예약 작업)
  • 터미널 (PTY 브리징)
  • 파일 관리
  • 상태 모니터링 (30초마다 보고: 부하/메모리/디스크/배터리/온도)

> 이것은 프로젝트에서 유일하게 「SSH를 쓰지 않는」 채널입니다 — 안드로이드 폰은 sshd를 사용하지 않고 SocketIO 상시 연결을 쓰기 때문입니다.

4. HTTP REST — 프런트엔드와 백엔드 사이

브라우저 프런트엔드는 REST API로 패널 백엔드를 호출하고, 동시에 SocketIO로 터미널 등 실시간 양방향 통신을 처리합니다.

---

세 가지 기기의 접근 경로 한눈에 보기

기기 유형연결 방식최종 안착 프로토콜설명
공인 IP가 있는 Linux 서버패널 직접 연결SSH가장 직접적인 시나리오
공인 IP가 없는 Linux 서버 (NAS/라즈베리파이 등)리버스 터널로 프록시 생성 → SSHSSH (터널 경유 운반)터널은 SSH의 「운반책」
안드로이드 폰 (Termux)SocketIO 롱폴링SocketIO (유일하게 SSH 미사용)폰 전용 안정 채널

---

데이터 저장

  • SQLite 데이터베이스 (data/ssheverywhere.db): 서버 카드, 포트 포워딩, 터널링 기록, 사용자, 작업 등.
  • 파일 시스템: 백업 파일, 터널 키, 정적 리소스.

---

배포 형태

  • 패널: systemd 서비스 ssh-everywhere.service, 0.0.0.0:5501 리스닝.
  • 리버스 터널: 0.0.0.0:4433 리스닝.
  • 대상 기기 측 Agent는 서비스 형태로 상주 (Linux는 systemd / Termux는 termux-services).

---

프로젝트 이름 「SSH Everywhere」에 대하여

프로젝트 이름은 SSH Everywhere이며, 의미는 「SSH처럼 어디서든 관리할 수 있다」입니다. SSH는 프로젝트 전체에서 단연 주력인 연결 방식입니다: 안드로이드 폰이라는 하나의 하위 시나리오를 빼면 나머지 모든 기능(Linux 서버 관리, 터널링 운영, 파일 전송, 상태 점검)이 최종적으로 SSH 위에 안착합니다. 그리고 리버스 터널의 본질 역시 「SSH를 어디든 배달하는 것」입니다. 그래서 「SSH Everywhere」라는 이름은 프로젝트의 핵심 역량을 정확하게 표현합니다.