Sharp と Redis によるローカル画像オリジンの構築
同じ画像 URL からリサイズ済みの JPEG または WebP を配信し、キャッシュ内で両者のバイト列が混ざらないようにします。このガイドではローカル画像オリジンを構築し、透明部分を持つサンプルを生成して、コールド時とウォーム時のレスポンスを確認します。オリジンは独自の画像 CDN を構成する要素の一つです。世界各地のエッジからの配信には別途 CDN が必要です。
前提条件
保守が継続されている Node.js 24 LTS の 24.15.0 以降、Yarn 4 対応の Corepack、Docker、cURL を使用します。この例では Express 5.2.1、Sharp 0.35.4、Redis クライアント 6.2.1、Redis 8.10.2 を使用します。Node の TypeScript ネイティブサポートにより、コンパイラーや tsx なしで .mts ファイルを直接実行します。
公開するソースは、レビュー済みで変更不可の単一フレームの JPEG または PNG のみにしてください。このオリジンにはアップロード用や認証用のルートがなく、一覧にあるすべての画像と派生画像が公開されます。以下のバイト数とピクセル数の制限は、受け入れる処理量を減らすものであり、Sharp のネイティブデコーダーをサンドボックス化するものではありません。
プロジェクトのセットアップ
新しい空の image-origin ディレクトリを作成し、そこでターミナルを開きます。次の内容を package.json として保存します。
{
"name": "image-origin",
"private": true,
"type": "module",
"packageManager": "yarn@4.12.0",
"scripts": { "fixture": "node create-fixture.mts", "start": "node server.mts" },
"dependencies": { "express": "5.2.1", "redis": "6.2.1", "sharp": "0.35.4" },
"devDependencies": { "@types/express": "5.0.6" }
}
.yarnrc.yml も保存します。ローカルの node_modules を選択し、親階層のプロジェクトにある Yarn 実行ファイルが使われるのを防ぎます。
nodeLinker: node-modules
enableGlobalCache: false
ignorePath: true
インストール前に、このプロジェクトをロックファイルの境界として設定します。以下のコマンドはすべてこのディレクトリから実行してください。
touch yarn.lock && corepack yarn install
生成された yarn.lock は保持してください。再インストール時には corepack yarn install --immutable を使用できます。create-fixture.mts を保存し、左半分が不透明な赤、右半分が透明な
640 × 400 のサンプルを生成します。既存のソースファイルの置き換えは拒否されます。
import { mkdir, writeFile } from 'node:fs/promises'
import sharp from 'sharp'
const width = 640
const height = 400
const pixels = Buffer.alloc(width * height * 4)
for (let y = 0; y < height; y += 1) {
for (let x = 0; x < width / 2; x += 1) {
const offset = (y * width + x) * 4
pixels[offset] = 255
pixels[offset + 3] = 255
}
}
const png = await sharp(pixels, { raw: { width, height, channels: 4 } }).png().toBuffer()
await mkdir('images', { recursive: true })
await writeFile('images/photo-v1.png', png, { flag: 'wx' })
サンプルを生成してから、ループバックにバインドした使い捨ての Redis キャッシュを起動します。ポート 6379 が使用中の場合は別のホスト側ポートを選び、オリジンの起動時に
REDIS_URL でその URL を指定してください。
corepack yarn fixture &&
docker run --detach --rm --name image-origin-redis \
-p 127.0.0.1:6379:6379 redis:8.10.2 \
redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru --save '' --appendonly no
このキャッシュは使い捨てです。この設定では Redis のスナップショットも追記専用ファイルも書き込みません。オリジナルは images/ に残ります。Redis の削除ポリシーにより、必要に応じてキャッシュのエントリーが削除されます。キャッシュミス時には再生成できます。
最小限の画像オプティマイザーの構築
optimizer.mts を保存します。呼び出し元は URL やユーザーが選んだパスではなく、公開マップ内のファイル名を渡します。受け入れるソースファイルは最大 8 MiB、入力画像は最大 12 メガピクセルです。リクエスト処理中も、このディレクトリは公開者の管理下に置く必要があります。
import { open, realpath } from 'node:fs/promises'
import { resolve, sep } from 'node:path'
import sharp from 'sharp'
export type Format = 'jpeg' | 'webp'
const MAX_BYTES = 8 * 1024 * 1024
const MAX_PIXELS = 12_000_000
sharp.concurrency(1)
sharp.cache(false)
export async function optimize(filename: string, size: number, format: Format): Promise<Buffer> {
const root = await realpath(resolve('images'))
const path = await realpath(resolve(root, filename))
if (!path.startsWith(root + sep)) throw new Error('Source is outside the publishing directory.')
const handle = await open(path, 'r')
let data: Buffer
try {
const stat = await handle.stat()
if (!stat.isFile() || stat.size === 0 || stat.size > MAX_BYTES) {
throw new Error('Source size is unsupported.')
}
data = Buffer.alloc(MAX_BYTES + 1)
let length = 0
while (length < data.length) {
const { bytesRead } = await handle.read(data, length, data.length - length, null)
if (bytesRead === 0) break
length += bytesRead
}
if (length === 0 || length > MAX_BYTES) throw new Error('Source size is unsupported.')
data = data.subarray(0, length)
} finally {
await handle.close()
}
const pipeline = sharp(data, { limitInputPixels: MAX_PIXELS, failOn: 'warning' })
const metadata = await pipeline.metadata()
if (!metadata.format || !['jpeg', 'png'].includes(metadata.format) ||
(metadata.pages ?? 1) !== 1) {
throw new Error('Only single-frame JPEG and PNG sources are supported.')
}
pipeline.rotate().resize({ width: size, height: size, fit: 'inside', withoutEnlargement: true })
return format === 'jpeg'
? pipeline.flatten({ background: 'white' }).jpeg({ quality: 80 }).toBuffer()
: pipeline.webp({ quality: 80 }).toBuffer()
}
画像はアスペクト比を維持し、拡大せずに、指定した正方形の内側に収めます。JPEG では透明部分を白背景に合成し、WebP では透明度を保持します。Sharp のデフォルトの出力ポリシーでは、sRGB に変換してソースのメタデータを削除します。回転処理では、メタデータを削除する前に EXIF の向きを適用します。デコードの成功はオリジナルの完全性の検証にはなりません。公開前にソースのピクセルを確認してください。
ネゴシエーションしたバリアントの配信とキャッシュ
server.mts を保存します。f を省略すると、Accept を使って形式をネゴシエーションします。または、f=jpeg か f=webp を明示的に指定します。幅の w には 320、640、1,280 を指定でき、デフォルトは 640 です。それ以外のパラメーターや重複したパラメーターは拒否されます。
import type { Response } from 'express'
import express from 'express'
import { createClient } from 'redis'
import { type Format, optimize } from './optimizer.mts'
const published = new Map([['photo-v1.png', 'photo-v1.png']])
const sizes = new Set(['320', '640', '1280'])
const types = { webp: 'image/webp', jpeg: 'image/jpeg' }
const CACHE_SECONDS = 3600
const app = express()
app.disable('x-powered-by')
const redis = createClient({
url: process.env.REDIS_URL ?? 'redis://127.0.0.1:6379',
disableOfflineQueue: true,
socket: { connectTimeout: 2000, reconnectStrategy: false },
})
redis.on('error', () => console.error('Image cache connection failed.'))
let active = 0
async function cacheCommand<T>(command: () => Promise<T>): Promise<T> {
// Closing the connection also rejects commands already sent to a stalled Redis server.
const timer = setTimeout(() => {
if (redis.isOpen) redis.destroy()
}, 2000)
try {
return await command()
} finally {
clearTimeout(timer)
}
}
function fail(res: Response, status: number, message: string): Response {
return res.status(status).set('Cache-Control', 'no-store').type('text').send(message)
}
function sendImage(res: Response, format: Format, bytes: Buffer): Response {
return res.type(types[format]).set('Cache-Control', `public, max-age=${CACHE_SECONDS}`)
.set('X-Content-Type-Options', 'nosniff').send(bytes)
}
app.get('/images/:name', async (req, res) => {
const filename = published.get(req.params.name)
if (!filename) return fail(res, 404, 'Image not found.')
const params = new URL(req.originalUrl, 'http://localhost').searchParams
if ([...params.keys()].some((key) => key !== 'w' && key !== 'f') ||
params.getAll('w').length > 1 || params.getAll('f').length > 1) {
return fail(res, 400, 'Unsupported image parameters.')
}
const size = params.get('w') ?? '640'
const requested = params.get('f')
const accepted = requested === null ? req.accepts(['image/webp', 'image/jpeg']) : null
const format = requested ?? (accepted === 'image/webp' ? 'webp' : 'jpeg')
if (requested === null && !accepted) return fail(res, 406, 'No supported image format.')
if (!sizes.has(size) || (format !== 'jpeg' && format !== 'webp')) {
return fail(res, 400, 'Unsupported image variant.')
}
if (requested === null) res.vary('Accept')
const key = JSON.stringify(['image-v1', filename, size, format])
if (active >= 2) return fail(res, 503, 'Image processor is busy.')
active += 1
try {
const cached = await cacheCommand(() => redis.get(key))
if (cached !== null) return sendImage(res, format, Buffer.from(cached, 'base64'))
const bytes = await optimize(filename, Number(size), format)
await cacheCommand(() => redis.set(key, bytes.toString('base64'), { EX: CACHE_SECONDS }))
return sendImage(res, format, bytes)
} catch {
console.error('Image request failed.')
return fail(res, 503, 'Image is temporarily unavailable.')
} finally {
active -= 1
}
})
app.use((_req, res) => fail(res, 404, 'Route not found.'))
app.use((_error: unknown, _req: express.Request, res: Response, _next: express.NextFunction) =>
fail(res, 400, 'Request could not be processed.'))
async function main(): Promise<void> {
const port = Number(process.env.PORT ?? '3000')
if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Invalid PORT.')
await redis.connect()
const server = app.listen(port, '127.0.0.1')
server.requestTimeout = 10_000
server.headersTimeout = 10_000
server.on('listening', () => console.log(`Image origin: http://127.0.0.1:${port}`))
server.on('error', () => {
console.error('Image server could not start.')
if (redis.isOpen) redis.destroy()
process.exitCode = 1
})
let stopping = false
const stop = () => {
if (stopping) return
stopping = true
const deadline = setTimeout(() => {
server.closeAllConnections()
if (redis.isOpen) redis.destroy()
process.exit(1)
}, 15_000)
deadline.unref()
server.close(() => {
if (redis.isOpen) redis.destroy()
clearTimeout(deadline)
})
}
process.once('SIGTERM', stop)
process.once('SIGINT', stop)
}
main().catch(() => {
console.error('Image origin startup failed.')
if (redis.isOpen) redis.destroy()
process.exitCode = 1
})
このターミナルでオリジンを起動します。
corepack yarn start
Image origin: http://127.0.0.1:3000 が表示されるまで待ちます。ポートが使用中、または Redis が利用できない場合、起動は失敗します。PORT=3002 corepack yarn start で別のオリジン用ポートを選び、以下の URL を調整してください。Redis は非公開で信頼できる状態に保ってください。キャッシュ内のバイト列は画像として再検証されません。
コールド時とウォーム時のバリアントの確認
プロジェクトディレクトリで別のターミナルを開き、同じ URL に四回リクエストします。これらのコマンドは、指定された四つの出力ファイルを上書きします。以前の結果を残す場合は、新しいディレクトリを使用してください。
curl -fsSLo photo.webp -D webp.headers -H 'Accept: image/webp' 'http://127.0.0.1:3000/images/photo-v1.png?w=320' &&
curl -fsSLo photo.jpg -D jpeg.headers -H 'Accept: image/jpeg' 'http://127.0.0.1:3000/images/photo-v1.png?w=320' &&
curl -fsSLo cached.webp -H 'Accept: image/webp' 'http://127.0.0.1:3000/images/photo-v1.png?w=320' &&
curl -fsSLo cached.jpg -H 'Accept: image/jpeg' 'http://127.0.0.1:3000/images/photo-v1.png?w=320'
両方のヘッダーファイルに Vary: Accept、Cache-Control: public, max-age=3600、および対応する Content-Type が含まれているはずです。Vary は、レスポンスが
Accept にも依存することを HTTP キャッシュに伝えます。Redis のキーがバリアントを区別するようになるわけではありません。キーにも解決後の形式を含める必要があります。
check-results.mts を保存し、ファイルをデコードして実際の形式と寸法を確認し、コールド時とウォーム時のバイト列を比較します。
import assert from 'node:assert/strict'
import { readFile } from 'node:fs/promises'
import sharp from 'sharp'
for (const [cold, warm, format] of [
['photo.webp', 'cached.webp', 'webp'],
['photo.jpg', 'cached.jpg', 'jpeg'],
]) {
const bytes = await readFile(cold)
assert.deepEqual(await readFile(warm), bytes)
const decoder = sharp(bytes)
const metadata = await decoder.metadata()
assert.equal(metadata.format, format)
assert.equal(metadata.width, 320)
assert.equal(metadata.height, 200)
const { data, info } = await decoder.ensureAlpha().raw().toBuffer({ resolveWithObject: true })
const left = (100 * info.width + 80) * info.channels
assert.ok(data[left] > 245 && data[left + 1] < 15 && data[left + 2] < 15)
assert.equal(data[left + 3], 255)
const right = (100 * info.width + 240) * info.channels
assert.equal(data[right + 3], format === 'webp' ? 0 : 255)
if (format === 'jpeg') assert.ok(data[right] > 245 && data[right + 1] > 245 && data[right + 2] > 245)
console.log(`${cold}: ${format}, 320 × 200, warm bytes match`)
}
node check-results.mts
コールド時の両方のファイルをブラウザーでも開いてください。左半分は赤く、右半分は WebP では透明、JPEG では白くなるはずです。コールド時とウォーム時のバイト列が等しいだけでは、キャッシュヒットの証明にはなりません。オリジンが動作している間に、Redis の二つのキーを調べます。
docker exec image-origin-redis redis-cli --scan --pattern '[[]"image-v1"*'
キーは ["image-v1","photo-v1.png","320","webp"] と
["image-v1","photo-v1.png","320","jpeg"] になっているはずです。各値には対応する画像が Base64 で格納され、有効期限は一時間です。新しい幅を指定すると別のバリアントが作成されます。w=1280 をリクエストしても、オプティマイザーはサンプルを拡大しないため、出力は 640 × 400 のままです。
変更したソースの公開
レビュー済みの photo-v2.png ファイルと、公開マップの新しい
['photo-v2.png', 'photo-v2.png'] エントリーを追加します。画像を利用するページでは /images/photo-v2.png?w=320 を使用してください。古いファイルとルートは変更しないでください。photo-v1.png を上書きしたり、既存の URL の参照先を変えたりしても、以前ブラウザーにキャッシュされたレスポンスは期限が切れるまで有効です。Redis キーに含まれるソースファイル名により、オリジンでバージョンを分離します。
出力設定を変更する際は、エンコーダーポリシーのプレフィックス image-v1 を更新します。これにより Redis キーは置き換わりますが、既存の HTTP キャッシュには新しい URL または意図的な無効化が依然必要です。オブジェクトストレージからは、公開処理を介して承認済みファイルを提供できます。任意のリモート URL からの取得は、この構成の対象外です。
ローカルオリジンの停止と復旧
オリジンのターミナルで Ctrl+C を押すと、新しい接続の受け入れを停止し、処理中のリクエストの完了を待ちます。15 秒後にはプロセスが接続を強制的に閉じ、失敗として終了します。変換処理が直ちにキャンセルされるわけではありません。続いてキャッシュを停止します。
docker stop image-origin-redis
Redis が利用できなくなるか、コマンドが二秒間停滞すると、オリジンはキャッシュなしで処理を続けるのではなく、キャッシュされない 503 を返します。期限に達すると共有 Redis 接続を閉じ、保留中のコマンドを拒否します。自動再接続とオフラインキューは無効です。Redis を再起動した後、このオリジンも再起動してください。セットアップ時の docker run コマンドだけを再実行し、続いて corepack yarn start を実行します。ソース生成処理は再実行しないでください。同時リクエスト数の上限である二件にはキャッシュアクセスも含まれ、各ハンドラーが終了するまで枠を占有します。そのため、上限を超える同時リクエストには 503 が返されます。これはプロセスごとの受け入れ制限であり、メモリーや CPU の総使用量を保証するものではありません。
オリジンと配信基盤の接続
Redis は、このオリジンで変換済みレスポンスを再利用します。利用者の近くにコピーを配置したり、公開 TLS を終端したり、性能向上を実証したりするものではありません。変換を行うオリジンの前段に置く CDN は、幅と明示的な形式をキーに含めるか、ネゴシエーションしたレスポンスの Vary: Accept を正しく尊重する必要があります。エラーはエッジキャッシュの対象から除外してください。オリジンのプロセスを増やすと、受け入れ上限の合計もその分増えます。
当社の S3 と CloudFront のガイドでは、ストレージを基盤とする別の配信構成を扱っています。この Express サーバーのデプロイ手順ではありません。マネージドの処理と配信については、Transloadit の画像処理と Smart CDNをご覧ください。
