Phase1 サーバー構築手順

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 を編集します。

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 スクリプトで確認:

.\scripts\test-feedback.ps1

または 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/ に保存される。

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）