ナレッジベース（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）、データフロー

きっかけ

Pixel 7a で flutter run 後、「フィードバックを送信」が失敗。 USB ログ（adb logcat 等）で原因を追えるか確認したい。

経緯

結論

Flutter を切る必要はない。 Docker 操作は別ターミナルで行い、修正後は Hot restart（R）で再試行可。

きっかけ

Docker Desktop 復旧後、Pixel 7a から FB 送信。 ダミー推論（label / score）は画面に表示されるが、送信は HTTP 400: {"detail":"image must be an image file"} で失敗。

経緯

結論 — 修正と結果

image_picker の XFile.mimeType を保持し、multipart 送信時に Content-Type を付与。2026-06-08 に Pixel 7a で HTTP 201 を確認。

// main.dart: 画像選択時
_imageMimeType = picked.mimeType;

// feedback_client.dart: 送信時
await http.MultipartFile.fromPath(
  'image',
  imagePath,
  contentType: MediaType.parse(mimeType ?? 'image/jpeg'),
);

修正後: Hot restart → 画像再選択 → 送信成功（HTTP 201）→ data/storage/ にファイル追加、で WBS 1.2.3 完了。

きっかけ

WBS 1.2.3 の実機検証で flutter run を使ったが、Flutter のライフサイクル （Hot reload と restart の違い、いつ何をするか）を把握していない状態だった。 本プロジェクトでは AI エージェントがビルド・修正を代行することが多いため、 開発者が最低限押さえる操作をここにまとめる。

Flutter 開発の全体像（3 段階だけ覚える）

flowchart LR
  P1["① 準備\nDocker・USB デバッグ"]
  P2["② flutter run\nビルド・インストール・起動"]
  P3["③ アプリ操作\n画像選択 → FB 送信"]
  P1 --> P2 --> P3
          

flutter run は「ソースをビルド → スマホに APK を入れる → アプリを起動 → PC と接続してログを表示する」 コマンドを一括で実行する。終了するまで PC とスマホは開発セッションとしてつながったまま。

開発セッションの標準手順（本プロジェクト）

flutter run 中のキー操作（ライフサイクルの核心）

flutter run が動いているターミナルでは、キー 1 文字で操作できる。 コードを直したあと「反映されない」ときは、reload と restart の違いを疑う。

初回セットアップで一度だけやること

本プロジェクト固有の設定

よくあるつまずき（Flutter 編）

関連ナレッジ

• K-15 — WBS 1.2 の位置づけとスタブの目的
• K-16 — USB デバッグ・ログの見方・1033 の切り分け
• K-17 — 実機 FB 送信の HTTP 400 対応（解決済み）

きっかけ

WBS 1.4 で android-build.yml を扱うにあたり、Docker の docker-compose.yml と GitHub Actions の YAML の関係が分かりにくい。「CI/CD でよく使う形式なのか」「どこでも同じ書き方なのか」という疑問。

結論 — YAML とは

YAML（.yml / .yaml）は、設定やデータを人間が読みやすいテキストで書くためのファイル形式（書き方のルール）である。 プログラミング言語ではなく、設定ファイルの書き方に近い。

• 字下げ（スペース）で階層を表す
• キー: 値 が基本
• - でリスト、# でコメント

共通する部分 / 違う部分

比喩: YAML は「用紙のフォーマット」、各 YAML ファイルは「ツール専用の申請書テンプレート」。 CI/CD で YAML がよく使われるのは、ビルド手順をリポジトリに置き、人間が読んで修正しやすいから。

きっかけ

WBS 1.4 の検証手順で「YAML をリモートに載せる」「Actions で手動ビルド」「artifact から APK をダウンロード」が出てくる。 それぞれが実体として何を意味するかを整理したい。

android-build.yml の役割

GitHub Actions 向けの作業指示書。次の3つを1ファイルに宣言する。

「リモートに載せる」とは

git push で .github/workflows/android-build.yml を GitHub 上に置くこと。 GitHub がこのファイルをワークフロー定義として読み込む。

追加の GitHub 設定: default ブランチに YAML があること、Settings → Actions が有効であること（多くは初期状態で ON）。

Actions で手動ビルド

GitHub 上の仮想マシン（ubuntu-latest）で flutter build apk --release 等を実行する。 ビルドはローカル PC ではなく GitHub クラウドで行われる。

artifact と APK

端末へ反映する流れ:

1. Actions 実行結果 → Artifacts → ZIP を PC にダウンロード
2. ZIP を解凍 → app-release.apk を取り出す
3. adb install または install-apk.ps1 で Pixel 7a へインストール

APK は GitHub 上に置かれたまま端末には届かない。PC 経由の手動インストールが Phase1 Android の想定（WBS 1.5.1）。

flowchart LR
  YML["android-build.yml を push"]
  GH["GitHub Actions クラウド"]
  ART["artifact ZIP"]
  PC["PC にダウンロード"]
  DEV["Pixel 7a adb install"]
  YML -->|"Run workflow または dispatch"| GH
  GH --> ART
  ART --> PC
  PC --> DEV
          

参照: Phase1 GHA・APK 手順

きっかけ

基本設計では月次1回のモデル更新を想定。 「人間が学習 → API で GitHub にビルド依頼 → 配布（TestFlight？）」という全体像を、このプロジェクトの実装に即して整理したい。

月次運用の流れ（Phase1）

flowchart TB
  H["人間: 月1回 学習を実施"]
  PS["run-training-stub.ps1"]
  TR["学習スタブ: models/versions/vN/"]
  API["GitHub API repository_dispatch"]
  GHA["android-build.yml 起動"]
  APK["artifact: app-release.apk"]
  ADB["adb install → Pixel 7a"]
  H --> PS
  PS --> TR
  PS --> API
  API --> GHA
  GHA --> APK
  APK --> ADB
          

自動 / 手動の境界

repository_dispatch について

「学習後に別途 PowerShell で API を叩く」のではなく、 run-training-stub.ps1 が学習スタブと dispatch を連続実行する。 Worker は POST /repos/{owner}/{repo}/dispatches を送信（worker/github_dispatch.py）。 要 worker/.env の GITHUB_TOKEN（PAT）と GITHUB_REPOSITORY。

配布 — Android と iPhone の違い

参照: データフロー（通信方向 ②③）、 Phase1 Worker 手順、 Phase1 GHA・APK 手順

きっかけ

WBS 1.4.3 の Worker dispatch 準備で、リポジトリの Settings → Secrets and variables → Actions を開いたが、 PAT 発行画面ではなかった。

結論 — 2 種類の「トークン置き場」

PAT 発行手順（Classic）

1. GitHub 右上アイコン → Settings（ユーザー）
2. Developer settings → Personal access tokens → Generate new token (classic)
3. Scope: repo
4. ghp_... を worker/.env に記載（gitignore、commit 禁止）

run-training-stub.ps1 は POST /repos/{owner}/{repo}/dispatches を送る（worker/github_dispatch.py）。 成功時は HTTP 204（body なし）。

参照: Phase1 Worker 手順 §3、 GHA 操作手順 §B

きっかけ

方法 A/B の E2E が進み、月次運用を想定したときの「期限切れ」「成果物の消滅」「端末に残るバージョン」の整理が必要になった。

1. PAT — 生成・期限・ローテーション

2. artifact — GitHub 上の保持期限

android-build.yml の upload-artifact は retention-days: 30。 30 日経過後、GitHub 上の artifact は削除される（リポジトリ commit とは無関係）。

flowchart LR
  GHA["GitHub Actions ビルド"]
  ART["artifact（最大30日）"]
  PC["PC に ZIP/APK 保存"]
  DEV["Pixel adb install"]
  GHA --> ART
  ART -->|"期限内にダウンロード"| PC
  PC --> DEV
          

3. ローカル APK 世代管理（推奨）

• ダウンロードした APK にバージョンラベルを付けて PC に保管（例: app-release-v1.apk、v2）
• 直近 2〜3 世代を保持 — ロールバック・比較用
• 大容量ファイルは gitignore 推奨（リポジトリには載せない）
• v1 → v2 など世代更新時、adb install -r が INSTALL_FAILED_UPDATE_INCOMPATIBLE になる場合は先に adb uninstall com.horsediagnosis.horse_stub（K-13）

4. 配布経路の整理

参照: GHA 操作手順 §F、 K-21（月次パイプライン）

きっかけ

本番セキュリティの話（API 認証・FW・DB 非公開）を理解するには、 「ネットワーク境界」「FW（ファイアウォール）」「ポート」などの前提が必要だった。 Raspberry Pi 構築時に FW 設定をしたが、OSI 参照モデルとの対応は整理されていなかった。

OSI 参照モデル — 7 層を「郵便」でイメージする

全部暗記する必要はない。層 3〜4（IP・ポート）と層 7（HTTP/API）が本プロジェクトでは重要。

ネットワーク境界 — 「誰がどこから届くか」の線

flowchart TB
  subgraph zone_internet["ゾーン: インターネット（全世界）"]
    Client[スマホ・curl]
  end
  subgraph zone_cf["ゾーン: Cloudflare"]
    Edge[エッジ HTTPS :443]
  end
  subgraph zone_pc["ゾーン: 役場 PC"]
    Tunnel[cloudflared]
    API[FastAPI :8000]
    DB[(PostgreSQL :5432 内部のみ)]
  end
  subgraph zone_lan["ゾーン: 同一 LAN（社内 Wi-Fi 等）"]
    LANPC[別の PC・スマホ]
  end
  Client --> Edge --> Tunnel --> API --> DB
  LANPC -.->|"裏口になりうる"| API
          

境界 = ゾーンの境目。セキュリティは「各境界に門番を置く」イメージ。 DB は PC の内側（Docker ネットワーク）だけにいるのが内側の境界。

ゾーン（Zone）とは

「信頼度や到達範囲が違うエリア」に名前を付けたもの。厳密な IT 用語というより、 図を読みやすくするためのラベル。 「ここにいる人／機器は、あそことはルールが違う」と区切る箱。

ゾーンをまたぐたびに「門番はいるか？」と聞くのがセキュリティ思考の基本（K-29）。 商用 FW 製品では「DMZ」「内部網」など正式なゾーン名を使うが、考え方は同じ。

FW（ファイアウォール）とは

層 3〜4 で動く門番。「この IP からの、このポート番号への入り口は開ける/閉じる」を決める。 ソフトウェアが多い（Windows Defender ファイアウォール、Linux の iptables/nftables）。 ルーターやクラウドにも FW 機能が入っている（ハードとソフトの境目は曖昧で、役割は同じ）。 Raspberry Pi で設定したのも同種。

FW だけがやること（本質）:

• 通す / 通さない を、主に 方向 × IP × ポート で決める
• 例: 「外向き（PC → 外）は OK」「内向き（LAN → PC の 8000）は NG」

FW だけではやらないこと:

• HTTP の内容を読んで「正規アプリか」判断する（それは層 7・API 認証）
• パスワードの中身を検証する（それはアプリや DB）
• ファイルサイズの制限（それも層 7）

つまり FW は「内〜ポート〜外」の出入り口の開閉が主役で合っている。 ただし「通信の中身までは見ない門番」なので、開けた穴の先には別の門番も要る（多層防御）。

本プロジェクトの現状と目標

結論

セキュリティは一箇所の鍵だけでは足りない（多層防御）。 FW は「裏口（ポート）を閉じる」、API 認証は「正規の利用者だけ通す」、HTTPS は「途中で読まれにくくする」—— 層が違うので全部そろえて初めて意味が通る。

きっかけ

「Cloudflare Tunnel 経由の HTTPS は安全か？」「SSL っぽい設定も見たがどういうことか？」 — セキュリティ設計を読む前に、通信の保護範囲を押さえる必要があった。

HTTPS が守るもの

転送中（路上）の盗み見・改ざんを困難にする。カフェ Wi‑Fi など不信頼な回線でも有効。

• ブラウザやアプリの鍵マーク = 「この区間は暗号化されている」
• 層 6（TLS）の仕事。Cloudflare が証明書を管理するので自前で Let's Encrypt 等は不要

通信の流れ（本プロジェクト）

sequenceDiagram
  participant App as スマホアプリ
  participant CF as Cloudflare エッジ
  participant Tun as cloudflared
  participant API as FastAPI

  App->>CF: HTTPS 暗号化（インターネット上）
  Note over App,CF: ここが「HTTPS が守る区間」
  CF->>Tun: Tunnel（専用の道）
  Tun->>API: 多くは HTTP（PC 内 localhost）
  Note over Tun,API: PC の中。外からは見えない
          

Cloudflare Tunnel の追加メリット

HTTPS が守らないもの

• https://api.dammy-otoko.com/api/v1/feedback の URL を知った人は、curl でも同じ HTTPS で POST できる
• 暗号化されているので路上では内容が読まれにくいが、サーバーはリクエストを受け付けてしまう
• だから 層 7 の API 認証（K-26）が別途必要

結論

Tunnel + HTTPS は通信路として妥当で、本プロジェクトでも採用継続。 残るリスクは「誰が API を叩けるか」「どれだけ送れるか」で、これはアプリ層の設計課題。

きっかけ

「危ない URL とは何か？」「PC の IP が漏れないなら大丈夫では？」「API キーを付けたら傍受で危しくないか？」 「アプリで動画禁止にすれば十分では？」— 本番前に整理したい論点が多かった。

公開 URL とは何か

https://api.dammy-otoko.com/api/v1/feedback はサーバー PC が勝手に作った URL ではない。 DNS → Cloudflare → Tunnel → PC 内 API という意図して作ったインターネット入口。

flowchart LR
  subgraph ok["正規の使い方"]
    App[本番アプリ] -->|HTTPS| URL[api.dammy-otoko.com]
  end
  subgraph ng["同じ入口を使う別ルート"]
    Curl[curl・いたずら] -->|HTTPS| URL
  end
  URL --> CF[Cloudflare] --> API[FastAPI]
          

• 端末は Cloudflare エッジに届ける — その理解で正しい
• 危険なのは「PC IP がバレる」ことより、公開入口に門番（認証）がないこと
• 検証環境では意図的に無認証。本番では SEC-01 で API キーを導入予定

API 認証 — 何をするか

「このリクエストを送っていいのは誰か」をサーバー（層 7）で確認する。

# 本番案
POST /api/v1/feedback
Authorization: Bearer <秘密の API キー>

アップロード制限 — アプリだけでは足りない理由

現状の API は image/* のチェックのみでサイズ上限なし（feedback.py）。本番では SEC-02 で上限を設ける。

結論

公開 URL は Cloudflare 経由の正面入口。HTTPS はその路上を守る。 入口の利用者確認（API キー）と量の制限（サイズ上限）は別レイヤーで足す。

きっかけ

「シークレット管理とは何の話か」「DB もユーザー/パスワードで守るのに、.env は認証なし？」 「秘密を DB に入れた方がよい？」「ローテーションは本当に必要？」— 用語の整理が必要だった。

「シークレット」とは

漏れたらなりすまし・不正操作につながる、パスワードのような文字列の総称。

.env と DB — なぜ秘密を DB に入れないのか

flowchart TD
  subgraph boot["API 起動時"]
    ENV["server/.env\n(DBパスワード等)"]
    API[FastAPI 起動]
    DB[(PostgreSQL)]
    ENV -->|"読み込み"| API
    API -->|"DBユーザー/パスワードで接続"| DB
  end
  subgraph ng["避けたいパターン"]
    DB2[(PostgreSQL)]
    SEC[secrets テーブルに APIキー等]
    API2[API 起動]
    API2 -->|"接続にパスワードが要る"| DB2
    DB2 --> SEC
  end
          

• API が DB に繋ぐ時点で、すでに DB パスワードがどこかにある（鶏と卵）
• 秘密を DB テーブルに入れると、DB 侵害 = 全部の秘密が一度に漏れる
• 小規模の定石: .env（gitignore）+ PC へのアクセス制限。大規模は Vault / Secret Manager

.env は「認証なしで誰でも読める」ではなく、その PC にログインできる人だけが読めるファイルとして守る。

ローテーション（取り替え）が必要な理由

「必須の儀式」ではなく漏洩したときのダメージを減らす保険。

運用: PAT は四半期（K-23）、漏洩時は即 revoke / 再発行。

結論

運用: scripts/rotate-server-secrets.ps1 -ApiKey -RestartApi でランダム生成して server/.env に書き込み（値は画面に出さない）。

どのディレクトリに何を書くかの一覧: docs/index — 構成とシークレット・README。

きっかけ

Cloudflare Access が Pages のメール認証と同じか？ログに個人情報が残るか？ — 設計だけでは実感しづらいので、体験で確認する方針（WBS 3.1.5）も決めた。

Cloudflare Access と Pages のメール認証

概念は同じ（コンテンツの前に「誰か」を確認）。向かう先が違う。

ログと個人情報（PII）

基本設計の「FB に個人情報を含めない」は方針。実態は実装次第なので実測で確認する。

本番設計: inference_result に氏名・位置情報を入れない。ログにリクエスト body を出さない方針。

実測確認手順（WBS 3.1.5・学習目的）

理論（K-24〜K-27）を体験で補強する。記録は開発ログまたは本節に追記。

1. 正規 FB 1 件 — .\scripts\test-feedback.ps1 -BaseUrl "https://api.dammy-otoko.com"
2. DB 確認 — feedbacks の中身（PII の有無）
3. Storage 確認 — data/storage/ のファイル
4. API ログ — docker compose logs api --tail 50
5. 無認証 curl — 現状、URL だけで POST できることを体感（K-26 の裏付け）
6. （任意）LAN から :8000 — http://<PC LAN IP>:8000/api/v1/health で裏口の理解（K-24）

詳細コマンド: セキュリティ設計 §9、WBS 3.1.5

実測記録（WBS 3.1.5 実施 — 2026-06-13）

次の設計タスク: 本番では server/.env に FEEDBACK_API_KEY を設定（SEC-01 実装済み・2026-06-14）。MS-6 前チェックリスト参照。

セキュリティナレッジの読む順（推奨）

flowchart LR
  K24[K-24 OSI・FW・境界]
  K25[K-25 HTTPS・Tunnel]
  K26[K-26 公開URL・API認証]
  K27[K-27 シークレット]
  K28[K-28 Access・実測]
  K29[K-29 考える型]
  K24 --> K25 --> K26 --> K27 --> K28 --> K29
          

結論

セキュリティは前提知識（ネットワーク・層）なしでは読みにくい。 K-24 から順に、最後に WBS 3.1.5 で実測すると理解が定着する。 設計の正本は セキュリティ設計。

きっかけ

セキュリティやインフラを学ぶたびに新概念が出てきて不安になる。 「結局、機械を組んだ経験やネットワークの深い理解がないと無理では？」という疑問。

結論 — 特別な経験がなくても使える「共通の型」はある

暗記力や配線経験より、データの流れを追い、境界で三つ質問する習慣の方が効く。 専門用語はその質問に名前を付けたもの、と捉えるとよい。

型 1 — 三つの質問（いちばん使う）

新しい構成を見たら、毎回これだけ聞く:

「あれ、この境界で誰がは確認してないな」「どこから別ルートがありそう」 — こう思えれば、OSI を全部知らなくても不足に気づける。

型 2 — 四つの資産（何を守るか）

flowchart LR
  subgraph assets["守るもの"]
    P[通路\n盗聴されないか]
    G[入口\n誰でも入れるか]
    D[中身\nDB・ファイル]
    K[鍵\nパスワード・トークン]
  end
          

四つのどれかに「それ、どう守ってる？」の答えが弱いと感じたら、そこがギャップ。

型 3 — 境界ごとの門番チェック

ゾーンをまたぐ線を 1 本引くたびに、次の 3 種類の門番があるか見る:

1. 暗号化 — 路上で読まれないか（HTTPS）
2. 入口の選別 — IP/ポートで絞るか（FW）、利用者を確認するか（API キー）
3. 中で何ができるか — 通ったあと、何を保存・実行できるか（サイズ上限、DB 権限）

本プロジェクトで「守られていないな」と分かったのも、この型の 2 番目: Cloudflare 経由の入口に利用者確認（API キー）がない、と気づいたから。

「物理経験・ネットワーク深理解」は必須か

不安の正体は「用語が増えること」より、全体の地図が頭にないことが多い。 地図は データフロー や K-24 のゾーン図で足りる。細部は必要になったときに足せばよい。

学習が不安なときの進め方

1. まず データフロー 1 本 だけ追う（FB がどこを通るか）
2. その線の上に 三つの質問 を置く
3. 弱い答えを 1 つだけ WBS タスクにする（一度に全部理解しようとしない）
4. 実測 1 回（curl、logs、DB）で理論を腹落ちさせる

きっかけ

WBS 3.1.4（SEC-01）実装後、test-feedback.ps1 で Tunnel 経由の疎通を確認したところ、 health は {"status":"ok"} だが POST が {"detail":"invalid api key"}（HTTP 401）。 警告「FEEDBACK_API_KEY looks like a placeholder」も表示された。

調査の結果、FEEDBACK_API_KEY を worker/.env に誤って追加していた（のち削除）。 「シークレットを足した」という感覚は正しいが、置き場所が違った。

正しい配置（本プロジェクト）

一覧表: docs/index — 構成とシークレット。

test-feedback.ps1 がキーを読む順序

1. 引数 -ApiKey（明示指定時）
2. PowerShell の $env:FEEDBACK_API_KEY（セッションに残っていると最優先）
3. server/.env（Get-DotEnvValue.ps1）

そのため、worker/.env に書いてもスクリプトは読まない。 逆に、過去にシェルへ export したプレースホルダが残っていると、server/.env を直しても 401 が続く。

解消手順（再現用）

# リポジトリ直下
Remove-Item Env:FEEDBACK_API_KEY -ErrorAction SilentlyContinue
.\scripts\rotate-server-secrets.ps1 -ApiKey -RestartApi
.\scripts\test-feedback.ps1 -BaseUrl "https://api.dammy-otoko.com"

GitHub Actions Secret も同様 — 値は server/.env の = 以降のみ。 FEEDBACK_API_KEY=... 行全体を Secret 欄に貼ると length がずれ、GHA ビルド APK からの実機 FB が 401 になる（runbook §4b-1）。

-RestartApi は server/.env の変更を API コンテナへ反映するために必須。 .env だけ直してコンテナを再起動しないと、ファイルとコンテナ内のキーがずれたままになる。

結果（2026-06-14）

• POST https://api.dammy-otoko.com/api/v1/feedback → HTTP 201
• レスポンス例: id 58b80bce-22c1-4de1-a010-2961f5b9e4d3、created_at 付き
• プレースホルダ警告なし

SEC-01 deny 確認 — 意図的に誤ったキーを流す

正しいキーで 201 が出たあと、認証が本当に効いているかを確認する。 K-28 で「無認証 POST が通る」ことを体感したのと対になる実測（SEC-01 有効時）。

# 誤ったキー → 401 invalid api key
.\scripts\test-feedback.ps1 -BaseUrl "https://api.dammy-otoko.com" -ApiKey "wrong-key-on-purpose"

# 認証なし → 401 missing or invalid authorization header
curl.exe -s -w "`nHTTP_CODE:%{http_code}`n" `
  -X POST "https://api.dammy-otoko.com/api/v1/feedback" `
  -F "image=@scripts\sample.jpg;type=image/jpeg" `
  -F "inference_result=<scripts\inference.json;type=application/json"

health はどのケースでも {"status":"ok"}。 POST だけが認証で弾かれる — app/deps/auth.py の SEC-01 どおり。 手順の写経: runbook §5.1。

IDE 通知（python.terminal.useEnvFile）について

Cursor / VS Code から「環境ファイルはあるがターミナル注入が無効」と出ることがある。 これは Python 拡張向けの任意機能で、本プロジェクトの PowerShell 運用には不要。 有効にすると $env:FEEDBACK_API_KEY が意図せずシェルに入り、今回のような混乱の原因になりうるため、オフのままでよい。

きっかけ

会議資料の全体構成図（サーバー・Tunnel・CI/CD・クライアント）だけでは Phase1 の実装理解に十分だったが、 SEC-01 以降「鍵はどこに置くか」「HTTPS と API キーの違い」「GHA Secret と PAT の違い」が増え、 1 枚の図だけでは追いにくくなった。

元の全体構成図（会議資料）

Phase1 Android 実装への読み替え

セキュリティ拡張版 — 全体（データの流れ + 鍵の流れ）

実線＝データ・処理の流れ、点線＝秘密情報（ビルド時・設定時のみ。実行中の HTTP 本体には載せない）。

flowchart TB
  subgraph Client["クライアント（Pixel / Flutter）"]
    APP["馬体診断スタブ APK"]
    KEY_IN["鍵: ビルド時 --dart-define で APK 内定数"]
    APP --- KEY_IN
  end

  subgraph Internet["インターネット"]
    CF["Cloudflare Edge\nHTTPS 終端"]
    GHA["GitHub Actions\nandroid-build.yml"]
    GH_SEC["Actions Secret\nFEEDBACK_API_KEY"]
    GH_SEC -.->|"ビルド時 inject"| GHA
    GHA -->|"artifact APK"| PC_DL["PC ダウンロード"]
  end

  subgraph Home["自宅 PC — Docker"]
    TUN["cloudflared"]
    API["FastAPI\nSEC-01 ミドルウェア"]
    ENV["server/.env\nFEEDBACK_API_KEY"]
    DB[(PostgreSQL)]
    STG[(Storage)]
    WK["Worker スタブ"]
    ENV -.->|"compose env"| API
  end

  subgraph LocalDev["開発者 PC（ビルド・運用）"]
    SENV["server/.env"]
    WENV["worker/.env\nGITHUB_TOKEN PAT"]
    PS1["build-flutter-apk.ps1\ntest-feedback.ps1"]
    SENV -.-> PS1
    WENV -.-> WK
    PS1 -->|"ローカル release APK"| APP
  end

  APP -->|"① FB POST\nAuthorization: Bearer 鍵"| CF
  CF -->|"Tunnel 中継"| TUN
  TUN --> API
  API -->|"鍵一致?"| STG
  API --> DB

  WK -->|"② repository_dispatch\nPAT で認証"| GHA
  GHA --> PC_DL
  PC_DL -->|"adb install"| APP

  style KEY_IN fill:#fef3c7
  style ENV fill:#fef3c7
  style GH_SEC fill:#fef3c7
  style WENV fill:#e0e7ff
          

秘密情報 — 3 種類を混同しない

詳細: K-22（PAT）、K-27（シークレット全般）、K-30（FEEDBACK_API_KEY 配置）。

SEC-01 が効く場所 / 効かない場所

FB 送信 1 本の流れ（SEC-01 有効時）

時系列の詳細・SEC 前との対比: シーケンス図 §2（旧: §1）。

sequenceDiagram
  participant Pixel as Pixel アプリ
  participant CF as Cloudflare Edge
  participant API as FastAPI
  participant STG as Storage

  Note over Pixel: ビルド済み APK 内に
FEEDBACK_API_KEY 定数
  Pixel->>CF: POST /feedback
Authorization Bearer 鍵
画像 multipart
  CF->>API: Tunnel 経由（TLS 済み）
  API->>API: SEC-01: 鍵一致?
  alt 鍵 OK
    API->>STG: 画像保存
    API-->>Pixel: 201 Created
  else 鍵 NG / なし
    API-->>Pixel: 401
  end
          

APK に鍵が入るまで（ビルド経路）

flowchart LR
  subgraph A["2-A ローカル"]
    SE["server/.env"]
    BF["build-flutter-apk.ps1"]
    DD1["--dart-define"]
    APK1["app-release.apk"]
    SE --> BF --> DD1 --> APK1
  end
  subgraph B["2-B GHA"]
    GS["Actions Secret\nFEEDBACK_API_KEY"]
    YML["android-build.yml"]
    DD2["--dart-define"]
    APK2["artifact APK"]
    GS --> YML --> DD2 --> APK2
  end
  APK1 --> Pixel["adb install"]
  APK2 --> Pixel
          

ソースコード（config.dart）にはロジックだけ書き、鍵の値はビルド引数で渡す。 これが「コードに書く」のではなく --dart-define になる理由（runbook §4b）。

「実機 FB 201 確認」とは — どこに書いてあるか

意味: PC スクリプトではなく実機アプリから FB を送り、画面に 送信成功 (HTTP 201) が出ること。 SEC-01 導入後は、APK に鍵が同梱されているかの最終確認になる。

読む順序（セキュリティで迷ったとき）

1. 本節 K-31 — 全体像と鍵の種類
2. シーケンス図 §0 — SEC 前後の時系列と抜け道
3. K-25 — HTTPS / Tunnel が守るもの
4. K-26 — API 認証の考え方
5. K-30 — FEEDBACK_API_KEY の置き場所と 401
6. セキュリティ設計 — SEC-01〜08 の正式定義