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

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

構成要素	Deploy	Undeploy
Agent	`scripts/deploy/agent.ps1`	`scripts/undeploy/agent.ps1`
Backend	`scripts/deploy/backend.ps1`	`scripts/undeploy/backend.ps1`
NATS server	`scripts/deploy/nats.ps1`	`scripts/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` が削除するもの
Agent	`config\agent.toml`、`logs\agent.*.log`、`outbox\`、`HKLM:\SOFTWARE\kanade\agent\`
Backend	`config\backend.toml`、`data\.db` (SQLite — 過去の results / inventory が消える)、`logs\backend.*.log`、`HKLM:\SOFTWARE\kanade\backend\`
NATS	`config\nats-server.conf`、`nats\` (JetStream — KV / Object Store / streams すべて消える)、`logs\nats*.log`
Client	追加なし (per-user な state はまだ存在しない)

⚠️ 危険なのは undeploy-nats.ps1 -Purge と undeploy-backend.ps1 -Purge。前者は fleet 全体の JetStream state (agent_releases、app_packages、scripts、jobs、agent_config、results stream) を消し、後者は projector の過去の SQLite を消します。どちらも out-of-band バックアップ無しではリカバリ不能。スクリプトは実行前に目立つバナーを出します。

ロールバックの定石

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
# Now nothing about kanade exists on the box.

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 を実行し直してください。
It doesn't touch NATS-side state when you remove the agent — the agent's target_version entry under agent_config.pcs.<pc> stays in the KV. Clean those up server-side with nats kv del agent_config pcs.<pc>.target_version (using an administrative broker credential) if needed.

kanade — 奏