クラウド中継ガイド

板板と PC が同じ Wi-Fi にあれば LAN で自動的につながるので、設定は不要です。 別のネットワークにあるとき（会社の PC と自宅の板板、スマホのテザリング中の PC、将来の 4G 版など）はクラウド中継を使います。PC と板板の両方が中継サーバーに接続し、自分のアカウントの中だけで承認と通知を転送します。

 拍板 Hub（会社の PC）──wss──▶ クラウド中継 ◀──wss── 板板（自宅）
                                    ▲
                 拍板ミニプログラム（WeChat ログイン = アカウント）

必要なバージョン

1. PC をログインさせる（PC ごとに 1 回）

1. Hub の 账号（アカウント）→ 登录（ログイン） を開くと（Hub の画面は中国語です）、QR コードと 8 文字のペアリングコードが表示されます（5 分間有効）。
2. スマホで「拍板」ミニプログラム → 我的 → 電脑与云端中转 → 扫码绑定电脑（またはコードを入力）。
3. ミニプログラムに PC 名が表示されるので確認すると、Hub が自動でログインし「○○ のアカウント · 中継オンライン」と表示されます。

ログイン情報は OS の暗号化（Windows は DPAPI）で保存されるので、再起動しても再ログインは不要です。

2. 板板をアカウントに紐付ける（デバイスごとに 1 回）

どちらの方法でも構いません。どちらも板板の上で確認ボタンを押す必要があります。画面に「确认绑定账号」（紐付けの確認）が出たら、BOOT をクリックまたは右に傾ける = 同意、ダブルクリックまたは左に傾ける = 拒否です。

• PC から：板板がこの PC と同じ Wi-Fi にいるとき、Hub の 账号 → 局域网里还没绑定的板板 → 绑定到账号（LAN 上の未紐付けの板板 → 紐付け）。
• ミニプログラムから：Wi-Fi 設定のあとに紐付けるか聞かれます。あとから 设置 → 云端中转 でも紐付けできます。

紐付けが済むと、板板の「デバイス」ページに 云端中转：电脑在线（中継：PC オンライン）と表示されます。

3. ふだんの使い方

何もする必要はありません。

• 同じ Wi-Fi：LAN（最速）。
• 別のネットワーク：自動的に中継。
• 両方でつながっている板板は LAN だけを使うので、承認が二重に出ることはありません。LAN が切れると中継に切り替わります。

ログアウト / 紐付け解除

板板を人に譲るときは先に解除してください。忘れても、新しい持ち主が板板で確認を押せば自分のアカウントに紐付けられます（中継は板板内の claim key で「いま誰が持っているか」を判断します）。

安全性

• アカウントの分離：トークンはそれぞれ 1 つのアカウントに属し、中継は同じアカウントの PC と板板の間でしか転送しません。from はサーバーが設定するので偽装できません。
• アカウント = WeChat：「この PC / 板板は誰のものか」はミニプログラムのクラウド関数でしか確定できず、openid は WeChat が渡すのでフロントエンドからは変えられません。
• リモートで奪えない：デバイス ID を知っていても紐付けには板板内の claim key が必要で、板板は確認ボタンが押されたときにしか渡しません。
• ペアリングコードの総当たり対策：8 文字、5 分で失効、1 回限り。10 分間に 10 回間違えるとそのアカウントはロックされます。ログイン後、PC にはどのアカウントに入ったかが表示されるので、自分のものでなければすぐログアウトできます。
• 通信の暗号化：すべて TLS（Let's Encrypt）。サーバーに保存するのはトークンのハッシュと openid の HMAC だけで、openid そのものは保存しません。
• 未対応：サーバー上ではメッセージを平文で転送しています（承認内容はサーバーから見えます）。次はエンドツーエンド暗号化で、中継が内容を読むことも承認を偽造することもできないようにします。

よくある質問

Hub に「这台电脑的登录已失效」（ログインが無効）と出る：ミニプログラムで解除されたか、中継サーバーの URL が変わりました。もう一度ログインしてください。

板板が「云端中转：连接中…」（接続中）のまま：証明書を検証する前に時刻合わせ（NTP）が必要です。インターネットに出られるか確認してください。0.5.0 より古いファームウェアは中継に対応していません。

ミニプログラムに中継の鍵が設定されていないと出る：下の「デプロイと管理」を参照してください。

デプロイと管理（メンテナー向け）

中継サーバーの場所

Azure 東アジア（香港）の AKS クラスター（Kubernetes、コントロールプレーンは無料プラン）。アドレスは https://paiban-relay.eastasia.cloudapp.azure.com。コードは relay/、インフラは infra/aks/。

            Azure ロードバランサー（パブリック IP + DNS 名）
                       │
          Traefik ×2（HTTPS。Let's Encrypt 証明書は cert-manager が自動更新）
                       │
            relay ×2（別々のノードで動き、どちらでも任意の接続を受けられる）
                       │  レプリカ間は LISTEN / NOTIFY で転送
                  PostgreSQL（8 GiB ディスク、毎日 Blob にバックアップ、30 日保持）

切れない理由： - 中継のレプリカは 2 つで、別々のノードで動きます。PC と板板が別のレプリカにつながっていても、PostgreSQL の LISTEN/NOTIFY でレプリカ同士が転送します。 - 更新時は新しいレプリカを起動して準備完了を確認してから古いものを止めます。古いレプリカはまずトラフィックを外し、それから終了コード 1012（サービス再起動）で接続を閉じます。 - クライアントはすぐに別のレプリカへ再接続します。オンライン状態は 20 秒保持されるので、相手側にはオフラインに見えません。 - その間に届いたメッセージは「メールボックス」に入り、再接続後に届きます。Hub とファームウェアも自分の送信メッセージをキューに入れて、再接続後に送ります。 - Azure は毎週日曜 3〜7 時（香港時間）にノードへパッチを当てます。1 台ずつ入れ替え、PodDisruptionBudget で少なくとも 1 つのレプリカが動き続けます。 - デプロイのたびに、ローリング再起動中に承認を往復させるライブチェックを実行します。250 往復がすべて届き、どちらも切断を見なかった場合だけデプロイ成功になります。

更新の流れ（GitHub Actions）

relay/ か infra/aks/ の変更を main に push すると Deploy relay (AKS) が動きます（Actions から Run workflow でも可）。

1. 一時的な PostgreSQL を起動して全テスト（2 レプリカ、ローリング再起動を含む）を実行し、1 つの server.js にまとめる。
2. OIDC で Azure にログイン（Azure のパスワードは保存しません。Azure はこのリポジトリの main ブランチからのトークンだけを信頼します）。
3. Bicep を実行。クラスターとバックアップ用ストレージは変更がなければそのまま。
4. Traefik と cert-manager をインストール / 更新。初回デプロイ時にクラスター内で秘密情報（RELAY_SECRET、ACCOUNT_SALT、DB パスワード）を生成し、以後は再利用します。表示はしません。
5. 新しい server.js を ConfigMap に入れ、ローリング更新を行う。イメージのビルドもレジストリも不要です。
6. HTTPS で /healthz を確認し、上記の無停止チェックを実行。結果は実行サマリーに表示されます。

独自ドメインを使う：infra/aks/config.env の EXTRA_HOSTS に追加（例：relay.example.com）し、paiban-relay.eastasia.cloudapp.azure.com に CNAME して push すれば、証明書が自動で発行されます。

初回：クラウド関数から中継を呼べるようにする

クラウド関数は管理キー RELAY_SECRET で中継の管理 API（ペアリング確認、デバイス登録）を呼びます。同じ値を 2 か所に設定します。

1. Azure Cloud Shell などで生成：openssl rand -hex 32。
2. GitHub リポジトリ Settings → Secrets and variables → Actions → New repository secret：名前 RELAY_SECRET。その後 Actions から Deploy relay (AKS) を 1 回実行すると クラスター側も切り替わります。
3. WeChat クラウド開発コンソール → クラウド関数 → paiban → 設定 → 環境変数：RELAY_SECRET = 同じ値。RELAY_URL は省略可（既定値は上の URL）。

ミニプログラムなしでテストする

リポジトリを公開すると、Actions の実行ログ（手動実行時の入力を含む）は誰でも見られます。Relay admin は引数を伏せ、PC 名も短くしますが、実際のユーザーの openid はここに入力しないでください。実アカウントの操作はミニプログラムで行い、調査が必要なときは Azure Cloud Shell で az aks get-credentials -g paiban-rg -n paiban-aks --admin && kubectl -n paiban exec deploy/relay -- node --no-warnings /app/server.js admin list <openid> を実行してください（結果は自分にしか見えません）。

Actions → Relay admin → Run workflow でコマンドを入力すると、結果が実行サマリーに出ます。

例：Hub でログインを押す → Relay admin で pair-confirm <コード> test-user を実行 → Hub が自動ログイン → Hub のアカウントページで LAN 上の板板を紐付け。ミニプログラムが使えるようになったら、WeChat ログインは別の openid になるので、そちらで紐付け直してください。