サーバー運用
管理と設定
管理画面、登録コードの配信（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 秒 |
| ユーザー（사용자） | すべてのアカウント — 電話番号、ログイン用メールアドレス（編集可）、接続状態、ログイン端末数、メッセージ数。すべての端末からログアウト（모든 기기 로그아웃）、番号をブロック（번호 차단） | 10 秒 |
| ボット（봇） | BotFather で作られたボット — 作成者、コマンドメニュー、接続方式（MTProto · HTTP ポーリング · Webhook のアドレスと失敗の理由）、待機中のアップデート数 | 10 秒 |
| 設定（설정） | 登録・ログインのルール、SMS、メール（SMTP）、電話番号のブロック | 手動で保存 |
| ストレージ（저장소） | データディレクトリ・DB のアドレス（パスワードは伏せる）、写真の数・容量、種類別の保存ストリーム数 | 10 秒 |
危険な操作（ログアウト・ブロック・コードの取り消し）は、2 回押さないと実行されません。
登録・ログインのコード
人がアプリに電話番号を入力すると、サーバーがコードを作り、設定（설정）タブで選んだ方法で送ります。
| 配信方式 | コードの届け先 | アプリの画面 |
|---|---|---|
| 管理画面（관리 화면） | 登録コード（가입 코드）タブ。運営者がコピーして直接伝える | 番号 → 「コードを送信しました」→ コード（新しい番号なら名前） |
| SMS | Twilio · Solapi · Webhook のいずれかで SMS | 管理画面方式と同じ |
| メール（이메일） | SMTP でメール | 番号 → メールアドレスを入力 → 「メールでコードを送信しました」→ コード |
- メール方式では、新規登録ではどんなアドレスでも使え、そのアドレスがアカウントのログイン用メールアドレス（로그인 이메일）になります。既存のアカウントは、登録済みのログイン用メールアドレスでのみ受け取れます — 他人の番号に自分のアドレスを入れてログインすることを防ぐためです。ログイン用メールアドレスのない既存のアカウントには、代わりに SMS（設定されていれば）または管理画面で送ります。ユーザー（사용자）タブで、ログイン用メールアドレスを設定できます。
- 送信はバックグラウンドで行われ、アプリはすぐにコード入力画面に進みます。送信結果（成功・失敗とその理由）は、登録コードタブに表示されます。
- 登録（名前の入力）は、コードが正しかった場合にのみできます。間違ったコードは許容回数までしか受け付けず、それ以降は正しいコードも拒否します。
設定 — 登録・ログイン
| 項目 | 意味 | 既定値 |
|---|---|---|
| 新規登録の許可（새 가입 허용） | オフにすると、既存のアカウントのみログイン可能。新しい番号は「番号が無効です」として拒否 | オン |
| コードの配信方式（코드 전달 방식） | 管理画面 / SMS / メール（관리 화면 / SMS / 이메일） | 管理画面 |
| 管理画面にコードを表示（관리 화면에 코드 표시） | SMS・メール方式でも、登録コードタブにコードを表示（送信失敗に備える） | オン |
| テスト番号（+99966…）（테스트 번호） | サーバー設定どおり / オン / オフ（서버 설정대로 / 켜기 / 끄기）。本番ではオフ | サーバー設定どおり |
| コードの桁数 · 有効時間（코드 자릿수 · 유효 시간） | 5〜6 桁 · 1〜60 分 | 5 桁 · 5 分 |
| 再要求の間隔 · 1 日の上限（재요청 간격 · 하루 최대） | 同じ番号がコードを再度受け取れるまでの秒数（0〜3600）· 24 時間以内の最大回数（1〜1000） | 60 秒 · 10 回 |
| 誤入力の許容回数（틀린 입력 허용 횟수） | 超えると、そのコードはロックされる（1〜20） | 5 回 |
設定 — 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} を使えます。
ユーザー管理
- すべての端末からログアウト（모든 기기 로그아웃）：そのアカウントのすべてのログイン（認証キー）を切断します。端末をなくしたユーザーに使います。
- 番号をブロック（번호 차단）：その番号はコードを受け取れなくなり、その番号のアカウントは、すべての端末から即座にログアウトされます。設定（설정）タブの電話番号のブロック（전화번호 차단）の一覧と同じです。
- ログイン用メールアドレス（로그인 이메일）：メール方式で、既存のアカウントがメールでログインするために必要です。
- @BotFather はサーバー内のボットなので、ログアウトの対象ではありません。
ボット管理
ボット（봇）タブで、各ボットの接続方式を確認します — MTProto で接続しているか、HTTP で直近 1 分以内に getUpdates を呼んだか、Webhook のアドレスは何か、現在失敗しているか（理由を含む）。待機中のアップデートが増え続けるなら、ボットプログラムが止まっているか、Webhook が失敗し続けています。ボットの削除・トークンの再発行は、ボットを作った人が @BotFather で行います。
環境変数
サーバーは設定ファイル（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 番号 | （イメージの既定値 1） |
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_TEST_NUMBERS | +99966… のテスト番号。開発専用 | false |
TELEGRAM_WEBHOOK_ALLOW_LOCAL | ボットの Webhook が http:// と内部アドレスを使えるようにする。開発専用 | （未設定 = false） |
JAVA_OPTS | JVM オプション（メモリ） | .env の値 |
データファイル
| ファイル | 内容 | 権限 |
|---|---|---|
keys/private.pem | サーバーの RSA 秘密鍵。絶対に外部に出さない | 600 |
keys/private.pem.pub | 公開鍵。アプリのビルドと /docs/server-key.pem に使われる | — |
data/admin-token | 管理画面のトークン | 600 |
data/operations.json | 設定（설정）タブの値 — 登録のルール、SMS・SMTP のシークレット、ブロックした番号 | 600 |
data/media/ | 写真の原本 | — |
PostgreSQL の events テーブル | アカウント・会話・メッセージ・ログイン・ボット・Webhook の設定 — すべての変更の記録 | — |
セキュリティに関するメモ
- 管理ポートをインターネットに直接公開しないでください。本番構成の Caddy は、
/admin、/health、/metricsのような管理用パスを 404 でブロックします。 - 管理データへのリクエストにはすべて
Authorization: Bearer <トークン>が必要で、ほかのサイトのページからは読み取れません。 - SMS・SMTP のシークレットは
operations.jsonにだけあり、画面と API は「保存済み」（저장됨）とだけ表示します。シークレットの欄を空のまま保存すると、既存の値が維持されます。 - トークンやシークレットはログに出力されず、ログの電話番号は一部を伏せて記録します。Bot API のアドレス（トークンを含む）もログに残しません。
- 認証キーは DB に入っているため、DB にアクセスできる人は、ユーザーのトラフィックを復号できます。DB とバックアップを、RSA 鍵と同じくらい厳重に守ってください。
制限
- 待機中のコードと最近の記録はメモリ上にあるため、サーバーを再起動すると消えます（アプリから再度要求すれば問題ありません）。
- SMS プロバイダーからの実際の送信は、各プロバイダーのアカウントで確認する必要があります。サーバーは、各プロバイダーのドキュメントどおりにリクエストを作ります。
- まだないもの：アカウントの削除、ボットの強制削除、メッセージの閲覧、ログの表示、グラフ。