ファイル配布ポータル：登録・停止・障害復旧の実装記録
文書番号：2603.00002
要旨
Workers、D1、R2を使い、必要な期間だけファイルを配布するポータルを実装した記録なのだ。ここでは2026年3月21日時点の構成、登録途中の失敗を公開状態にしない方法、D1とR2の参照先不一致で起きた障害と確認結果を整理するのだ。現在の稼働状態や包括的なセキュリティ検証を保証する記録ではないのだ。
配布の構成と状態遷移
管理者が案件と暗号化ファイルを登録し、利用者はID・Pass・Pass2による確認後に短命セッションを使って取得する構成なのだ。D1は案件・認証・監査情報、非公開R2は配布オブジェクト、Workersは画面と認証・配布の経路を担当するのだ。
| 経路 | 実装した役割 |
|---|---|
GET / | 公開・停止状態に応じた入口 |
POST /auth、POST /verify | 案件認証と追加確認 |
GET /download | ダウンロード画面 |
POST /download | 認証状態を確認した取得と回数管理 |
SITE_MODEで公開、停止、メンテナンスを切り替え、公開停止時には早期返却するのだ。常時公開ではなく、案件確認後に開き、終了後に閉じる運用を想定したのだ。
登録途中の失敗を扱う設計
登録CLIは、配布物のtar化、暗号化、SHA-256計算、D1仮登録、R2アップロード、D1有効化の順に処理するのだ。仮登録はis_enabled=0とし、保存と整合確認が終わるまで配布を有効化しないのだ。
途中状態を保存してresume-caseで再開、cleanup-pendingで後始末できるようにしたのだ。平文のPass・Pass2・復号パスフレーズは永続化せず、一時ファイルは中断時の削除対象にしたのだ。この設計だけで秘密情報の流出耐性を証明したことにはならず、端末・ログ・バックアップも確認対象になるのだ。
| 管理操作 | 目的 |
|---|---|
create-case、verify-case | 案件登録とD1/R2の対応確認 |
open-site、close-site、maintenance-site | 公開状態の変更 |
disable-case、delete-file | 案件無効化と保存物削除 |
list-cases、show-case、show-audit | 案件・失敗理由・操作履歴の確認 |
発生した障害と修正結果
| 事象 | 原因と修正 | 確認した範囲 |
|---|---|---|
deploy時にsrc/index.tsが見つからない | 一時設定を別ディレクトリに置き相対パスが崩れたため、設定をリポジトリ直下に生成 | 設定位置を修正してdeployを進めた |
| 認証後のダウンロード失敗 | D1はremote、CLIのR2操作はlocalを向いていたため、R2のput/get/deleteをremoteへ統一 | 監査のmissing_objectとremoteオブジェクト不在を確認し、再投入後HTTP 200とハッシュ一致を確認 |
| 運用JSONの日本語表示不良 | ローカル表示時の文字コード推定に依存したため、BOM付き保存と読込み時のBOM除去へ変更 | 当該表示・読込みの問題への対応 |
既に停止中のclose-siteが失敗 | 置換前後が同値だとエラーにしていたため、キー存在と値変更を分離 | 同値の停止操作を扱えるように修正 |
保存先が存在することと、利用者が通る経路から同じ保存先を読めることは別の確認なのだ。D1の案件、R2のキー、実際のHTTP応答、取得物のハッシュを組にして確認した点が、この実装から得た知見なのだ。
実施した確認と残る検証
2026年3月21日、READMEファイルを使ったテスト案件で、認証、ダウンロード、復号、展開、本文の確認を行ったのだ。初回は上記の保存先不一致で失敗し、修正後に取得できたのだ。終了後に案件のD1行・監査情報・R2オブジェクトを削除し、サイトを停止状態へ戻したのだ。これは当時のテスト用データの後始末であり、本番の監査記録を常に削除する運用を推奨するものではないのだ。
当時の静的確認はnode --check scripts/admin.mjsとnpm run check、自動テストは11件成功・0件失敗だったのだ。これらは本サイトの記事ビルドとは別の実装に対する当時の結果なのだ。現在のコードや環境で再実行した結果には読み替えないのだ。
| 未完了だった項目 | 運用前・変更時に確認すること |
|---|---|
| ブラウザE2E自動化 | 期限切れ、失敗ロック、再送、回数超過、停止中の取得 |
| ダウンロード経路のIP単位制限 | 共有IPの影響、制限回避、正規利用の誤遮断 |
| ローカル管理情報とD1の双方向同期 | 片側の更新・中断時の復旧、競合、重複実行 |
| 包括的な認可・負荷・復旧検証 | 別案件へのアクセス、同時取得、鍵更新、D1/R2障害時の状態 |
実装された機能の存在と、業務要件を満たす運用開始判断は区別するのだ。確認済みの通常経路を起点に、上表の失敗経路と残余リスクを評価する必要があるのだ。
構成を理解するための公開資料
以下は利用サービスの説明であり、この独自実装の成功結果を証明する出典ではないのだ。