docs: centralize device connection guides, add private relay docs

- new Connect a Device page: one-time QR pairing, transport choices, device management - new Private Relay page: E2EE guarantees, demand-driven lifecycle, relay vs tunnel - rewrite mobile page around the native iOS/Android apps (TestFlight + APK) - update remote-instances, security, tunnels, and remote-access troubleshooting to point at the new pairing flow - translate everything across all 8 locales and update the sidebar
2026-07-10 15:30:50 +03:00
parent b3fa19fe3e
commit 7ea974d89b
64 changed files with 1452 additions and 190 deletions
@@ -0,0 +1,56 @@
+---
+title: 기기 연결
+description: 일회용 QR 코드로 휴대폰, 데스크톱, 다른 브라우저를 OpenChamber 서버와 페어링하세요.
+---
+
+# 기기 연결
+
+일회용 QR 코드를 스캔해 다른 기기(모바일 앱, 데스크톱 앱, 다른 컴퓨터의 브라우저)를 OpenChamber 서버와 페어링하세요. 기기를 연결하는 권장 방법이며, 열어야 할 포트도 입력할 주소도 없습니다.
+
+## 기기 페어링하기
+
+1. OpenChamber가 실행 중인 컴퓨터에서 **Settings → Remote Instances → 이 서버에 연결**을 열고 **기기 추가**를 누릅니다.
+2. 나중에 알아볼 수 있도록 기기 이름(예: *My iPhone*)을 지정합니다.
+3. 기기를 어디에서 사용할지 선택합니다.
+   - **이 컴퓨터 전용** — 같은 컴퓨터에서 실행되는 앱용
+   - **집 네트워크 전용** — Wi-Fi로 직접 연결하며, 이 네트워크 밖에서는 작동하지 않습니다
+   - **어디서나** — 집에서도 밖에서도 작동합니다. 밖에서는 설정이 필요 없는 종단 간 암호화 터널인 [Private Relay](/ko/private-relay/)를 통해 연결됩니다
+4. **QR 코드 만들기**를 누릅니다.
+5. 다른 기기에서 코드를 스캔합니다.
+   - **모바일 앱** — 연결 화면(또는 인스턴스 목록)에서 **QR 코드 스캔**을 탭합니다
+   - **데스크톱 앱** — 대신 연결 링크를 복사해 **Settings → Remote Instances → 다른 OpenChamber 서버 → 링크 가져오기**에 붙여넣습니다
+
+기기가 연결되는 즉시 대화 상자가 자동으로 닫히고, 기기가 실시간 상태와 함께 목록에 나타납니다. 이것으로 페어링 완료입니다.
+
+## 페어링이 안전한 이유
+
+- **QR 코드는 일회용입니다.** 기기가 코드를 사용하는 순간 더 이상 작동하지 않으며, 사용되지 않으면 저절로 만료됩니다.
+- **기기마다 고유한 토큰을 받습니다.** 코드를 스캔해도 UI 비밀번호는 절대 노출되지 않으며, 한 기기의 토큰으로 다른 기기를 사칭할 수 없습니다.
+- **제어권은 항상 사용자에게 있습니다.** 페어링된 모든 기기는 이름, 플랫폼, 연결 상태와 함께 목록에 표시되며, 언제든 어떤 기기든 해지할 수 있습니다.
+- **집 밖 트래픽은 종단 간 암호화됩니다.** **어디서나**를 선택하면 네트워크 밖의 트래픽은 [Private Relay](/ko/private-relay/)를 통해 전달되며, 릴레이는 지나가는 내용을 읽을 수 없습니다.
+
+## 페어링된 기기 관리하기
+
+**Settings → Remote Instances → 이 서버에 연결**에는 이 서버에 접근할 수 있는 모든 기기가 표시됩니다. 온라인이면 초록색 점이, 로컬 네트워크와 릴레이 중 어느 경로로 연결되어 있는지도 함께 표시됩니다.
+
+- **해지**는 기기 접근을 즉시 차단합니다. 마음이 바뀌면 새 QR 코드로 다시 페어링하세요.
+- **해지된 항목 지우기**로 목록을 정리할 수 있습니다.
+
+같은 기기가 나중에 다시 로그인해도 항목은 하나로 유지되므로 중복이 쌓이지 않습니다.
+
+## 명령줄에서 연결하기
+
+서버가 headless(UI가 열려 있지 않음)로 실행 중이면 그 컴퓨터의 터미널에서 연결 링크를 만드세요:
+
+```bash
+openchamber connect-url --port 3000 --qr
+```
+
+출력된 링크와 QR 코드는 설정 대화 상자에서 만든 것과 똑같이 작동합니다.
+
+## 관련 항목
+
+- [Private Relay](/ko/private-relay/) — "어디서나" 연결의 작동 방식과 릴레이가 볼 수 있는 것과 없는 것
+- [모바일 앱](/ko/mobile/) — iOS 또는 Android 앱 설치
+- [원격 인스턴스](/ko/remote-instances/) — SSH나 링크로 데스크톱 앱을 서버에 연결
+- [원격 접속](/ko/troubleshooting/remote-access/) — 기기가 연결되지 않을 때
@@ -1,31 +1,43 @@
 ---
-title: PWA 및 모바일 접속
-description: OpenChamber를 앱으로 설치하고 휴대폰에서 사용하세요.
+title: 모바일 앱 & PWA
+description: iOS 또는 Android에 OpenChamber 앱을 설치하고 서버에 연결하세요.
 ---

-# PWA 및 모바일 접속
+# 모바일 앱 & PWA

-OpenChamber 웹 앱은 휴대폰 앱(PWA)처럼 설치되므로 홈 화면에 두고 전체 화면으로 사용할 수 있습니다. [터널](/ko/tunnels/)과 함께 사용하면 어디서든 세션을 확인할 수 있습니다.
+OpenChamber에는 iPhone과 Android용 네이티브 앱이 있어 휴대폰에서 세션을 지켜보고, 에이전트에 답하고, 작업을 관리할 수 있습니다. 집에서는 Wi-Fi로, 밖에서는 [Private Relay](/ko/private-relay/)를 통해 어디서든 가능합니다.

-## 설치하기
+## 앱 설치하기

-OpenChamber는 브라우저의 내장 설치 기능을 사용하므로 별도의 다운로드가 없습니다.
+- **iPhone/iPad** — [TestFlight 베타](https://testflight.apple.com/join/5ek6GU1E)에 참여하세요
+- **Android** — [최신 릴리스](https://github.com/openchamber/openchamber/releases/latest)에서 APK를 다운로드하세요

- **데스크톱 브라우저** — 주소 표시줄의 **Install** 옵션을 사용합니다
+## 서버에 연결하기
+
+1. OpenChamber가 실행 중인 컴퓨터에서 **Settings → Remote Instances → 이 서버에 연결**을 열고 **기기 추가**를 누릅니다.
+2. **어디서나**를 선택하고(휴대폰을 집에서만 쓸 거라면 **집 네트워크 전용**) **QR 코드 만들기**를 누릅니다.
+3. 모바일 앱에서 **QR 코드 스캔**을 탭하고 카메라를 코드에 향하게 합니다.
+
+앱이 연결되고 서버를 기억합니다. QR 코드는 일회용이며 기기마다 해지 가능한 고유 토큰을 받습니다. 페어링이 안전한 이유는 [기기 연결](/ko/connect-devices/)을 참고하세요.
+
+앱을 여러 서버와 페어링하고 인스턴스 목록에서 전환할 수 있습니다. 앱은 각 서버가 접근 가능한지, 로컬 네트워크와 릴레이 중 어느 경로로 연결되어 있는지 표시합니다.
+
+## PWA (브라우저 설치)
+
+앱 스토어를 전혀 거치고 싶지 않다면? 웹 앱을 브라우저에서 바로 설치할 수 있습니다:
+
+- **데스크톱 브라우저** — 주소창의 **설치** 옵션을 사용하세요
 - **iPhone/iPad (Safari)** — 공유 → **홈 화면에 추가**
 - **Android (Chrome)** — 메뉴 → **앱 설치** / **홈 화면에 추가**

-설치되면 브라우저 크롬 없이 자체 창에서 열립니다.
-
-## 휴대폰에서 접근하기
-
-서버가 사용자의 컴퓨터에서 실행될 때 휴대폰에서 OpenChamber를 열려면 [터널](/ko/tunnels/)을 시작하고 휴대폰에서 링크를 열거나 QR 코드를 스캔합니다. 이렇게 할 때는 항상 강력한 [UI 비밀번호](/ko/security/)를 사용하세요.
+네트워크 밖에서 PWA에 접근하려면 [터널](/ko/tunnels/)과 강력한 [UI 비밀번호](/ko/security/)가 필요합니다. 네이티브 앱은 릴레이를 통해 이를 알아서 처리합니다.

 ## 모바일 설정

-**Settings → OpenChamber** 아래의 몇 가지 옵션은 모바일 및 설치된 경험을 조정합니다. 앱의 설치 이름, 화면 방향, 화면 키보드의 동작 방식이 해당됩니다.
+**Settings → OpenChamber**에서 몇 가지 옵션으로 모바일 및 설치된 앱 경험을 조정할 수 있습니다. 앱의 설치된 이름, 화면 방향, 화면 키보드 동작 등입니다.

 ## 관련 항목

- [Tunnels](/ko/tunnels/) — 다른 네트워크에서 인스턴스에 접근하세요
- [Security](/ko/security/) — 노출하기 전에 UI를 보호하세요
+- [기기 연결](/ko/connect-devices/) — 페어링, 일회용 QR 코드, 기기 관리
+- [Private Relay](/ko/private-relay/) — "어디서나" 접속의 작동 방식
+- [보안](/ko/security/) — 노출하기 전에 UI를 보호하세요
@@ -0,0 +1,44 @@
+---
+title: Private Relay
+description: 포트도, 터널도, 설정도 없이 종단 간 암호화 릴레이로 어디서든 OpenChamber 서버에 접속하세요.
+---
+
+# Private Relay
+
+OpenChamber Private Relay를 사용하면 페어링된 기기가 셀룰러, 카페 네트워크, 다른 도시 등 어디서든 서버에 접속할 수 있습니다. 포트를 열거나 터널을 설정하거나 컴퓨터를 인터넷에 노출할 필요가 없습니다. 릴레이는 스스로 관리됩니다. [기기 연결](/ko/connect-devices/)에서 **어디서나**로 기기를 페어링하기만 하면 됩니다.
+
+## 작동 방식
+
+서버가 OpenChamber 릴레이 인프라로 아웃바운드 연결을 열고 유지합니다. 기기가 네트워크 밖에 있으면 기기도 릴레이에 연결되고, 릴레이가 둘 사이의 암호화된 트래픽을 전달합니다. 컴퓨터에서 인터넷의 인바운드 연결을 수신 대기하는 것은 아무것도 없습니다.
+
+직접 연결이 가능하면(같은 Wi-Fi로 집에 돌아왔을 때) 기기가 직접 연결을 우선하고 릴레이는 완전히 건너뜁니다.
+
+## 릴레이가 볼 수 있는 것과 없는 것
+
+릴레이는 중개자가 아니라 내용을 볼 수 없는 배달부입니다:
+
+- **종단 간 암호화.** 기기와 서버가 서로 직접 암호화 키를 합의합니다. 릴레이는 키가 없는 봉인된 트래픽을 전달할 뿐이며, 코드도 프롬프트도 비밀번호도 읽을 수 없습니다.
+- **사용자의 기기만 연결할 수 있습니다.** 기기는 [일회용 페어링](/ko/connect-devices/)을 통해 *사용자의* 서버가 발급한 토큰을 가지고 있어야 합니다. 누구도 릴레이를 통해 서버를 발견하거나 사용자가 만든 토큰 없이 연결할 수 없으며, 어떤 토큰이든 언제든 해지할 수 있습니다.
+- **페어링 링크는 일회용입니다.** 페어링 QR 코드는 정확히 한 번만 작동하고 사용되지 않으면 만료되므로, 유출된 오래된 링크는 쓸모가 없습니다.
+- **직접 켜기 전까지는 아무것도 공유되지 않습니다.** 릴레이는 사용자가 켜거나 릴레이로 기기를 페어링하기 전까지 꺼져 있으며, 언제든 끌 수 있습니다. 끄면 릴레이를 통해 연결된 기기가 즉시 차단됩니다.
+
+## 언제 실행되나요
+
+릴레이는 자체적으로 수명 주기를 관리하므로 신경 써야 할 스위치가 없습니다:
+
+- **필요할 때 시작됩니다.** **어디서나** 페어링을 만들면 릴레이가 켜지고, 페어링된 기기가 하나라도 릴레이에 의존하는 한 재시작 후에도 다시 올라옵니다.
+- **스스로 멈춥니다.** 릴레이를 사용하는 기기나 대기 중인 페어링이 없어지면(예: 릴레이로 페어링된 마지막 기기를 해지한 뒤) 자동으로 종료됩니다.
+
+**Settings → Remote Instances → OpenChamber Relay**에는 실시간 상태(연결됨, 재연결 중, …)와 현재 릴레이를 통해 연결된 기기 수가 표시됩니다. 같은 곳에서 **끄기**를 눌러 릴레이 접근을 즉시 차단할 수도 있으며, 로컬 네트워크의 기기는 영향을 받지 않습니다.
+
+## 릴레이와 터널, 무엇을 쓸까?
+
+- 페어링된 자신의 기기에서 자신의 서버에 접속하려면 **릴레이**를 사용하세요. 설정이 전혀 필요 없고 아무것도 공개적으로 노출되지 않습니다.
+- 일반 **공개 URL**이 필요할 때는 [터널](/ko/tunnels/)을 사용하세요. 예를 들어 페어링할 수 없는 컴퓨터의 일반 브라우저에서 OpenChamber를 열거나, [UI 비밀번호](/ko/security/) 뒤에서 접근을 공유할 때입니다.
+
+## 관련 항목
+
+- [기기 연결](/ko/connect-devices/) — 일회용 QR 코드로 기기 페어링
+- [모바일 앱](/ko/mobile/) — iOS 또는 Android 앱 설치
+- [보안](/ko/security/) — 비밀번호, 패스키, 노출 기본 사항
+- [원격 접속](/ko/troubleshooting/remote-access/) — 연결이 완료되지 않을 때
@@ -24,9 +24,13 @@ OpenChamber가 연결 확인, 원격 설정, 서버 시작, 포트 포워딩 단

 SSH 및 UI 비밀번호를 저장할지, 매번 입력할지 결정합니다. 연결이 끊기면 OpenChamber가 어느 단계가 실패했는지 알려주므로 고칠 수 있습니다. [Remote access](/ko/troubleshooting/remote-access/)를 참고하세요.

-## 직접 연결 링크
+## 연결 링크

-원격 머신에서 OpenChamber가 이미 실행 중이면 그 머신에서 연결 링크를 만들고 **Settings → Remote Instances → Server links**에서 가져오세요:
+원격 머신에서 OpenChamber가 이미 실행 중이라면 데스크톱 앱을 연결하는 가장 쉬운 방법은 페어링 링크입니다. 원격 서버의 UI에서 **Settings → Remote Instances → 이 서버에 연결 → 기기 추가**를 열어 링크를 만들고, 데스크톱의 **Settings → Remote Instances → 다른 OpenChamber 서버 → 링크 가져오기**에서 가져오세요. 전체 흐름은 [기기 연결](/ko/connect-devices/)을 참고하세요.
+
+**어디서나**로 만든 링크에는 직접 주소와 [Private Relay](/ko/private-relay/) 경로가 모두 들어 있습니다. 데스크톱이 서버에 도달할 수 있으면(같은 네트워크) 직접 연결하고, 밖에 있으면 종단 간 암호화 릴레이로 대체합니다. 저장된 각 서버 옆의 상태에 어느 경로가 사용 중인지 표시됩니다.
+
+원격 머신의 터미널에서도 링크를 만들 수 있습니다:

 ```bash
 openchamber connect-url --port 3000 --server http://your-host:3000 --qr
@@ -34,9 +38,11 @@ openchamber connect-url --port 3000 --server http://your-host:3000 --qr

 해당 포트에 서버가 없으면 `connect-url`이 먼저 서버를 시작합니다. Headless 서버에는 `--api-only`, 시작 시 LAN에 바인딩하려면 `--lan`, 브라우저 접근 보호에는 `--ui-password`, 저장된 연결 이름에는 `--name`을 사용하세요.

-생성된 링크에는 OpenChamber 앱용 client token이 들어 있습니다. 이 token은 브라우저 UI 비밀번호와 별개이며, 취소하거나 삭제하기 전까지 서버 재시작 후에도 유지됩니다.
+생성된 링크에는 일회용 페어링 시크릿이 들어 있습니다. 한 번 가져오면 기기는 브라우저 UI 비밀번호와 별개인 고유 client token을 갖게 되며, 발급한 서버에서 해지하기 전까지 서버 재시작 후에도 유지됩니다.

 ## 관련 항목

+- [기기 연결](/ko/connect-devices/) — 페어링 링크, QR 코드, 기기 관리
+- [Private Relay](/ko/private-relay/) — "어디서나" 연결의 작동 방식
 - [OpenCode Server](/ko/opencode-server/) — 웹이나 VS Code에서 원격 서버에 연결하세요
 - [Remote access](/ko/troubleshooting/remote-access/) — 연결이 완료되지 않을 때
@@ -25,13 +25,20 @@ openchamber --ui-password be-creative-here

 패스키는 현재 비밀번호에 연결됩니다. 비밀번호를 변경하거나 제거하면 저장된 패스키가 삭제되며, 다시 추가해야 합니다.

+## 기기 토큰
+
+[기기 연결](/ko/connect-devices/)로 페어링된 기기는 UI 비밀번호가 아닌 기기별 고유 토큰으로 인증합니다. 페어링 링크는 일회용이며 사용되지 않으면 만료됩니다. 페어링된 모든 기기는 **Settings → Remote Instances → 이 서버에 연결**에 표시되며, 언제든 어떤 기기든 해지할 수 있습니다. 집 밖에서의 연결은 종단 간 암호화되어 트래픽을 읽을 수 없는 [Private Relay](/ko/private-relay/)를 통해 이루어집니다.
+
 ## 노출하기 전에

 - 기본적으로 OpenChamber는 사용자 자신의 컴퓨터(`127.0.0.1`)에서만 수신 대기합니다. 더 넓게 수신 대기하려면 의도적인 변경이 필요하며, 먼저 비밀번호를 설정해야 합니다.
- 인터넷에 포트를 여는 것보다 [터널](/ko/tunnels/)이나 사설 네트워크(예: VPN)를 선호하세요.
+- 자신의 기기라면 [Private Relay](/ko/private-relay/)를 통한 [페어링](/ko/connect-devices/)을 선호하세요. 아무것도 공개적으로 노출되지 않습니다.
+- 공개 URL이 필요하다면 인터넷에 포트를 여는 것보다 [터널](/ko/tunnels/)이나 사설 네트워크(예: VPN)를 선호하세요.
 - OpenChamber를 자체 HTTPS 서버 뒤에 둔다면 [Reverse Proxy](/ko/reverse-proxy/)를 참고하세요.

 ## 관련 항목

- [Tunnels](/ko/tunnels/) — 원격으로 인스턴스에 접근하는 권장 방법
+- [기기 연결](/ko/connect-devices/) — 일회용 페어링과 기기별 토큰
+- [Private Relay](/ko/private-relay/) — 어디서든 가능한 종단 간 암호화 접속
+- [Tunnels](/ko/tunnels/) — 필요할 때 공개 URL 노출
 - [Reverse Proxy](/ko/reverse-proxy/) — 자체 서버 뒤에서 OpenChamber 실행
@@ -12,6 +12,15 @@ description: 터널, 원격 인스턴스, 다른 기기에서 OpenChamber에 접
 - 같은 컴퓨터에서 `http://localhost:3000`을 먼저 엽니다. 이것이 실패하면 원격 문제가 아닙니다. [OpenCode 연결](/ko/troubleshooting/opencode-connection/)을 참고하세요
 - `openchamber status`로 서버가 실행 중인지 확인합니다

+## 페어링된 기기가 연결되지 않음
+
+- QR 코드/페어링 링크는 **일회용**입니다. 이미 스캔되었거나 만료되었다면 **기기 추가**에서 새로 만드세요
+- 기기를 **집 네트워크 전용**으로 페어링했다면 그 네트워크 밖에서는 연결할 수 없습니다. **어디서나**로 다시 페어링하세요
+- **어디서나** 페어링이라면 서버의 **Settings → Remote Instances → OpenChamber Relay**를 확인하세요. **연결됨**으로 표시되어야 하며, 아니라면 껐다가 다시 켜세요
+- 기기가 **해지**되었다면 토큰은 영구히 사라진 것입니다. 새 QR 코드로 다시 페어링하세요
+
+이 연결의 작동 방식은 [기기 연결](/ko/connect-devices/)과 [Private Relay](/ko/private-relay/)를 참고하세요.
+
 ## 터널 링크가 작동하지 않음

 - `openchamber tunnel status --all`을 실행합니다
@@ -34,5 +43,5 @@ OpenChamber를 리버스 프록시 뒤에 두었는데 이상하게 로드되거

 ## 관련 항목

- [Tunnels](/ko/tunnels/) · [Remote Instances](/ko/remote-instances/) · [Reverse Proxy](/ko/reverse-proxy/)
+- [기기 연결](/ko/connect-devices/) · [Private Relay](/ko/private-relay/) · [Tunnels](/ko/tunnels/) · [Remote Instances](/ko/remote-instances/) · [Reverse Proxy](/ko/reverse-proxy/)
 - [Security](/ko/security/) — 노출하기 전에 UI를 보호하세요
@@ -5,7 +5,9 @@ description: 원격 및 모바일 접근을 위해 OpenChamber를 안전하게

 # 터널

-터널은 OpenChamber로 연결되는 공개 링크로, 휴대폰이나 다른 네트워크에서 접근할 수 있게 해줍니다. 실행 중인 인스턴스에 터널을 만들려면 `openchamber tunnel`을 사용하세요.
+터널은 OpenChamber로 연결되는 공개 링크로, 다른 네트워크의 일반 브라우저에서 접근할 수 있게 해줍니다. 실행 중인 인스턴스에 터널을 만들려면 `openchamber tunnel`을 사용하세요.
+
+> **자신의 기기**(모바일 앱, 다른 데스크톱)를 연결할 때는 보통 터널이 필요 없습니다. 대신 [기기를 페어링](/ko/connect-devices/)하고, 설정이 전혀 필요 없는 종단 간 암호화 [Private Relay](/ko/private-relay/)에 집 밖 접속을 맡기세요.

 ## 사전 요구 사항

@@ -111,6 +113,7 @@ openchamber tunnel stop --port 3000

 ## 관련 문서

+- [기기 연결](/ko/connect-devices/) — 자신의 기기는 터널 대신 페어링하세요
 - [보안](/ko/security/) — 외부에 공개하기 전에 UI를 보호하세요
 - [데스크톱 터널](/ko/desktop-tunnels/) — CLI 시작 없이 데스크톱 앱에서 터널 설정
 - [PWA 및 모바일 접속](/ko/mobile/) — 휴대폰에서 OpenChamber에 접속하세요