ファイルアップロードを極める:開発者向け総合ガイド
ファイルアップロードは、サーバーに到達しても保存前に失敗することがあります。このガイドでは、Node.js、Flask、PHP のローカル画像アップロードハンドラー、認証付き Rails アプリケーションへの統合、リクエスト、検証、保存の各段階での障害を切り分ける Postman のワークフローを紹介します。
はじめに:ファイルアップロードとは?
ブラウザーは、選択したファイルのバイト列を受信エンドポイントに送信します。multipart/form-data では、各ファイルやテキストフィールドが、フィールド名を持つ個別のパートになります。受信側はパートを解析し、受け入れポリシーを適用して、受け入れたバイト列をストレージに書き込みます。クライアントが指定するファイル名や MIME タイプはラベルにすぎず、実際の内容を証明するものではありません。
基本的なファイルアップロード機能の設定
ハンドラーをひとつ選び、127.0.0.1:3000 で一度にひとつだけ実行します。この HTML フォームは、myfile というフィールド名でファイルを送信します。
<form action="http://127.0.0.1:3000/upload" method="post" enctype="multipart/form-data">
<label for="myfile">Image</label>
<input id="myfile" type="file" name="myfile" />
<button type="submit">Upload File</button>
</form>
enctype="multipart/form-data" 属性は必須です。通常のフォームフィールドとともにファイルデータを送信するようブラウザーに指示します。
以下の Node、Flask、PHP プログラムは、ローカルで動作するアップロードハンドラーの実例です。ループバックにバインドし、ストレージは静的ファイルのルートやドキュメントルートの外に置いてください。ログイン機能は実装していません。デプロイ前に、認証、認可、CSRF 対策、ユーザーごとのクォータ、レート制限をこれらの前段に設けてください。Rails のコードは、既存の認証付きアプリケーションに統合するものです。
Bash と、別途インストールした Node.js および Corepack を使用します。Yarn インストールガイドを参照してください。検証済みのバージョンは Node.js 24.21.0 と Yarn 4.18.0 です。再現用に固定したバージョンであり、本質的な最低要件ではありません。既存の JavaScript プロジェクトの外で作業し、そのパッケージマネージャー設定がインストールに影響しないようにします。次のブロックをシェルに貼り付けてください。サブシェルを使うため、失敗しても作業ディレクトリとシェルオプションは変更されません。
(
for tool in node corepack; do
command -v "$tool" >/dev/null || { printf 'Missing %s\n' "$tool" >&2; exit 1; }
done
[ -z "${YARN_RC_FILENAME:-}" ] || { printf 'Use the default Yarn configuration filename\n' >&2; exit 1; }
node --input-type=module -e '
import { existsSync } from "node:fs";
import { dirname, join } from "node:path";
let directory = process.cwd();
for (;;) {
if (["package.json", "yarn.lock", ".yarnrc.yml", ".pnp.cjs"].some(name => existsSync(join(directory, name)))) {
throw new Error("Choose a directory outside an existing JavaScript project");
}
const parent = dirname(directory);
if (parent === directory) break;
directory = parent;
}
' &&
mkdir upload-node && cd upload-node &&
printf '%s\n' '{"private":true,"type":"module","packageManager":"yarn@4.18.0"}' > package.json &&
printf 'nodeLinker: node-modules\nenableGlobalCache: false\n' > .yarnrc.yml &&
corepack yarn add express@5.2.1 express-fileupload@1.5.2 file-type@22.1.0 &&
corepack yarn node --input-type=module -e "await import('express'); await import('express-fileupload'); await import('file-type')"
)
このブロックは upload-node を作成しますが、呼び出し元は元のディレクトリに残ります。インストールに失敗した場合は、そのディレクトリとファイルを残してください。接続の問題や報告されたインストールの問題を修正したら、依存関係を明示したリストで再試行します。解決処理の早い段階で失敗した後は、yarn install だけを実行すると、マニフェストが空でも成功することがあります。
(
cd upload-node &&
corepack yarn add express@5.2.1 express-fileupload@1.5.2 file-type@22.1.0 &&
corepack yarn node --input-type=module -e "await import('express'); await import('express-fileupload'); await import('file-type')"
)
upload-node/upload.ts として保存します。パーサーはファイルデータをメモリに保持し、リクエストごとに最大ふたつのファイルバッファーを使用します。ハンドラーはボディ長の宣言を必須とし、同時に処理中の HTTP レスポンスをふたつまで許可し、保存パスをサーバー側で生成します。HTTP カウンターの枠はレスポンスが閉じると解放されます。クライアントの切断後も完了まで続く非同期書き込みの数を制限するものではありません。
import { randomUUID } from 'node:crypto'
import { mkdir, rm, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import express from 'express'
import fileUpload from 'express-fileupload'
import { fileTypeFromBuffer } from 'file-type'
const app = express()
const maxBytes = 5 * 1024 * 1024
const root = join(process.cwd(), 'private-uploads')
await mkdir(root, { recursive: true, mode: 0o700 })
let active = 0
const parse = fileUpload({
// Busboy signals its limit at the threshold; the extra byte keeps maxBytes inclusive.
limits: { fileSize: maxBytes + 1, files: 2, fields: 0, parts: 3 },
abortOnLimit: true,
useTempFiles: false,
uploadTimeout: 10_000,
})
app.post('/upload', (req, res, next) => {
const length = req.get('content-length') ?? ''
if (!/^[1-9][0-9]*$/.test(length)) return res.status(411).send('Content length required')
if (Number(length) > 6 * 1024 * 1024) return res.status(413).send('Request too large')
if (active >= 2) return res.status(503).send('Busy')
active += 1
res.once('close', () => { active -= 1 })
next()
}, parse, async (req, res) => {
const files = req.files
const file = files?.myfile
if (!files || Object.keys(files).length !== 1 || !file || Array.isArray(file)) {
return res.status(400).send('Send exactly one myfile')
}
if (file.truncated || file.size < 1 || file.size > maxBytes) {
return res.status(413).send('Invalid file size')
}
let type
try {
type = await fileTypeFromBuffer(file.data.subarray(0, 4100))
} catch {
return res.status(400).send('Unrecognized image')
}
const extensions = new Map([['image/jpeg', 'jpg'], ['image/png', 'png'], ['image/gif', 'gif']])
const extension = extensions.get(type?.mime)
if (!extension) return res.status(400).send('Unrecognized image')
const directory = join(root, randomUUID())
let created = false
try {
await mkdir(directory, { mode: 0o700 })
created = true
await writeFile(join(directory, 'image.' + extension), file.data, { flag: 'wx', mode: 0o600 })
if (res.destroyed) {
await rm(directory, { recursive: true, force: true })
return
}
res.status(201).send('File uploaded successfully')
} catch {
if (created) await rm(directory, { recursive: true, force: true })
throw new Error('Storage failed')
}
})
app.use((_error, _req, res, _next) => {
if (!res.headersSent) res.status(500).send('Upload failed')
})
const server = app.listen(Number(process.env.PORT ?? 3000), '127.0.0.1', (error) => {
if (error) {
console.error('Upload server could not start')
process.exitCode = 1
}
})
server.requestTimeout = 15_000
server.headersTimeout = 10_000
セットアップを実行したのと同じ呼び出し元からサーバーを起動します。
(
cd upload-node && corepack yarn node upload.ts
)
そのターミナルは開いたままにし、終了時は Ctrl+C でサーバーを停止します。フォームを form.html として保存し、ブラウザーで開くか、後述の Postman の手順を使ってください。受け入れたリクエストごとに 201 を返し、image.jpg、image.png、または image.gif を含む新しい非公開ディレクトリを作成します。送信されたファイル名を保存パスに使うことはありません。express-fileupload はマルチパート解析を提供しますが、保守されている他のパーサーより本質的に安全というわけではありません。file-type が識別するのはシグネチャであり、ファイルの安全性ではありません。スクリプトのバイト列が追記された PNG でも、PNG と識別されることがあります。非公開ストレージと生成した拡張子により、クライアント指定の名前で Web 経由で実行可能なファイルが作られることを防ぎます。画像を安全に公開配信するには、別途デコード、再エンコード、セキュリティスキャンのポリシーが必要です。
各フレームワークでのファイルアップロード処理
Python(Flask)
検証済みの Python ランタイムは 3.12.3、Flask は 3.1.3、Pillow は 12.3.0 です。Python の venv モジュールと pip のインストールが必要です。新しい作業ディレクトリで独立したプロジェクトを使い、呼び出し元ではその venv を有効化しないでください。
(
command -v python3 >/dev/null || { printf 'Missing python3\n' >&2; exit 1; }
mkdir upload-flask && cd upload-flask &&
python3 -m venv .venv &&
.venv/bin/python -m pip install Flask==3.1.3 Pillow==12.3.0
)
upload-flask/app.py として保存します。この完全なハンドラーは非公開ストレージを作成し、実際の画像パーサーで検証して、サーバーが選んだ拡張子のみを使います。リクエストの上限にはマルチパートのオーバーヘッドが含まれ、ファイルの上限は別途検証します。
from io import BytesIO
from pathlib import Path
import os
import uuid
import warnings
from flask import Flask, abort, request
from PIL import Image, UnidentifiedImageError
app = Flask(__name__)
app.config['MAX_CONTENT_LENGTH'] = 6 * 1024 * 1024
# Keep Flask's default form-memory limit; Werkzeug also applies it to parser buffers.
app.config['MAX_FORM_PARTS'] = 2
root = Path.cwd() / 'private-uploads'
root.mkdir(mode=0o700, exist_ok=True)
Image.MAX_IMAGE_PIXELS = 20_000_000
extensions = {'JPEG': 'jpg', 'PNG': 'png', 'GIF': 'gif'}
@app.post('/upload')
def upload():
if set(request.files) != {'myfile'} or len(request.files.getlist('myfile')) != 1:
abort(400)
data = request.files['myfile'].stream.read(5 * 1024 * 1024 + 1)
if not data or len(data) > 5 * 1024 * 1024:
abort(413)
try:
with warnings.catch_warnings():
warnings.simplefilter('error', Image.DecompressionBombWarning)
with Image.open(BytesIO(data), formats=['JPEG', 'PNG', 'GIF']) as image:
extension = extensions.get(image.format)
image.verify()
except (UnidentifiedImageError, OSError, SyntaxError, ValueError,
Image.DecompressionBombError, Image.DecompressionBombWarning):
abort(400)
if extension is None:
abort(400)
destination = root / (uuid.uuid4().hex + '.' + extension)
created = False
try:
descriptor = os.open(destination, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
created = True
with os.fdopen(descriptor, 'wb') as output:
output.write(data)
except OSError:
if created:
destination.unlink(missing_ok=True)
abort(500)
return 'File uploaded successfully.', 201
@app.errorhandler(500)
def storage_error(_error):
return 'Upload failed.', 500
if __name__ == '__main__':
app.run(host='127.0.0.1', port=int(os.environ.get('PORT', '3000')), debug=False)
元の呼び出し元から起動し、Ctrl+C で停止します。
(
cd upload-flask && .venv/bin/python app.py
)
venv の作成後に pip が失敗した場合は、venv を残して元の呼び出し元から再試行します。
(
cd upload-flask && .venv/bin/python -m pip install Flask==3.1.3 Pillow==12.3.0
)
組み込みサーバーはローカル開発用です。Node と同じフォームと
myfile フィールドを使用します。Pillow の検証では、画像の再エンコードも、追記されたコンテンツの除去も行いません。元ファイルは非公開で保存してください。信頼できない一般からのトラフィックを受け入れる前に、画像処理を隔離し、CPU とメモリの制限を設けてください。
PHP
この例は PHP 8.4.27 とその FileInfo 拡張機能で検証しました。サポート対象の PHP 8.4 ブランチの最新パッチリリース、または同等のセキュリティ修正がバックポートされたベンダー保守のビルドを使用してください。2026年10月21日のセキュリティリリースでは、重大なリモートコード実行の脆弱性がふたつ修正されました。上流の 8.4 ブランチでは、8.4.27 以降にこれらの修正が含まれます。アップロード制限やエラー出力の非表示は、この更新の代わりにはなりません。
別途公開された PHP の10月23日のセッションに関する勧告は、セッションアップロード進捗が有効で、session.serialize_handler を
php_binary または php_serialize に設定し、その後 session_start() より前に ini_set() を使って
php に切り替えるホストに関するものです。アプリケーションでこの処理を行っている場合は、追加修正が提供されるまで、サーバー設定で session.upload_progress.enabled=0 を設定し、PHP ワーカーを再起動してください。この設定はリクエスト解析前に適用されている必要があります。このスタンドアロンのハンドラーはセッションを開始しません。
最初にディレクトリを作成します。
(
command -v php >/dev/null || { printf 'Missing php\n' >&2; exit 1; }
php -r 'exit(extension_loaded("fileinfo") ? 0 : 1);' &&
mkdir upload-php && cd upload-php &&
mkdir public && mkdir -m 700 private-uploads
)
ハンドラーを upload-php/public/upload.php として保存します。元の呼び出し元から起動し、Ctrl+C で停止します。
(
cd upload-php &&
php -d display_errors=0 -d upload_max_filesize=5M -d post_max_size=6M -d max_file_uploads=2 -S 127.0.0.1:3000 -t public
)
フォームの action または Postman の URL を
http://127.0.0.1:3000/upload.php に設定します。非公開ディレクトリは PHP が所有し、書き込み可能である必要があります。
PHP のアップロード仕様には、アップロードエラーコードとサーバー上の一時パスが含まれます。内容を調べる前に、これらを確認してください。送信された拡張子は決して保持しないでください。picture.php という名前のファイルに画像のバイト列が含まれることもあります。
<?php
declare(strict_types=1);
header('Content-Type: text/plain; charset=utf-8');
header('Cache-Control: no-store');
function rejectUpload(int $status): never {
http_response_code($status);
exit('Upload rejected.');
}
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
header('Allow: POST');
rejectUpload(405);
}
if ((int) ($_SERVER['CONTENT_LENGTH'] ?? 0) > 6 * 1024 * 1024) {
rejectUpload(413);
}
$file = $_FILES['myfile'] ?? null;
if (count($_FILES) !== 1 || !is_array($file) ||
!isset($file['error']) || !is_int($file['error'])) {
rejectUpload(400);
}
if ($file['error'] === UPLOAD_ERR_INI_SIZE || $file['error'] === UPLOAD_ERR_FORM_SIZE) {
rejectUpload(413);
}
if ($file['error'] !== UPLOAD_ERR_OK || !is_string($file['tmp_name'] ?? null) ||
!is_uploaded_file($file['tmp_name'])) {
rejectUpload(400);
}
$directory = null;
try {
$size = filesize($file['tmp_name']);
if ($size === false || $size < 1 || $size > 5 * 1024 * 1024) {
rejectUpload(413);
}
$mime = (new finfo(FILEINFO_MIME_TYPE))->file($file['tmp_name']);
$extensions = ['image/jpeg' => 'jpg', 'image/png' => 'png', 'image/gif' => 'gif'];
if (!is_string($mime) || !isset($extensions[$mime])) {
rejectUpload(400);
}
$root = dirname(__DIR__) . '/private-uploads';
if (!is_dir($root) || !is_writable($root)) {
throw new RuntimeException('Storage unavailable');
}
$candidate = $root . '/' . bin2hex(random_bytes(16));
if (!mkdir($candidate, 0700)) {
throw new RuntimeException('Storage unavailable');
}
$directory = $candidate;
$destination = $directory . '/image.' . $extensions[$mime];
if (!move_uploaded_file($file['tmp_name'], $destination) || !chmod($destination, 0600)) {
throw new RuntimeException('Storage unavailable');
}
http_response_code(201);
echo 'File uploaded successfully.';
} catch (Throwable $error) {
if ($directory !== null) {
if (isset($destination) && is_file($destination)) {
unlink($destination);
}
rmdir($directory);
}
error_log('Upload storage failed');
http_response_code(500);
echo 'Upload failed.';
}
HTTP 環境へのデプロイでは display_errors を無効化し、PHP のファイルシステム警告からパスが漏れないようにします。FileInfo は内容の推定を行うもので、マルウェアスキャンでも完全な画像デコーダーでもありません。PHP はリクエスト終了時に一時アップロードファイルを削除します。ハンドラーは受け入れたファイルのみを非公開ストレージに移動します。ランダムな非公開サブディレクトリにより、他の受け入れ済みアップロードが
move_uploaded_file() で上書きされることを防ぎます。
Ruby on Rails
attached、content_type、size の各バリデーターは、Rails 本体ではなく
active_storage_validations が提供します。この例では Rails 8.1.3.1、検証済みの Ruby 3.3.10 ランタイム、この gem のバージョン 4.1.1 を使用します。既存アプリケーションの Gemfile に追加し、bundle install を実行します。
gem 'active_storage_validations', '4.1.1'
アプリケーションで解決済みの依存関係は Gemfile.lock に保持してください。
Active Storage がインストール済みの、既存の認証付きアプリケーションを使用します。Active Storage ガイドに従い、非公開の Disk サービスまたは非公開のオブジェクトストレージを設定してください。ローカルの Disk サービスでは、ルートを public の外に置き、そのディレクトリのモードを 0700 にします。以下のコンテンツ偽装対策オプションには、UNIX の file 実行ファイルも必要です。検証した補助プログラムは file 5.46 と 5.48 です。後述の受け入れ結果の表に示すとおり、PNG の分類が異なります。このホストは Rack 3.2.7 を使用しました。補助プログラムは Ruby gem とは別にインストールしてください。
# app/models/user.rb
class User < ApplicationRecord
has_one_attached :myfile
validates :myfile,
content_type: { in: ['image/png', 'image/jpeg', 'image/gif'], spoofing_protection: true },
size: { between: 1..5.megabytes }
end
認証層がすでに current_user を提供するアプリケーションで、このコントローラーを使用します。params[:user_id] からユーザーを選択しないでください。受け入れるのは新しいマルチパートアップロードのみで、クライアント指定の
Active Storage 署名付き blob ID は受け入れません。
# app/controllers/uploads_controller.rb
class UploadsController < ApplicationController
before_action :require_upload_user
protect_from_forgery with: :exception
def new
render :new
end
def create
file = params.require(:user).permit(:myfile)[:myfile]
unless file.is_a?(ActionDispatch::Http::UploadedFile)
return render plain: 'Send a file.', status: :bad_request
end
user = current_user
if user.update(myfile: file)
render plain: 'File uploaded successfully.', status: :created
else
reasons = user.errors.details[:myfile].map { |detail| detail[:error].to_s }.uniq
Rails.logger.warn('Upload validation rejected: ' + reasons.join(', '))
render plain: 'File rejected.', status: :unprocessable_entity
end
end
private
def require_upload_user
head :unauthorized unless current_user
end
end
次のルートを config/routes.rb に追加します。
get '/upload', to: 'uploads#new'
post '/upload', to: 'uploads#create'
このビューを app/views/uploads/new.html.erb として保存します。Rails は CSRF トークンと、コントローラーが期待する入れ子の
user[myfile] フィールド名を出力します。
<%= form_with scope: :user, url: '/upload', multipart: true do |form| %>
<%= form.label :myfile, 'Image' %>
<%= form.file_field :myfile, accept: 'image/png,image/jpeg,image/gif', required: true %>
<%= form.submit 'Upload file' %>
<% end %>
既存アプリケーションをプロジェクトディレクトリから起動します。
bin/rails server -b 127.0.0.1 -p 3000
通常のログイン手順でサインインし、/upload にアクセスします。ローカルサーバーは Ctrl+C で停止します。current_user は、サインイン中の
User を返す必要があります。この機能では添付を任意としているため、ユーザーの作成や名前の編集も引き続き行えます。
ストレージサービスは非公開に保ち、認証付きダウンロードコントローラーを設定してください。デフォルトの Active Storage 署名付き URL は、ユーザーごとの認可ではありません。Rails がマルチパートデータを解析する前に、Web サーバーでリクエストボディの上限を適用してください。モデルの検証は解析後に行われるため、このネットワークリソース制限の代わりにはなりません。これらの例では直接アップロードを有効にしていません。他のフローから生じる未使用の blob には、別途保持ポリシーが必要です。
ファイルアップロードでよくある問題と解決策
ファイルをアップロードできないのはなぜ?
まずレスポンスを確認し、どの段階でリクエストが拒否されたかを調べます。これらのローカルハンドラーはいずれも、空でなく、5 MiB(5,242,880 バイト)以下のファイルを必要とします。ちょうど 5 MiB も含みます。Node、Flask、PHP はさらに、宣言されたリクエストボディを、マルチパートのオーバーヘッドを含め 6 MiB までに制限します。Rails では、モデル検証前に既存の Web サーバーでこのボディ上限を適用する必要があります。
| 症状 | これらの例での確認事項 |
|---|---|
| 404 または 405 | URL と POST メソッドを確認します。PHP は /upload.php、他の例は /upload で受信します。 |
| 400 | マルチパートのエンコード、期待されるフィールド、後述の内容識別ポリシーを確認します。Flask はピクセル数の上限超過や画像検証の失敗でも 400 を返します。Node のパーサーはアップロードの無通信タイムアウト後にファイルを残さないことがあり、フィールド欠落と同じ 400 になります。 |
| Node の 411 | 既知のボディ長を送信します。この実例は、チャンク形式のストリーミングリクエストを拒否します。 |
| 413 | ファイルとリクエストのバイト数上限を確認します。Node、Flask、PHP は空ファイルにも 413 を使います。Flask のパーサーは、パート数超過やフォームのメモリ上限超過でも 413 を返すことがあります。 |
| Rails の 401 | ホストアプリケーションでサインインします。アップロード側から ID でユーザーを選択することはできません。 |
| Rails の 422 | セッションの CSRF トークンと、入れ子の user[myfile] ファイルフィールドを指定します。CSRF が有効なリクエストでも、空ファイルを含む内容やサイズの検証に失敗することがあります。 |
| 500 | ストレージの権限を確認します。検証した Rails ホストでは、ハンドラー実行前に Rack のファイル数やパート数の上限に達した場合も 500 が返りました。 |
| Node の 503 | すでにふたつの HTTP レスポンスが処理中です。完了を待って再試行します。 |
小さな PNG でも、バイト数の上限内でありながらピクセル数の上限を超えることがあります。Flask は 20,000,000 ピクセルを超える画像を拒否します。ちょうどその数なら寸法チェックを通過します。verify() の呼び出しは、ピクセルを完全にデコードせずにファイル構造を検証します。Node のシグネチャ検索、PHP の FileInfo、Rails の MIME 偽装チェックも同様に、すべての画像をデコードできること、メタデータが除去されること、ファイルにマルウェアがないことを証明するものではありません。
以下の識別上の境界は、記載した固定バージョンの依存関係で観測したものです。「受け入れ」は元のバイト列を非公開で保存したことを意味し、公開配信の承認ではありません。
| 入力 | Node | Flask | PHP 8.4.27 FileInfo | Rails と file 5.46 / 5.48 |
|---|---|---|---|---|
| 通常の PNG、メタデータ付き JPEG、GIF | 受け入れ | 受け入れ | 受け入れ | 受け入れ / 受け入れ |
| 有効な MPF/MPO 複数画像 JPEG | JPEG として受け入れ | 400:Pillow が MPO と報告し、返却形式の許可リスト外 | JPEG として受け入れ | 受け入れ / 受け入れ |
| コンパクトな APNG | 400:APNG と識別 | PNG として受け入れ | PNG として受け入れ | 受け入れ / 422:MIME 不一致 |
| アニメーションマーカーの前に 12 KB のメタデータがある APNG | PNG として受け入れ | PNG として受け入れ | PNG として受け入れ | 受け入れ / 422:MIME 不一致 |
| そのマーカーの前に 40 KB または 90 KB がある APNG | PNG として受け入れ | PNG として受け入れ | PNG として受け入れ | 受け入れ / 受け入れ |
Node は先頭の 4,100 バイトのみを調べます。file 5.48 の
PNG マジックルールは、オフセット 33 から 16,384 バイトの範囲でアニメーションマーカーを検索します。マーカーを検索範囲の外に移すと、画像がアニメーションかどうかは変わらなくても識別結果が変わります。これらのハンドラーは、アニメーションを一律に禁止するものではありません。Flask による MPO の拒否もポリシー上の境界であり、JPEG の破損を証明するものではありません。Pillow の MPO サポートを参照してください。
マルチパートの個数制限には、別の落とし穴があります。解析済みフィールド数は、送信された全パート数とは一致しません。Node はファイルパートを最大ふたつ、全体で最大みっつのパートまで調べ、テキストフィールドを破棄し、解析済みマップに複数のファイルが見える場合は拒否します。パーサーのパート上限を超えた別のファイルは省略され、見えている myfile だけが 201 で保存されることがあります。Flask はテキストパートも含めて合計ふたつのパートを許可し、それを超えると 413 を返します。見えているファイルが重複している場合は 400 を返します。フォームのデフォルトのメモリ上限は 500,000 バイトのままで、ファイルやボディの上限とは別です。
記載した PHP の max_file_uploads=2 は、ファイルパートを最大ふたつ処理します。重複するスカラーの myfile パートは最後に処理されたものに集約され、それ以降のファイルパートは無視されることがあります。Rails も同様に、最後に解析された
user[myfile] を採用し、コントローラーの入力として許可されていない他のフィールドを無視します。検証した Rack ホストでは、ファイルパート 127 個、総パート数 4,095 個は受け入れられました。ファイルパートが 128 個、または総パート数が
4,096 個に達すると、パーサー例外が発生しました。これらは制限された解析済みフィールドに対するポリシーであり、生のリクエストに含まれるすべての重複や追加ファイルの拒否を保証しません。このタスクでは、ファイルをひとつだけ送り、不要なフィールドは送らないでください。
解決策
まずデコード可能とわかっている画像を使い、フィールド名、ボディサイズ、内容、保存先の権限のうち、入力条件を一度にひとつだけ変えてください。Node にはさらに、10 秒間のアップロード無通信タイマーと、15 秒の HTTP リクエストタイムアウト設定があります。遅いリクエストはサイズ上限未満でも失敗することがあります。これらの設定は、実時間で厳密なレスポンス期限を保証するものではありません。
Rails の検証失敗については、掲載したコントローラーは
errors.details の理由コードのみを、「Upload validation rejected」というプレフィックス付きで記録します。422 の後にこのログを確認し、コンテンツタイプ、偽装、サイズによる拒否を区別してください。送信されたバイト列、ファイル名、セッション Cookie、トークンは記録しないでください。
ストレージエラーを再試行する前に、Rails の状態を調べてください。検証による拒否では、それまでの添付参照とバイト列が維持されます。その後の書き込み失敗は別です。Active Storage はコミット後のアップロードより前に参照を保存します。インラインジョブアダプターを使った検証対象の Disk サービスでは、強制的に書き込みを失敗させると 500 が返り、存在しないファイルを指す新しい参照がコミット済みになりました。以前の blob とそのバイト列は残りましたが、ユーザーの現在の添付ではなくなりました。新しいクエリでユーザーを読み直し、その blob の実ファイルまたはダウンロードを確認してから、以前の blob とジョブキューを調べてください。500 はロールバックを意味しません。次の更新前にストレージの原因を修正し、参照の整合性を回復してください。
Postman によるファイルアップロード API のテスト
まず、起動中の Node または Flask の実例を使います。この手順は Postman 12.31.7 の Linux デスクトップクライアントで検証しました。PHP は同じフィールドを使い、URL は /upload.php になります。Rails では、認証済みセッションと CSRF トークンも指定する場合を除き、アプリケーションが生成したフォームを使ってください。
http://127.0.0.1:3000/uploadへの POST リクエストを作成します。- Body を開き、form-data を選択します。
myfileを追加し、型として File を選び、OS のファイル選択ダイアログでローカル画像を選択します。- マルチパートの Content-Type ヘッダーは Postman に任せ、一致する boundary が含まれるようにします。
- Send をクリックします。201 と新しい保存ファイルひとつを確認し、そのバイト列を選択した画像と比較します。
- フィールドだけを
wrongfieldに変えて再送信します。Node、Flask、PHP は、保存ファイルを追加せずに 400 を返します。
コマンドラインで確認するには、選択した有効な PNG を、呼び出し元のディレクトリの
sample.png に配置します。--fail-with-body に対応した cURL を使用してください。このコマンドは cURL 8.5.0 で検証しました。
curl --fail-with-body --silent --show-error -F "myfile=@./sample.png" http://127.0.0.1:3000/upload
成功レスポンスは、ハンドラーが書き込みを完了したことを示します。private-uploads も調べ、保存されたバイト列全体を比較し、別のデコーダーで保存画像を開いてください。レスポンスだけでは、正しい出力を確認したかどうかはわかりません。これらの実例は受け入れた元ファイルを保持します。終了したらサーバーを停止し、自分のテスト用アップロードだけを削除してください。
ファイルアップロードのセキュリティベストプラクティス
元ファイルは静的ファイルのルートやドキュメントルートの外に保管してください。Node と PHP の例は、アップロードごとにサーバーが命名した新しい非公開サブディレクトリを使います。Flask は、サーバーがランダムに命名したファイルを排他的に作成します。受け入れられたリクエストを繰り返すと、それぞれ別の出力が保持されます。いずれも送信されたファイル名を保存パスに使わないため、写真の名前を
photo.php に変えても、その名前の PHP スクリプトは作成されません。
識別、デコード、マルウェアスキャン、公開は、それぞれ別の判断です。画像の後半が破損していてもヘッダーは識別できることがあり、Node と PHP の例はそのようなファイルも保存することがあります。Pillow の検証でさえ、完全なデコードではありません。公開配信の前に、対応する内容を完全にデコードし、リソース制限を適用し、意図した出力を生成して、スキャンポリシーに従う、隔離された処理段階を設けてください。これらの段階が完了するまでは、元ファイルを非公開に保ちます。これらのローカルハンドラーには、スキャナーも公開処理も実装されていません。
高度なファイルアップロード技術
実際の課題が中断した転送の再開やアップロード進捗の表示であれば、Web アプリケーションのファイルアップロード最適化に進んでください。クライアントとゲートウェイ間の別の契約を扱うものであり、これらのマルチパートエンドポイントにそのまま使えるクライアントではありません。セッションを使った Laravel と Vue の統合には、Laravel アップロードガイドを参照してください。
まとめと参考資料
マルチパートアップロードが失敗したら、成功する最小限のリクエストを保持し、条件をひとつだけ変えて比較してください。Flask アップロードガイド、PHP アップロードドキュメント、Active Storage ガイドでは、これらの例の基盤となる各環境固有の仕様を説明しています。
