kanade-backend のアップデート

backend は管理対象ホスト 1 台 (またはそれ以上) で Windows サービスとして動いています。agent 経由のアップデートとはつまり、そのホスト上で動いている agent がサービスを止め、バイナリを差し替え、再起動するという話 — operator はそのホストに一度もログインしません。

end-to-end フロー

┌── operator host ──────────────────────────────────────────┐
│  1. build kanade-backend.exe                              │
│  2. kanade app publish kanade-backend <v> <exe>           │
│  3. edit deploy-backend.ps1 (set $AgentSource* knobs)     │
│  4. kanade script publish deploy-backend <v> <edited.ps1> │
│  5. kanade job create install-kanade-backend.yaml         │
│  6. kanade exec install-kanade-backend --pcs <host>       │
└────────────────────────────────────────────────────────────┘
                      │
                      ▼
┌── target host (running kanade-agent as LocalSystem) ──────┐
│  • agent receives the Command on commands.pc.<host>       │
│  • fetches deploy-backend.ps1 from OBJECT_SCRIPTS         │
│    sha-verifies it (`script_object` machinery, #214)      │
│  • stages it under                                        │
│    C:\ProgramData\Kanade\agent-scripts\<UUID>\            │
│    kanade-<UUID>.ps1                                      │
│  • runs `powershell -File <launcher>` (PR #230 fix)       │
│  • launcher invokes the user script via `& '...'`         │
│    so [CmdletBinding()] / param() headers parse           │
│  • script downloads kanade-backend.exe from               │
│    OBJECT_APP_PACKAGES (via /api/app-packages/…)          │
│    sha-verifies it (separate hash, on the exe itself)     │
│  • Stop-Service KanadeBackend                             │
│  • copy exe over C:\Program Files\Kanade\…                │
│  • Start-Service KanadeBackend                            │
│  • exit 0 — result published to NATS                      │
└────────────────────────────────────────────────────────────┘

sha チェックが 2 段ある理由は意図的: スクリプト本体のハッシュは agent が実行前に検証 (スクリプトの完全性)、バイナリのハッシュはスクリプトが swap 前に検証 (バイナリの完全性、operator が $AgentSourceSha256 で指定)。

ステップごとの手順

1. kanade-backend をビルド

cargo build --release -p kanade-backend

出力: target/release/kanade-backend.exe。

2. バイナリを publish

kanade app publish kanade-backend 0.43.0 target/release/kanade-backend.exe

これでバイナリが OBJECT_APP_PACKAGES/kanade-backend/0.43.0 にアップロードされ、sha-256 digest が表示されます。digest を控えておきましょう — 後でスクリプトに lowercase-hex 形式で書き込みます。

3. scripts/deploy/backend.ps1 を編集

ローカルコピーを作って、先頭の 4 つの $Agent* ノブをセットします:

$AgentSourceUrl       = 'http://kanade-backend.example.com:8080'
$AgentSourceVersion   = '0.43.0'
$AgentSourceSha256    = '<kanade-backend.exe の lowercase hex>'
$AgentSourceAuthToken = '<backend HTTP API 用 bearer>'

スクリプトの他の部分は触らないでください — このノブが「agent モード」(backend からダウンロード) と「手動インストールモード」(ローカルフォルダから 読み込み) を切り替えるトリガになっています。

$AgentSourceSha256 は Get-FileHash kanade-backend.exe -Algorithm SHA256 の hex 形式の値です。

kanade app publish の出力にある base64url 形式しか手元にない場合は decode します。CLI から出る base64 は URL-safe で padding なしのことがあるので、FromBase64String に通す前に padding を補う必要があります:

$b64 = '<paste the SHA-256= value here, without the SHA-256= prefix>'
$b64 = $b64.Replace('-', '+').Replace('_', '/')
if ($b64.Length % 4) { $b64 += '=' * (4 - $b64.Length % 4) }
[BitConverter]::ToString([Convert]::FromBase64String($b64)).Replace('-', '').ToLowerInvariant()

Python の場合: python -c "import base64; print(base64.urlsafe_b64decode('<b64>' + '=' * (-len('<b64>') % 4)).hex())"

$AgentSourceAuthToken は 2026-05-26 の live test 以降必須です — backend の /api/app-packages/<name>/<ver> エンドポイントは token なしだと HTTP 401 を返します。auth なしの lab 環境のときだけ空のままで OK。

4. 編集したスクリプトを publish

kanade script publish deploy-backend 0.43.0 .\deploy-backend.edited.ps1

アップロード先は OBJECT_SCRIPTS/deploy-backend/0.43.0。

5. ジョブを登録 / 更新

リポジトリの configs/jobs/installers/install-kanade-backend.yaml がテンプレートです。version: と script_object: をいま publish したバージョンに合わせて編集してから upsert:

id: install-kanade-backend
version: 0.43.0
execute:
  shell: powershell
  script_object: deploy-backend/0.43.0
  timeout: 300s
  run_as: system
require_approval: true

kanade job create jobs\install-kanade-backend.yaml

run_as: system は必須です: Stop-Service / Start-Service / sc.exe はいずれも admin が必要です。本番環境では agent は LocalSystem で動いているので問題ありません。

6. 起動

kanade exec install-kanade-backend --pcs <backend-host>

CLI はすぐに exec_id を返します。実際のインストールは対象ホスト上で非同期に走ります。

7. 確認

backend の results エンドポイントを叩く (もしくは SPA の Activity ビューを見る):

curl -H "Authorization: Bearer <token>" `
  "http://<backend>/api/results?limit=5"

自分の exec_id が exit_code: 0 で、stdout が kanade-backend <new-version> で終わっていれば成功です。

ありがちなトラブル