# 이름 있는 터널

기본적으로 Termbridge은 Cloudflare의 계정이 필요 없는 Quick Tunnels(`trycloudflare.com`)을 사용합니다. 편리하지만 사용량이 많으면 속도 제한이 적용될 수 있습니다.

Termbridge을 자주 사용한다면 Cloudflare 계정으로 이름 있는 터널을 설정하세요.

## 이름 있는 터널을 사용하는 이유

- **속도 제한 없음**: Quick Tunnels를 많이 사용하면 429 오류가 발생할 수 있습니다
- **일관된 URL**: 임의의 문자열 대신 고정된 하위 도메인을 사용할 수 있습니다
- **사용자 지정 도메인**: `term.example.com`처럼 자체 도메인을 사용할 수 있습니다
- **향상된 안정성**: 이름 있는 터널은 장시간 세션에서 더 안정적입니다

## 설정

### 1. Cloudflare 계정 만들기

계정이 없다면 [cloudflare.com](https://cloudflare.com)에서 가입하세요.

### 2. Zero Trust에서 터널 만들기

1. [Cloudflare Zero Trust](https://one.dash.cloudflare.com/)으로 이동합니다
2. **네트워크** → **터널**로 이동합니다
3. **터널 만들기**를 클릭합니다
4. 커넥터로 **Cloudflared**을 선택합니다
5. 터널 이름을 지정합니다(예: e.g, `termbridge`)
6. 터널 토큰을 복사합니다

### 3. 공개 호스트 이름 추가

1. 터널 설정에서 **공개 호스트 이름**으로 이동합니다
2. `http://localhost:8080` 또는 선택한 포트를 가리키는 호스트 이름을 추가합니다
3. `term.example.com` 같은 하위 도메인을 사용합니다

### 4. 토큰으로 Termbridge 실행하기

```bash
termbridge --port 8080 --tunnel-token <TOKEN> --tunnel-url https://term.example.com
```

또는 환경 변수를 사용하세요:

```bash
export TERMBRIDGE_TUNNEL_TOKEN=<TOKEN>
export TERMBRIDGE_TUNNEL_URL=https://term.example.com

termbridge --port 8080
```

> **참고**
> 호스트 이름이 특정 포트를 가리키도록 설정되어 있으므로 이름 있는 터널에서는 `--port` 플래그가 필요합니다.


## 구성 옵션

| 플래그 | 환경 변수 | 설명 |
|------|---------------------|-------------|
| `--port <port>` | - | 로컬 포트(이름 있는 터널에서 필수) |
| `--tunnel-token <token>` | `TERMBRIDGE_TUNNEL_TOKEN` | 터널 토큰 |
| `--tunnel-url <url>` | `TERMBRIDGE_TUNNEL_URL` | 공개 호스트 이름 URL |

## 터널 완전히 비활성화하기

자체 리버스 프록시나 공개 URL이 있는 경우:

```bash
termbridge --no-tunnel --public-url https://your-server.com
```

또는:

```bash
export TERMBRIDGE_TUNNEL=none
export TERMBRIDGE_PUBLIC_URL=https://your-server.com

termbridge
```

Termbridge은 터널을 시작하지 않고 제공한 URL을 QR 코드에 사용합니다.

## 문제 해결

### "429 요청이 너무 많음"

Quick Tunnels에 속도 제한이 적용되었다는 뜻입니다. 해결 방법:

1. 몇 분 기다린 뒤 다시 시도합니다
2. 남아 있는 `cloudflared` 프로세스를 모두 종료합니다: `pkill cloudflared`
3. 이름 있는 터널로 전환합니다(권장)

### 터널은 시작되지만 URL이 작동하지 않음

- Cloudflare의 호스트 이름이 `--tunnel-url`과 일치하는지 확인하세요
- Cloudflare의 포트가 `--port`와 일치하는지 확인하세요
- cloudflared가 최신 버전인지 확인하세요: `cloudflared update`

### 이름이 지정된 터널이 연결되지 않음

- 토큰이 올바른지 확인하세요
- Cloudflare Zero Trust 대시보드에서 오류를 확인하세요
- 오류 메시지를 보려면 `cloudflared tunnel run <TOKEN>`을 직접 실행해 보세요