SHA-256 と Node.js による効率的なファイル重複排除
ファイルの SHA-256 ダイジェストをデータベースの一意キーにすると、ファイル名が異なっていても、同じ内容の再アップロードを拒否できます。このチュートリアルでは、ローカルの Node.js サービスを構築し、cURL でファイルを送信して、再起動後も重複排除レコードが保持されることを確認します。
コンテンツベースの重複排除の仕組み
サーバーは受信した各ファイルを生成した名前で保存し、そのバイト列をストリームとして
SHA-256 に渡して、ダイジェストを SQLite に挿入します。挿入に成功するとファイルを保持します。挿入が競合すると新しいコピーを削除し、HTTP 409 Conflict を返します。
重要な判定は、単一のデータベース文 INSERT … ON CONFLICT(hash) DO NOTHING で行われます。SQLite の UPSERT の動作により、一意キーを使って同時アップロードの競合を処理できます。先にダイジェストを検索してから挿入すると、二つのリクエストがどちらも未登録と判断するおそれがあります。主キーだけで一意性を確保できるため、別途ハッシュのインデックスを作る必要はありません。
この方式で検出するのは、バイト列が同一のファイルです。ファイル名を変更してもダイジェストは変わりませんが、画像の再エンコードや埋め込みメタデータの変更では変わることがあります。見た目が似た画像は検出しません。
なぜ MD5 を使わないのか?
衝突耐性が重要な用途に MD5 は適していません。同じダイジェストを持つ異なるファイルを意図的にアップロードされる可能性がある場合も該当します。SHA-256 が提供するのは衝突耐性であり、衝突が存在しないという数学的な保証ではありません。この例では、ダイジェストが一致すれば重複と扱います。厳密な同一性の確認が必要なアプリケーションでは、一致したアップロードを破棄する前に保存済みのバイト列と受信したバイト列を比較し、衝突したファイルを別途保存する方法を用意してください。
プロジェクトのセットアップ
Linux シェル、cURL、Node.js 24 または 26 LTS 系列の最新パッチ適用済みリリースを使用してください。この例は、2026年11月7日に Node.js 24.22.2 と 26.13.0、Corepack 0.34.5、Yarn 4.12.0 でテストしました。これらの Node パッチには2026年10月のセキュリティ修正が含まれます。選択した LTS 系列には継続してパッチを適用してください。Node.js 24.15.0 と 26.8.1 での過去の実行結果は、当時の互換性確認の結果です。
プロジェクトを作成する前に、node --version、curl --version、corepack --version を確認してください。Corepack がない場合は、個別にインストールしてください。Node.js 26 には同梱されていません。Corepack は、以下で指定するバージョンの Yarn をダウンロードします。Node の組み込み TypeScript サポートは、保存した .ts ファイルをコンパイル工程なしで実行しますが、型チェックは行いません。
以下をターミナルに貼り付けてください。新しいプロジェクトを作成した後、元のディレクトリに戻ります。file-deduplication がすでに存在する場合は、別の親ディレクトリを選んでください。このコマンドは既存のディレクトリを再利用しません。
(
mkdir file-deduplication &&
cd file-deduplication &&
printf '%s\n' '{"private":true,"type":"module","packageManager":"yarn@4.12.0"}' > package.json &&
printf '%s\n' 'nodeLinker: node-modules' 'enableScripts: true' 'ignorePath: true' > .yarnrc.yml &&
touch yarn.lock &&
corepack yarn add --exact express@5.2.1 multer@2.4.0 sqlite3@5.1.7
)
インストールが成功してから次に進んでください。sqlite3 にはネイティブバインディングが含まれます。利用するプラットフォーム向けのビルド済みバイナリがない場合は、インストールガイドにビルドの前提条件が記載されています。上記のバージョンでは、テストした Linux 環境で SQLite 3.44.2 を使用します。ローカルの yarn.lock によって独立したプロジェクトになり、node-modules によって node がパッケージを直接解決できます。ignorePath は、上位プロジェクトの yarnPath が別の Yarn 実行ファイルを選択するのを防ぎます。ネイティブ SQLite バインディング用にインストールスクリプトを有効にしています。sqlite3 のリポジトリは現在アーカイブされています。そのため、これはバージョンを固定したローカルの例として扱い、新たにデプロイするサービスへ応用する前に、保守されているデータベースドライバーを選んでください。
ローカルのアップロードハンドラーの作成
ブロック全体を file-deduplication/server.ts として保存してください。このサービスは 127.0.0.1 にバインドし、認証は行いません。空のファイルを含む任意のファイルのバイト列を受け付けますが、処理も配信も行いません。ローカルでのみ使用してください。MIME フィルタリングではアップロードの安全性を確認できません。
import { createHash } from 'node:crypto'
import { createReadStream } from 'node:fs'
import { rm } from 'node:fs/promises'
import express, { type ErrorRequestHandler } from 'express'
import multer from 'multer'
import sqlite3 from 'sqlite3'
async function hashFile(filePath: string): Promise<string> {
const hash = createHash('sha256')
for await (const chunk of createReadStream(filePath)) hash.update(chunk)
return hash.digest('hex')
}
async function storeFile(
db: sqlite3.Database,
filePath: string,
name: string,
size: number,
): Promise<{ hash: string; stored: boolean }> {
let stored = false
try {
const hash = await hashFile(filePath)
const changes = await new Promise<number>((resolve, reject) => {
db.run(
`INSERT INTO files (hash, original_name, file_path, size)
VALUES (?, ?, ?, ?) ON CONFLICT(hash) DO NOTHING`,
[hash, name, filePath, size],
function (error) {
if (error) reject(error)
else resolve(this.changes)
},
)
})
stored = changes === 1
return { hash, stored }
} finally {
// Finish cleanup before the route sends a duplicate or failure response.
if (!stored) await rm(filePath, { force: true })
}
}
async function main(): Promise<void> {
const port = Number(process.env.PORT ?? '3000')
if (!Number.isInteger(port) || port < 1 || port > 65535) {
console.error('PORT must be an integer from 1 to 65535')
process.exit(1)
}
const db = await new Promise<sqlite3.Database>((resolve, reject) => {
const database = new sqlite3.Database('deduplication.db', (error) => {
if (error) reject(error)
else resolve(database)
})
})
await new Promise<void>((resolve, reject) => {
db.exec(
`CREATE TABLE IF NOT EXISTS files (
hash TEXT NOT NULL PRIMARY KEY,
original_name TEXT NOT NULL,
file_path TEXT NOT NULL,
size INTEGER NOT NULL,
upload_date TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
)`,
(error) => (error ? reject(error) : resolve()),
)
})
const app = express()
const upload = multer({
dest: 'uploads/',
limits: { fileSize: 10 * 1024 * 1024, files: 1, fields: 0 },
})
app.post('/upload', upload.single('file'), async (req, res) => {
if (!req.file) return res.status(400).json({ error: 'Send one file in the file field' })
const { path, originalname, size } = req.file
const { hash, stored } = await storeFile(db, path, originalname, size)
if (!stored) return res.status(409).json({ error: 'Duplicate file detected', hash })
return res.status(201).json({ message: 'File stored', hash, size })
})
app.get('/files', (_req, res, next) => {
db.all(
'SELECT original_name AS name, hash, size, upload_date FROM files ORDER BY hash',
(error, rows) => {
if (error) return next(error)
res.json(rows)
},
)
})
const handleError: ErrorRequestHandler = (error: unknown, _req, res, _next) => {
if (error instanceof multer.MulterError) {
const status = error.code === 'LIMIT_FILE_SIZE' ? 413 : 400
res.status(status).json({ error: 'Send one file of at most 10 MiB and no text fields' })
return
}
console.error('Request failed; check the database and upload directory')
res.status(500).json({ error: 'Could not complete the request' })
}
app.use(handleError)
await new Promise<void>((resolve, reject) => {
app.listen(port, '127.0.0.1', (error?: Error) => {
if (error) reject(error)
else resolve()
})
})
console.log(`Listening on http://127.0.0.1:${port}`)
}
main().catch((error: unknown) => {
const code = error instanceof Error && 'code' in error ? error.code : 'STARTUP_FAILED'
console.error(`Could not start server (${code}); check the port and storage permissions`)
process.exit(1)
})
Multer のディスクストレージは、クライアントのファイル名をパスに使わず、生成したファイル名を割り当てます。SQLite は最初に受け付けた名前をメタデータとして保持します。function 形式の通常のコールバックを db.run で使うのは意図的です。this.changes は、その完了した文に属し、行が挿入された場合と、競合によって何も行われなかった場合を区別します。
サーバーの起動
セットアップを実行したのと同じ親ディレクトリで、以下を貼り付けてください。
(
cd file-deduplication &&
node server.ts
)
Listening on http://127.0.0.1:3000 が表示されるまで待ってください。EADDRINUSE が発生した場合は、既存のリスナーを停止するか、PORT=3001 を node server.ts より前に設定し、以降のすべてのリクエストでそのポートを使ってください。Express 5 はバインドの失敗を起動コールバックで報告するため、そこでエラーを確認しています。データベースやディレクトリの権限エラーは、サーバーを起動する前に解消する必要があります。
アップロード、再送信、バイト列の変更
別のターミナルで、改行を含む六バイトをアップロードしてください。
printf 'hello\n' | curl -sS -i -F 'file=@-;filename=hello.txt' http://127.0.0.1:3000/upload
レスポンスのステータスは 201 Created で、JSON 本文は次のとおりです。
{"message":"File stored","hash":"5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03","size":6}
同じバイト列を別の名前でアップロードしてください。
printf 'hello\n' | curl -sS -i -F 'file=@-;filename=renamed.txt' http://127.0.0.1:3000/upload
409 Conflict が返り、error は Duplicate file detected、ハッシュは同じ値になります。最初に保存したコピーは残ります。これらのアップロードコマンドでは、想定どおりの 409 レスポンスを確認できるよう、cURL の -f オプションを意図的に省略しています。cURL が正常終了しただけでは、サーバーがファイルを受け付けたとは限りません。
次に、最初のファイル名で異なるバイト列を送信し、その後に空のファイルを送信してください。
printf 'different\n' | curl -sS -i -F 'file=@-;filename=hello.txt' http://127.0.0.1:3000/upload
curl -sS -i -F 'file=@/dev/null;filename=empty.bin' http://127.0.0.1:3000/upload
どちらも 201 を返し、サイズはそれぞれ 10 と 0 です。どちらのリクエストも、繰り返すと 409 を返します。受け付けたファイルのうち二つは元の名前が同じですが、file-deduplication/uploads/ 内には三つのファイル、データベースには三つのレコードがあります。次のコマンドでレコードを一覧表示してください。
curl -fsS http://127.0.0.1:3000/files
すべてのリクエストが完了したら、Ctrl+C でサーバーを停止し、同じコマンドで再起動して、最初のアップロードを繰り返してください。再び 409 が返ります。deduplication.db と uploads/ はどちらもプロジェクトディレクトリにあるため、一緒に保持し、そのディレクトリから再起動してください。この例は新しい内容を追加し、内容が重複する場合は最初のコピーを保持します。再起動しても、どちらの保存先も消去されません。
新しい同一内容のアップロードが同時に発生すると、一意キーによる挿入で一つのリクエストが
201 として受け付けられます。残りは余分なファイルを削除した後、409 を返します。ファイルの欠落、フィールド名の誤り、余分なファイル、テキストフィールドには
400、10 MiB を超えるファイルには 413 を返します。ストレージの障害では汎用的な 500 を返すため、再試行する前にサーバーのターミナルとファイルシステムを確認してください。
大きなファイルの効率的な処理
インクリメンタルハッシュ APIにより、hashFile はファイル全体をバッファーに保持せず、チャンク単位で読み取れます。Multer はまずアップロード全体をディスクに書き込み、ハッシュ計算時に再度読み取ります。そのため、重複検出で節約できるのは保持するストレージ容量であり、アップロードの帯域幅や一時的なディスク使用量は削減できません。
hash.update() の呼び出しは、それぞれメインスレッドで CPU を消費します。ファイルあたり 10 MiB の制限は、このローカルの例における入力サイズの上限であり、同時リクエスト数やディスク使用量の合計を制限するものではありません。より大きな負荷を扱う場合は、この上限を引き上げる前に同時実行数とストレージの制限が必要です。
パフォーマンス、ストレージ、セキュリティのヒント
SQLite の挿入はアトミックですが、ファイルの書き込みとデータベースへの挿入は単一のトランザクションではありません。その間にクラッシュすると、参照されないファイルが残ることがあります。保存済みファイルを削除したり破損したりしてもハッシュレコードは削除されないため、保存したバイト列が失われているにもかかわらず、後のアップロードが拒否される可能性があります。ストレージの権限が変わると、削除処理も失敗することがあります。この例は、こうした不整合の解消や、検索のたびに保存済みファイルを検証する処理を行わず、電源断に対する永続性も保証しません。
サービスを停止した状態で、データベースとファイルを整合性のあるペアとしてバックアップしてください。公開アップロード向けに応用する前に、認証、所有権の確認、クォータ、レコードとファイルの整合性を回復する復旧処理を追加してください。利用者全体を対象にした重複レスポンスは、他の利用者が特定の内容をアップロードしたことを漏らすおそれがあります。重複排除の対象範囲は慎重に選んでください。
