Phase1 ナレッジ

きっかけ

runbook では「PoC の Tunnel を再利用し、cloudflared の接続先を Raspberry Pi から Windows PC に移す」とある。 一方で、「Pi の cloudflared を止めなくても、別 Tunnel を新規に立てればよいのでは？」という疑問が生じた。

経緯

結論

変更するのは cloudflared が動くマシン だけ。 Tunnel 名・公開 URL・DNS は PoC 資産をそのまま使う。 自宅 PC は CGNAT（キャリア側の NAT により、自宅回線にインターネットから直接届くグローバル IP が無い状態）のため、 ルーターのポート開放だけでは外部公開できない。cloudflared が Cloudflare へ外向きに接続し、 そのトンネル経由でリクエストを受け取る構成が必須。

flowchart LR
  subgraph before["移行前"]
    APP1[クライアント] --> CF1[Cloudflare]
    CF1 --> PI[cloudflared @ Pi] --> API1[PoC API]
  end
  subgraph after["移行後"]
    APP2[クライアント] --> CF2[Cloudflare]
    CF2 --> PC[cloudflared @ Windows] --> API2[FastAPI + DB]
  end
  before -.->|"Tunnel・URLは同じ"| after
          

きっかけ

リポジトリ内に server/ があり、runbook では server/.env に TUNNEL_TOKEN を書くとある。 「server という名前のディレクトリは単にバックエンドをまとめただけ？」 「.env はなぜ Git に載せず、.env.example だけ載せるの？」という整理の質問。

経緯

結論

flowchart TB
  EX[.env.example Git管理] -->|copy| ENV[.env ローカルのみ]
  ENV --> COMPOSE[docker-compose.yml]
  COMPOSE --> DB[(db)]
  COMPOSE --> API[api]
  COMPOSE --> CF[cloudflared]
          

• server/ = バックエンド実行一式（API・DB・Tunnel）。物理サーバーそのものではない
• .env = Compose 起動時に読み込む秘密情報・接続設定
• .env.example = 必須キーの説明付きテンプレ。clone 後の最初の一歩

きっかけ

Pi 側 cloudflared 停止後、PC で docker compose --profile tunnel up -d cloudflared を実行。 docker compose ps で cloudflared が Restarting (255) を繰り返す。 外部 URL は error code: 1033。localhost の API は正常。

経緯

cloudflared.exe service install eyJhIioi...（ここから末尾までがトークン）

結論

flowchart LR
  UUID["Tunnel ID UUID"] -->|誤| X["255 / 1033"]
  EYJ["Connector Token service install 以降"] -->|正| OK["cloudflared Up / MS-1"]
          

きっかけ

runbook では移行前に Pi で docker compose stop cloudflared とある。 「止めずに PC でも繋いだらダメなのか？」

経緯

結論

flowchart TB
  REQ[api.dammy-otoko.com] --> CF[Cloudflare]
  CF --> PI[Pi cloudflared]
  CF --> PC[PC cloudflared]
  PI --> OLD[PoC API]
  PC --> NEW[新 FastAPI]
          

手順の順序: Pi 停止 → PC 起動。PoC の api サービス停止は任意（Tunnel には無関係）。

きっかけ

PC 側 cloudflared が token エラーで落ちている間、Cloudflare ダッシュボードに 「Install cloudflared connector」および Windows 向け cloudflared.exe service install が表示された。 「これを実行しないと Tunnel が有効化されないのでは？」という不安。

経緯

結論

ダッシュボードの .exe 手順 = コネクタ未接続時のガイド。 本プロジェクトでは docker compose --profile tunnel up -d cloudflared が .exe インストールに相当する。

きっかけ

Windows PC で docker compose up を実行したところ、 最初は docker コマンド自体が見つからない。 インストール後は docker version で Client（クライアント）の情報だけ表示され、 Server（サーバー＝コンテナを実際に動かす Docker Desktop 本体）の行がなく、 open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified というエラー。 Raspberry Pi 用の sudo docker を Windows で試すも、Windows 標準では sudo は使えない。

経緯

結論

docker コマンドは「リモコン（Client）」、Docker Desktop 本体は「エンジン（Server）」。 リモコンだけあっても、エンジンが止まっていればコンテナは動かない。 Windows では Linux と違い sudo は不要。

flowchart LR
  PS[PowerShell の docker コマンド]
  CLI[Docker Client]
  ENG[Docker Engine Docker Desktop本体]
  PS --> CLI
  CLI -->|"名前付きパイプで接続"| ENG
  ENG --> CNT[db api cloudflared コンテナ]
  CLI -.->|"Engine 未起動"| ERR[pipe not found エラー]
          

きっかけ

MS-1 確認用に4つのコマンドを実行したが、「何をしているか分からない」状態だった。 runbook の手順を理解するための整理。

経緯

2026-06-07、次の順で実行し MS-1 を達成した。

1. docker compose up -d --build db api — DB・API 起動（Tunnel なし）
2. curl.exe http://localhost:8000/api/v1/health — ローカル疎通
3. docker compose --profile tunnel up -d cloudflared — Tunnel 接続
4. test-feedback.ps1 -BaseUrl "https://api.dammy-otoko.com" — 外部経路で FB 送信

結論

sequenceDiagram
  participant U as 操作者
  participant DC as docker compose
  participant DB as db
  participant API as api
  participant CF as cloudflared
  U->>DC: up -d --build db api
  DC->>DB: Healthy 待ち
  DC->>API: 起動 port 8000
  U->>DC: --profile tunnel up cloudflared
  DC->>CF: TUNNEL_TOKEN で接続
          

きっかけ

Pi に SSH 接続し docker compose ps を実行。 permission denied while trying to connect to the docker API at unix:///var/run/docker.sock。 sudo 付きで再実行すると cloudflared が Up 5 weeks と確認できた。 停止後、PoC API（コンテナ名 poc-api）も止めたいが docker compose stop poc-api → no such service。

経緯

結論

flowchart TB
  PS[docker compose ps]
  PS --> NAME[NAME = コンテナ名]
  PS --> SVC[SERVICE = stop で指定する名前]
          

きっかけ

docker compose up 成功直後、 curl http://localhost:8000/api/v1/health が 「接続が予期せずに閉じられました」。 コンテナは Started なのに疎通失敗 — API が壊れたのかと誤解しやすい。

経緯

結論

Windows の runbook 疎通確認は curl.exe を明示する。runbook v1.3 で反映済み。

きっかけ

FB 受信で画像は data/storage/ に保存される。 それならファイルだけで足りないか — DB の役割の質問。

経緯

結論

flowchart LR
  POST[POST /feedback] --> IMG[画像 storage/]
  POST --> DB[(feedbacks)]
          

きっかけ

test-feedback.ps1 に -BaseUrl がある。 引数なしと https://api.dammy-otoko.com 指定の違いが MS-1 確認で重要。

経緯

結論

flowchart TB
  subgraph A["経路A localhost"]
    L1[PC] --> L2[api:8000]
  end
  subgraph B["経路B 公開URL MS-1"]
    T1[PC] --> T2[Cloudflare] --> T3[cloudflared] --> T4[api]
  end
          

経緯（時系列まとめ）

flowchart TD
  A[Docker Desktop 起動] --> B[db + api 起動]
  B --> C[localhost 疎通 OK]
  C --> D[Pi cloudflared 停止 sudo]
  D --> E[PC cloudflared 起動]
  E --> F{TUNNEL_TOKEN 正しい?}
  F -->|Tunnel ID を誤設定| G[255 / 1033]
  G --> H[service install 以降のトークンに修正]
  F -->|Connector Token 正| I[cloudflared Up]
  H --> I
  I --> J[公開 URL health OK]
  J --> K[test-feedback.ps1 MS-1]
          

最大のハマりどころは TUNNEL_TOKEN に Tunnel ID（UUID）を入れてしまったこと。 正しくは Cloudflare 画面の cloudflared.exe service install の後に続く長い文字列。 それ以外（Docker Desktop 未起動、Pi で sudo が必要、PowerShell の curl 別名）は、 個別に切り分け可能な問題だった。

きっかけ

MS-1 達成後、README・開発ログ・Phase1 ナレッジなどの変更を GitHub へ反映しようとした。 git add . のあと、 git push -m "Cloudflaredをraspberry pi →Windowsへ置き換え" を実行したところ、 error: unknown switch 'm' となった。 「add の次は push ではなかったか？」という疑問。

経緯

結論

flowchart LR
  W[作業ディレクトリの変更] --> A["git add"]
  A --> S[ステージ領域]
  S --> C["git commit -m メッセージ"]
  C --> L[ローカル履歴]
  L --> P[git push]
  P --> R[GitHub origin]
          

実行例:

git status
git add .
git commit -m "CloudflaredをRaspberry PiからWindows PCへ移行し、MS-1達成のドキュメントを更新"
git push

コミットに含めない方がよいもの: server/.env（秘密情報）は .gitignore 済み。 scripts/inference.json は test-feedback.ps1 実行時に毎回生成される一時ファイルのため、 必要なければ add しない（または今後 .gitignore に追加する）。

きっかけ

WBS 1.1（サーバー環境構築）と MS-1（Tunnel 経由 FB 受信）が完了した。 次に何をするか — WBS・検証計画では 1.2 スタブ Android アプリ が続く。

経緯

結論 — WBS 1.2 の内訳

flowchart LR
  S1["1.2.1 Flutter プロジェクト app/"]
  S2["1.2.2 画像選択・ダミー推論・FB 送信"]
  S3["1.2.3 端末から Tunnel 経由 FB 検証"]
  S1 --> S2 --> S3
          

前提（サーバー側）: Windows PC で Docker Desktop 起動 → db・api・cloudflared が稼働していること。

参照: WBS・ガントチャート、機能・関数定義一覧（F-01〜F-03）、データフロー