원격 개발 및 관리

이 가이드는 두 가지 내용을 다룹니다: 로컬 VelaTerm을 다른 장치에 열어주는 방법과, 원격 머신에 연결하여 그곳에서 세션을 개발하고 관리하는 방법입니다.

1. 두 가지 진입점, 두 가지 방향

두 가지 원격 기능은 모두 제목 표시줄의 오른쪽(테마 전환기 옆)에 있습니다:

지구본 아이콘은 **원격 액세스(브라우저)**입니다 — 이 기능을 사용하면 휴대폰, 태블릿 또는 다른 컴퓨터가 브라우저를 통해 사용자의 VelaTerm에 접근할 수 있습니다. 화살표 아이콘은 원격 서버에 연결 기능으로, 이 기능을 사용하면 현재 컴퓨터가 클라이언트 역할을 하여 다른 머신에서 개발 작업을 수행할 수 있습니다. 서버가 실행 중일 때 지구본 아이콘이 녹색으로 점등됩니다.

2. 이 컴퓨터를 열기(원격 액세스)

2.1 서버 시작하기

지구본 아이콘을 클릭한 다음 포트(기본값 8799 — 이미 사용 중이면 변경)와 접근 비밀번호를 설정한 뒤 ‘서버 시작’을 클릭합니다:

어떤 장치든 접속하려면 접근 비밀번호가 필요합니다. 이 비밀번호는 서버가 실행 중일 때만 유효하며, 서버가 종료된 후에는 다음에 새로운 비밀번호를 설정해야 합니다.

2.2 장치 연결하기

서버가 실행되면 패널에 상태, 인증서 지문, 그리고 자동으로 생성된 페어링 링크가 표시됩니다:

연결하려면 페어링 링크를 자신의 장치로 전송합니다(AirDrop, 자신에게 메시지 보내기 등 어떤 방법이든 가능함). 그 링크를 브라우저에서 열고 접근 비밀번호를 입력합니다. 이 링크에는 암호화된 페어링 자격 증명이 포함되어 있으며, 브라우저와 서버 간의 트래픽은 종단 간 암호화됩니다. 알아두어야 할 두 가지 사항이 있습니다:

• 이 링크는 일종의 키입니다. 반드시 자신의 장치들과만 공유해야 합니다. 링크가 유출된 것으로 의심되면 ‘링크 재생성’을 클릭하면 기존 링크는 즉시 무효화되고, 모든 연결된 장치들은 새 링크를 사용할 때까지 연결이 끊깁니다.
• 처음 연결할 때 브라우저는 신뢰할 수 없는 인증서에 대해 경고를 표시합니다. 이는 자체 서명된 인증서의 일반적인 현상입니다. 브라우저에 표시된 지문과 패널에 있는 인증서 지문을 비교해 보세요. 둘이 일치하면 자신의 장치와 통신하고 있는 것입니다.

여러 네트워크 인터페이스(유선, Wi-Fi, VPN)가 있는 경우, 패널에는 선호하는 주소가 표시되고 나머지 주소들은 “1개 더 있는 URL” 항목 아래에 표시됩니다. 연결하는 장치와 같은 네트워크에 있는 주소를 선택하세요.

휴대폰에서 동일한 링크를 열면 자동으로 모바일 레이아웃으로 전환됩니다(2단계 네비게이션과 터미널 키바가 표시됨). 별도의 설정이 필요하지 않습니다.

2.3 브라우저 측면의 사용 환경

연결된 장치에서 보는 로그인 페이지와 메인 UI:

브라우저 클라이언트는 데스크톱과 동일한 실시간 세션을 공유합니다. 동일한 트리 구조, 동일한 터미널 출력이 제공되며, 양쪽 모두 입력할 수 있고 실시간으로 상대방의 작업을 확인할 수 있습니다. 창 배열(열린 탭, 분할 등)은 각 클라이언트별로 독립적으로 결정됩니다.

터미널 크기에는 “소유자” 개념이 적용됩니다. 여러 클라이언트에서 하나의 세션이 열려 있을 경우, 크기는 소유자의 터미널 크기를 따르며, 다른 클라이언트들은 축소된 미러 화면을 보게 되고 화면 상단 오른쪽에 “미러 … 이 창에 맞추려면 클릭”이라는 표시가 나타납니다(위 스크린샷 참조). 이 버튼을 클릭하면 현재 창의 크기를 직접 조정할 수 있습니다.

2.4 장치 관리

패널의 ‘페어링된 장치’ 목록에는 연결된 모든 장치가 표시됩니다:

장치를 차단하려면 해당 장치 옆의 ‘차단’ 버튼을 클릭한 뒤 확인합니다. 그러면 해당 장치는 즉시 연결이 끊기고 다시 연결할 수 없습니다(새로운 페어링 링크가 필요함). 다른 장치들은 영향을 받지 않습니다. 장치 이름은 각 클라이언트가 자체적으로 보고하는 것이므로, 이를 정체성이 아닌 단순한 라벨로 간주해야 합니다. 모든 장치를 한 번에 차단하려면 ‘링크 재생성’을 사용하세요.

2.5 서버 중지하기

패널 하단에 있는 ‘서버 중지’를 클릭합니다. 브라우저 클라이언트들은 연결이 끊기지만, 실행 중인 세션들은 영향을 받지 않습니다. 이 세션들은 데스크톱 앱 자체에 속하기 때문입니다.

3. 외부로 연결하기(원격 서버에 연결)

제목 표시줄에 있는 연결 버튼을 클릭하면 패널에 SSH 모드와 URL 모드가 제공됩니다.

3.1 SSH 모드: 원격 환경에 필요한 것은 SSH뿐입니다

VelaTerm 구성 요소가 설치되어 있지 않은 원격 개발용 장치(일반적으로 Linux 또는 macOS)의 경우, 연결 시 전체 프로세스가 자동으로 실행됩니다. 원격 머신의 OS와 아키텍처를 확인한 뒤, 해당 환경에 맞는 vela-server를 전송하고 지속적으로 실행되도록 설정한 뒤, 로컬 포트 포워딩을 설정하고 원격 창을 열어 자동으로 로그인합니다.

user@host[:port] 값을 입력한 뒤 ‘연결’을 클릭합니다. 알아두면 유용한 세부 사항들이 있습니다:

**처음 연결할 때 호스트 키 확인.**새로운 호스트는 확인을 위해 자신의 SSH 호스트 키 지문을 표시합니다. “지문이 일치합니다. 연결”을 클릭하면 해당 호스트는 known_hosts 파일에 저장되어 더 이상 확인 메시지가 표시되지 않습니다. 만약 기존 호스트의 지문이 변경된 경우, 패널이 빨간색으로 변하므로 그 이유를 확인한 뒤(OS 재설치, 다른 머신 사용, 링크가 조작된 경우 등) 다시 확인해야 합니다.

**인증.**기존의 SSH 설정(ssh-agent, ~/.ssh/config, 키 등)이 자동으로 재사용됩니다. 공개 키 인증에 실패할 경우에만 비밀번호 입력 창이 나타납니다. “비밀번호 기억” 옵션을 선택하면 비밀번호가 시스템 키체인에 저장되어(데이터베이스에는 저장되지 않음) 다음에도 자동으로 사용됩니다.

데이터 모드: "원격 데스크톱 앱의 데이터베이스 사용". 선택 해제된 상태(기본값)에서는 원격 서버가 해당 컴퓨터에 설치된 어떤 VelaTerm 데스크톱 앱과도 완전히 분리된 독립적인 데이터 디렉터리(~/.velaterm/data)를 사용합니다. 선택된 경우에는 원격 데스크톱 릴리스 빌드의 데이터베이스가 사용되어 양쪽 모두 동일한 세션 트리를 볼 수 있으며, 이는 "그 컴퓨터에서 VelaTerm 일상적으로 작업하고 저는 원격으로 동일한 프로젝트를 처리하는 경우"에 적합합니다. 공유되는 것은 디스크상의 데이터베이스 파일이지 실행 중인 프로세스는 아닙니다(§4.1 참조); 양쪽을 동일한 버전으로 유지하는 것이 권장됩니다.

최근 호스트. 연결했던 호스트들이 목록으로 표시되며, 하나를 클릭해도 입력란만 채워질 뿐 자동 연결은 되지 않습니다 — 확인한 후 연결을 누르세요. 열쇠 아이콘은 저장된 비밀번호를 의미하며, ×는 해당 호스트(및 저장된 비밀번호)를 삭제합니다.

연결 진행 상황. 처음 연결할 때는 서버 바이너리(수십 MB)가 전송되며, 버튼에는 백분율과 함께 준비 중/전송 중이라는 표시가 나타납니다. 재연결 시에는 이미 원격에 있는 서버가 재사용되어 훨씬 빠릅니다.

3.2 URL 모드: 상대방이 이미 원격 접근을 사용 중인 경우

다른 컴퓨터의 VelaTerm에서 원격 접근이 실행 중이고(§2) 그 컴퓨터의 페어링 링크를 가지고 있는 경우에 사용됩니다. 일반 브라우저에서 링크를 열 때와 달리 전용 창이 제공되며, 키체인 기반의 자동 로그인과 앱이 처리하는 지문 인증 기능이 있습니다.

페어링 링크를 붙여넣고, 상대방에서 설정한 접근 비밀번호를 입력한 후 연결을 누르세요. 첫 연결 시에는 TLS 인증서 지문을 확인합니다(상대방 패널에 표시된 인증서 지문과 비교); 그 이후에는 동일한 지문이면 바로 연결됩니다. 비밀번호도 시스템 키체인을 통해 동일한 방식으로 저장됩니다.

4. 연결 해제, 창 닫기 및 남아 있는 내용

4.1 세 가지 상태 계층

"연결이 해제된 후에도 데이터가 그대로 남아 있는지"는 어떤 계층에 대해 묻는지에 따라 달라집니다:

처음 두 계층은 구조상 안전합니다. 고려해야 할 유일한 계층은 세 번째 계층입니다: 원격 서버 프로세스가 살아있는 한 사용자의 실행 중인 세션도 계속 존재합니다.

4.2 창을 닫는 것의 의미

SSH 모드: 이 연결을 통해 원격 서버가 시작되었으며 사용자 소유이므로, 창을 닫으면 어떻게 할지 묻습니다 — "서버 중지"를 선택하면 원격 쪽에서 서버가 종료되어 실행 중인 세션이 종료됩니다; "계속 실행"을 선택하면 사용자 쪽만 연결이 끊어지고 서버는 계속 작동하여 다음 연결 시 모든 세션이 그대로 유지됩니다. 사용자가 자리를 비운 동안에도 에이전트가 계속 작동하게 하려면 "계속 실행"을 선택하세요.

URL 모드: 이미 그곳에서 실행 중이던 프로그램의 게스트로 참여한 경우입니다. 창을 닫는 것은 단순히 사용자가 떠나는 것을 의미하며, 상대방은 계속 작동하고 사용자가 돌아오면 모든 것이 그대로 남아 있습니다.

4.3 연결 끊김 및 재연결

네트워크 문제가 발생하면 원격 창 상단에 빨간색 재연결 바가 나타나 자동으로 재시도가 이루어집니다; 실행 중인 세션은 영향을 받지 않습니다 — SSH 모드에서는 원격 서버가 SSH 세션과 분리되어 있어(설계상 네트워크 끊김에도 견딜 수 있음) 문제가 없습니다.

알아두어야 할 한 가지 한계점은, 자동 재연결 기능은 창에서 로컬 포트로의 연결 부분만 처리한다는 것입니다. SSH 터널 프로세스나 원격 서버 자체가 종료된 경우 빨간색 바는 계속 회전할 뿐 재연결 기능은 도움이 되지 않으며, 메인 창으로 돌아가 다시 연결을 눌러야 합니다. 연결 과정에서 원격 서버가 여전히 살아있는지 확인하며, 살아있으면 그대로 재사용되어 세션이 그대로 유지되고, 서버가 종료된 경우에만 새로운 서버가 시작됩니다.

또한, 원격 컴퓨터가 절전 모드에 들어가거나 로그아웃하거나 재부팅하면 SSH 모드의 서버와 그 실행 중인 세션이 종료됩니다; 세션 트리는 디스크에 저장되어 있어 영향을 받지 않습니다.

4.4 간단 참고

5. 보안 모델 개요

비밀번호(SSH 계정 비밀번호, 원격 로그인 비밀번호)는 명시적으로 선택한 경우에만 저장되며, 데이터베이스가 아닌 시스템 키체인에만 저장됩니다. LAN 브라우저 접근은 자체 서명된 인증서를 사용한 TLS를 통해 이루어지며, 페어링 링크에는 종단 간 암호화된 자격 증명이 포함되고, 서버는 페어링되지 않은 평문 연결을 거부합니다. SSH 호스트 키와 원격 TLS 인증서는 처음 사용 시 신뢰 원칙을 따르므로, 이미 알려져 있고 변하지 않은 경우에는 바로 연결되고, 새로운 대상에 대해서는 한 번의 인증 요청이 있으며, 지문이 변경된 경우에는 빨간색 경고가 표시되어 확인 전에 조사해야 합니다. 개별 장치는 언제든지 차단할 수 있으며(§2.4), 페어링 링크는 필요에 따라 재생성할 수 있습니다.

한 가지 더: 원격 창의 제목 표시줄에 빨간색 "⚠ vX ≠ vY" 배지가 표시되면, 사용자의 클라이언트 UI와 원격 서버가 서로 다른 버전을 사용하고 있음을 의미하므로 일부 기능이 정상적으로 작동하지 않을 수 있습니다; 양쪽 모두를 동일한 버전으로 업그레이드하세요.

6. 자주 묻는 질문

**연결은 되었는데 사이드바가 비어 있거나 빨간색 바가 계속 회전하나요?**대부분 SSH 터널이나 원격 서버가 사라진 경우입니다. 창 내에서 재연결하는 것으로는 해결할 수 없습니다(§4.3). 메인 창으로 돌아가 다시 연결해 보세요.

**포트 8799가 시작되지 않나요?**다른 프로그램이 해당 포트를 사용하고 있습니다. 패널에서 다른 포트를 선택한 후 다시 시작해 보세요.

**브라우저에서 인증서가 신뢰할 수 없다고 나오나요?**자체 서명된 인증서의 경우 정상적인 현상입니다. 지문을 확인한 후 계속 진행하세요(§2.2). 브라우저별 경고를 생략하려면 페어링 링크를 통해 접속하면 앱이 자동으로 신뢰 여부를 처리해 줍니다.

**자리를 비운 동안에도 원격 에이전트가 계속 작동하게 하고 싶나요?**SSH 모드에서 “창을 닫아도 계속 실행” 옵션을 선택하면 세션이 원격 쪽에서 계속 진행됩니다. 나중에 다시 연결하면 마지막에 멈춘 부분부터 바로 이어집니다.

**휴대폰에서 터미널이 너무 작게 보이나요?**이는 데스크톱 화면 크기를 따라 자동으로 조정되는 것입니다. 터미널의 우측 상단에 있는 “이 창에 맞게 조정”을 눌러 현재 기기의 화면 크기에 맞게 조정해 보세요.