Skip to content

Relay Server

Jump to bottom
Sangyong Bae edited this page Sep 3, 2026 · 3 revisions

릴레이 서버 (nexa-beepd)

LAN 밖의 상대와 통신하게 해 주는 선택적 구성 요소. 기본 모드(LAN 직접)에는 서버가 전혀 필요 없다 — 서버는 "다른 네트워크의 상대"를 위해서만 존재한다. 상세 원문: docs/41 설치·운영 가이드 · docs/42 랑데부 동작 원리 · docs/32 ADR-0013 설계 결정

서버가 하는 일 / 절대 못 하는 일

하는 일 못 하는 일(설계로 봉인)
프레즌스 — 회전 RID(하루마다 바뀌는 16B 식별자)로 "이 지문의 사용자가 접속해 있나"만 답한다 대화 내용 읽기 — 모든 대화는 단말↔단말 Noise_XX 종단 암호화. 서버는 암호문 조각만 나른다
랑데부 — 두 단말이 서로의 공인 (IP:포트)를 알도록 관측값을 교환(STUN-lite) 사용자 열거 — 명부가 없다. 회전 RID는 "이미 지문을 아는 사람"만 계산할 수 있다
홀펀칭 조율 — 양쪽이 동시에 UDP를 쏘도록 신호(성공 = 서버는 경로에서 빠짐) 저장 — 메시지·파일·메타 어느 것도 저장하지 않는다(버퍼가 아니라 파이프)
릴레이 폴백 — 펀칭 실패(대칭 NAT 등) 시 암호문을 대신 나른다(연결당 1 MiB/s 기본 상한) 조용한 키 교체 — 서버 키가 바뀌면 클라이언트가 접속을 중단하고 시끄럽게 경고한다(TOFU 핀)

공식 기본 서버

항목 값
주소 beepd.sosomlab.com:47300 (TCP+UDP)
서버 신원(핀) 5c5ee9321439f0292f90f6d7b949e5be3e8dc94cfc6a142208e957bf83c0cb5e

앱(v0.2.4+)의 서버 주소 기본값이라 따로 입력할 것이 없다. 첫 접속 때 표시되는 핀이 위 값과 다르면 접속하지 말 것(사칭·중간자 — 앱이 자동으로 차단·경고한다).

클라이언트에서 연결하기 (v0.2.5)

  1. 설정 › Server → Server mode = Managed, 이어서 [Test]를 한 번 누른다 — 주소·포트는 기본값이 이미 공식 서버다. (v0.2.6+ — 모드 전환·값 변경은 자동 접속하지 않고 Test 성공만이 접속을 연다. 성공은 저장되어 이후 부팅·재접속은 자동. v0.2.4~0.2.5는 Managed 저장만으로 접속.)
  2. 테스트 행 아래 상태 노트가 "✓ Server verified — beepd.sosomlab.com:47300 (key 5c5ee932)" (초록 배경)인지 확인. 접속 중에는 툴바 프로필 왼쪽에 파란 waypoints 표시가 뜬다.
  3. 상대 찾기 — 두 가지 길:
    • 자동 목록(roster · v0.2.5): 설정 "서버 사용자에게 나를 표시"(기본 켜짐)를 둔 사용자끼리는 서버에 붙는 순간 서로 목록에 자동으로 뜬다(공개키만 실린다 · 이름·프로필은 연결 후 교환 · 끄면 목록도 받지 않는 상호 규칙).
    • 지문 직접 연결: 상대의 64자리 지문을 ⌘/Ctrl+K 창에 붙여넣는다. 내 지문은 프로필 우측 상단 [전체 지문 복사](v0.2.5) 또는 nexa-beep --whoami의 full = 줄.
  4. 성립하면 대화 헤더에 상대 아바타·이름과 "서버 경유"(파랑 · v0.2.6+ — 서버 랑데부) 또는 "인터넷 경유"(주황 — IP/도메인 직접 등록) 배지가 뜬다. 메시지는 즉시 가능하고, 파일은 /verify 지문 대조 후에 열린다(인터넷 경유 = 신뢰 경계 밖 — 안전 게이트).

직접 서버 세우기 (자가 호스팅)

어떤 서버든 똑같이 동작한다 — 공식 서버는 편의일 뿐 특권이 없다.

# 패키지 매니저 (beepd-v0.2.5부터)

> 2026-09-03 현황: brew ✓ · winget `SosomLab.NexaBeepd` PR #422579 = 자동 검증 통과(`Validation-Completed`) · 모더레이터 승인 대기 · Chocolatey 모더레이션 대기.
brew install kiros33/tap/nexa-beepd     # macOS(Apple Silicon) · Linux
winget install SosomLab.NexaBeepd       # Windows (중앙 검수 통과 후)
choco  install nexa-beepd               # Windows (중앙 검수 통과 후)

# 또는 릴리스 자산 직접 (Linux는 musl 정적 — 어느 배포판이든 바이너리 하나)
curl -fsSLO https://github.com/SosomLab/nexa-beep/releases/download/beepd-v0.2.5/nexa-beepd-0.2.5-linux-x64.tar.gz
tar -xzf nexa-beepd-0.2.5-linux-x64.tar.gz && sudo install -m 0755 nexa-beepd-0.2.5-linux-x64/nexa-beepd /opt/beepd/nexa-beepd
sudo /opt/beepd/nexa-beepd --port 47300   # 첫 실행 = 키 생성 + "서버 신원(핀)" 출력
  • 방화벽은 TCP·UDP 같은 포트(기본 47300)를 둘 다 연다 — 클라우드 보안 목록과 OS 방화벽(firewalld/ufw) 두 겹 모두.
  • 상주 등록(systemd·작업 스케줄러·launchd), 1GB 무료 VM 체크리스트(OOM 방지), 서버 키 백업(= 사용자 핀 생존): docs/41.
  • 사용자에게 배포할 값은 주소:포트 + 핀 64hex 두 가지다. 클라이언트는 설정 › Server 주소에 그 값을 넣으면 된다(첫 접속 자동 핀 · 이후 불일치 = 차단).

실측 (2026-08-22)

  • 실 NAT 연결 실증: 집(맥) ↔ 회사(윈도우)가 공식 서버 랑데부로 연결 — 서로 다른 공인 IP 뒤에서 성립. 파일 전송도 무해화 게이트를 거쳐 정상 동작.
  • 서버 상주 사양: OCI 무료 티어 1GB VM에서 상주 메모리 수 MB · 바이너리 651KB(musl 정적).
  • 서버 재시작 시 클라이언트가 자동 재접속(백오프) — 키가 보존되는 한 핀도 그대로.

Clone this wiki locally