> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.

# トークン移行ツールの停止と再開

> トークン移行ツールは、再起動後、永続ボリュームに保存されたタイムスタンプの時点から処理を再開します。一部のトークンを再処理することはありますが、トークンの移行漏れは発生しません。

トークン移行ツール（Token Migrator）は、セルフマネージド環境で Authlete 2.3 から 3.0 へトークンを移行するために、Helm チャートでデプロイするツールです。導入手順は「[Kubernetes インストールガイド](/ja/deployment-and-operations/self-managed-deployment/kubernetes-installation-guide#移行フェーズ（任意）)」の「移行フェーズ（任意）」を参照してください。

トークン移行ツールは、コンテナが起動すると自動的に移行を開始します。初回の起動であるかどうか、前回の停止が意図的であったかどうかは、移行の開始に影響しません。トークン移行ツールは、Helm チャートがマウントする永続ボリュームに進捗を保存します。永続ボリュームに保存された進捗がある場合、トークン移行ツールは最後に保存した時点から処理を再開します。前回の続きから再開するには、同じ永続ボリュームをマウントした状態で起動する必要があります。再開時に一部のトークンを再処理することはありますが、トークンの移行漏れは発生しません。

## トークン ID のマッピングファイル（mapping-output）

`mapping-output` ディレクトリには、クライアントごとにひとつのマッピングファイルが格納されます。マッピングファイルは、トークン移行ツールが移行処理の一環として生成します。マッピングファイルは、移行元の各トークン ID を移行先のトークン ID に対応付けます。トークン移行ツールは、移行元のトークンが変更されたときに、マッピングファイルを使用して更新対象となる移行先のトークンを特定します。各ファイルの名前は `<サービス ID>:<クライアント ID>.json` です。

マッピングファイルが失われた場合、トークン移行ツールはマッピングファイルを再生成します。ただし、一部のトークンが、マッピング済みの既存トークンの更新ではなく、移行先に新しいトークンとして作成されることがあります。マッピング済みだった既存のトークン（古いトークン）は移行先に残るため、移行元でリフレッシュまたは失効されたトークンが、移行先では有効なままとなる可能性があります。

マッピングファイルが失われた場合は、トークン移行全体を最初からやり直すことを推奨します。次の手順でやり直します。

1. トークン移行ツールを停止します。
2. 移行済みのサービスとクライアントを移行先から削除します（トークン移行ツールが使用するサービスとクライアントは残します）。
3. トークン移行ツールの永続ボリューム上のファイルをすべて削除します。
4. [サービスとクライアントを再度移行](/ja/deployment-and-operations/migration-from-existing-system/migrating-settings-from-an-older-version-of-authlete)します。
5. トークン移行ツールを起動します。

## 復旧ポイント

### 処理完了時点のタイムスタンプの保存方法

移行中、トークン移行ツールは、どの時点までのトークン変更をすべて処理したかを、処理完了時点のタイムスタンプとして記録します（ログ上の表記は `moving timestamp` です）。処理完了時点のタイムスタンプまでのトークン変更をすべて処理した後、トークン移行ツールはタイムスタンプの値を **ミリ秒**単位の Unix エポック時刻で `timestamp.txt` に書き込みます（例: `1784401524667`）。

`timestamp.txt` は、トークン移行ツールが停止した場合の復旧ポイントです。次回の起動時、トークン移行ツールは `timestamp.txt` に記録された時刻から処理を再開します。

トークン移行ツールはすべてのトークン変更を処理してから `timestamp.txt` を書き込むため、`timestamp.txt` の時点から再開しても、トークン変更の処理漏れは発生しません。ただし、作成済みまたは更新済みのトークンを再処理することはあります。

### timestamp.txt が失われた場合

`timestamp.txt` が失われると、トークン移行ツールは次回の起動時に `timestamp.txt` を読み込めず、起動時のログに `Read in moving timestamp initial value` の代わりに `Setting moving timestamp to the provided initial timestamp [<value>]ms` を出力します（「[処理完了時点のタイムスタンプの確認](/ja/deployment-and-operations/self-managed-deployment/token-migrator/interpreting-token-migrator-logs#処理完了時点のタイムスタンプの確認)」を参照）。`timestamp.txt` が失われた場合は、次の手順で復旧します。

1. トークン移行ツールを停止します（例: `tokenmigrator.enabled` を `false` に設定して `helm upgrade` を実行します）。
2. シャットダウン時のログ `Shutting down sync migration task, latest timestamp [<value>]ms` から、処理完了時点のタイムスタンプの最新値を確認します（「[シャットダウン時のログ](/ja/deployment-and-operations/self-managed-deployment/token-migrator/interpreting-token-migrator-logs#シャットダウン時のログ)」を参照）。
3. 確認したタイムスタンプの値（ミリ秒単位）のみを記載した `<マウントパス>/timestamp.txt` を作成します。
4. トークン移行ツールを再度起動します。

コンテナが強制終了され、シャットダウン時のログが出力されなかった場合は、失われた処理完了時点のタイムスタンプよりも前であることが確実な値を使用してください（例: 最後に出力された `Read in moving timestamp initial value` ログの値）。当該値から再開した場合の影響は、一部のトークンの再処理に限られます。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.