Founding StoryIf & Else Story
VibeShellVibeShell GatewayVibeShell Hook
How to고객지원
AboutContact
VibeShell Gateway로 돌아가기

// guide

VibeShell Gateway 활용방법

VibeShell Gateway의 아키텍처, 설정, 보안 기능, 운영 방법을 안내합니다.

아키텍처

VibeShell Gateway는 모바일 앱과 SSH 서버 사이에서 보안 프록시 역할을 합니다. Tailscale 네트워크를 통해 포트 포워딩 없이 안전한 연결을 제공합니다.

VibeShell App
    ↓ (Tailscale VPN)
Tailscale Network
    ↓
VibeShell Gateway (:8022)
    ↓ (SSH Proxy)
SSH Server (:22)

듀얼 모드 지원

Tailscale 모드 (tailscale.enabled: true)

Tailscale 네트워크를 통해 연결합니다. 포트 포워딩이 불필요하며, 외부에서 접근할 수 없어 가장 안전합니다.

Direct TCP 모드 (tailscale.enabled: false)

일반 TCP로 직접 연결합니다. 테스트 환경이나 내부 네트워크에서 Tailscale 없이 사용할 때 적합합니다.

gateway.yaml 설정

/etc/vibeshell-gateway/gateway.yaml
server:
  host: "0.0.0.0"
  port: 8022
  health_port: 8080

tailscale:
  enabled: true
  auth_key: "tskey-auth-xxxxx"
  hostname: "vibeshell-gw"

auth:
  pairing_timeout: "5m"
  token_ttl: "24h"
  refresh_window: "1h"

targets:
  - name: "web-server"
    host: "192.168.1.10"
    port: 22
    allowed_users: ["deploy", "admin"]
  - name: "db-server"
    host: "192.168.1.20"
    port: 22
    allowed_users: ["dba"]

access_control:
  max_sessions: 10
  idle_timeout: "30m"

logging:
  level: "info"
  metadata_only: true
server

게이트웨이 리스닝 설정. port는 SSH 프록시 포트(기본 8022), health_port는 헬스체크 HTTP 포트(기본 8080).

tailscale

Tailscale 연동 설정. auth_key는 Tailscale Admin Console에서 생성한 인증 키. hostname은 Tailscale 네트워크에서 보이는 이름.

auth

인증 설정. pairing_timeout은 QR 페어링 유효 시간. token_ttl은 인증 토큰 만료 시간. refresh_window는 토큰 갱신 허용 시간.

targets

접속할 SSH 서버 목록. 여러 서버를 배열로 등록하고, allowed_users로 허용 사용자를 제한합니다.

access_control

접근 제어. max_sessions로 동시 세션 수를 제한하고, idle_timeout으로 유휴 세션을 자동 종료합니다.

logging

로깅 설정. metadata_only: true로 설정하면 세션 메타데이터만 기록하고 실제 데이터는 로깅하지 않습니다.

다중 타겟 서버

targets 배열에 여러 SSH 서버를 등록하면 하나의 게이트웨이로 다수의 서버에 접속할 수 있습니다.

targets:
  - name: "web-server"
    host: "192.168.1.10"
    port: 22
    allowed_users: ["deploy", "admin"]
  - name: "db-server"
    host: "192.168.1.20"
    port: 22
    allowed_users: ["dba"]
  - name: "dev-server"
    host: "10.0.0.5"
    port: 2222
    allowed_users: ["developer"]

allowed_users로 각 서버별 접근 가능한 사용자를 제한할 수 있습니다.

보안 기능

QR 페어링

VibeShell 앱에서 게이트웨이가 생성한 QR 코드를 스캔하여 디바이스를 등록합니다. pairing_timeout으로 QR 유효 시간을 설정합니다 (기본 5분).

토큰 인증

페어링 후 발급되는 인증 토큰으로 세션을 관리합니다. token_ttl은 토큰 만료 시간, refresh_window는 만료 전 자동 갱신 허용 시간입니다.

메타데이터 로깅

metadata_only: true로 설정하면 접속 시간, 사용자, 타겟 서버 등 메타데이터만 기록하고 실제 SSH 트래픽은 로깅하지 않습니다.

헬스체크

상태 확인
curl http://localhost:8080/health
{
  "status": "ok",
  "tailscale": "connected",
  "targets": 2,
  "active_sessions": 1
}

systemd 서비스 관리

서비스 시작sudo systemctl start vibeshell-gateway
서비스 중지sudo systemctl stop vibeshell-gateway
서비스 재시작sudo systemctl restart vibeshell-gateway
상태 확인sudo systemctl status vibeshell-gateway
자동 시작 설정sudo systemctl enable vibeshell-gateway
로그 확인sudo journalctl -u vibeshell-gateway -f

트러블슈팅

Tailscale auth key 만료

Tailscale auth key는 기본 90일 후 만료됩니다. 만료 시 게이트웨이가 Tailscale 네트워크에 연결되지 않습니다.

해결: Tailscale Admin Console에서 새 auth key를 생성하고 gateway.yaml을 업데이트한 후 서비스를 재시작합니다.

포트 충돌

8022 또는 8080 포트를 다른 서비스가 사용 중일 수 있습니다.

# 포트 사용 확인
sudo ss -tlnp | grep -E '8022|8080'

# gateway.yaml에서 포트 변경
server:
  port: 9022
  health_port: 9080

SSH 타겟에 연결 안 됨

게이트웨이에서 타겟 서버까지 네트워크가 연결되는지 확인합니다.

# 타겟 서버 연결 확인
nc -zv 192.168.1.10 22

# 게이트웨이 로그 확인
sudo journalctl -u vibeshell-gateway --since "5 min ago"
VibeShell Gateway 소개VibeShell 소개고객지원