検証と非公開ストレージを備えた Flask ファイルアップロード
Flask でファイルをアップロードするには、マルチパートフォームを送信し、リクエストを検証して、アップロードされたストリームを保存します。このチュートリアルでは、JPEG、PNG、PDF ファイルを受け付け、公開 static ディレクトリの外に保存するローカルのブラウザーフォームを作成します。保存されたバイト列を確認し、アップロードが拒否されたときの動作も確かめます。
Flask 環境のセットアップ
Bash、Python 3.14、仮想環境のサポート、libmagic をインストールした Linux を使用します。システムライブラリについては、python-magic のインストール手順を参照してください。Python パッケージだけをインストールしても、システムライブラリはインストールされません。この例では Flask 3.1.3、Flask-WTF 1.3.0、python-magic 0.4.27 を使用します。
プロジェクトを保管するディレクトリで、次のコマンドを実行します。
mkdir flask-upload-demo &&
cd flask-upload-demo &&
python3 -m venv .venv &&
.venv/bin/python -m pip install Flask==3.1.3 Flask-WTF==1.3.0 python-magic==0.4.27 &&
mkdir templates
プロジェクトがすでに存在する場合や、セットアップのいずれかの手順が失敗した場合は、コマンドが停止します。成功した場合にのみ先に進み、ターミナルの作業ディレクトリを
flask-upload-demo にしたまま、次の二つのファイルを作成します。
ファイルアップロードフォームの作成
次の内容を templates/upload.html として保存します。
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Upload a file</title>
</head>
<body>
<h1>Upload a file</h1>
<p>Choose a JPEG, PNG, or PDF. The whole request must fit within 16 MiB.</p>
{% for message in get_flashed_messages() %}
<p role="status">{{ message }}</p>
{% endfor %}
{% if error %}<p role="alert">{{ error }}</p>{% endif %}
<form method="post" enctype="multipart/form-data" novalidate>
{{ form.hidden_tag() }}
{{ form.file.label }} {{ form.file }}
{% for errors in form.errors.values() %}
{% for message in errors %}
<p role="alert">{{ message }}</p>
{% endfor %}
{% endfor %}
<button type="submit">Upload</button>
</form>
</body>
</html>
マルチパートエンコーディングでファイルのバイト列を送信します。hidden_tag() は CSRF トークンを出力し、Flask-WTF がブラウザーのセッションと照合します。novalidate により、ブラウザーが送信を止めないため、ファイル未選択時のサーバー応答を確認できます。フォームクラスは、後述の app.py に定義します。
ファイルアップロード処理の実装
次のアプリケーション全体を app.py として保存します。
import os
import tempfile
from pathlib import Path
import magic
from flask import Flask, flash, redirect, render_template, request, url_for
from flask_wtf import FlaskForm
from flask_wtf.file import FileAllowed, FileField, FileRequired
from werkzeug.exceptions import RequestEntityTooLarge
app = Flask(__name__)
app.config['SECRET_KEY'] = os.environ['FLASK_SECRET_KEY']
app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024
upload_directory = Path(app.instance_path) / 'uploads'
upload_directory.mkdir(mode=0o700, parents=True, exist_ok=True)
ALLOWED_TYPES = {
'image/jpeg': ('jpg', 'jpeg'),
'image/png': ('png',),
'application/pdf': ('pdf',),
}
class UploadForm(FlaskForm):
file = FileField('File', validators=[
FileRequired('Choose a file.'),
FileAllowed(['jpg', 'jpeg', 'png', 'pdf'], 'Choose a JPEG, PNG, or PDF.'),
])
def save_upload(file):
extension = file.filename.rsplit('.', 1)[-1].lower()
detected_type = magic.from_buffer(file.read(2048), mime=True)
file.seek(0)
extensions = ALLOWED_TYPES.get(detected_type)
if extensions is None or extension not in extensions:
raise ValueError('The file contents do not match an allowed file type and extension.')
# The client filename never becomes a storage path.
target = tempfile.NamedTemporaryFile(
dir=upload_directory, prefix='upload-', suffix='.' + extensions[0], delete=False,
)
try:
with target:
file.save(target)
except OSError:
Path(target.name).unlink(missing_ok=True)
raise
return Path(target.name).name
@app.errorhandler(RequestEntityTooLarge)
def too_large(error):
# Do not parse the rejected request again while rendering its error page.
form = UploadForm(formdata=None)
return render_template(
'upload.html', form=form,
error='Upload request is too large. Choose a smaller file.',
), 413
@app.route('/', methods=['GET', 'POST'])
def upload():
form = UploadForm()
if request.method == 'GET':
return render_template('upload.html', form=form)
if not form.validate_on_submit():
return render_template('upload.html', form=form), 400
try:
filename = save_upload(form.file.data)
except ValueError:
return render_template(
'upload.html', form=form,
error='The file contents do not match an allowed file type and extension.',
), 400
except (OSError, magic.MagicException) as error:
app.logger.error('Upload failed (%s)', type(error).__name__)
return render_template(
'upload.html', form=form,
error='The file could not be saved. Please try again.',
), 500
flash(f'Saved as {filename}.')
return redirect(url_for('upload'), code=303)
Flask-WTF のファイルバリデーターは、ファイルが選択されていることと、その拡張子が許可されていることを検証します。続いてヘルパーが、python-magic のガイダンスに従い、libmagic で先頭の 2,048 バイトを調べ、保存前にストリームを巻き戻します。巻き戻さないと、保存されるファイルから読み取り済みのバイト列が欠落します。この判定には、ブラウザーが申告する MIME タイプを使用しません。
これらの検証では、テキストファイルを .png に改名した場合など、明らかな不一致を拒否します。ただし、ファイルを完全にデコードするわけではなく、すべての破損を検出したり、内容が無害であると証明したりするものでもありません。アプリケーションに必要なセキュリティスキャンや形式固有の処理が成功するまでは、アップロードしたファイルを非公開にしてください。
NamedTemporaryFile は、受け付けたアップロードごとに新しい名前を作成し、Linux ではファイルのアクセス権を作成ユーザーのみに制限します。photo.png という名前のファイルを二つアップロードしても、別々のファイルになります。関数名とは異なり、delete=False は正常にアップロードされたファイルを、削除するまで instance/uploads に保持します。書き込みまたはクローズのエラーを捕捉した場合は、その試行で作成途中だったファイルを削除します。ただし、プロセスが強制終了された場合や、ファイルシステムが削除を拒否した場合は、ファイルが残ることがあります。
フォームの実行とアップロードの検証
同じプロジェクトディレクトリで、ローカルセッション用のシークレットを生成し、Flask を起動します。
FLASK_SECRET_KEY="$(.venv/bin/python -c 'import secrets; print(secrets.token_hex(32))')" &&
export FLASK_SECRET_KEY &&
.venv/bin/python -m flask --app app run --host 127.0.0.1 --port 5000
http://127.0.0.1:5000/ を開き、File で小さな JPEG、PNG、PDF のいずれかを選択し、Upload を押します。返されたページには、Saved as に続いて、生成されたファイル名が表示されます。POST が成功すると GET にリダイレクトされるため、結果ページを再読み込みしてもファイルは再送信されません。フォームを意図的に再送信すると、別のコピーが作成されます。
別のターミナルでプロジェクトディレクトリに移動し、元のファイルと保存されたファイルを比較します。ページに表示された生成済みの名前を使い、例の両方のパスを置き換えてください。
cmp -- '/path/to/photo.png' 'instance/uploads/upload-example.png'
出力がなく、終了ステータスがゼロであれば、バイト列は一致しています。保存されたファイルは Flask の static ディレクトリの外にあり、このアプリケーションにはダウンロードルートもありません。instance ディレクトリを、公開 Web サーバーのマッピングに含めないでください。
Ctrl+C で Flask を停止します。再起動するには、プロジェクトディレクトリから起動コマンドを再実行します。新しいシークレットが生成されるため、開いているフォームは送信前に再読み込みしてください。ポート 5000 が使用中の場合は、コマンドとブラウザーの URL で未使用のポートを指定します。この開発サーバーはループバックでのみ待ち受けます。このアプリケーションには、ログイン、ストレージ容量の割り当て、自動削除ポリシーはありません。
エラー処理と検証
ブラウザーの Network パネルで POST のステータスを確認しながら、次のケースを試してください。
| 入力または条件 | 期待される応答 | 保存結果 |
|---|---|---|
| ファイルを選択せずに送信 | 400 と Choose a file. | 新規ファイルなし |
.txt ファイルを選択 | 400 と Choose a JPEG, PNG, or PDF. | 新規ファイルなし |
プレーンテキストを .png に改名、または空の .png を送信 | 400 と内容と形式の不一致メッセージ | 新規ファイルなし |
| 16 MiB 以上のファイルを選択 | 413 と Upload request is too large. Choose a smaller file. | 新規ファイルなし |
送信前にブラウザーの開発者ツールで非表示の csrf_token 入力要素を削除 | 400 と The CSRF token is missing. | 新規ファイルなし |
| 保存先ディレクトリに書き込めない状態でアップロード | 500 と The file could not be saved. Please try again. | 作成に失敗した場合は新規ファイルなし |
リクエスト制限にはマルチパートのフィールドと境界も含まれるため、受け付けられるファイルの最大サイズは 16 MiB より少し小さくなります。Flask はマルチパートのフィールドサイズと数も制限します。アップロードのドキュメントでは、開発サーバーへのアップロードによっては、413 応答を表示する代わりに接続リセットで終了する場合があると説明されています。
CSRF エラーが発生した場合は、ページを再読み込みしてファイルを選択し直してください。複数のアプリケーションプロセスを実行する場合は、シークレットを一定に保ってください。セッションとトークンの署名が各プロセスで一致している必要があります。CSRF 保護はフォームのセッショントークンを検証するもので、アップロードするユーザーを認証するものではありません。ストレージの障害時は例外の型だけをログに記録し、ローカルパスや診断の詳細はページに表示しません。
Flask ファイルアップロード API が必要な場合
この例は HTML を返し、ブラウザーのセッション Cookie と CSRF トークンを必要とします。そのため、それらを含まない単純なマルチパートの cURL リクエストはフォーム検証に失敗します。別途 API を作成する場合は、検証と保存のロジックを再利用する前に、アップロードを許可する対象、クライアントの認証方法、クライアントが処理する JSON 応答を決めてください。Cookie 認証を使う API にも CSRF 保護は必要です。応答形式を変えても、この要件はなくなりません。
大容量ファイルのアップロード処理
後でアプリケーションを Nginx の背後に配置すると、Nginx の
client_max_body_size によって、Flask に届く前にリクエストが拒否されることがあります。プロキシとアプリケーションの制限をそろえ、両方の層でエラーを処理してください。プロキシの制限だけを引き上げても、Flask の 16 MiB 制限は変更されません。
再開可能なアップロードには、tus などのプロトコルと、それに対応するサーバーおよびクライアントを使用してください。このフォームは単一のマルチパートリクエストを送信します。ブラウザーでファイルをチャンクに分割する場合は、チャンクを追跡して結合するための別のサーバー実装が必要です。
バックグラウンド処理は、ファイルの受信後に行う別の工程です。ワーカーは保存済みのバイト列を処理できますが、このフォームでアップロードを再開可能にしたり、リクエスト制限を回避したりするものではありません。このローカルの例は、ファイルを保存した時点で終了します。後で処理が遅くなった場合は、Flask の Celery ガイドで、追加のワーカーとブローカーのセットアップを確認できます。失敗したジョブと保持するアップロードについてのポリシーも必要になります。
アップロードを公開する前に
実際のユーザーデータを蓄積する前に、instance/uploads の保持ポリシーを決めてください。一般からのアクセスを受け付けたり、ダウンロードを公開したりする前に、認証、ユーザーごとの認可と容量制限、ファイル形式に応じた内容の検証を追加してください。これらは、アップロードされたファイルを使用するアプリケーション側で決める事項です。このローカルフォームを、それらのテストに利用できます。
