サーバー運用

管理と設定

管理画面、登録コードの配信（SMS・メール）、サーバーの設定値、バックアップとセキュリティ — 運営者向けのリファレンス。

サーバーには、ブラウザーで開く管理画面が組み込まれています。サーバーの状態を確認し、登録・ログインのコードをどのように届けるかを決め、ユーザーとボットを管理します。このドキュメントは、管理画面とサーバーの設定値を 1 か所にまとめたリファレンスです。先にインストールが必要なら、サーバーのインストールを参照してください。管理画面の表示は韓国語なので、タブ・ボタン・設定項目の名前には、韓国語の表記を添えています。

管理画面を開く

管理画面は管理用 HTTP ポート（本番構成では 8080）の /admin/ にあり、サーバー自身（127.0.0.1）からのみ開けます。運営者は SSH トンネルで入ります。

# 自分のコンピューターで（起動したままにしておく）
ssh -N -L 8080:127.0.0.1:8080 <ユーザー>@<サーバー>
# ブラウザー: http://localhost:8080/admin/

# トークン（サーバー上で）
sudo cat /srv/pabal/pabal_server/data/admin-token

トークンを入力して開く（열기）を押します。ブラウザーがトークンを記憶し、右上のトークンを消去（토큰 지우기）で消せます。トークンを自分で決めるには、TELEGRAM_ADMIN_TOKEN（16 文字以上）を指定してください — その場合、ファイルは書き込まれません。

タブごとの表示内容

タブ	内容	更新間隔
ダッシュボード（대시보드）	現在接続中の人・セッション・接続、人・ボット・グループ・メッセージ・写真・ファイルの数、稼働時間・ポート・DB、JVM、ヘルスチェック。テスト番号が有効なら警告バーを表示	5 秒
登録コード（가입 코드）	待機中のコード（番号・配信方式・送信状態・コード・残り時間・誤入力の回数）と最近の記録。コードのコピー・取り消し	3 秒
ユーザー（사용자）	すべてのアカウント — 電話番号、ログイン用メールアドレス（編集可）、接続状態、ログイン端末数、メッセージ数。すべての端末からログアウト（모든 기기 로그아웃）、番号をブロック（번호 차단）、アカウントの削除（계정 삭제。本人確認のメモとともに — 削除したアカウントは id とメモだけが残る）	10 秒
ボット（봇）	BotFather で作られたボット — 作成者、コマンドメニュー、接続方式（MTProto · HTTP ポーリング · Webhook のアドレスと失敗の理由）、待機中のアップデート数	10 秒
音声（음성）	音声ボット — ゲートウェイ・中継・ポリシーの状態、緊急停止スイッチ、一般公開、文字起こしの許可、進行中の通話と切断、ボットの許可・停止、テスター、上限（下記）	5 秒
通報（신고）	アプリの「通報」で届いたもの — 通報時点の内容の写し（送った人が削除したあとも読める）。削除（会話の双方から、グループならすべてのメンバーから）、アカウントの停止（すべての端末からログアウトし、再びログイン・登録できない）、停止中のアカウントの一覧。停止されたまま退会したアカウントの番号では、退会から1 年（既定）新しく登録できない — 停止するときに選ぶか、一覧の再登録の制限（재가입 막기）で、より遅い終了日・無期限に延ばす（1 年と選んだ日の遅いほうまで — 短くはできない。管理 API：`POST /admin/api/reports/<id>/suspend` `{"userId": …, "blockSignupUntil": "2028-01-01"}` または `"blockSignupForever": true`、あとから変えるには `POST /admin/api/suspensions/<id>/block-signup`、本文が空なら既定に戻る）。処理済みの通報も見られる。処理済みの通報は処理した日から 3 年たつとコピーごと消す（カードにその日付）— 紛争・捜査・訴訟が始まったら保存（보존）で解除するまで残す（管理 API: `POST /admin/api/reports/<id>/hold`、解除は `/release`）	10 秒
サポート（고객센터）	@PabalSupport に届いた会話。会話を選んで返信すると、サポートのボットの名前でその会話に送られます	10 秒
設定（설정）	登録・ログインのルール、アプリ審査用のアカウント、SMS、メール（SMTP）、電話番号のブロック、ウェブサイトに載る運営者の情報	手動で保存
予約 ID（예약 아이디）	誰も取れないようにふさいでおいたユーザー名 — 検索、追加、一覧のダウンロード（.txt）、サーバーが既定でふさぐ ID。すでに誰かが使っている名前は、予約しても取り上げない	開いたときに 1 回
ストレージ（저장소）	データディレクトリ・DB のアドレス（パスワードは伏せる）、写真とファイルの数と容量、種類別の保存ストリーム数	10 秒

危険な操作（ログアウト・ブロック・コードの取り消し）は、2 回押さないと実行されません。

登録・ログインのコード

人がアプリに電話番号を入力すると、サーバーがコードを作り、設定（설정）タブで選んだ方法で送ります。

配信方式	コードの届け先	アプリの画面
管理画面（관리 화면）	登録コード（가입 코드）タブ。運営者がコピーして直接伝える	番号 → 「コードを送信しました」→ コード（新しい番号なら名前）
SMS	Twilio · Solapi · Webhook のいずれかで SMS	管理画面方式と同じ
メール（이메일）	SMTP でメール	番号 → メールアドレスを入力 → 「メールでコードを送信しました」→ コード

メール方式では、新規登録ではどんなアドレスでも使え、そのアドレスがアカウントのログイン用メールアドレス（로그인 이메일）になります。既存のアカウントは、登録済みのログイン用メールアドレスでのみ受け取れます — 他人の番号に自分のアドレスを入れてログインすることを防ぐためです。ログイン用メールアドレスのない既存のアカウントには、代わりに SMS（設定されていれば）または管理画面で送ります。ユーザー（사용자）タブで、ログイン用メールアドレスを設定できます。
送信はバックグラウンドで行われ、アプリはすぐにコード入力画面に進みます。送信結果（成功・失敗とその理由）は、登録コードタブに表示されます。
登録（名前の入力）は、コードが正しかった場合にのみできます。間違ったコードは許容回数までしか受け付けず、それ以降は正しいコードも拒否します。
番号変更（アプリの設定 → 電話番号）は既定で閉じており、アプリにはエラーが表示されます。番号変更の許可をオンにすると、コードは配信方式にかかわらず新しい番号に SMS でだけ届きます（登録コードタブには、コード表示をオンにしても表示されません — そこで受け取る人がその番号の持ち主とは限らないためです）。文面は SMS 設定の番号変更用の文面（번호 바꾸기 문구、既定 [파발] 번호 바꾸기 확인 코드: {code}）です。再送間隔と 1 日の上限は新しい番号とアカウントの両方にかかり、ブロック・停止された番号と、ほかのアカウントが使っている番号は、コードを求めたときと移るときの 2 回拒否されます。コードはそのアカウントとその番号にだけ有効で、一度しか使えません。その番号を待っているほかの人のログインコードはそのまま残ります。移ったあと、古い番号ではそのアカウントにログインできません。

項目	意味	既定値
新規登録の許可（새 가입 허용）	オフにすると、既存のアカウントのみログイン可能。新しい番号は「番号が無効です」として拒否	オン
コードの配信方式（코드 전달 방식）	管理画面 / SMS / メール（관리 화면 / SMS / 이메일）	管理画面
管理画面にコードを表示（관리 화면에 코드 표시）	SMS・メール方式でも、登録コードタブにコードを表示（送信失敗に備える）	オン
テスト番号（+99966…）（테스트 번호）	サーバー設定どおり / オン / オフ（서버 설정대로 / 켜기 / 끄기）。本番ではオフ	サーバー設定どおり
コードの桁数 · 有効時間（코드 자릿수 · 유효 시간）	5〜6 桁 · 1〜60 分	5 桁 · 5 分
再要求の間隔 · 1 日の上限（재요청 간격 · 하루 최대）	同じ番号がコードを再度受け取れるまでの秒数（0〜3600）· 24 時間以内の最大回数（1〜1000）	60 秒 · 10 回
誤入力の許容回数（틀린 입력 허용 횟수）	超えると、そのコードはロックされる（1〜20）	5 回
番号変更の許可（번호 바꾸기 허용）	ログイン中のアカウントが、アプリの「番号を変更」で別の番号に移れる。SMS を設定した後でのみオンにできる	オフ

設定 — SMS

プロバイダー	入力する値	備考
Webhook（웹훅）	受信先のアドレス（https://…）、Authorization ヘッダー（任意）	サーバーが `POST {"phone":"+8210…","code":"12345","text":"…"}` を送ります。2xx なら成功。自前の SMS サーバーや、別のサービスにつなぐときに使います
Twilio	Account SID、Auth Token、送信元番号または Messaging Service SID	海外の番号を含む全世界
Solapi（旧 CoolSMS）	API Key、API Secret、送信元番号	韓国国内向けの SMS。送信元番号は、Solapi に事前登録された番号。+82 の番号は 010… の形式で送ります

文面には {code}（コード）と {minutes}（有効時間）を入れられます。既定値：[파발] 인증 코드: {code}（「[Pabal] 認証コード：{code}」）。保存したら、テスト送信（테스트 발송）で確認してください。

設定 — メール（SMTP）

サービス	サーバー · ポート · セキュリティ	ユーザー名 · パスワード
Gmail	`smtp.gmail.com` · 587 · STARTTLS	Gmail のアドレス · アプリパスワード（Google アカウント → セキュリティ → 2 段階認証プロセス → アプリパスワード）
NAVER	`smtp.naver.com` · 587 · STARTTLS	ID · パスワード（メールの環境設定で POP3/SMTP の使用をオン）
社内メールリレー	リレーのアドレス · 25 · なし	空欄

送信元アドレスは、SMTP アカウントから送信できるアドレスである必要があります。件名・本文でも {code}、{minutes} を使えます。

ユーザー管理

すべての端末からログアウト（모든 기기 로그아웃）：そのアカウントのすべてのログイン（認証キー）を切断します。端末をなくしたユーザーに使います。
番号をブロック（번호 차단）：その番号はコードを受け取れなくなり、その番号のアカウントは、すべての端末から即座にログアウトされます。設定（설정）タブの電話番号のブロック（전화번호 차단）の一覧と同じです。
ログイン用メールアドレス（로그인 이메일）：メール方式で、既存のアカウントがメールでログインするために必要です。
アカウントを削除（계정 삭제）：アカウントの削除を依頼したユーザーに、本人であることを確認してから使います。アプリのアカウント削除とまったく同じものを削除し、元に戻せません。アカウントの ID か電話番号をもう一度入力し、依頼がどこから来て本人をどう確認したかをメモに残すと実行されます。メモは ID・日付と一緒に残ります（電話番号・メールアドレスと、そのアカウントの名前・ユーザー名は取り除かれます）。登録済みのログイン用メールアドレス以外から届いたメールでの依頼は、同じ画面からそのアカウントの電話番号に確認コードを SMS で送り、依頼者がメールで返してきたコードを入力して確認します。ボットとサーバー自身のアカウントは、ここでは削除できません。
@BotFather はサーバー内のボットなので、ログアウトの対象ではありません。

ボット管理

ボット（봇）タブで、各ボットの接続方式を確認します — MTProto で接続しているか、HTTP で直近 1 分以内に getUpdates を呼んだか、Webhook のアドレスは何か、現在失敗しているか（理由を含む）。待機中のアップデートが増え続けるなら、ボットプログラムが止まっているか、Webhook が失敗し続けています。ボットの削除・トークンの再発行は、ボットを作った人が @BotFather で行います。

音声タブ

音声ボット（人が電話をかけると AI 音声モデルが応答するボット、音声ボット）を運営する場所です。サーバーで音声が有効になっていなくてもタブは表示され、状態の欄が何が足りないかを教えてくれます。有効にする方法はサーバーのインストール — 音声ボット。5 秒ごとに更新されます。

欄	表示される内容と、できること
いちばん上の数字	進行中の通話 · 今日使った時間（サーバーの 1 日の上限、通話中に確保した時間） · 接続中のゲートウェイ · 音声を有効にしたボット（許可したボット） · テスター（一般公開したか）
状態	ゲートウェイのリンク（アドレス、または「オフ（リンクのシークレットなし）」（꺼짐 (링크 비밀 없음)））、通話中継（TURN。なければ「すべてのボットの通話が話し中」（모든 봇 통화가 통화 중））、プライバシーポリシーの `bot-calls` 節があるか（なければ「どのボットも電話を受けない」（어떤 봇도 받지 않음））、待機中の同意、そして話し中で終えた電話の理由別の回数（例：워치가 못 거는 모드（ウォッチからかけられないモード）— Apple Watch から、ツール・MCP・自前のキー・ストリームモード・オーナーの文字起こしを使うボットにかけた場合、`WATCH_NOT_YET`）
緊急停止スイッチ	すべての音声通話を止める（모든 음성 통화 멈추기）：押した瞬間にこのサーバーで有効になり、進行中のボットの通話がすべて終わり、新しい通話を受けず、どのボットにも通話ボタンが表示されなくなります。そのあと保存されるので、サーバーを再起動してもそのままです（保存に失敗すると警告）。音声通話を再開する（음성 통화 다시 열기）で解除します
一般公開	一般公開の前は、下のテスターだけが音声ボットに電話できます。全員に開くには、欄に `공개합니다`（「公開します」）をそのまま入力して全員に公開（모두에게 공개）（サーバーの送り先キー `TELEGRAM_VOICE_RECIPIENTS` が処理地域を決めていない `…@unset` なら拒否 — 先に地域を入れたアプリのビルドを出す必要があります）。テスターだけに戻す（시험자만으로 되돌리기）で元に戻します。一般公開の前に法的な確認と提供元（Google）の書面での回答を済ませるかどうかは運営者が判断することです — コードは止めません
ゲートウェイ	接続中のゲートウェイごとに id、担当中の通話/容量、音声の送り先（`google.vertex.gemini-live@us-central1` など）、機能（`tools`・`byok`・`transcripts`・`stream` …）、エンジン、boot
文字起こし · 自前のキー	文字起こしの許可：欄に `대화 기록을 허용합니다`（「文字起こしを許可します」）を入力して文字起こしを許可（대화 기록 허용）。法的な確認の前には許可しないでください。オフにするとすぐに無効になり、進行中の通話と、ボットがまだ受け取っていない会話の文章も捨てます。発信者が選ぶ会話を残す機能はこの許可とは関係がなく、管理画面にスイッチはありません — プライバシーポリシーの `bot-calls-keep-text` 節が有効にします（サーバーのインストール — 会話を残す）。自前のキー：受け付けているかどうかと受け付けない理由、マスターキーの id、キーを持つボットの数（キーそのものはどこにも表示されない）
進行中の通話	通話 id、ボット、発信者（名前・id）、状態、経過/最大、ゲートウェイ、開いているツール問い合わせの数。切断（끊기）（2 回押すと実行）
音声ボット	音声を使えるボット：許可したボットだけ（허용한 봇만）（既定）または @BotFather で作ったすべてのボット（@BotFather 로 만든 모든 봇）。ボット id または @ユーザー名で許可（허용）。表：ボット、作成者、状態（オン・オフ、電話を受けられるかとその理由、停止、ストリームモードなら音声の送り先のアドレス、ツールと回答・エラー・タイムアウトの回数）、声・言語、上限、今日の通話。できること：許可（허용）・許可を取り消す（허용 취소）、確認して再び許可（확인하고 다시 허용）、停止（멈추기）（理由は必須、200 文字、ボットのオーナーに表示、進行中の通話は終わる）・再開（다시 열기）、設定を見る（설정 보기）
ボットの設定を見る	指示文・あいさつの原文（確認用）、ツールの定義とツールごとの応答時間（p50・p95）、ツール問い合わせの届け先、同意したルールの版、なりすまし検査の適用・免除、最近の変更、月ごとの通話・時間・受けられなかった数・拒否
テスター	人の id または @ユーザー名（@ はあってもなくてもよく、大文字・小文字は区別しない）でテスターに入れる（시험자로 넣기）・外す（빼기）（ボットとサーバー自身のアカウントは不可）。サーバーの設定 `TELEGRAM_VOICE_TESTERS` で入れた人は「サーバー」（서버）と表示され、ここでは外せません
上限	下の表 + なりすまし検査に加える名前（사칭 검사에 더할 이름）（1 行に 1 つ）。保存すると、電話を受けられなくなったボットを知らせます
ボットからの電話	全体のスイッチ：欄に `봇이 거는 전화를 켭니다` をそのまま入力してオンにします — 法的な確認のあとでだけ（許可画面の文言の `callme.legal_review` が `done` でなければ拒否。開発・テストサーバーの例外は `TELEGRAM_VOICE_CALLME_UNREVIEWED`）。オフにするとすぐに新しい依頼は `503`。国（既定 `82`、`999` はテストサーバーのみ）、上限（本番サーバーは下限より緩く保存されない）、オーナーが有効にしたボットの表（審査の状態、トークンによる停止、自動停止、今日の依頼）、ボットの詳細（名前・@ユーザー名・写真・指示文・あいさつ・ツール・声・言語・モード・目的・オーナーの名前とその `outboundReviewHash`）で許可・許可の取り消し、自動停止の解除、判定の段階ごとの拒否の回数

許可は審査です。「許可したボットだけ」のモードでボットを許可すると、現在の指示文・あいさつ・ツール（ストリームモードならストリームのアドレス）を許可したことになります。ボットのオーナーがそのうち 1 つでも変えると、ボットの表に「指示文・あいさつが変わった — 確認して再び許可すると電話を受けます」（지시문·인사말이 바뀜 — 확인하고 다시 허용해야 전화를 받습니다）が表示され、確認して再び許可（확인하고 다시 허용）を押すまで、そのボットは電話を受けません。ボットの言語が韓国語・英語以外のボットは、「@BotFather で作ったすべてのボット」のモードでも同じです — 保存時の自動ルール検査が、韓国語と英語しか読めないためです。そのようなボットの表には「韓国語・英語以外のボット（自動ルール検査では読めない）：指示文・あいさつを読んでください — 確認して再び許可すると電話を受けます」（한국어·영어가 아닌 봇 (자동 규칙 검사가 읽지 못함): 지시문·인사말을 읽어 주세요 — 확인하고 다시 허용해야 전화를 받습니다）が表示されるので、その言語を読める人が指示文・あいさつを読んで許可してください。

上限	既定	範囲
1 回の通話の最大（秒）	600	60〜3600、サーバーの設定 `TELEGRAM_VOICE_MAX_SECONDS` まで
ボット 1 つの同時通話	2	1〜100、サーバーの設定 `TELEGRAM_VOICE_BOT_CONCURRENCY` まで
1 人の 1 時間あたりの通話数	20	1〜200
1 人の 1 日の通話（分）	60	1〜600
ボット 1 つの 1 日の通話（分）	60	1〜6000
ボットのオーナー 1 人の 1 日の通話（分）	120	1〜6000
サーバー全体の 1 日の通話（分）	300	1〜100000
受け付ける最短の通話（秒）	60	30〜300 — 残り時間がこれより少なければ受けない
新しいアカウントの制限（日）	7	0〜90（0 = オフ）— テスターと、ボットが 1 日以上前にメッセージを送った人は例外

1 日はサーバーのタイムゾーン（TELEGRAM_VOICE_TIME_ZONE、既定 Asia/Seoul）が基準です。通話を受け付けるときに、その日の残り時間の範囲で最大の長さを決めてすべての上限に確保し、終わるとサーバーの時計で実際の秒数だけを請求します。ボットのオーナーの自前のキーで受ける通話は、発信者の上限だけを使います。
ボットのオーナーは、自分のボットの 1 回の通話の長さ（既定 300 秒）と同時通話を、この上限の範囲でだけ決められます。
すべての操作（緊急停止スイッチ、一般公開、許可、停止、切断、上限 …）は、登録コードタブの活動記録に 음성: …（「音声：…」）として残ります。
音声通話の品質の数値（最初の音声までの時間、割り込み時に止まるまでの時間、ツールの応答時間など）はこのタブにはなく、管理用ポートの /metrics にだけあります（JSON では voice.、Prometheus 形式 /metrics?format=prometheus では voice_ で始まる名前）。人・ボット・言葉は含まず、合計だけです。

同じことは管理 API でもできます（すべて Authorization: Bearer <トークン>）：GET /admin/api/voice、GET /admin/api/voice/bots/<id>、POST で voice/kill {"on": true}、voice/launch {"launched": true, "confirm": "…"}、voice/transcripts {"allowed": true, "confirm": "…"}、voice/testers・voice/testers/remove {"userId": …}、voice/gate {"botGate": "ALLOWLIST"}、voice/bots/allow・voice/bots/disallow {"botId": …}、voice/bots/<id>/suspend {"reason": "…"}・…/lift・…/name-exempt、voice/calls/<id>/end、上限は /admin/api/settings/voice。ボットからの電話は voice/outbound {"on": true, "confirm": "…"}、voice/outbound/settings {"countries": […], "limits": {…}}、GET /admin/api/voice/outbound/bots/<id>、voice/outbound/bots/allow {"botId": …, "expect": "<outboundReviewHash>"}・voice/outbound/bots/disallow、voice/outbound/bots/<id>/lift。

環境変数

サーバーは設定ファイル（server-config.json）を読み込んだあと、環境変数で上書きします。本番用の Compose ファイルが下の値を設定するので、通常は .env を編集するだけで十分です。

変数	意味	本番 Compose での値
`TELEGRAM_PORT`	MTProto のポート	`MTPROTO_PORT` (8443)
`TELEGRAM_HOST`	MTProto が待ち受けるアドレス	`0.0.0.0`
`TELEGRAM_PUBLIC_HOST`	アプリに通知するサーバーのアドレス（`help.getConfig`）	`PUBLIC_IP`
`TELEGRAM_WEB_PORT`	Web サイト・ドキュメント・Bot API・管理画面のポート	`8080`
`TELEGRAM_WEB_HOST`	そのポートが待ち受けるアドレス。既定は `127.0.0.1`	`0.0.0.0`（コンテナ内。ホストには 127.0.0.1 でのみ公開）
`TELEGRAM_PUBLIC_URL`	Web サイトのアドレス。リンク（`me_url_prefix`）・招待リンク・ドキュメントの例・プレビュー画像に使われる	`https://DOMAIN/`
`TELEGRAM_DATA_DIR`	写真・ファイル・admin-token・operations.json の場所	`/app/data`
`TELEGRAM_RSA_KEY`	サーバーの RSA 秘密鍵のパス（なければ初回に作成。公開鍵は `.pub`）	`/app/keys/private.pem`
`TELEGRAM_DC_ID`	このサーバーの DC 番号。アプリがホームとして使う DC（Telegram アプリはすべて 2）と同じでなければなりません — 違うと写真やファイルのダウンロードが始まりません	`DC_ID`（2）
`TELEGRAM_DB_TYPE`	`memory` · `h2` · `postgresql`	`postgresql`
`TELEGRAM_DB_URL`、`TELEGRAM_DB_USERNAME`、`TELEGRAM_DB_PASSWORD`	JDBC 接続	`jdbc:postgresql://pabal-postgres:5432/pabal`、`pabal`、`POSTGRES_PASSWORD`
`TELEGRAM_DB_MAX_POOL_SIZE`	DB の接続数	`20`
`TELEGRAM_ADMIN_TOKEN`	管理画面のトークン（空なら `data/admin-token` に作成）	`ADMIN_TOKEN`
`TELEGRAM_MAX_FILE_SIZE`	送信できる最大のファイルサイズ（`2GB`・`512MB`・バイト数）。パートは届いたそばからディスクに書き込まれるため、上限となるのはメモリではなくディスクです	`MAX_FILE_SIZE` (2GB)
`TELEGRAM_TEST_NUMBERS`	`+99966…` のテスト番号。開発専用	`false`
`TELEGRAM_WEBHOOK_ALLOW_LOCAL`	ボットの Webhook が http:// と内部アドレスを使えるようにする。開発専用	（未設定 = false）
`TELEGRAM_FCM_CREDENTIALS`	Android プッシュ用の Firebase サービスアカウント鍵ファイルのパス。空ならプッシュは無効（サーバーのインストール — 手順 10）	`FCM_CREDENTIALS`（空）
`TELEGRAM_FCM_PROJECT_ID`	鍵ファイルの `project_id` ではない Firebase プロジェクトに送る場合のみ	`FCM_PROJECT_ID`（空）
`TELEGRAM_PUSH_PREVIEWS`	`false` にすると、プッシュ通知にメッセージの内容を出さず送信者だけを表示	`PUSH_PREVIEWS`（`true`）
`TELEGRAM_TURN_HOST`、`TELEGRAM_TURN_PORT`、`TELEGRAM_TURN_SECRET`	通話中継（TURN） — 別々のネットワークにいる 2 つのアプリが出会う場所。シークレットが空なら直接接続だけになります（サーバーのインストール — 通話中継）	`TURN_HOST`（空なら `DOMAIN`）、`TURN_PORT`（3478）、`TURN_SECRET`（空）
`TELEGRAM_APNS_KEY`、`TELEGRAM_APNS_KEY_ID`、`TELEGRAM_APNS_TEAM_ID`、`TELEGRAM_APNS_TOPIC`、`TELEGRAM_APNS_MIN_BUILD`、`TELEGRAM_APNS_VOIP_MIN_BUILD`	iPhone のプッシュ（APNs） — キーファイルのパス、キー ID（空ならファイル名から）、アプリに署名したチーム、バンドル ID、送る最も低いビルド、CallKit の通話画面を使う最初のビルド。キーがなければ iPhone のプッシュは無効です（サーバーのインストール — 手順 11）	`APNS_*`（キーなし、空 — ファイル名から、`4Z8R468M2D`、`me.pabal.ios`、4、空）
`TELEGRAM_STATIC_MAPS_KEY`、`TELEGRAM_STATIC_MAPS_PER_DAY`、`TELEGRAM_STATIC_MAPS_PER_USER_HOUR`	位置情報メッセージの地図画像 — Google Maps Static API のキー、1 日に新しく取得する画像の数、1 人が 1 時間に新しく取得させられる数。キーがなければ地図画像は無効です（サーバーのインストール — 地図画像）	`STATIC_MAPS_*`（キーなし、300、120）
`JAVA_OPTS`	JVM オプション（メモリ）	`.env` の値

環境変数 — 音声ボット

本番では、追加の Compose ファイル deploy/docker-compose.voice.yml がこのうちリンク・中継・タイムゾーン・上限・テスター・最小ビルドを .env の値から入れ、残りは機能ごとに確認してから加えます（サーバーのインストール — 音声ボット）。ゲートウェイ（pabal-voice）の VOICE_* の設定は、リポジトリの voice/README.md にあります。

変数	既定	意味
`TELEGRAM_VOICE_LINK_SECRET_FILE`	—	ゲートウェイと同じ 32 バイトのリンクのシークレット（64 桁の hex）。ないか誤っていれば音声は無効
`TELEGRAM_VOICE_LINK_HOST`、`TELEGRAM_VOICE_LINK_PORT`	`127.0.0.1`、8095	リンクが待ち受ける場所。ループバックでなければ `TELEGRAM_VOICE_LINK_ANY_ADDRESS=true` が必要、公開アドレスは常に拒否
`TELEGRAM_VOICE_LINK_ANY_ADDRESS`	—	「このネットワークはサーバーとゲートウェイだけが使う」という宣言
`TELEGRAM_VOICE_TURN_HOST`、`TELEGRAM_VOICE_TURN_PORT`	—	ゲートウェイに渡す中継のアドレス（サーバーの LAN アドレス）。ループバックなら無視
`TELEGRAM_VOICE_MAX_SECONDS`	600	このサーバーが許す最も長い通話（60〜3600）
`TELEGRAM_VOICE_BOT_CONCURRENCY`	2	ボット 1 つの同時通話の上限（運営者・ボットのオーナーは下げることだけできる）
`TELEGRAM_VOICE_TIME_ZONE`	`Asia/Seoul`	1 日・1 か月の上限の基準
`TELEGRAM_VOICE_TESTERS`	—	テスターのユーザー id の一覧（管理画面の一覧と統合される）。`*` はテストサーバーだけ
`TELEGRAM_VOICE_RECIPIENTS`	`google.vertex.gemini-live@us-central1`	アプリの確認画面が伝える送り先。ゲートウェイのものと同じでないと通話が通らない
`TELEGRAM_VOICE_MIN_BUILD_DESKTOP`、`_ANDROID`、`_IOS`、`_WATCHOS`	1, 62151, 5, 1	確認画面が実際に入った最初のアプリのビルド（デスクトップはタグ `pabal-bc` の後ろの数字）。送り先が変わったら、新しいビルドを出してからこの値を上げる。デスクトップは、韓国語・英語以外の確認画面を初めて承認するときに 2 に上げる
`TELEGRAM_VOICE_MIN_SHEET_VERSION`	1	受け付ける最も低い確認画面の版
`TELEGRAM_VOICE_TOOL_RESULT_BYTES`	16384	ツールの答えの最大の大きさ（1024〜16384）
`TELEGRAM_VOICE_KEYS_MASTER_FILE`、`TELEGRAM_VOICE_KEYS_PREVIOUS_MASTER_FILE`	—	自前のキー・ストリームのシークレットを包むマスターキー、交換中の古いキー。バックアップの外の 700 のフォルダーに
`TELEGRAM_VOICE_OWN_KEYS_APPS_READY`	—	アプリが自前のキーのボットの確認画面（第 2 版）を表示するようになったあとでだけ `true`。それまでは自前のキーを受け付けない
`TELEGRAM_VOICE_OWN_KEY_MIN_SHEET_VERSION`、`TELEGRAM_VOICE_TRANSCRIPT_MIN_SHEET_VERSION`	2, 1	自前のキーの通話・文字起こしの案内に必要な確認画面の版（本番サーバーは自前のキーの版を 2 より下げない）
`TELEGRAM_VOICE_STREAM_MIN_BUILD_DESKTOP`、`_ANDROID`、`_IOS`	0（なし）	ストリーム用の確認画面が入った最初のアプリのビルド。0 なら誰もストリームのボットにかけられない
`TELEGRAM_VOICE_STREAM_MIN_SHEET_VERSION`	2	ストリーム用の確認画面の版
`TELEGRAM_VOICE_STREAM_DENY_ADDRESSES`	—	ストリームのアドレスが到達してはならない、このデプロイ自身のアドレス（公開ホストとサイトのホストは自動で含まれる）
`TELEGRAM_WATCH_API_PORT`、`_HOST`、`_ANY_ADDRESS`、`TELEGRAM_WATCH_AUDIO_URL`、`TELEGRAM_WATCH_ALLOW_PLAIN`、`TELEGRAM_WATCH_SESSION_DAYS`、`TELEGRAM_WATCH_AUTH_PER_MINUTE`	—、`127.0.0.1`、—、—、—、7、30	Apple Watch の API と音声のエッジのアドレス（サーバーのインストール — Apple Watch の入口）。`ALLOW_PLAIN` は開発専用
`TELEGRAM_VOICE_EVIDENCE_KEY_DIR`	—	ボットからの電話の許可の記録（HMAC の証拠）に使う鍵のフォルダー。700、バックアップされるフォルダーの外。`scripts/voice-evidence-key.py` で作り、取り替える。なければ誰も許可をオンにできない。Docker Compose では `.env` に書くだけではサーバーに届かない — ボットからの電話をオンにするとき、`deploy/docker-compose.voice.yml` の `pabal-server` の `environment`（コンテナー内のパス）と `volumes`（ホストのそのフォルダー）に加える
`TELEGRAM_VOICE_OUTBOUND_MIN_BUILD_DESKTOP`、`_ANDROID`、`_IOS`、`_WATCHOS`	0（なし）	許可画面の入った最初のアプリのビルド。これより古いビルドは許可をオンにできず、ボットの電話も鳴らない。0 ならそのプラットフォームはなし
`TELEGRAM_VOICE_CALLME_DEVICE_AGE_SECONDS`	86400	許可をオンにできる端末の、ログインからの時間（秒）。変えられるのはテストサーバーだけ（本番サーバーは警告して無視）
`TELEGRAM_VOICE_KEEP_TEXT_UNREVIEWED`	—	法的な確認前の「会話を残す」チェックボックスの文言をウォッチに表示。社内の試験サーバー専用
`TELEGRAM_MCP_*`、`TELEGRAM_MCP_APPS_READY`	—	MCP の部品（`deploy/docker-compose.mcp.yml` が入れる）。`TELEGRAM_MCP_EGRESS_OWN_ADDRESSES`（Pabal の公開アドレス）は、MCP でなくても Webhook・ツールのリクエストが Pabal 自身に行かないように使われます
`TELEGRAM_VOICE_BOTS`、`TELEGRAM_VOICE_NOTICE_CHECK=off`、`TELEGRAM_VOICE_STREAM_ALLOW_PRIVATE`	—	テストサーバー専用（`TELEGRAM_TEST_NUMBERS=true` のときだけ）：列挙したボット（id・@名前、`*` はすべてのボット）を許可 · 法的な節の確認を飛ばす · ストリームのアドレスにプライベートアドレスを許可
`TELEGRAM_VOICE_CALLME_UNREVIEWED`、`TELEGRAM_VOICE_DEV_ECHO_OUTBOUND`、`TELEGRAM_VOICE_TEST_DIAL`、`TELEGRAM_VOICE_TEST_DIAL_USERS`	—	テスト・開発サーバー専用：法的な確認の前にボットからの電話のスイッチをオンにできる（開発・テストサーバー）· エコーのゲートウェイがボットの電話をかける（開発サーバー、`TELEGRAM_TEST_MODE`）· 管理 API のテスト発信と、それが鳴らすアカウント（+99966 のテスト番号のほかに 20 個まで、テストサーバー）。本番サーバーは警告して無視

データファイル

ファイル	内容	権限
`keys/private.pem`	サーバーの RSA 秘密鍵。絶対に外部に出さない	600
`keys/private.pem.pub`	公開鍵。アプリのビルドと `/docs/server-key.pem` に使われる	—
`keys/firebase-service-account.json`	（任意）Android プッシュ用の Firebase 秘密鍵。漏れたら Firebase コンソールで削除し、新しく取得する	600
`data/admin-token`	管理画面のトークン	600
`data/operations.json`	設定（설정）タブの値 — 登録のルール、SMS・SMTP のシークレット、ブロックした番号、音声タブの設定（緊急停止スイッチ・一般公開・テスター・許可したボット・上限）	600
`keys/voice-link.secret`	（音声ボット）ゲートウェイと同じリンクのシークレット	400
`/etc/pabal/voice/voice-master.key`	（音声ボット）ボットのオーナーの自前のキー・ストリームのシークレットを包むマスターキー。データフォルダーの外、バックアップに入れない	600（フォルダー 700）
`data/media/`	写真とファイルの原本	—
PostgreSQL の `events` テーブル	アカウント・会話・メッセージ・ログイン・ボット・Webhook の設定 — すべての変更の記録	—

セキュリティに関するメモ

管理ポートをインターネットに直接公開しないでください。本番構成の Caddy は、/admin、/health、/metrics のような管理用パスを 404 でブロックします。
管理データへのリクエストにはすべて Authorization: Bearer <トークン> が必要で、ほかのサイトのページからは読み取れません。
SMS・SMTP のシークレットは operations.json にだけあり、画面と API は「保存済み」（저장됨）とだけ表示します。シークレットの欄を空のまま保存すると、既存の値が維持されます。
トークンやシークレットはログに出力されず、ログの電話番号は一部を伏せて記録します。Bot API のアドレス（トークンを含む）もログに残しません。
プッシュ通知のデバイストークンはログにフィンガープリントとしてだけ残り、Firebase 鍵ファイルの内容と通知の内容はログに残りません。
認証キーは DB に入っているため、DB にアクセスできる人は、ユーザーのトラフィックを復号できます。DB とバックアップを、RSA 鍵と同じくらい厳重に守ってください。

制限

待機中のコードと最近の記録はメモリ上にあるため、サーバーを再起動すると消えます（アプリから再度要求すれば問題ありません）。
SMS プロバイダーからの実際の送信は、各プロバイダーのアカウントで確認する必要があります。サーバーは、各プロバイダーのドキュメントどおりにリクエストを作ります。
まだないもの：ボットの強制削除、メッセージの閲覧、ログの表示、グラフ、プッシュ通知の統計（プッシュはサーバーのログで確認します）。