オープンソースツールで効率的な CLI ファイルアップロード
アップロードコマンドが URL を返しても、ダウンロードしたファイルが入力と一致するとは限りません。この手順では curl と一時的なローカル
transfer.sh サーバーを使い、空でないファイルを一つアップロードして、ダウンロード後にバイト単位で比較します。クラウドアカウントを使わずに、検証済みのコピーと SHA-256 チェックサムがディスク上に残ります。
主な CLI アップロードツールの比較
受信先のシステムに合わせてツールを選びます。以下の例では、curl を HTTP クライアントとして、transfer.sh をサーバーとして使います。
| ツール | 用途 | 選定前の確認事項 |
|---|---|---|
s3cmd | S3 または互換オブジェクトストレージへのアップロードと同期 | バケットと、実行する操作の権限を持つ認証情報が必要です。 |
rclone | クラウドストレージのバックエンド間でのコピーと同期 | チェックサムなどの機能はバックエンドによって異なります。 |
curl | 既存のエンドポイントへの HTTP アップロード | メソッド、認証、レスポンス形式はエンドポイントによって決まります。 |
rsync | 管理下のマシンとのファイル同期 | リモートシェル経由の転送には、両方のマシンに rsync が必要です。 |
lftp | FTP または SFTP による転送とミラーリング | 転送先が対応するプロトコルとアカウントを選びます。 |
ストレージを使うワークフローについては、署名付き PUT URL による S3 への一括エクスポートまたは DigitalOcean Spaces での rclone の使用を参照してください。これらにはプロバイダーの設定が必要です。ここでは受信サーバーを手元のマシンで実行し、アップロードとダウンロードが終わった後に削除します。
transfer.sh による手軽なファイル共有
これはローカルの Linux Docker デーモンを使い、ループバック上で行う匿名 HTTP テストです。コンテナーの実行中はそのマシンから URL にアクセスできますが、公開共有リンクではありません。機密情報を含まず、内容が変化しないテストファイルを使ってください。この例には、永続的なサーバーストレージ、認証、再開機能、速度のベンチマークはありません。
固定したリリースはゼロバイトのアップロードを拒否します。以下のスクリプトも、結果ディレクトリやコンテナーを作成する前に空のファイルを拒否します。転送処理に空のファイルが含まれる場合は、空のファイルに対応する転送先を選んでください。
コマンドは Linux x86-64 上で、Bash 5.3.15、curl 8.22.0、Docker Engine 29.7.2、GNU coreutils 9.11、GNU diffutils 3.12 を使ってテストしました。実行ファイルの検索パス上に docker、bash、curl、cmp、sha256sum
が必要です。また、ローカルの Docker デーモンにアクセスできる必要があります。リモートの Docker コンテキストを使うと、サーバーは別のマシン上に配置されます。Docker のドキュメントによると、28.0.0 より前のリリースでは、localhost に公開したポートが同じネットワークセグメント上のホストに露出する場合があります。
以下で使うイメージを、指定どおりに取得してください。
docker pull dutchcoders/transfer.sh@sha256:9383e66489ab3a7a56bec1b67d2e27d41c072102d515cdc5ab35f913b72e8a09
このダイジェストは、2023年12月4日にリリースされた
transfer.sh v1.6.1に固定しています。このイメージの公開環境へのデプロイを推奨するものではなく、再現可能なローカル演習として扱ってください。プロジェクトの Docker 手順では、更新され続ける latest タグよりも、バージョン付きのイメージが望ましい理由を説明しています。
自前の transfer.sh インスタンスの実行
作業用の一時ディレクトリに、以下を upload-check.sh として保存してください。シェルに読み込むのではなく、Bash で実行します。スクリプトは新しい結果ディレクトリを作成し、ホストのポートを自動で割り当て、自身のコンテナーが準備完了になるまで待機します。成功を報告する前に、そのコンテナーを削除します。
ローカルストレージとアップロード用の一時ファイルは、64 MiB のメモリ上のマウントを共有します。メタデータや一時ファイルのための空きを確保してください。これは小さなファイル向けの演習であり、大容量ファイル用のサービスではありません。サーバーに渡すファイル名は payload.bin に固定しているため、ローカルファイル名の空白、先頭のハイフン、URL の区切り文字が URL 構文として扱われることはありません。
#!/usr/bin/env bash
set -euo pipefail
umask 077
fail() { printf '%s\n' "$*" >&2; exit 1; }
[[ $# -eq 2 ]] || fail 'Usage: bash upload-check.sh INPUT NEW_RESULT_DIRECTORY'
input=$1
result_dir=$2
# Prefix relative paths so a literal "-" is a file, not curl's stdin selector.
[[ $input == /* || $input == ./* || $input == ../* ]] || input=./$input
[[ $result_dir == /* || $result_dir == ./* || $result_dir == ../* ]] || result_dir=./$result_dir
[[ -f $input && -r $input ]] || fail "Input is not a readable regular file: $input"
[[ -s $input ]] || fail "transfer.sh v1.6.1 rejects empty uploads: $input"
port=${UPLOAD_PORT:-0}
[[ $port =~ ^[0-9]{1,5}$ ]] || fail 'UPLOAD_PORT must be 0 or a port from 1 to 65535.'
(( 10#$port <= 65535 )) || fail 'UPLOAD_PORT exceeds 65535.'
port=$((10#$port))
name=${UPLOAD_NAME:-cli-upload-${RANDOM}-${RANDOM}-$$}
image=dutchcoders/transfer.sh@sha256:9383e66489ab3a7a56bec1b67d2e27d41c072102d515cdc5ab35f913b72e8a09
# An existing result directory is never reused or removed.
mkdir -- "$result_dir" || fail "Choose a new result directory: $result_dir"
work=$result_dir/.work
mkdir -- "$work"
verified=0
checksum=''
cleanup() {
status=$?
trap - EXIT
# A CID file identifies only the container this invocation created.
if [[ -s $work/container.id ]]; then
container_id=$(< "$work/container.id")
if ! docker rm --force "$container_id" >/dev/null; then
printf 'Cleanup failed; remove container %s when Docker is available.\n' "$container_id" >&2
status=1
fi
fi
if (( status == 0 && verified == 1 )); then
mv -- "$work/download.part" "$result_dir/download.bin" || status=1
fi
rm -rf -- "$work" || status=1
if (( status == 0 && verified == 1 )); then
printf 'Verified: %s\nSHA-256: %s\n' "$result_dir/download.bin" "$checksum"
fi
exit "$status"
}
trap cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
trap 'exit 129' HUP
docker create --cidfile "$work/container.id" --name "$name" --pull=never \
--publish "127.0.0.1:$port:8080" \
--read-only --user 5000:5000 --cap-drop ALL --security-opt no-new-privileges \
--tmpfs /tmp:rw,size=64m,mode=1777 --memory 128m --cpus 1 --pids-limit 64 \
"$image" --provider local --basedir /tmp/data --temp-path /tmp \
> "$work/create.log"
container_id=$(< "$work/container.id")
docker start "$container_id" >/dev/null
binding=$(docker port "$container_id" 8080/tcp)
[[ $binding == 127.0.0.1:* ]] || fail 'Expected a loopback port binding.'
origin=http://$binding
curl_local() {
curl --disable --noproxy '*' --globoff --fail --silent --show-error \
--connect-timeout 2 --max-time 30 "$@"
}
ready=0
for ((attempt=0; attempt<40; attempt++)); do
if [[ $(docker inspect --format '{{.State.Running}}' "$container_id") != true ]]; then
docker logs "$container_id" >&2
fail 'Server exited before readiness.'
fi
if [[ $(curl_local --max-time 1 --output /dev/null --write-out '%{http_code}' \
"$origin/health.html" 2>/dev/null) == 200 ]]; then
ready=1
break
fi
sleep 0.25
done
if (( ready == 0 )); then
docker logs "$container_id" >&2
fail 'Server did not become ready.'
fi
if ! upload_status=$(curl_local --upload-file "$input" --output "$work/url.txt" \
--write-out '%{http_code}' "$origin/payload.bin"); then
docker logs "$container_id" >&2
fail "Upload failed: $input"
fi
[[ $upload_status == 200 ]] || fail "Unexpected upload HTTP status: $upload_status"
url=$(< "$work/url.txt")
path=${url#"$origin/"}
[[ $url == "$origin/"* && $path =~ ^[A-Za-z0-9]+/payload\.bin$ ]] \
|| fail 'Server returned an unexpected download URL.'
if ! download_status=$(curl_local --output "$work/download.part" \
--write-out '%{http_code}' "$url"); then
fail 'Download failed.'
fi
[[ $download_status == 200 ]] || fail "Unexpected download HTTP status: $download_status"
cmp -- "$input" "$work/download.part" || fail "Downloaded bytes differ: $input"
checksum=$(sha256sum < "$work/download.part")
checksum=${checksum%% *}
verified=1
--upload-file は curl に HTTP PUT を送信させます。--fail は、HTTP エラー時にコマンドを失敗させます。さらに、スクリプトは各段階で HTTP 200 を要求します。--disable を curl の最初のオプションに指定し、個人用設定ファイルによるリダイレクトの追加やリクエストの変更を防ぎます。--globoff は、ローカルファイル名に含まれる角括弧や波括弧を curl が展開しないようにします。サーバーが返す URL は、Docker が割り当てたオリジンと完全に一致する必要があります。最後に、cmp がダウンロードした全バイトを検証してから、スクリプトは download.bin を保持します。
スクリプトは正常終了時、Ctrl+C、TERM または HUP シグナルの受信時にクリーンアップします。Bash だけに送られたシグナルは、実行中のコマンドが戻るまで待機する場合があります。各 curl 転送の制限時間は 30秒です。作成したコンテナーの ID を指定して削除するため、名前が衝突しても他のコンテナーを削除することはありません。SIGKILL、マシンのクラッシュ、Docker デーモンへの接続喪失により、クリーンアップできない場合があります。UPLOAD_NAME では実行を識別しやすい名前を選べます。UPLOAD_PORT では、既定の自動割り当てではなく、特定のホストポートを要求できます。どちらのオプションも、既存のコンテナーや使用中のポートを再利用可能にするものではありません。
インスタンス経由でのファイル共有
小さなバイナリのテストデータを作成し、保存したスクリプトを実行します。丸括弧内にシェルオプションを閉じ込めています。noclobber は既存の sample.bin の上書きを拒否します。そのファイル名と upload-result の両方が未使用のディレクトリを使ってください。
(
set -euo pipefail
set -o noclobber
printf '\000\377\001\200\012\015\052\000\101\102' > ./sample.bin
bash ./upload-check.sh ./sample.bin ./upload-result
)
この十バイトのデータで成功した場合の出力は次のとおりです。
Verified: ./upload-result/download.bin
SHA-256: d77823e7a78045d088fa69d1572861efee50fa35240f7555fa860d02d22633d5
upload-result/download.bin を開くか、sample.bin と比較してください。このファイルはサーバーの削除後も残ります。自分のファイルをアップロードするには、Bash の呼び出しで ./sample.bin を置き換え、新しい結果ディレクトリを選んでください。コマンドが完了するまで、入力ファイルを変更しないでください。失敗するとゼロ以外の終了ステータスを返し、一時ダウンロードを削除します。新しく作成した結果ディレクトリには、検証済みのコピーは残りません。同じ結果ディレクトリを使った再実行は、ディレクトリが空でも拒否されます。
CLI アップロードのセキュリティ対策
ループバックにより、この例へのアクセスはローカルホストに限定されます。ただし、そのホスト上の他のプロセスやユーザーは、匿名エンドポイントに引き続きアクセスできます。コンテナーに保存されたファイルはコンテナーの削除時に消えますが、元の入力ファイルと検証済みのダウンロードはディスク上に残ります。ここでの平文 HTTP は、ローカルテストのための選択です。他のマシンからアクセスできるサービスでは、実データを送る前に、認証付き HTTPS とデータ保持ポリシーを選んでください。推測困難な URL でも、ダウンロードする人を認証することにはなりません。
よくある問題のトラブルシューティング
| 症状 | 確認事項 |
|---|---|
| Docker がコンテナーを作成または起動できない | 固定したイメージを取得済みで、ローカルデーモンにアクセスできることを確認してください。UPLOAD_PORT が使用中、または UPLOAD_NAME が既存の場合、起動に失敗します。別の値を選んでください。 |
| サーバーが終了する、または準備完了にならない | クリーンアップ前に表示されるコンテナーの診断情報を読んでください。スクリプトは、自身のサーバーがヘルスチェックに合格するまでアップロードしません。 |
| アップロードまたはダウンロードが失敗する | curl のエラーと処理段階のメッセージを読んでください。サーバーの 64 MiB の一時マウントが満杯になる場合があるため、より小さなファイルを試してください。転送は 30秒でタイムアウトします。 |
| ダウンロードしたバイトが一致しない | 転送中に入力が変更されなかったか確認してください。HTTP リクエストの成功だけでは不十分です。スクリプトはこのダウンロードを破棄します。 |
| 結果ディレクトリがすでに存在する | 新しいディレクトリを選んでください。スクリプトは以前の結果を置き換えずに保持します。 |
| クラウドの処理で帯域制限が必要 | --limit-rate を s3cmd と使うか、--bwlimit を rclone と使ってください。これらのフラグはそれぞれ別のツール用です。 |
この検証を自動化する場合は、終了ステータスで判定し、実行ごとに新しい結果ディレクトリを指定してください。定期実行を設定しても、一時コンテナーが永続的なバックアップや公開ファイルサービスになるわけではありません。
ブラウザーからのアップロードへの展開
ブラウザーのアップロード画面には、Uppy がファイル選択と進捗表示を提供します。tus プロトコルは、サーバーが対応している場合に、再開可能な HTTP アップロードを扱います。これらはクライアント側とサーバー側の別々の選択肢です。この transfer.sh の PUT の例は tus を実装していません。ローカルでアップロードとダウンロードを行って CLI ワークフローを検証し、その後、アプリケーションのストレージ要件とアクセス要件に合わせて受信サービスを選んでください。
