EN | JA

kanade をホストから取り除く (undeploy)

本番でのロールバック経路。rollout で何かが壊れた、ホストを廃止する、再インストール用にまっさらな状態に戻したい — そんなときホストから kanade を剥がすために、deploy と対になる undeploy スクリプトをコンポーネントごとに 1 本ずつ用意しています。

構成要素DeployUndeploy
Agentscripts/deploy/agent.ps1scripts/undeploy/agent.ps1
Backendscripts/deploy/backend.ps1scripts/undeploy/backend.ps1
NATS serverscripts/deploy/nats.ps1scripts/undeploy/nats.ps1
Client (Tauri)configs/jobs/installers/scripts/install-kanade-client.ps1 (エージェント経由)scripts/undeploy/client.ps1

4本とも管理者専用かつ冪等です。アンインストールが途中で終わったあとに再実行しても安全ですし、対象がすでに無い状態で実行しても安全です (各ステップが「not present, skipping」と記録して次に進みます)。

デフォルトの姿勢: 安全側

フラグなしで実行するとスクリプトは:

  • Windows サービスを停止します。
  • SCM からサービスを unregister します (エントリが実際に消えるまで待つので、後続の再 deploy が pending な削除と race しません)。
  • %ProgramFiles%\Kanade\ からインストール済みバイナリを削除します。中途半端な <exe>.new / <exe>.old の swap 残骸もまとめて削除。
  • deploy スクリプトが作成した inbound のファイアウォールルールを削除します (-KeepFirewall で skip 可 — 外部の WAF / グループポリシーがルールを管理している場合に有用)。
  • %ProgramData%\Kanade\ 配下 (config、log、JetStream データ、SQLite DB、…) は 残します。フォレンジック / rollback / 再 deploy が state を失わずに進められるように。
  • HKLM:\SOFTWARE\kanade\<role>\* のレジストリ secret も 残します。

よくあるケース —「この端末の kanade がおかしいので、状態を壊さずに外したい」— にはこれで十分です。

-Purge: 破壊的クリーンアップ

追加で:

  • そのコンポーネント固有の %ProgramData%\Kanade\ 配下エントリを削除します。重要なのは そのコンポーネント自身のファイルだけ — agent / backend / NATS は同じ root を共有しているので、各スクリプトは他のコンポーネントのファイルには触れません。
  • 対応する HKLM:\SOFTWARE\kanade\<role>\* キーを削除します (-KeepSecrets を併せて渡すとスキップ — 複数コンポーネントで同じ bearer を共有しているときに有用)。
構成要素-Purge が削除するもの
Agentconfig\agent.toml、logs\agent.*.log、outbox\、HKLM:\SOFTWARE\kanade\agent\
Backendconfig\backend.toml、data\*.db* (SQLite — 過去の results / inventory が消える)、logs\backend.*.log、HKLM:\SOFTWARE\kanade\backend\
NATSconfig\nats-server.conf、nats\ (JetStream — KV / Object Store / streams すべて消える)、logs\nats*.log
Client追加削除なし。-Purge は未実装のプレースホルダーで、ユーザーごとのウィンドウサイズなどの状態を保持します。

⚠️ undeploy-nats.ps1 -Purge と undeploy-backend.ps1 -Purge は破壊的です。前者はフリート全体の JetStream 状態(agent_releases、app_packages、scripts、jobs、agent_config、results stream)を消し、後者は永続アカウント、承認、スケジューラ完了記録を含むバックエンド SQLite を消します。別途バックアップがなければ復旧できません。 スクリプトは実行前に警告を表示します。

ロールバックの定石

canary 1 台で rollout が壊れたとき

# On the canary, as Admin:
.\scripts\undeploy\agent.ps1            # safe default
# kanade is now off the host. Re-deploy when ready:
.\scripts\deploy\agent.ps1 -SourceDir C:\path\to\prev-version

ホストを恒久的に廃止する

.\scripts\undeploy\agent.ps1 -Purge

dev box を再インストール用にまっさらにする

.\scripts\undeploy\agent.ps1 -Purge
.\scripts\undeploy\backend.ps1 -Purge   # ⚠️ SQLite gone
.\scripts\undeploy\nats.ps1 -Purge      # ⚠️ JetStream gone
.\scripts\undeploy\client.ps1
# Client user state and registration/shortcut artifacts may remain.

state は触らず壊れたサービスだけ作り直す

.\scripts\undeploy\backend.ps1          # safe default: SQLite intact
.\scripts\deploy\backend.ps1 -Recreate  # fresh service registration, same data

undeploy がやらないこと

  • この端末が居なくなったことをフリートの他の部分に通知はしません。バックエンドはハートビートが時効になるまで (/api/agents の staleness 閾値) 「エージェント」に載せ続けます。SPA から即座に消したい場合は、undeploy のあとバックエンド API で行を削除してください。
  • デプロイ済みバイナリを以前のバージョンへ戻すことはしません。このスクリプトの語彙では「ロールバック」は「完全に削除する」という意味です。古いバージョンへ入れ替えたい場合は、そのバイナリが入ったフォルダに対して対応する deploy-*.ps1 を実行し直してください。
  • エージェント削除時に NATS 側の状態は変更しません。PC ごとの target pin は kanade config unset --pc <pc> target_version、そのスコープ全体は kanade config clear --pc <pc> で削除します。認証付きバックエンド API を使い、operator 権限が必要です。
  • client スクリプトが削除するのは実行ファイルと swap 残骸のみです。ユーザー状態、プロトコル登録、ショートカットは削除せず、-Purge もこれらの削除を実装していません。