# ワークフローと操作方法

Canonical page: https://phishdestroy.github.io/TgWitness/ja/docs/reference/operations/

パネルの日常的な運用：モード、監視カテゴリ、パラメータ、通知、エクスポート、バックアップ、および容量について。

初回接続の際は、[アカウントおよびセッション形式](https://phishdestroy.github.io/TgWitness/ja/docs/reference/accounts/)をご利用ください。 保存されたバージョン、イベントポリシー、およびデータ欠落に関する説明については、 [「収集の仕組み」](https://phishdestroy.github.io/TgWitness/ja/docs/reference/collection/)をご覧ください。本ガイドでは、日常的な運用と復旧について解説しています。

## オペレーターのワークフロー

フローチャート · 保存先と鍵の保護方法を選択してください → トークンを使用してパネルを開く; トークンを使用してパネルを開く → ワークスペースを選択してください; ワークスペースを選択してください → ダイレクト接続またはプロキシ接続の設定; ダイレクト接続またはプロキシ接続の設定 → 電話番号を入力するか、ファイルまたはQRコードを選択してください; 電話番号を入力するか、ファイルまたはQRコードを選択してください → アカウントの身元を確認し、アクセス可能なグループを選択してください; アカウントの身元を確認し、アクセス可能なグループを選択してください → イベントおよび添付ファイルの保存ポリシーを設定してから、監視を開始してください; イベントおよび添付ファイルの保存ポリシーを設定してから、監視を開始してください → エラー、アクセス、キュー、ディスクの状態を監視します; エラー、アクセス、キュー、ディスクの状態を監視します → 独立したチェックポイントを保持する; 独立したチェックポイントを保持する → 資料のエクスポートと検証 · 保存先と鍵の保護方法を選択してください · トークンを使用してパネルを開く · ワークスペースを選択してください · ダイレクト接続またはプロキシ接続の設定 · 電話番号を入力するか、ファイルまたはQRコードを選択してください · アカウントの身元を確認し、アクセス可能なグループを選択してください · イベントおよび添付ファイルの保存ポリシーを設定してから、監視を開始してください · エラー、アクセス、キュー、ディスクの状態を監視します · 独立したチェックポイントを保持する · 資料のエクスポートと検証

**図表をテキストで記述**

1. 保存先と鍵の保護方法を選択してください → トークンを使用してパネルを開く
2. トークンを使用してパネルを開く → ワークスペースを選択してください
3. ワークスペースを選択してください → ダイレクト接続またはプロキシ接続の設定
4. ダイレクト接続またはプロキシ接続の設定 → 電話番号を入力するか、ファイルまたはQRコードを選択してください
5. 電話番号を入力するか、ファイルまたはQRコードを選択してください → アカウントの身元を確認し、アクセス可能なグループを選択してください
6. アカウントの身元を確認し、アクセス可能なグループを選択してください → イベントおよび添付ファイルの保存ポリシーを設定してから、監視を開始してください
7. イベントおよび添付ファイルの保存ポリシーを設定してから、監視を開始してください → エラー、アクセス、キュー、ディスクの状態を監視します
8. エラー、アクセス、キュー、ディスクの状態を監視します → 独立したチェックポイントを保持する
9. 独立したチェックポイントを保持する → 資料のエクスポートと検証

認証、通信接続、グループへのアクセス、および配信の完全性は、 それぞれ異なる特性です。接続ステータスが緑色であっても、すべての イベントが記録されたことを意味するわけではありません。

## 主鍵を共有せずに作業内容を共有する

「オープン**アクセス」**機能により、レビュー担当者やアナリストに独自のトークンを付与できます。対象のアカウント やチャットを選択し、閲覧、エクスポート、または操作を許可します。 収集の開始・停止を行うオペレーターにはワークスペース全体へのアクセス権が必要ですが、レビュー担当者は 単一のチャットに限定することも可能です。セッション制限、有効期限、およびIPルールは、 Telegramアカウントの認証とは別個に設定されます。[アクセスと権限については](https://phishdestroy.github.io/TgWitness/ja/docs/reference/access/)こちらをご覧ください。

**「Open sessions」**を使用して接続を終了するか、アクセス権を無効化してすべての セッションを終了させてください。管理者コンソールでは、ワークスペースを横断して 現在のプロセスのアクティビティを一元的に確認できます。セッションを終了しても、データ収集は継続されます。

## 実行モード

| モード | アクション | 動作 |
| --- | --- | --- |
| デモ | scripts\Demo.cmd または `--demo` | 合成データ；実際のアカウントとの連携は無効化されています |
| 所見 | 監視を開始する | 選択した情報源について、配信された更新情報を記録します |
| 履歴のスナップショット | 出典 → 履歴のスナップショット | 最大500件の最新メッセージを保存します。過去の変更履歴のすべてを復元することはできません。 |
| 一時停止 | 観察の一時停止 | データを保持したまま、収集を停止し、キューに格納されたジョブを保留にする |
| レビュー／引き継ぎ | エクスポート | ZIP、JSONL/CSV/HTML、チェックポイント、処理確認書、およびタイムスタンプのリクエスト |
| 複数のアカウント | ワークスペース、または上部の「**+**」ボタン | 1つのプロセス内で、いくつでも個別のワークスペースを作成できます |

ローカルデモへのアクセスは、手動でトークンを入力することなく自動的に開始されます。これは、 隔離された 合成デモへの直接ループバックアクセスにのみ有効な、プロセス存続期間中の機能を使用しており、メインパネルのトークンは開示されません。実際のワークスペースおよびリモート またはプロキシ経由のデモアクセスでは、トークン認証が維持されます。デモへのアクセスによって、Telegramの権限が付与されることはありません。

## 監視カテゴリ

![アカウントごとの監視設定と合成ソースデータ](https://phishdestroy.github.io/TgWitness/assets/sources.png)

[**ソース] → [キャプチャ設定] → [保存する変更の選択]** で、新しいメッセージ、編集、 削除通知、リアクションの更新、メンバーシップのイベントを個別に選択できます。デフォルトでは すべてのカテゴリが保存されます。**「メッセージ、編集、削除」**を選択すると、元のコンテキストが 保持され、個別のリアクションやメンバーシップの更新は保存されません。 「**すべての表示可能なアクティビティ」を選択すると、** これら5つすべてが保存されます。プリセットで形式を変更できます。「**監視設定を保存」**を押して適用してください。

保存されたポリシーは、そのワークスペース内で選択されたすべての情報源に適用されます。その他の ワークスペースは、それぞれ独自の設定を維持します。実際の変更ごとに、署名付きの変更前・変更後の 値が記録されます。また、現在のポリシーは、処理レシートおよび観測 開始記録にも含まれます。カテゴリを無効にしても、それ以前の観測データは削除されません。再有効化 しても、見逃された変更は復元されません。 このバージョンでは、グループごとのカテゴリ上書き機能はありません。

以前のコンテンツが重要な場合は、新しいメッセージの記録を有効にしておいてください。削除通知では、 一度もキャプチャされなかったテキストを復元することはできません。運用・カバレッジ記録やその他のグループ サービスイベントは常に保持されます。 明示的な履歴スナップショットは、 リアルタイムのカテゴリ選択とは別のものであり、サービスメッセージが含まれる場合があります。これらの設定は、 それ以外にはキャプチャされたTelegramオブジェクトに埋め込まれた反応やメンバーのメタデータを 削除するものではありません。

履歴のスナップショットは、一時停止中に添付ファイルをキューに入れる場合があります。処理を行うには、監視を開始してください。 キューに入れられたからといって、ダウンロードされたわけではありません。利用できない元のファイルは、 新しい編集版に置き換えられず、結果は個別に記録されます。

**「ロック」**操作を行うと、ブラウザへのアクセス権と秘密フィールドはクリアされますが、データ収集は継続されます。 タブを閉じても、プロセスは実行されたままとなります。Pythonプロセスまたはサービスを停止すると、 ブラウザの状態にかかわらず、データ収集は停止します。

追加のワークスペースを削除すると、そのコレクターが停止し、ローカルデータが削除されます。 ロックされたファイルやファイルシステムのエラーにより削除が中断された場合、パネルには失敗が報告され、 そのワークスペースは「利用不可（`DeletionPending`）」としてリストに残ります。そのファイルを保持している プログラムを閉じてから、**削除を**再試行してください。 TgWitnessを再起動しても、そのワークスペースは停止したままとなり、 部分的に削除されたジャーナルや鍵は再作成されません。削除が成功したことは、 ディレクトリが削除された後にのみ記録されます。別途エクスポートまたはバックアップされたコピーは、 それぞれの保存ポリシーに従って保持されます。

## 通知

オープン**ソース → 通知 → アラートおよび日次サマリー**。TgWitnessは Appriseを利用して、Matrix、Telegram、Discord、Slack、ntfy、電子メール、およびその他の 対応サービスへアラートを送信します。1つのワークスペースに複数の送信先を追加することができます。

1. 1行につき1つのApprise送信先URLを入力してください。ご利用のサービスに応じた [サービスカタログおよびURL形式](https://appriseit.com/services/)をご使用ください。
2. 「**通知を送信**」をオンにしてから、「問題アラート」、「監視対象の チャットでの変更」、および「日次サマリー」を選択してください。サマリーの時刻はサーバーの時刻に基づきます。
3. 削除および編集された メッセージの保存テキストをアラートに含めたい場合は、「**短い抜粋を含める」**をオンにしてください。
4. **「保存」通知**をタップし、次に「**テスト送信」**をタップして配信状況を確認してください。

独自の受信先を設定する場合は、AppriseのJSON[Webhook](https://appriseit.com/services/json/)をご利用ください。 例えば、`jsons://notify.example.org/tgwitness`はHTTPS経由でその エンドポイントにJSONを送信します。これは架空の例ですので、実際の受信先に置き換えてください。

宛先や設定は、選択されたワークスペースに属します。変更通知は、 新たに追加されたチャットを含め、監視対象のソースを網羅しています。トップバーのベルアイコンには、 最近の問題やチャットの変更も一覧表示されます。

デモでは、通知設定は表示されていますが、送信機能は無効になっています。実際のワークスペースで 配信設定を行ってください。通知は、そのワークスペースのDirect、SOCKS5、または HTTPルートを使用します。MTProxyでは通知を転送できません。SMTPなどのHTTP以外の宛先には、 ダイレクトルートが必要です。

## パネルレイアウト

![合成データを用いた接続ワークスペース](https://phishdestroy.github.io/TgWitness/assets/connection.png)

**ジャーナルには**、観測結果、検索、およびフィルタが表示されます。編集を行うと、記録された各バージョンが表示され、 削除を行うと、利用可能な場合は削除前のコンテンツが表示されます。出典が不明な場合は、その旨が明示されます。 集計データは「**概要**」で確認でき、取得の詳細についてはローカルガイドに記載されています。

編集されたメッセージを開くと、**文中の差分**または**並べて表示**でバージョンを比較できます。**元データ**には保存されたフィールドが表示されます。隠しリンクやボットボタンへの変更は個別に表示されます。添付ファイルのプレビューを開くと、保存された画像、音声、または動画を確認できます。ダウンロードボタンを使用すると、保存されたオリジナルファイルを取得できます。

**Live** は、レコードの到着に合わせてジャーナルとチャットを更新します。確認中は一時停止するか、準備ができたときに新着イベントボタンを使用してください。その間も収集は継続されます。**Ctrl/Cmd+K** でパネルのアクションを検索したり、ジャーナル内を検索したりできます。

**「ソース」**には、監視範囲（選択したチャット、Telegramのフォルダ、またはアカウント全体 ）、あらゆる種類のアクセス可能なチャット、優先度スターが付いた選択済みソース、添付ファイル および再確認の設定、履歴のスナップショットが含まれます。非公開のソースは、公開リンクなしで、ダイアログまたはID によって選択されます。「アクセスステータス」は、恒久的な権限ではなく、直近の確認状況を表しています。

ソースをフィルタリングしてチェックボックスを選択し、まとめて有効化、一時停止、または優先としてマークできます。利用可能なチャットリストでは、**選択した項目を追加**は選択した項目を使用し、**一致するすべてを追加**は現在の検索条件とタイプフィルターを使用します。

**「チャット」→**「**ユーザー**一覧」には、メッセージが保存されているすべてのユーザーが表示されます。チャットでユーザープロファイル機能が有効になっている場合、 クリックするとそのユーザーのプロファイルが開き、ジャーナル記録へのリンクが表示されます。

**Witnessは**読み取り専用のウィットネストークンを作成し、各ウィットネスが最後に確認された日時を表示するとともに、 （[独立したウィットネスを](https://phishdestroy.github.io/TgWitness/ja/docs/reference/witness/)）1つ実行するためのコマンドとオプションを提供します。

**「パラメータ」**には、他のページに記載されていないワークスペースのあらゆる制限やペースが記載されています： 読み込まれるダイアログの数、チャットリストの再読み込み頻度、ハートビートおよびチェックポイントの 間隔、起動時のバッファ、再チェック時のリクエストの分散方法（最初の遅延、 パスごとのチャット数、チャット間の休止時間、復元および再リクエストされるメッセージ数）、ディスクの予約容量、ダウンロードのタイムアウトおよび 再試行、ユーザープロファイルの検索条件（独自の正規表現を含む）、 通知のサイズと頻度、スナップショット、ZIPおよびブラウザダウンロードの制限、ならびにTelegram クライアントのタイムアウトと再試行。 各フィールドにはその範囲とデフォルト値が表示されており、変更されたフィールドには マークが付いており、1つずつ、またはまとめて元に戻すことができます。すべての変更は 「`parameters.changed`」として変更前後の値とともに記録され、観測開始記録には その時点で有効な値が記載されます。 設定値は次回使用時から適用され、クライアントのタイムアウトや再試行は 次回の接続時から適用されます。再確認間隔、添付ファイルの種類とサイズ、証拠データおよびオフサイトコピーの 間隔については、それぞれのページに表示され、プリセットだけでなく、範囲内の任意の値を設定できます。

上部バーのベルアイコンには、監視対象のチャットにおける最近の問題や変更が一覧表示されます。未読のものは、 既読としてマークされるまでカウントされます。変更はチャットごとおよび時間ごとにグループ化され（「削除 12件、 編集 1件、見つかりませんでした 0件」）、ログアウトやディスク容量不足などの問題は、 チャットがどれほど活発であってもリストに残ります。

**アカウント作成**は電話番号入力欄から始まります。**「続行」をクリックすると**、 コード入力画面に直接遷移し、API認証情報が未入力の場合にのみ入力が求められます。QRコードおよびファイルインポートは、 別のタブから利用可能です。保存されたAPI認証情報は、そのワークスペース内でのみ再利用されます。 入力画面にはサイドバー、統計情報、設定に関する説明文は表示されません。 「**設定**」 アイコンをタップすると、API、プロキシ、ストレージ、および追加アカウントの設定画面が開きます。新規インストールは ここから開始されます。ソースが選択されていない接続済みアカウントの場合は、**「チャットを選択」**画面から開始されます。 ルートの変更には監視の一時停止が必要であり、未完了のログインはキャンセルされます。既存の ジャーナルを、別のTelegramアカウントに自動的に再紐付けすることはできません。

**エクスポート機能は**ジャーナルの整合性を確認し、ポータブルなファイルを生成します。そのワークスペースIDは ダウンロード用CLIに渡すことができます。各エクスポートでは、ジャーナル全体のプレフィックスが固定されます。それ以降の イベントは、次のエクスポートに含まれます。検索フィルターはパッケージの範囲を変更しません。 詳細な署名および対象範囲に関する情報は、「**検証と制限事項**」に記載されています。

このパネルでは、「**Collector」の健全性状況**として、コレクターの状態、キュー入りまたは失敗したメディア、最も古い保留中のメディア、空き ディスク容量、リクエストの一時停止、およびアクセスが未確認のソースを報告します。 これらの詳細は、初期状態では折りたたまれており、「アカウント」画面では非表示になっています。セットアップ カードには、次の手順（アカウントの接続、ソースの選択、または監視の開始）が表示されます。 アカウント一覧は読み込み時のスナップショットであり、 選択されたワークスペースは定期的に更新されます。これはマルチプロセス型のSLAモニターではありません。

UIでは、ソースコンテンツに対してローカルアセットとテキストレンダリングを採用しています。デスクトップおよび幅の狭い Chromiumレイアウトでの動作確認は完了しています。これは完全なアクセシビリティ認証ではありません。 スクリーンリーダーおよび人間によるユーザビリティ評価については、別途作業が必要です。

## 導入環境

| 環境 | インストール | 検証状況 |
| --- | --- | --- |
| Windows PC／サーバー | Python 3.11 以上、scripts\Setup.cmd/Start.cmd、プライベートデータディレクトリ | Windows/Python 3.12環境でローカルに検証済みです。 |
| Linuxサーバー／VPS | Pythonのvenv、専用サービスユーザー、HTTPS/SSH | コード、CI、および systemd の例が提供されていますが、このホスト上では実行されていません。 |
| macOS | Pythonのvenv、フォアグラウンドプロセス、またはユーザーエージェント | launchd の使用例を掲載しています。別途、インストール状況の確認が必要です。 |
| Docker/Compose | 永続ボリューム、ワーカー1台 | 定義とCIランタイムチェックが提供されています。ローカル環境ではDockerは利用できません。 |
| スマートフォン用ブラウザ | 稼働中のサーバー上の保護されたパネルに接続してください | Chromiumのナローレイアウトでの動作確認済みです。コレクターはiOS/Androidでは動作しません。 |

移植性が高いため、クラウドサービスやフロントエンドの構築は必須ではありません。ただし、各ターゲットには 互換性のある Python/crypto 依存関係、ローカルディスク、およびネットワークアクセスが必要です。 [DEPLOYMENT.md](https://phishdestroy.github.io/TgWitness/ja/docs/reference/deployment/) および[サービステンプレート](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md)をご参照ください。

ワークスペースは、CPU、メモリ、およびイベントループを共有します。プロセスの分離を行うには、個別の インスタンス、ポート、データディレクトリ、およびアカウント認証を使用してください。別々のインスタンス間で統一された 管理パネルは存在しません。複数のワーカーを1つのデータベースに割り当てないでください。

## 起動時の確認とエクスポート

準備済みの環境を起動する前に、`python start.py --check` を実行してください。機械可読なチェックを行う場合は `--json` を追加するか、指定した `--data-dir`、`--host`、`--port` を渡してください。 このコマンドは、Telegramへのログインやジャーナルの作成を行わずに、前提条件を確認します。 ジャーナルの検証やキャプチャの準備状況の確認は行いません。ジャーナルの検証は アプリケーションの起動時に実行されます。ポートが使用中の場合は、単に既存のインスタンスが存在している可能性があります。

File System Access API をサポートするブラウザでは、書き込み可能な ストリームを通じてエクスポートデータが保存されます。その他のブラウザでは、最大 128 MiB までがバッファリングされます。より大規模な エクスポートや、ファイルストリーミングに対応していないブラウザでは、ストリーミング CLI をご利用ください：

```
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
```

子ワークスペース用のエクスポートから「`--profile ID` 」を追加してください。リモートアクセスには「`--url https://server` 」を使用してください。プレーンHTTPは、ループバック先でのみ受け入れられます。トークンは ファイルから読み込まれ、ヘッダーとして送信されます。画面に表示されたり、URLに含まれたりすることはありません。リダイレクトは 拒否されます。既存の出先は上書きされません。 転送に失敗した場合は、 その一時的な部分ファイルが削除されます。報告される SHA-256 は転送チェックサムです。署名付き ZIP ファイルについては、信頼できるフィンガープリントまたはチェックポイントを用いて別途検証してください。

## バックアップ、復元、および中断について

1. 監視を一時停止し、プロセスを完全に終了させてください。
2. データディレクトリ全体をコピーしてください：データベース、WAL/SHM（存在する場合）、メディア、 `credentials.enc`、`signing.enc`、`network.enc`、Vaultキー/メタデータ、トークン、 チェックポイント、およびすべての`profiles/`ディレクトリです。
3. 外部キーモードの場合、マスターキーを別途保管し、各 `vault.external.json`を保持してください。新しいキーを生成しても、以前の秘密鍵を復元することはできません。
4. 宛先が停止している間に復元を行い、元のキーを設定し、 アクセスを制限し、再開前に整合性を検証してください。
5. ダウンタイムおよび検証結果を記録してください。履歴のスナップショットだけでは、 中断中に削除が行われなかったことを証明することはできません。

証拠用ZIPファイルには、セッションや秘密鍵は含まれておらず、完全なサービスバックアップではありません。 以下の4つの項目については、異なる方法で保護されています：

| 概要 | 保護 |
| --- | --- |
| パスワードなしでファイルをエクスポートする（デフォルト設定） | 暗号化はされていません。署名されているため、変更は検出可能ですが、ファイルをお持ちの方なら誰でも閲覧できます。 |
| パスワード付きでファイルをエクスポートする | パスワードを設定した場合、エクスポートされたデータは変更されることなく、7-ZipやWinRARで開くことができるWinZip AES-256 ZIP形式で保存されます。パスワードは保存されません（[証拠の取り扱い](https://phishdestroy.github.io/TgWitness/ja/docs/reference/evidence/)）。 |
| ジャーナルデータベースおよびディスクに保存された添付ファイル | TgWitnessによる暗号化は行われません。暗号化されたディスクまたはボリュームをご利用ください。 |
| Telegramのセッションと署名鍵 | データディレクトリ内で暗号化されています（`credentials.enc`、`signing.enc`、`network.enc`）。 |

フルサービスのバックアップとは、前述の停止されたデータディレクトリのことであり、エクスポートではありません。 両方とも、保護されたストレージと意図的な転送メカニズムを使用してください。一時的なサーバーエクスポートは各ワークスペースの `temporary-exports/`に保存されます。完了したレスポンスはクリーンアップされ、中断されたエクスポート ファイルは、そのワークスペースのインスタンスロックが保持されている間に、次回の起動時に削除されます。

接続が復旧したとしても、その間に生じた変更が確実に復元されるわけではありません。 永続的なメディアジョブおよびTelegramの更新位置情報は、再起動後も保持されます。 [証拠形式については](https://phishdestroy.github.io/TgWitness/ja/docs/reference/evidence/#durable-collection-and-process-receipts-02)、そちらをご参照ください。

## 容量と保存期間

デフォルトの制限値は、**「Parameters」**で変更可能です：最初の 1,000 件のダイアログ、スナップショットあたり 500 件のメッセージ 、4 GiB の非圧縮署名付き ZIP コンテンツ（これより大きなアーカイブには `verify.py --max-gib N` が必要です）、および 128 MiB のブラウザ用フォールバック。 添付ファイルは、「**ソース」→「添付ファイル」**で、 種類ごとに1～2,000 MiBを消費します。ダウンロード用CLIのデフォルト転送量は5 GiBです。利用可能なディスク容量が これより少ない場合は、ジャーナル、メディア、WAL、一時的なエクスポート、およびバックアップ用に十分な空き容量を確保してください。 エクスポートでは、Composeの512 MiB（`/tmp`）ではなく、データ容量が使用されます。

単にグループ数を数えるのではなく、1秒あたりのイベント数、キューの経過時間、メディアのバイト数、ディスクのレイテンシを測定します。 ローカルでの合成ベンチマークでは、Telegramでの配信が保証されるわけではありません。 自動的な保存データの削除機能はありません。ジャーナルの末尾を削除すると、 保存されているチェックポイントとの関連性が無効になります。

優先再チェック機能はすでに実装されています。スター付きの情報源はデフォルトで15分ごとに再チェックされ、 その他の情報源は6時間ごとに再チェックされます（[再チェックの優先順位を](https://phishdestroy.github.io/TgWitness/ja/docs/reference/collection/#recheck-tiers)参照）。パスワードで保護された エクスポート機能は、前述の通り実装されています。 Telegram/プロキシのリアルタイム受信、耐久性のある再生、 管理者ログおよびリアクションのポーリング、隔離されたワーカー、TgWitness自体によるローカルジャーナルおよびメディアの 暗号化、ならびに独立したレビューについては、引き続き別途の作業となります。アクセス範囲の制限については、 「[アクセスと権限](https://phishdestroy.github.io/TgWitness/ja/docs/reference/access/)」に記述されています。 [READINESS.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/READINESS.md)、[LIVE_ACCEPTANCE.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/LIVE_ACCEPTANCE.md)、および [VERIFICATION.md](https://phishdestroy.github.io/TgWitness/ja/docs/reference/verification/)をご参照ください。