docs: add localized documentation pages

Adds translated docs for Spanish, Korean, Polish, Portuguese, Ukrainian, and Chinese Covers install, quickstart, themes, troubleshooting, tunnels, and reverse proxy guides Updates docs workflow, sidebar, and contributor documentation
2026-05-23 00:33:39 +03:00
parent 82633d97f5
commit 6f4e0068c1
47 changed files with 3638 additions and 17 deletions
@@ -0,0 +1,25 @@
+---
+title: OpenChamber 문서
+description: 웹, 데스크톱, VS Code에서 OpenChamber를 설정하고 운영하는 가이드.
+---
+
+# OpenChamber 문서
+
+OpenChamber는 OpenCode를 둘러싼 시각적 작업 공간입니다.
+
+이 문서를 사용해:
+
+- 워크플로에 맞는 플랫폼을 설치하세요
+- 원격 사용을 위해 OpenChamber를 안전하게 공개하세요
+- 외관을 맞춤 설정하고 흔한 문제를 해결하세요
+
+## 먼저 읽어보기
+
+- [설치](/ko/install/)
+- [빠른 시작](/ko/quickstart/)
+- [터널](/ko/tunnels/)
+- [문제 해결](/ko/troubleshooting/)
+
+## OpenChamber는 무엇을 위한 것인가
+
+OpenChamber는 관제 센터가 도움이 되는 AI 코딩 작업을 위한 것입니다. 세션 분기, diff 검토, 터미널 관리, 도구 진행 상황 관찰, 프로젝트 액션 실행, 그리고 에이전트가 작업하는 동안 전체 보드를 한눈에 유지하는 일입니다.
@@ -0,0 +1,33 @@
+---
+title: 설치
+description: 데스크톱, 웹, VS Code용 OpenChamber를 설치하세요.
+---
+
+# 설치
+
+OpenChamber에는 세 가지 주요 플랫폼이 있습니다:
+
+- macOS용 데스크톱 앱
+- 설치 가능한 PWA를 갖춘 CLI 호스팅 웹 앱
+- VS Code 확장
+
+## 사전 요구 사항
+
+먼저 [OpenCode](https://opencode.ai)를 설치하세요.
+
+## 웹 + PWA
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/openchamber/openchamber/main/scripts/install.sh | bash
+openchamber --ui-password be-creative-here
+```
+
+그런 다음 CLI가 출력한 URL을 여세요(보통 `http://localhost:3000`).
+
+## 데스크톱
+
+GitHub 릴리스 페이지 또는 OpenChamber 다운로드 페이지에서 최신 데스크톱 빌드를 내려받으세요.
+
+## VS Code
+
+VS Code 마켓플레이스에서 설치하고 평소 사용하는 OpenCode 워크플로로 로그인하세요.
@@ -0,0 +1,22 @@
+---
+title: 빠른 시작
+description: OpenChamber를 빠르게 시작하고 작업에 맞는 플랫폼을 선택하세요.
+---
+
+# 빠른 시작
+
+## 가장 빠른 경로
+
+1. OpenCode를 설치합니다.
+2. OpenChamber CLI를 설치합니다.
+3. `openchamber --ui-password be-creative-here`를 실행합니다.
+4. 컴퓨터에서 웹 UI를 엽니다.
+5. 필요하면 터널을 시작하고 휴대폰으로 QR 코드를 스캔합니다.
+
+특히 인스턴스를 원격으로 공개할 계획이라면 강력한 UI 비밀번호를 사용하세요.
+
+## 어떤 플랫폼을 사용해야 하나요?
+
+- macOS 중심의 일상 작업에는 **데스크톱**을 사용하세요
+- 원격 접근과 모바일 검토에는 **웹**을 사용하세요
+- 코드 옆에서 에디터 네이티브 세션을 원하면 **VS Code**를 사용하세요
@@ -0,0 +1,347 @@
+---
+title: 리버스 프록시
+description: Nginx, Nginx Proxy Manager 또는 다른 리버스 프록시 뒤에서 OpenChamber를 올바르게 구성하세요.
+---
+
+# 리버스 프록시
+
+Nginx, Nginx Proxy Manager, Caddy, Cloudflare 또는 다른 리버스 프록시 뒤에서 OpenChamber를 실행한다면 이 페이지를 사용하세요.
+
+## 프록시를 두기 전에
+
+1. 먼저 OpenChamber가 직접 작동하는지 확인하세요.
+2. 같은 네트워크에서 `http://<server-ip>:3000` 또는 사용자 지정 포트를 여세요.
+3. 직접 연결이 작동한 후에만 리버스 프록시를 추가하세요.
+
+## 프록시가 지원해야 하는 것
+
+- 실시간 메시지 전송을 위한 WebSocket:
+  - `/api/event/ws`
+  - `/api/global/event/ws`
+  - `/api/terminal/ws`
+- 버퍼링 없는 SSE:
+  - `/api/event`
+  - `/api/global/event`
+  - `/api/notifications/stream`
+  - `/api/openchamber/events`
+  - `/api/terminal/:sessionId/stream`
+- 첨부 파일 및 파일 작업을 위한 대용량 요청 본문
+- 실시간 스트림과 터미널 세션을 위한 긴 읽기 타임아웃
+
+## 중요한 규칙
+
+- WebSocket 프록시를 활성화하세요.
+- SSE 경로에서 버퍼링을 비활성화하세요.
+- OpenChamber가 이미 응답을 압축한다면 프록시에서 gzip을 비활성화하세요.
+- 압축은 한 계층에서만 켜두세요.
+- `Host`, `X-Forwarded-For`, `X-Forwarded-Proto` 같은 일반 프록시 헤더를 전달하세요.
+- 사용자가 파일을 업로드한다면 본문 크기 제한을 늘리세요.
+
+## 빠른 체크리스트
+
+- LAN에서 OpenChamber에 직접 접근 가능
+- 프록시에서 WebSocket 활성화
+- SSE 경로의 버퍼링 꺼짐
+- 프록시 호스트에서 `gzip off`, 또는 다른 방식으로 프록시 압축 비활성화
+- 첨부 파일에 충분히 큰 `client_max_body_size`
+- 스트림에 충분히 긴 `proxy_read_timeout`
+
+## 예시: Nginx
+
+<details>
+<summary>예시 구성 보기</summary>
+
+```nginx
+client_max_body_size 50M;
+client_body_buffer_size 50M;
+proxy_request_buffering off;
+
+proxy_http_version 1.1;
+proxy_set_header Connection "";
+proxy_set_header Host $host;
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+proxy_set_header X-Forwarded-Host $host;
+
+gzip off;
+
+location = /api/terminal/ws {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+}
+
+location = /api/global/event/ws {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+}
+
+location = /api/event/ws {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+}
+
+location ~ ^/api/(event|global/event|notifications/stream|openchamber/events)$ {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Accept "text/event-stream";
+    proxy_set_header Cache-Control "no-cache";
+    proxy_buffering off;
+    proxy_cache off;
+    gzip off;
+    add_header X-Accel-Buffering "no" always;
+    add_header Cache-Control "no-cache, no-transform" always;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+}
+
+location ~ ^/api/terminal/.+/stream$ {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Accept "text/event-stream";
+    proxy_set_header Cache-Control "no-cache";
+    proxy_buffering off;
+    proxy_cache off;
+    gzip off;
+    add_header X-Accel-Buffering "no" always;
+    add_header Cache-Control "no-cache, no-transform" always;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+}
+
+location /api {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+}
+
+location / {
+    proxy_pass http://127.0.0.1:3000;
+}
+```
+
+</details>
+
+## 예시: Nginx Proxy Manager
+
+<details>
+<summary>Advanced 탭 예시 보기</summary>
+
+```nginx
+client_max_body_size 50M;
+client_body_buffer_size 50M;
+proxy_request_buffering off;
+
+proxy_http_version 1.1;
+proxy_set_header Connection "";
+proxy_set_header Host $host;
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+proxy_set_header X-Forwarded-Host $host;
+
+gzip off;
+
+location = /api/terminal/ws {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    proxy_connect_timeout 30s;
+}
+
+location = /api/global/event/ws {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    proxy_connect_timeout 30s;
+}
+
+location = /api/event/ws {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_buffering off;
+    proxy_cache off;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    proxy_connect_timeout 30s;
+}
+
+location = /api/event {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Accept "text/event-stream";
+    proxy_set_header Cache-Control "no-cache";
+    proxy_buffering off;
+    proxy_cache off;
+    gzip off;
+    add_header X-Accel-Buffering "no" always;
+    add_header Cache-Control "no-cache, no-transform" always;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    proxy_connect_timeout 30s;
+}
+
+location = /api/global/event {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Accept "text/event-stream";
+    proxy_set_header Cache-Control "no-cache";
+    proxy_buffering off;
+    proxy_cache off;
+    gzip off;
+    add_header X-Accel-Buffering "no" always;
+    add_header Cache-Control "no-cache, no-transform" always;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    proxy_connect_timeout 30s;
+}
+
+location = /api/notifications/stream {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Accept "text/event-stream";
+    proxy_set_header Cache-Control "no-cache";
+    proxy_buffering off;
+    proxy_cache off;
+    gzip off;
+    add_header X-Accel-Buffering "no" always;
+    add_header Cache-Control "no-cache, no-transform" always;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    proxy_connect_timeout 30s;
+}
+
+location = /api/openchamber/events {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Accept "text/event-stream";
+    proxy_set_header Cache-Control "no-cache";
+    proxy_buffering off;
+    proxy_cache off;
+    gzip off;
+    add_header X-Accel-Buffering "no" always;
+    add_header Cache-Control "no-cache, no-transform" always;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    proxy_connect_timeout 30s;
+}
+
+location ~ ^/api/terminal/.+/stream$ {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Accept "text/event-stream";
+    proxy_set_header Cache-Control "no-cache";
+    proxy_buffering off;
+    proxy_cache off;
+    gzip off;
+    add_header X-Accel-Buffering "no" always;
+    add_header Cache-Control "no-cache, no-transform" always;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    proxy_connect_timeout 30s;
+}
+
+location /api {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+    proxy_connect_timeout 30s;
+}
+
+location / {
+    proxy_pass http://127.0.0.1:3000;
+}
+```
+
+</details>
+
+이 호스트에 대해 Nginx Proxy Manager에서 `Websockets Support`도 활성화하세요.
+
+## 흔한 실패 징후
+
+### 페이지는 로드되지만 메시지 전송이 실패함
+
+- 프록시에서 WebSocket이 활성화되지 않음
+- `/api/event/ws` 또는 `/api/global/event/ws`가 올바르게 전달되지 않음
+
+### 알림 또는 실시간 상태가 업데이트되지 않음
+
+- SSE 경로 중 하나가 버퍼링되거나 캐시됨
+- `X-Accel-Buffering "no"`가 누락됨
+
+### 파일 업로드가 실패함
+
+- `client_max_body_size`가 너무 작음
+
+### 로컬에서는 모두 작동하지만 프록시 뒤에서만 깨짐
+
+- 프록시가 실시간 트래픽을 압축하고 버퍼링함
+- 프록시에 WebSocket 지원이 없음
+
+## 예시: Caddy
+
+<details>
+<summary>예시 구성 보기</summary>
+
+```caddy
+reverse_proxy 127.0.0.1:3000 {
+    # WebSocket support is automatic in Caddy
+
+    # Flush SSE responses immediately
+    flush_interval -1
+
+    # Pass through Host and proxy headers
+    header_up Host {host}
+    header_up X-Real-IP {remote_host}
+    header_up X-Forwarded-For {remote_host}
+    header_up X-Forwarded-Proto {scheme}
+
+    # Increase timeouts for long-lived streams
+    transport http {
+        read_timeout 3600s
+        write_timeout 3600s
+    }
+}
+```
+
+</details>
+
+Caddy는 WebSocket 업그레이드를 자동으로 처리합니다 — 추가 구성이 필요 없습니다. `flush_interval -1` 지시어는 SSE 청크가 버퍼링 없이 즉시 전달되도록 보장합니다.
+
+## CDN 및 이중 압축 경고
+
+리버스 프록시 앞에 CDN(예: Cloudflare)을 두는 경우 이중 압축에 유의하세요:
+
+- OpenChamber는 HTTP 응답을 gzip으로 압축합니다(임계값 1KB).
+- Cloudflare와 다른 CDN도 기본적으로 응답을 압축합니다.
+- 이로 인해 이중 압축된 응답이나 잘못된 `Content-Encoding` 헤더가 발생할 수 있습니다.
+
+이를 피하려면 **한** 계층에서 압축을 비활성화하세요:
+
+- **Cloudflare:** Rules → Compression → disable(또는 "Passthrough" 모드 사용).
+- **Nginx:** `gzip off`(위 예시에 이미 표시됨).
+- **Caddy:** 업스트림이 이미 압축된 콘텐츠를 보내면 Caddy는 기본적으로 다시 압축하지 않습니다.
+
+SSE 스트리밍 경로는 OpenChamber에서 압축에서 제외되지만, CDN이 여전히 버퍼링할 수 있습니다. SSE 경로에서 버퍼링을 비활성화하는 방법은 CDN 문서를 확인하세요.
+
+## 관련 항목
+
+- [터널](/ko/tunnels/)
+- [문제 해결](/ko/troubleshooting/)
@@ -0,0 +1,30 @@
+---
+title: 테마
+description: 내장 테마와 사용자 정의 테마로 OpenChamber를 맞춤 설정하세요.
+---
+
+# 테마
+
+OpenChamber는 내장 테마와 사용자 정의 테마 JSON 파일을 지원합니다.
+
+## 사용자 정의 테마 추가
+
+1. 테마 디렉터리를 만듭니다:
+
+```bash
+mkdir -p ~/.config/openchamber/themes
+```
+
+2. 해당 디렉터리에 JSON 파일을 추가합니다(예: `my-theme.json`).
+3. OpenChamber를 열고 **Settings -> Theme -> Reload themes**로 이동합니다.
+4. 드롭다운에서 테마를 선택합니다.
+
+## 테마 위치
+
+- macOS/Linux: `~/.config/openchamber/themes/`
+
+## 전체 JSON 형식 참조
+
+메인 저장소 문서의 전체 형식 가이드를 사용하세요:
+
+- [`docs/CUSTOM_THEMES.md`](https://github.com/openchamber/openchamber/blob/main/docs/CUSTOM_THEMES.md)
@@ -0,0 +1,30 @@
+---
+title: 문제 해결
+description: 흔한 설정 및 실행 문제와 빠른 해결 방법.
+---
+
+# 문제 해결
+
+## OpenChamber 명령이 종료되거나 시작되지 않음
+
+- Node.js `>=20`인지 확인하세요
+- `openchamber --version`을 실행하세요
+- 필요하면 최신 CLI를 다시 설치하세요
+
+## 웹 UI에 접근할 수 없음
+
+- `openchamber logs`로 서버 로그를 확인하세요
+- 활성 포트를 확인하세요(기본값 `3000`)
+- 터널 링크를 테스트하기 전에 먼저 `http://localhost:3000`을 직접 여세요
+
+## 원격/터널 링크가 작동하지 않음
+
+- `openchamber tunnel status --all`을 실행하세요
+- 같은 인스턴스/포트에서 터널을 다시 시작하세요
+- 이전 토큰이 이미 사용되었다면 연결 링크를 다시 생성하세요
+
+## VS Code 확장이 연결되지 않음
+
+- OpenChamber 서버가 실행 중인지 확인하세요
+- 확장이 최신인지 확인하세요
+- VS Code 창을 새로 고치고 연결을 다시 시도하세요
@@ -0,0 +1,77 @@
+---
+title: 터널
+description: 원격 및 모바일 접근을 위해 OpenChamber를 안전하게 공개하세요.
+---
+
+# 터널
+
+실행 중인 OpenChamber 인스턴스를 공개하려면 `openchamber tunnel`을 사용하세요.
+
+## 빠른 시작 (Cloudflare 빠른 모드)
+
+1. OpenChamber를 시작합니다:
+
+```bash
+openchamber
+```
+
+2. 터널을 시작합니다:
+
+```bash
+openchamber tunnel start --provider cloudflare --mode quick
+```
+
+3. 상태를 확인합니다:
+
+```bash
+openchamber tunnel status
+```
+
+기본적으로 OpenChamber는 대화형 TTY 세션에서 QR 코드를 출력합니다. `--qr`로 QR 출력을 강제하거나 `--no-qr`로 비활성화하세요.
+
+## 관리형 모드
+
+### 관리형 원격
+
+Cloudflare가 관리하는 토큰 + 호스트네임을 사용합니다:
+
+```bash
+openchamber tunnel start --provider cloudflare --mode managed-remote --token-file ~/.secrets/cf-token --hostname app.example.com
+```
+
+### 관리형 로컬
+
+로컬 `cloudflared` 구성을 사용합니다:
+
+```bash
+openchamber tunnel start --provider cloudflare --mode managed-local --config ~/.cloudflared/config.yml
+```
+
+## 프로필 (managed-remote)
+
+재사용 가능한 프로필을 저장합니다:
+
+```bash
+openchamber tunnel profile add --provider cloudflare --mode managed-remote --name prod-main --hostname app.example.com --token-file ~/.secrets/cf-token
+```
+
+저장된 프로필로 시작합니다:
+
+```bash
+openchamber tunnel start --profile prod-main
+```
+
+## 유용한 명령
+
+```bash
+openchamber tunnel providers
+openchamber tunnel ready --provider cloudflare
+openchamber tunnel doctor --provider cloudflare
+openchamber tunnel stop --port 3000
+```
+
+## 동작 참고 사항
+
+- OpenChamber 인스턴스(포트)당 활성 터널은 하나입니다
+- 같은 인스턴스에서 새 모드/공급자를 시작하면 이전 터널이 대체됩니다
+- 새 연결 링크를 생성하면 사용되지 않은 이전 링크가 무효화됩니다