構築・運用手順書（Runbook）

§1 サーバー構築

WBS 1.1（サーバー環境構築）の runbook です。 Cloudflare Tunnel 経由で FastAPI へ FB を受信できる状態を目指します。

1. 前提

• Windows 11 + Docker Desktop がインストール済み・起動していること
• PoC で構築済みの Cloudflare リソースが有効であること（下表）
• PoC 記録または Zero Trust ダッシュボードから TUNNEL_TOKEN を取得できること

1.1 再利用する PoC 資産（確立済み）

1.2 実施順序（変更後）

2. Docker Desktop の準備

スリープ復帰後や初回セットアップ時は、タスクバーで Docker Desktop が起動していることを確認します。

docker version
        docker compose version

コマンドが通れば次のステップへ進みます。

3. 環境変数の準備（WBS 1.1.2）

cd server
        copy env.example .env

.env を編集します。テンプレートは server/env.example（SEC 変数含む）。

4. API + DB の起動（WBS 1.1.2）

cd server
        docker compose up -d --build db api

起動確認（PowerShell では curl.exe 推奨）:

curl.exe http://localhost:8000/api/v1/health

期待レスポンス: {"status":"ok"}

5. FB 受信 API 疎通（WBS 1.1.3・ローカル）

PowerShell スクリプトで確認（server/.env の FEEDBACK_API_KEY を自動読み込み。リポジトリ直下から実行）:

cd C:\Dev\github-actions-test
        .\scripts\test-feedback.ps1 -BaseUrl "https://api.dammy-otoko.com"

API キーをランダム生成して server/.env に書き込む（運用向け）:

.\scripts\rotate-server-secrets.ps1 -ApiKey -RestartApi

-RestartApi は docker compose up -d --force-recreate api まで実行。DB パスワードは既存 volume がある場合は -DbPassword を慎重に。

または curl 直接:

curl -X POST http://localhost:8000/api/v1/feedback ^
          -F "image=@scripts\sample.jpg" ^
          -F "inference_result={\"label\":\"A\",\"score\":0.92}"

成功時: HTTP 201 と id が返る。画像は data/storage/ に保存される。

SEC-01 有効時（FEEDBACK_API_KEY 設定済み）の成功例: 末尾に HTTP_CODE:201。失敗時の切り分けは §8・K-30。

5.1 SEC-01 deny 確認（意図的に誤ったキー・認証なし）

正しいキーで 201 が出たら、わざと間違った値を流して 401 で弾かれることも確認する。 health は引き続き ok のまま（インフラは生き、POST だけ認証で拒否）。

実測記録: K-30 deny 確認（2026-06-14）。

リポジトリ全体のディレクトリと .env の対応: docs/index — 構成とシークレット。

6. Cloudflare Tunnel 移行（WBS 1.1.1）

6.1 移行前の確認（任意）

Pi 側がまだ応答していることを確認できます（移行前は PoC の /ping が返る）。

curl https://api.dammy-otoko.com/ping

期待（移行前）: {"message":"pong"}（PoC FastAPI）

6.2 Raspberry Pi 側 cloudflared の停止

同一 Tunnel に複数コネクタがあると、リクエストが Pi と本 PC に振り分けられ、意図しない応答になる可能性があります。移行前に Pi 側を停止します。

# Raspberry Pi 上で実行（SSH）。docker 権限がない場合は sudo を付ける
        cd ~/poc-api   # PoC の compose ディレクトリ
        sudo docker compose stop cloudflared

停止対象は compose のサービス名 cloudflared（コンテナ名 poc-api 等とは異なる場合あり）。

6.3 本 PC で cloudflared 起動

server/.env に TUNNEL_TOKEN（eyJ... 形式）を設定済みであることを確認し:

cd server
        docker compose --profile tunnel up -d cloudflared

cloudflared の起動コマンドは --token のみです。--url との併用は禁止（PoC でタイムアウトの原因になった設定）。 Cloudflare ダッシュボードの「Windows 向け cloudflared.exe インストール」手順は不要（本プロジェクトは Docker コンテナで運用。ダッシュボードの Docker タブまたはトークンコピーで可）。

6.4 Tunnel 経由の疎通確認

curl.exe https://api.dammy-otoko.com/api/v1/health
        .\scripts\test-feedback.ps1 -BaseUrl "https://api.dammy-otoko.com"

期待（移行後）:

• /api/v1/health → {"status":"ok"}
• POST /api/v1/feedback → HTTP 201

7. 完了チェック（MS-1）

2026-06-07 達成済み。

• GET /api/v1/health がローカルで成功する
• POST /api/v1/feedback で画像・JSON が保存される
• https://api.dammy-otoko.com 経由でも同じ API が応答する
• DB（feedbacks テーブル）にレコードが記録される

8. トラブルシュート

9. 参照資料（PoC）

§2 AI Worker スタブ

WBS 1.3（AI Worker スタブ）の runbook です。 実際の学習は行わず、ベースモデルをコピーして新版本を生成し、 完了後に GitHub repository_dispatch で Actions を起動します。

1. 前提

• Windows 11 + Python 3.10 以上
• リポジトリをクローン済み（models/base/stub.tflite が存在すること）
• 1.3.3 の検証には GitHub PAT とリポジトリ名の設定（後述）
• .github/workflows/android-build.yml がリモートに push 済み（dispatch 先ワークフロー）

2. ディレクトリ構成

models/
        ├── base/stub.tflite      # ベースモデル（スタブ）
        ├── manifest.json         # バージョン管理
        └── versions/             # 生成物（gitignore、ローカルのみ）
        
        worker/
        ├── __main__.py           # CLI エントリ
        ├── training_stub.py      # F-20 run_training_stub()
        ├── github_dispatch.py    # F-21 trigger_github_dispatch()
        └── .env.example
        
        scripts/run-training-stub.ps1

3. 環境変数（WBS 1.3.3）

worker/.env.example を worker/.env にコピーし、値を設定します。worker/.env は .gitignore 対象 — commit しない。

3.1 PAT（Personal Access Token）の発行

1. GitHub 右上の自分のアイコン → Settings（リポジトリではなくユーザー）
2. 左下 Developer settings → Personal access tokens → Tokens (classic)
3. Generate new token (classic)
4. Note: 例 github-actions-test-worker / Expiration: 任意（期限切れ前にローテーション — K-23）
5. Scopes: repo（Classic）。Fine-grained の場合は対象 repo へ Contents + Actions
6. 生成された ghp_... を worker/.env の GITHUB_TOKEN に貼り付け

3.2 worker/.env の内容

トークン未設定の場合、学習スタブのみ実行し dispatch はスキップします（ローカル検証用）。

2026-06-10 確認: PAT 設定後 run-training-stub.ps1 → dispatch 204 → Build #2 → artifact v2 → Pixel 7a install まで通し確認（1.5.2）。

4. 学習スタブのみ（WBS 1.3.1 / 1.3.2）

.\scripts\run-training-stub.ps1 -SkipDispatch

期待結果:

• models/versions/v{N}/horse_model.tflite が作成される
• models/manifest.json の latest_version が更新される
• コンソールに version: v{N} が表示される

5. 学習完了 → GitHub Actions 起動（WBS 1.3.3）

1. worker/.env に GITHUB_TOKEN / GITHUB_REPOSITORY を設定
2. ワークフローを main に push（初回のみ）
3. 以下を実行:

.\scripts\run-training-stub.ps1

期待結果:

• コンソール: status: 204（repository_dispatch 成功）
• GitHub → Actions → Android Build が model-updated で起動
• ジョブログに model_version / model_path が出力される

6. 手動で Actions を試す（任意）

GitHub リポジトリの Actions タブから Android Build → Run workflow でも起動できます（workflow_dispatch）。

7. 完了チェック（WBS 1.3）

• run_training_stub() で versions/v1/ が生成される
• 再実行で v2 にインクリメントされる
• trigger_github_dispatch() で HTTP 204 が返る
• Actions の android-build.yml が dispatch で実行される

8. 次のステップ

APK ビルド・端末インストールは Phase1 GHA・APK 手順 を参照してください。

9. トラブルシュート

§3 GHA・APK 配布

WBS 1.4（GHA Android ビルド）と 1.5.1（APK インストール）の runbook です。 android-build.yml が Flutter APK をビルドし、artifact として配布します。

1. 前提

• リポジトリの default ブランチに .github/workflows/android-build.yml が存在すること
• GitHub → Settings → Actions が有効
• 端末配布時: PC に Android SDK platform-tools（adb）と USB デバッグ有効な端末

2. 概念整理（初めて読む場合）

手順の前に全体像を押さえる場合は Phase1 ナレッジ K-20（GHA・artifact・APK）と K-21（月次パイプライン）を参照。 YAML の基礎は K-19。

3. 手動ビルド（WBS 1.4.1）

画面操作の詳細は GHA 操作手順（UI）§A を参照。

1. GitHub リポジトリ → Actions → Android Build
2. Run workflow → ブランチ選択 →（任意）model_version を入力 → Run
3. 完了後、実行結果 → Artifacts → app-release-apk-<version> をダウンロード

ZIP 内の app-release.apk が成果物です（設計上の app-release.apk）。

4. モデル同梱の仕組み（WBS 1.4.2）

ビルド前にワークフローが以下を実行します。

1. repository_dispatch の model_version / model_path を取得（手動時は入力または manifest.json）
2. models/<path> がリポジトリにあればそれを、なければ models/base/stub.tflite をコピー
3. app/assets/models/ に配置して flutter build apk --release

4b. SEC-01 — APK に FEEDBACK_API_KEY を同梱（WBS 3.1.4 クライアント側）

サーバーで SEC-01 が有効なとき、アプリも Authorization: Bearer を送る必要がある。 Flutter はビルド時 --dart-define=FEEDBACK_API_KEY=... でキーを埋め込む（app/lib/config.dart）。

# GitHub CLI（任意）
        gh secret set FEEDBACK_API_KEY --repo OWNER/REPO
        
        # ローカル APK（リポジトリ直下）
        .\scripts\build-flutter-apk.ps1
        .\scripts\install-apk.ps1 -ApkPath "app\build\app\outputs\flutter-apk\app-release.apk"

4b-1. GitHub Actions Secret 登録（画面手順・2026-06-14 証跡）

PAT（Developer settings）ではない。 リポジトリの Settings から登録する。 直接 URL: https://github.com/<owner>/<repo>/settings/secrets/actions

1. リポジトリを開く → 上部タブ Settings
2. 左サイドバー Security and quality → Secrets and variables → Actions
3. Repository secrets の New repository secret
4. Name: FEEDBACK_API_KEY（完全一致）
5. Secret: server/.env の = の右側だけ（下記注意）
6. Add secret → 一覧に FEEDBACK_API_KEY が表示される

4b-2. Secret 登録後の GHA ビルド（2-B）

1. Actions → 左 Android Build
2. Run workflow → Branch: main →（任意）model_version ラベル → Run workflow
3. 成功 run を開く → ジョブ Build release APK ログに FEEDBACK_API_KEY is set (length …) があること
4. run ページ下部 Artifacts → ZIP ダウンロード → 解凍 → app-release.apk
5. install-apk.ps1 → 実機 FB（§4c）

ダウンロードするのはモデルファイル単体ではなく APK（artifact）。 TFLite モデルはビルド時に APK 内へ同梱済み。

Secret 未設定で GHA ビルドすると workflow に warning が出る（無認証 APK）。 キー変更時は server/.env 更新 → GitHub Secret 更新 → APK 再ビルド・再配布（セキュリティ設計 のローテーション方針）。

4c. 実機 FB 201 確認（SEC-01 クライアント検証）

2026-06-14: 経路 2-A（ローカル APK）で Pixel 7a 実機 FB 201 確認済み。

2026-06-15: 経路 2-B（GHA artifact + Actions Secret）で Pixel 7a 実機 FB 201 確認済み。

「実機 FB 201」とは、Pixel 等の実機アプリから Tunnel 経由で FB を送り、 アプリ画面に 送信成功 (HTTP 201) と表示されることを確認することです。 （PC の test-feedback.ps1 で 201 が出ても、APK に鍵が入っていなければ実機は 401 になります。）

失敗時: 401 → Secret 値の誤り（FEEDBACK_API_KEY=... 行全体を貼ると length がずれる。例: 68 vs 正 43）→ Secret を = 右のみに修正 → GHA 再ビルド → 再 install。 鍵未同梱はビルドログの length 未表示・warning で判別（K-30）。 図解: K-31 全体構成図（セキュリティ拡張版）。

5. Worker 連携ビルド（WBS 1.4.3）

画面確認は GHA 操作手順（UI）§B。PAT 設定は Worker 手順 §3（K-22）。

.\scripts\run-training-stub.ps1

成功時: コンソール status: 204 → Actions に Android Build が自動起動（2026-06-10: Build #2 確認）。

6. Pixel 7a へインストール（WBS 1.5.1）

adb devices
        .\scripts\install-apk.ps1 -ApkPath "C:\path\to\app-release.apk"

複数端末がある場合:

.\scripts\install-apk.ps1 -ApkPath "C:\path\to\app-release.apk" -DeviceId 3C261JEHN19182

起動後、アプリ上部付近に 同梱モデル: vN (... bytes) が表示されれば同梱成功です。

7. 完了チェック（MS-2 向け）

2026-06-10: 手動ビルド経路（workflow_dispatch）で以下を達成。詳細: GHA 操作手順（UI）。

• workflow_dispatch で APK artifact が取得できる — 達成（app-release-apk-v1）
• APK を adb でインストールしアプリが起動する — 達成（Pixel 7a）
• 画面に同梱モデルバージョンが表示される — 達成（同梱モデル: v1）
• release APK から Tunnel 経由 FB 送信 — 達成（HTTP 201）
• Worker dispatch 後に GHA が自動起動し新 artifact ができる — 達成（Build #2 → app-release-apk-v2、WBS 1.4.3）

7b. 月次通しチェック（WBS 1.5.2）

2026-06-10〜11: 方法 B（Worker dispatch）通し E2E 完了（実機 v2・FB 確認済み）。

• run-training-stub.ps1 → v2 生成 + dispatch 204 — 達成
• Android Build #2（Repository dispatch）成功 — 達成
• app-release-apk-v2 artifact 取得 — 達成
• Pixel 7a へ adb install — 達成（uninstall 後に再 install）
• 起動後 同梱モデル: v2 (92 bytes) 表示 — 達成（2026-06-11）
• Tunnel 経由 FB 送信 — 達成（HTTP 201、ID: 45cbbe07-c287-4db9-845f-dce8904bff91）

運用（PAT ローテーション・artifact 30 日・ローカル APK 保管）: K-23。

8. トラブルシュート

§4 GHA 操作（UI）

本資料は、GitHub 上で Android Build ワークフローを起動し、 artifact から APK を取得するまでの画面操作を、スクショ付きで記録する runbook です。 概念整理は K-20、端末インストールは Phase1 GHA・APK 手順 を参照してください。

0. 初回セットアップ（1回だけ）

0.0 なぜ Actions にワークフローが表示されるか

GitHub はリポジトリの default ブランチ（main） 上の .github/workflows/*.yml を自動的に読み取り、Actions タブの左サイドバーに一覧表示します。 追加の「GitHub 側設定ボタン」は基本的に不要です（Actions が有効であることのみ）。

0.1 ワークフロー YAML をリモートに載せる

ローカルに .github/workflows/android-build.yml があることを確認し、 main ブランチへ push します。

git status
        git add .github/workflows/android-build.yml
        git commit -m "Add Android Build workflow"
        git push origin main

push 後、GitHub リポジトリの Code タブで .github/workflows/android-build.yml が見えることを確認します。 push だけではビルドは走りません（on: push が無いため）。

0.2 GitHub Actions が有効か確認

1. リポジトリ → Settings → 左メニュー Actions → General
2. Actions permissions が「Allow all actions…」または組織ポリシーで許可されていること
3. Fork や Organization リポジトリの場合、管理者承認が必要なことがあります

0.3 Worker dispatch を使う場合のみ — PAT 設定

手動ビルド（方法 A）だけ試す場合はスキップ可。方法 B には必要です。

1. GitHub 右上の自分のアイコン → Settings（リポジトリではなくユーザーの Settings）
2. 左下 Developer settings → Personal access tokens → Generate new token (classic)
3. Classic PAT なら repo スコープ。Fine-grained なら対象リポジトリへの Contents + Actions 書き込み
4. PC で worker/.env.example を worker/.env にコピーし設定（commit しない）:

GITHUB_TOKEN=ghp_xxxxxxxxxxxx
        GITHUB_REPOSITORY=makoto55879/github-actions-test

GITHUB_REPOSITORY は owner/repo 形式（URL の github.com/owner/repo と一致）。

A. 手動ビルド（workflow_dispatch）

A-1. Actions タブを開く

1. ブラウザでリポジトリを開く（例: github.com/makoto55879/github-actions-test）
2. 上部タブの Actions をクリック

A-2. Android Build ワークフローを選ぶ

1. 左サイドバーの Android Build をクリック
2. 中央に「This workflow has a workflow_dispatch event trigger」等の表示があることを確認
3. 右側（または上部）の Run workflow ボタンが表示される

A-3. Run workflow を実行

1. Run workflow をクリック → ドロップダウンが開く
2. Branch: main を選択（default ブランチ）
3. Model version label (optional): 任意（例: v1）。空欄なら manifest.json の latest を使用
4. Path under models/ (optional): 通常は空欄（リモートに無いパスは base スタブ + ラベルのみ）
5. 緑色の Run workflow をクリック

A-4. 実行状況を確認

1. 一覧に新しい実行が追加される（黄色 ● = 実行中、緑 ✓ = 成功、赤 ✗ = 失敗）
2. 実行行をクリック → ジョブ Flutter APK with bundled model → 各 step のログを確認
3. 初回ビルドは Flutter セットアップ含め 約 7 分 程度（実測: 7m 18s）

A-5. artifact から APK をダウンロード

1. 実行が緑のチェックで完了したら、同じページを下へスクロール
2. Artifacts セクションに app-release-apk-<version> が表示される
3. 名前をクリック → ZIP が PC にダウンロードされる
4. ZIP を解凍 → 中の app-release.apk がインストール対象

A-6. Pixel 7a へインストール

APK は PC 上のファイルのままでは Pixel には入りません。 USB 接続 + adb install（またはプロジェクトの install-apk.ps1）で入れます。 flutter run で入れたデバッグ版とは別ビルド（release APK）です。

準備 — 端末確認

接続デバイスを名前付きで見るなら flutter devices（WBS 1.2.3 と同じ）:

cd c:\Dev\github-actions-test\app
        flutter devices

例: Pixel 7a (mobile) • 3C261JEHN19182 • android-arm64 — インストール時の -DeviceId は 3C261JEHN19182（真ん中の ID）。

adb 形式だけ見る場合:

& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" devices

1. Pixel 7a を USB で PC に接続
2. 端末で USB デバッグ を有効（開発者向けオプション）
3. 「USB デバッグを許可しますか？」→ 許可（WBS 1.2.3 と同様）

方法 1 — スクリプト（推奨）

install-apk.ps1 は Android SDK の adb.exe を自動検出します（PATH 未設定でも可）。

cd c:\Dev\github-actions-test
        
        flutter devices   # 任意: Pixel 7a と DeviceId を確認
        
        .\scripts\install-apk.ps1 `
          -ApkPath "C:\Users\wt2bp\Downloads\app-release-apk-v1\app-release.apk" `
          -DeviceId 3C261JEHN19182

成功時の表示例: Success または Performing Streamed Install のあと終了コード 0。

方法 2 — adb を直接

& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" install -r "C:\Users\wt2bp\Downloads\app-release-apk-v1\app-release.apk"

-r は上書きインストール。デバッグ版（flutter run）が残っていると署名不一致になる場合:

& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" uninstall com.horsediagnosis.horse_stub

インストール後の確認

1. Pixel 7a のアプリ一覧から「馬体診断スタブ」（または horse_stub）を起動
2. 画面上部付近に 同梱モデル: v1 (... bytes) が表示されれば GHA ビルドの同梱成功
3. DEBUG リボンは release ビルドでは出ない（正常）

B. Worker dispatch（repository_dispatch）

B-1. 前提確認

• worker/.env に GITHUB_TOKEN / GITHUB_REPOSITORY が設定済み
• 方法 A と同様、android-build.yml が main に push 済み

B-2. PC で学習スタブ + dispatch を実行

cd c:\Dev\github-actions-test
        .\scripts\run-training-stub.ps1

期待されるコンソール出力（例 — 2026-06-10 実測）:

[1/2] run_training_stub()
          version: v2
          path:    models/versions/v2/horse_model.tflite
        [2/2] trigger_github_dispatch()
          repo:    makoto55879/github-actions-test
          event:   model-updated
          status:  204

• status: 204 → dispatch 成功（GitHub は body なしで 204 を返す）
• トークン未設定時は dispatch がスキップされ、学習スタブのみ実行される

学習だけ試す場合: .\scripts\run-training-stub.ps1 -SkipDispatch

B-3. GitHub Actions で自動起動を確認

1. GitHub → Actions → 左 Android Build
2. 一覧に新しい実行が追加されている（Event 列に Repository dispatch / model-updated）
3. 2026-06-10 実測: Android Build #2 が dispatch 由来で起動（#1 の Manually run とは別）
4. 手動（A）と同様、完了後に Artifacts から APK をダウンロード（v2 実行なら app-release-apk-v2）

B-4. artifact 取得 → 端末 install（2026-06-10 実測）

1. Build #2 成功後、Artifacts から app-release-apk-v2 をダウンロード → ZIP 解凍 → app-release.apk
2. Pixel 7a へ install（端末 ID は flutter devices で確認）:

.\scripts\install-apk.ps1 `
          -ApkPath "C:\path\to\app-release-apk-v2\app-release.apk" `
          -DeviceId 3C261JEHN19182

INSTALL_FAILED_UPDATE_INCOMPATIBLE が出た場合（方法 A の v1 でも発生）:

adb -s 3C261JEHN19182 uninstall com.horsediagnosis.horse_stub
        .\scripts\install-apk.ps1 -ApkPath "..." -DeviceId 3C261JEHN19182

起動後、画面上部の 同梱モデル: v2 (... bytes) を確認。Tunnel 経由 FB 送信も試す。

B-5. 3回目以降（月次イメージ）

1. 再度 .\scripts\run-training-stub.ps1 → v3 が生成される
2. dispatch → 新 artifact app-release-apk-v3
3. ダウンロード → install（署名不一致時は B-4 の uninstall 手順）

C. 方法 A と B の違い（まとめ）

D. スクショの追加・更新方法

未撮影の図は docs/assets/img/gha/ に PNG を置き、本 HTML の placeholder を <img> に差し替えます。

E. トラブルシュート

F. 運用上の注意（Phase1 Android）

詳細は K-23。要点のみ:

G. 関連資料

• K-20 — GHA・artifact・APK の概念
• K-21 — 月次パイプライン全体像
• K-22 — PAT と Actions Secrets の違い
• K-23 — PAT ローテーション・artifact 保持・APK 世代管理
• Phase1 GHA・APK 手順 — モデル同梱・adb・MS-2 チェックリスト
• Runbook §2 Worker — PAT・-SkipDispatch

§5 PC 間移設（検証 PC → 役場 PC）

WBS 3.1.1 本番移設のたたき手順です。コンテナを stop → 別 PC で up だけでは不十分です。 永続データと .env も移してください。

5.1 旧 PC（検証機）

cd server
docker compose --profile tunnel stop cloudflared
docker compose --profile tunnel down

down -v は使わない（DB volume が消えます）。

5.2 バックアップ例

# DB volume（名前は環境により server_pgdata 等）
docker run --rm -v server_pgdata:/data -v C:\backup:/backup alpine ^
  tar czf /backup/pgdata.tar.gz -C /data .

# 画像・.env も C:\backup 等へコピー

5.3 新 PC（役場 PC）

1. Docker Desktop インストール
2. リポジトリ取得・server/.env 配置
3. data/storage/ をコピー
4. volume 復元後 docker compose up -d --build db api
5. 旧 PC の Tunnel を止めたうえで docker compose --profile tunnel up -d cloudflared
6. .\scripts\test-feedback.ps1 で疎通確認

連携方針: 外部連携 §1 環境整理。