# 名前付きトンネル

既定では、TermbridgeはCloudflareのアカウント不要なQuick Tunnel（`trycloudflare.com`）を使います。便利ですが、頻繁に使うとレート制限が適用されることがあります。

Termbridgeを頻繁に使う場合は、Cloudflareアカウントで名前付きトンネルを設定してください。

## 名前付きトンネルを使う理由

- **レート制限なし**: Quick Tunnelは頻繁に使うと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. **Networks** → **Tunnels** に移動します
3. **Create a tunnel** をクリックします
4. コネクターとして **Cloudflared** を選択します
5. トンネルに名前を付けます（e.g、`termbridge`など）
6. トンネルトークンをコピーします

### 3. 公開ホスト名を追加する

1. トンネル設定で **Public Hostname** に移動します
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はトンネルの起動を省略し、QRコード用に指定したURLを使います。

## トラブルシューティング

### 「429 Too Many Requests」

Quick Tunnelにレート制限が適用されています。対処方法：

1. 数分待ってから再試行します
2. 古い`cloudflared`プロセスを終了します: `pkill cloudflared`
3. 名前付きトンネルに切り替えます（推奨）

### トンネルは起動するがURLが動作しない

- Cloudflareのホスト名が`--tunnel-url`と一致することを確認します
- Cloudflareのポートが`--port`と一致することを確認します
- cloudflaredが最新であることを確認します: `cloudflared update`

### 名前付きトンネルに接続できない

- トークンが正しいことを確認します
- Cloudflare Zero Trustダッシュボードでエラーを確認します
- `cloudflared tunnel run <TOKEN>`を直接実行し、エラーメッセージを確認します