Skip to content

Drive

テナント単位のファイル管理スペース。アップロード、フォルダ、共有、クォータ、タスク添付、ドキュメント

概要

Drive は Misskey のドライブに倣った、テナント単位のファイル管理スペースである。アップロードしたファイルをフォルダで整理し、タスクへの添付や共有 URL の発行に利用できる。ストレージは S3 互換(AWS S3 / MinIO)とローカルディスクの 2 種類で、環境変数で切り替える。このページには全体に効くアクセスの規則・設定・決定の記録を書き、機能ごとの規則は次のページに書く。

ページ 内容
ファイル multipart のアップロード、一覧、メタデータ、名前・配置・本文の更新、削除、配信、タスク添付、Markdown 本文の KEY-N の自動結び付け
フォルダと共有 階層フォルダ、project_id の継承・移動先の認可・プロジェクトルートの保護、利用者指定共有、公開リンク共有
クォータ 使用量の取得、テナントの個別クォータの設定、アップロード・本文の更新時の検証
ドキュメント プロジェクトのルートフォルダ直下の .md を読み書きする画面

振る舞い

ファイルの URL

全ファイルの URL は /v1/drive/files/{id}/content に統一する。テナント一般ファイルもプロジェクトファイルも同じエンドポイントで、セッション・PAT・共有トークンのいずれかが要る。

S3 バックエンドでも S3 の直 URL はクライアントに渡さず、バックエンドが S3 からストリームで取得して応答する。DB には storage_key のみを保持し、API の応答を作るときに URL を組み立てる。

ストレージバックエンド

バックエンドは StorageBackend trait(upload / delete / get_stream)で抽象化する。同じバックエンドに利用者のアバター画像も置く。キーは avatar-{uuid}.{ext} で、drive_files の行は作らず、規則の定義元はアカウント設定のアバターのアップロードである。

  • upload はストリームを受け取る。content_length の None は長さ未知で、Some なら書いた長さと食い違うと SizeMismatch になる
  • get_stream はプロキシ配信用のストリーミングダウンロードで、object が無いときはローカル・S3 とも StorageError::NotFound を返す
  • ローカルの実装はチャンクを BufWriter へ順に書き込む
  • S3 の実装は長さが未知(None)か 5 MiB 以上なら multipart upload を使い、5 MiB ごとに part を送る。5 MiB を超えて貯めず、途中で失敗したら abort する
  • 単一 PUT(全量バッファ)は 5 MiB 未満と分かっている本文だけに使う。アップロード API は長さ未知、本文更新 API は既知の長さを渡す

S3 バックエンドはクレート object_store(AmazonS3Builder)を使い、S3 互換エンドポイント(MinIO / Cloudflare R2 / Backblaze B2 / Wasabi)に対応する。バケットは非公開でよい。

S3_FORCE_PATH_STYLE は URL の形式を選ぶ。AWS S3 は仮想ホスト形式(bucket.s3.amazonaws.com)が標準で、MinIO などのセルフホスト互換では http://endpoint/bucket/key の形式(パス形式)が要る。true に設定すると AmazonS3Builder の仮想ホスト形式を無効にする。

ローカルバックエンドは開発環境・セルフホスト向けで、LOCAL_UPLOAD_DIR で保存先ディレクトリを指定する。

設定

apps/backend/.env で設定する環境変数は次のとおりである。

変数 既定 内容
STORAGE_BACKEND local local または s3。それ以外は起動時にエラー
UPLOAD_MAX_SIZE_MB 100 1 ファイルあたりの上限(MB)。ファイル本体の上限で、multipart の境界とヘッダーは含めない
DRIVE_SYSTEM_MAX_QUOTA_MB 51200(50 GB) テナントが設定できる容量の上限(MB)。0 は上限なし
DRIVE_DEFAULT_QUOTA_MB 10240(10 GB) テナントの既定の容量(MB)。0 は無制限
S3_ENDPOINT S3 用。例は https://s3.amazonaws.com、MinIO は http://localhost:9000
S3_BUCKET S3 用。例は my-task-drive
S3_REGION S3 用。例は ap-northeast-1
S3_ACCESS_KEY_ID S3 用。例は AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY S3 用。例は wJalrXUtnFEMI...
S3_FORCE_PATH_STYLE false S3 用。MinIO などでは true に設定する
LOCAL_UPLOAD_DIR ./uploads ローカル用。例は /var/task/uploads

脅威と対策

脅威ごとの対策は次のとおりである。

脅威 対策
他テナントのファイルへのアクセス ファイル自身の tenant_id に対する所属を確認する。明示的な共有による本文アクセスは認可の節の例外に従う
プロジェクト外の利用者によるファイルアクセス drive_files.project_id に対する公開規則とフォルダ共有を確認し、どちらでも許可されなければ 403
S3 の直接 URL によるプロジェクトファイルの漏洩 プロジェクトファイルの S3 URL はクライアントに渡さない。バックエンドのプロキシ経由のみとする
任意ファイルの上書き ストレージキーは UUID v4 で生成する
超大型ファイルによる DoS RequestBodyLimitLayer とストリーム中の実測値を UPLOAD_MAX_SIZE_MB から設定する
パストラバーサル(ローカル) ストレージキーは UUID のみを使う。元ファイル名はメタデータのみとする
共有トークンの総当たり 公開共有のレートリミットに書く
共有経由の過剰アクセス viewer の共有では削除・アップロードの API を 403 で止める

認可

ファイル本文のアクセス規則

テナント配下の管理 API はセッション認証または PAT 認証が必須である。GET /v1/drive/files/{id}/content は認証任意だが、取得にはテナント/プロジェクト権限または共有トークンが要る。GET /v1/drive/share/{token} とその /files は共有トークン自体を認証情報として扱う。

ファイルの種類 閲覧できる人
project_id = NULL(テナント一般ファイル) テナント所属者、テナントオーナー、有効なフォルダ共有トークンの提示者
project_id = <id>(プロジェクトファイル) そのプロジェクトに入れる人、テナントオーナー、フォルダ共有権限を持つ利用者とトークン

プロジェクトに入れるかは、ファイルの tenant_id に所属していることを先に確認したうえで、プロジェクトの公開規則で判定する。判定の詳細はテナント / プロジェクト認可に書く。テナントに所属しないプロジェクト限定のゲストは、プロジェクトメンバーであるだけでは Drive へアクセスできない。

フォルダ共有は所属とは独立した明示的な付与なので、テナントから外しても失効しない。テナント一般ファイルの本文取得では利用者指定共有を見ず、テナント所属か共有トークンだけで判定する。プロジェクトファイルの本文は、セッションまたは PAT の認証と有効な利用者指定共有があれば、テナント外の受信者も取得できる。いずれも満たさない場合は 403 Forbidden を返す。

判定の順序

ファイルへのアクセスは次の順に判定する。

  1. 共有トークンの提示者は、テナント所属と独立して判定する。ファイルに folder_id があり、有効なトークンの共有があれば許可する
  2. 認証済みの利用者は read:drive を持たなければ拒否する
  3. テナントが 2FA を強制していれば、ここで確かめる。プロジェクトファイルの枝はテナントの所属判定を通らない
  4. テナント一般ファイルは、テナント所属者またはオーナーだけに許可する。利用者指定共有は見ない
  5. PAT のテナント・プロジェクトの束縛を、ファイル自身の値と突き合わせる
  6. テナントオーナー、または「テナントに所属し、プロジェクトの公開規則を満たす人」に許可する
  7. フォルダの利用者指定共有があれば許可する

has_user_share / has_token_share はファイルの folder_id からフォルダ階層を祖先方向へ辿り、いずれかのフォルダに有効な共有の行があれば true を返す。各階層を順に問い合わせる。空でない token を提示した場合はトークンの判定を優先し、無効・期限切れなら認証済みでも 403 を返す。

PAT のスコープ

Drive に関わるスコープは次のとおりである。

スコープ 説明
read:project プロジェクトの読み取り
write:project プロジェクトの作成・更新。削除はセッション専用
write:tenant テナントの設定変更。read:tenant を包含する
api すべての read:* / write:* を包含する
read_api すべての read:* を包含する
read:drive ドライブのファイル・フォルダの一覧取得、ダウンロード、使用量の確認
write:drive ファイルのアップロード・削除・移動、フォルダの作成・削除・移動、共有の作成・取り消し。read:drive を包含する

read_api は read:drive を、api は read:drive / write:drive と、クォータ設定に要る write:tenant を包含する。いずれもスコープの要件を満たすだけであり、テナント所属・プロジェクト権限・オーナー限定の判定は別に行う。

スコープは apps/backend/crates/entity/src/scopes.rs の Scope enum に定義する。包含関係は Scope::implies の網羅 match が一箇所で持ち、has_scope はそれを引くだけである。規則の一覧は個人アクセストークンの認可の含意の規則にある。

エンドポイントごとの必要なスコープは次のとおりである。

メソッド パス スコープ 備考
GET /v1/tenants/{tenant_id}/drive/files read:drive
POST /v1/tenants/{tenant_id}/drive/files write:drive クォータの検証あり
GET /v1/tenants/{tenant_id}/drive/files/{id} read:drive
PATCH /v1/tenants/{tenant_id}/drive/files/{id} write:drive
PUT /v1/tenants/{tenant_id}/drive/files/{id}/content write:drive テキスト本文の更新。クォータの検証あり
DELETE /v1/tenants/{tenant_id}/drive/files/{id} write:drive
GET /v1/tenants/{tenant_id}/drive/files/{id}/tasks read:drive + read:task 結び付いたタスクの一覧
GET /v1/drive/files/{id}/content read:drive 共有トークンの利用時はスコープ不要
GET /v1/drive/files/{id}/content?token= スコープ不要 公開リンクのトークンで代替する
GET /v1/tenants/{tenant_id}/drive/usage read:drive
PATCH /v1/tenants/{tenant_id}/drive/quota write:tenant テナントオーナー限定
GET /v1/tenants/{tenant_id}/drive/folders read:drive
POST /v1/tenants/{tenant_id}/drive/folders write:drive
PATCH /v1/tenants/{tenant_id}/drive/folders/{folder_id} write:drive
DELETE /v1/tenants/{tenant_id}/drive/folders/{folder_id} write:drive
GET /v1/tenants/{tenant_id}/drive/folders/{folder_id}/shares read:drive
POST /v1/tenants/{tenant_id}/drive/folders/{folder_id}/shares write:drive
DELETE /v1/tenants/{tenant_id}/drive/folders/{folder_id}/shares/{share_id} write:drive
GET /v1/drive/share/{token} スコープ不要 公開リンク(認証不要)
GET /v1/drive/share/{token}/files スコープ不要 公開リンク(認証不要)

未実装と既知の制限

Drive 全体に効く差分は次のとおりである。機能ごとの差分は各ページの同じ名の節に書く。ここに記載した項目は期待する仕様ではなく、修正対象として追跡するための現状である。

優先度 項目 現状と影響
高 ストレージ削除の非同期整合性 個別削除は DB の削除後のストレージエラーを無視し、プロジェクト/テナントの CASCADE 削除ではストレージの削除自体を行わない。孤児オブジェクトを回収する仕組みが要る
中 ストレージ種別の切り替え DB に storage_type を保存するが、取得・削除は起動中の単一バックエンドだけを使う。STORAGE_BACKEND を変更すると、変更前のファイルを取得・削除できない
低 使われない S3 公開 URL の設定 実装は S3_PUBLIC_BASE_URL を読み込むが、全ファイルをプロキシ配信するので値は使われない
なし フロントエンド Drive のページ、ファイルブラウザ、クォータ、共有の UI が無い。ドキュメント画面、タスク添付の UI、入力欄への貼り付けだけがある

実装の順序は次のとおりである。バックエンドの基本 API と階層変更の境界の保護は揃っているので、残るストレージ・共有の差分を直し、その契約をテストで固定してからフロントエンドへ進む。

順序 内容 完了条件
1 ストレージ削除の回収経路の追加 個別・プロジェクト・テナントの削除と失敗時の再試行をテストできる
2 フォルダ・共有受信者向けの一覧 API の整理 プロジェクト権限と共有範囲に沿って、子フォルダを含む一覧を提供できる
3 ストレージバックエンドの移行方針の決定 storage_type ごとに取得するか、切り替え前の移行を必須化する
4 フロントエンドの実装 ファイルブラウザ、クォータ、共有の UI を提供する

決定の記録

日付 決定 理由
2026-05-26 ファイルサイズの上限は UPLOAD_MAX_SIZE_MB で設定変更可とする(既定 100 MB) 記録なし
2026-05-26 プロジェクトファイルはプロジェクトメンバーまたはテナントオーナーのみ閲覧可とする(2026-08-18 に改訂) 記録なし
2026-05-26 プロジェクトファイルの URL はバックエンド経由でプロキシし、S3 の URL を直接渡さない S3 のエンドポイントを変更しても DB の URL が古くならない
2026-05-26 S3_FORCE_PATH_STYLE で設定可とする(MinIO など向け) 記録なし
2026-05-26 プロジェクトの作成時に対応するドライブのフォルダを自動で作る 記録なし
2026-05-26 テナント別の容量は tenants.drive_quota_bytes で個別に設定する。NULL のときは DRIVE_DEFAULT_QUOTA_MB を適用する(0 は無制限) 記録なし
2026-05-26 システムの上限は DRIVE_SYSTEM_MAX_QUOTA_MB で設定する。テナントオーナーはこの値を超えて設定できない。0 は上限なし 記録なし
2026-05-26 クォータ超過時の応答は 413 Content Too Large とする 記録なし
2026-05-26 システムの上限違反時の応答は 400 Bad Request とする 記録なし
2026-05-26 フォルダ共有は利用者指定と公開リンクの 2 種類で、配下のサブフォルダ・ファイルに再帰で継承する 記録なし
2026-05-26 公開リンクのトークンは 32 文字 URL-safe ランダムで、有効期限を設定できる(NULL は無期限) 記録なし
2026-05-26 PAT のスコープに read:drive(閲覧)・write:drive(書き込み)を新設する。write:drive は read:drive を包含する。admin:tenant は全 Drive 操作を包含する(2026-10-04 に admin:tenant を廃止し、api が包含する形へ。クォータ設定は write:tenant) 記録なし
2026-05-26 drive_files.url の列を廃止し、全ファイルを /v1/drive/files/{id}/content で統一して配信する S3 のエンドポイントの変更やローカルサーバーの移転の影響を受けない
2026-05-26 project_id IS NULL OR folder_id IS NOT NULL を DB の CHECK 制約とアプリのバリデーションの両方で強制する 記録なし
2026-05-26 バックエンドは share_token のみを返し、フロントが window.location.origin で URL を組み立てる 記録なし
2026-05-26 ファイルにもフォルダの project_id を非正規化して保持する アクセス制御を毎回フォルダ階層を辿らず O(1) で判定する
2026-08-10 一般ファイルの配信はテナント所属者・オーナー、または有効なフォルダ共有トークンのみとする 記録なし
2026-08-18 プロジェクトファイルは、テナントに所属していることを先に確認したうえで、プロジェクトの公開規則で判定する ファイル ID だけで引ける配信経路があるので、プロジェクト所属だけを見るとテナント境界を越えられる
2026-09-03 S3 バケットは公開を前提としない。全ファイルをバックエンドのプロキシで配信する 記録なし
2026-09-03 ファイルまたは子フォルダが存在するフォルダの削除は 409 Conflict とする(強制削除は将来対応) 記録なし
2026-09-03 MIME タイプは全種類を許可する 記録なし
2026-09-03 共有権限は viewer(閲覧のみ)だけを実装する。editor は将来対応 記録なし
2026-09-03 StorageBackend trait は BoxStream を使う。S3 の全量バッファは TASK-163 で解消した(2026-11-01 の行) 100 MB のファイルを複数同時に全量バッファすると GByte 単位のメモリを消費しうる
2026-09-03 editor を指定した場合は 422 Unprocessable Entity を返す。実装は将来対応 記録なし
2026-09-03 上限の引き下げ時は DB の個別設定値を変更せず起動時に警告する。実効クォータは新しいシステムの上限で頭打ちにする 記録なし
2026-09-03 Drive のファイルとタスクの紐付け・解除の API を実装した 記録なし
2026-09-04 フォルダの project_id は階層のルートから継承し、移動時は配下(フォルダ・ファイル)まで揃える。既に食い違っている行は backfill マイグレーション(m20260904000000_drive_project_id_backfill)で直す。起点は project_id を持つフォルダ全件(一般フォルダ配下へ移動されたプロジェクトルートも含む)で、そこから project_id が NULL の子孫だけへ伝播する。深さでは打ち切らない。一般ツリーの配下に残った project_id は触らない 打ち切ると残りが NULL のまま成功してしまう。一般ツリーの project_id は階層より厳しい判定になるだけで、NULL へ落とすと非メンバーへ開く
2026-09-04 配下に別プロジェクトの project_id を持つ行(フォルダ・ファイルとも)があるツリー、または親子が循環しているツリーは 1 行も書き換えず、マイグレーションを失敗させる。該当する行を人が直してから流し直す 継承で上書きするとそのプロジェクトのファイルが別プロジェクトのメンバーへ公開され、元のメンバーはアクセスを失う。修正前はプロジェクトルートの移動もできたので、この状態が既存データにありうる
2026-09-04 フォルダの作成・移動、ファイルの作成・移動は、テナント単位のアドバイザリロック(pg_advisory_xact_lock)で直列化する。ACL と親の project_id はロック取得後に同一トランザクションで読み、挿入・移動・子孫の同期まで同じトランザクションで終える ロックの外で読むと、移動中のフォルダへ子を作ったときに移動前の project_id を継承した行が同期の後から挿入され、ACL 漏れが再発する
2026-10-16 本文の ETag は SHA-256(drive_files.content_hash)から作る強い ETag とする。ハッシュを持たない既存行は backfill せず、updated_at(Unix ミリ秒)とサイズで代替する。比較は文字列の完全一致で、弱い ETag(W/)は受けないとした(2026-10-21 に W/ を外して比べる形へ改めた)。期待値は標準の If-Match / If-None-Match ヘッダーで受け、JSON ボディでの期待値の指定は採らない。If-Match の比較は行ロック取得後に行い、ヘッダー省略時は後勝ちとする 同期型クライアントが標準の HTTP キャッシュ処理のまま扱えるようにする
2026-10-16 Markdown 本文の KEY-N の抽出は forge の task_refs を再利用する。手動の添付(manual)は本文由来(body)に負けない(本文に書いても body に書き換えず、本文から消えても消さない)。body の解除は本文の編集で行い、DELETE は 409。手動で POST すると manual に昇格する。結び付け先は手動の添付と同じ範囲で、さらに保存者が入れるプロジェクトのタスクだけとする。1 ファイル 200 件まで。プロジェクトファイルが別プロジェクトのタスクに持つ body 行は、プロジェクトへの移動と本文の保存で外す(保存者が入れるかに依らない) 別プロジェクトに結ぶと添付一覧からファイル名が別プロジェクトの人に見える
2026-10-16 フォルダ一覧に project_id / parent_id / root_only、ファイル一覧に mime_type / q / sort を足した。プロジェクトのルートは project_id + root_only で取る(ProjectResponse には持たせない) 記録なし
2026-10-16 プロジェクトのドキュメントは専用の表を作らず、ルートフォルダ直下の .md ファイルとして扱う。種類・ステータス・承認・履歴は持たず、種類は作成時のテンプレートの選択にだけ使う 記録なし
2026-10-17 保存者が入れないプロジェクトへの body 行は残す 保存者は本文の参照を判断できない。入れない人が誤字を直しただけで、別プロジェクトの添付一覧から資料が消えたり戻ったりしないようにする
2026-10-20 write:drive だけの PAT は body の同期を飛ばす。結び付いたタスクの一覧は read:task も要求する タスクの題・状態を返すので、手動の添付やタスク側の添付一覧と同じく write:task / read:task の絞りを越えさせない
2026-10-21 If-Match / If-None-Match の W/"..." は W/ を外して比べる(TASK-336) 本番は Cloudflare 越しで、圧縮した応答の強い ETag が弱い ETag に付け替えられ、ブラウザがそれを If-Match に戻すとドキュメントの保存が常に 412 になっていた。本文の ETag は内容のハッシュなので弱い一致で失うものは無い
2026-10-29 プロジェクトフォルダの共有の一覧・作成・取り消しは、作成者であっても現在そのプロジェクトに入れること(またはテナントオーナー)を条件にする(TASK-376) プロジェクトから外れた作成者が公開リンクや自分宛ての共有を作り、ファイルの閲覧を取り戻せた
2026-11-01 StorageBackend::upload の長さは Option<u64>(None は未知)とする。S3 は未知か 5 MiB 以上なら multipart で流し、全量を貯めない。アップロード API は全パートを読み終えてから DB に登録し、name / folder_id の順序を問わない(file が 2 つなら 400)。リクエスト本文の上限は UPLOAD_MAX_SIZE_MB + 64 KiB(multipart の境界とヘッダー)とし、ファイル本体の上限はハンドラーが実測で守る(TASK-163) 記録なし
2026-11-01 公開共有の API は接続元 IP × トークン指紋の組で固定窓 60 秒 120 回(定数。環境変数は設けない)とする。フォルダ取得・一覧・本文の合計で数え、別トークン・別 IP・認証済みの経路は巻き込まない(TASK-167) 120 回は共有フォルダを開いて一覧と数十ファイルの本文を読む利用が通る数である
2026-11-04 mime_type はソースコードの拡張子の上書き表を申告された Content-Type より優先する ブラウザが .ts を video/mp2t のように申告することがあり、そのまま保存すると本文更新 API が対象外として弾く
2026-11-18 入力欄に貼り付けたファイルの URL は、本文には API の相対パス /v1/drive/files/{id}/content で書き、web は描画するときに /api を前に足す。動画と音声も画像の記法 ![名前](URL) で書き、名前の拡張子でプレイヤーに描き分ける(TASK-137) 本文は CLI・デスクトップ・MCP も読む。/api は web の中継の都合で、他のクライアントでは引けない。本文の URL には拡張子も MIME タイプも無いので、描画側が API を呼ばずに種類を知る材料は名前だけである
2026-11-18 貼り付けたファイルはプロジェクトのルートフォルダに置き、タスクの添付にはしない。貼り付け専用のサイズ上限は設けない(TASK-137) 保存先を添付と同じにすると、読める人が本文を読める人と揃う。上限の値を返す API が無く、web で同じ値を持つと設定とずれる
2026-11-18 表示・再生できるかはブラウザの読み込みの結果で決め、読み込めなければその場でダウンロードのリンクに替える。ファイルの変換はしない(TASK-137) 表示できるかはブラウザとコーデックで決まり、拡張子では分からない(HEIC、HEVC の .mov)

Type to search…

↑↓ navigate↵ selectEsc close