Go と Libvips による高速な画像処理サーバーの構築
Go で小規模な HTTP API を公開し、libvips でネイティブの画像処理を実行できます。ここでは govips を使い、共通のリクエストハンドラーで画像のリサイズ、切り抜き、透かし追加、形式変換を行います。
これは制限を設けたループバック接続用のデモであり、認証付きの公開アップロードサービスではありません。リクエストや画像サイズを検証していても、ネイティブの画像処理には分離と運用上の制限が必要です。
なぜ Libvips を使うのか?
Libvips は画像パイプラインをオンデマンドで評価し、中間処理を削減できます。実際の速度とメモリ使用量は、処理内容、コーデック、画像サイズ、同時実行数によって異なります。常に高速化するとは考えず、実際のワークロードでベンチマークを実施してください。
Go 環境のセットアップ
前提条件
保守が継続されている Go リリース、C コンパイラー、pkg-config、libvips を使用してください。この例は Linux 上で Go 1.26.8、govips v2.18.0、libvips 8.14.1 と 8.18.6 を使ってテストしています。固定バージョンのモジュールは Go 1.25.0 を最小要件として宣言しています。この最小要件と、ここでテストしたバージョンは別のものです。
インストール
Ubuntu 24.04 では、ネイティブの開発用ライブラリをインストールします。
sudo apt-get install --no-install-recommends build-essential pkg-config libvips-dev
Go は Go インストールガイドに従って別途インストールしてください。
macOS では、brew install vips pkg-config でネイティブライブラリをインストールします。コンパイラー固有の設定は、govips のプラットフォーム別手順に従ってください。
Bash で新しいプロジェクトを作成し、依存関係のインストールが成功した場合にのみ、そのディレクトリに移動します。モジュールファイルは両方とも保持してください。インストールに失敗した場合は、再試行する前に、途中まで作成されたディレクトリを確認してください。
mkdir image-api &&
(
cd image-api &&
go mod init example.com/image-api &&
go get github.com/davidbyttow/govips/v2/vips@v2.18.0
) &&
cd image-api
基本的な画像処理サーバーの構築
プログラム全体を main.go に保存してください。JPEG と PNG を入力として受け付け、静止画像を出力します。形式と処理パラメーターは明示的に指定します。画像と任意の透かし画像には、同じサイズ検証とデコーダー検証を適用します。
package main
import (
"bytes"
"context"
"errors"
"image"
_ "image/jpeg"
_ "image/png"
"io"
"log"
"mime/multipart"
"net"
"net/http"
"net/url"
"os"
"os/signal"
"strconv"
"syscall"
"time"
"github.com/davidbyttow/govips/v2/vips"
)
const maxBytes = 8 << 20
const maxPixels = 4_000_000
var slots = make(chan struct{}, 2)
var invalid = errors.New("unsupported image request")
func number(values url.Values, key string, fallback, minimum, maximum int) (int, error) {
text := values.Get(key)
if text == "" {
if _, present := values[key]; present { return 0, invalid }
return fallback, nil
}
if len(text) > 4 { return 0, invalid }
for _, character := range text {
if character < '0' || character > '9' { return 0, invalid }
}
value, err := strconv.Atoi(text)
if err != nil || value < minimum || value > maximum { return 0, invalid }
return value, nil
}
func loadImage(header *multipart.FileHeader) (*vips.ImageRef, error) {
file, err := header.Open()
if err != nil { return nil, err }
defer file.Close()
data, err := io.ReadAll(io.LimitReader(file, maxBytes+1))
if err != nil || len(data) == 0 || len(data) > maxBytes { return nil, invalid }
config, format, err := image.DecodeConfig(bytes.NewReader(data))
if err != nil || (format != "jpeg" && format != "png") ||
config.Width < 1 || config.Height < 1 ||
config.Width > 4096 || config.Height > 4096 ||
config.Width > maxPixels/config.Height {
return nil, invalid
}
source, err := vips.NewImageFromBuffer(data)
if err != nil { return nil, err }
if source.Pages() > 1 {
source.Close()
return nil, invalid
}
if err := source.AutoRotate(); err != nil {
source.Close()
return nil, err
}
// Normalize 16-bit PNG samples before compositing or using an 8-bit white background.
if err := source.ToColorSpace(vips.InterpretationSRGB); err != nil {
source.Close()
return nil, err
}
return source, nil
}
func transform(source *vips.ImageRef, operation string, values url.Values,
form *multipart.Form) error {
switch operation {
case "resize", "crop":
width, err := number(values, "width", 256, 1, 2048)
if err != nil { return err }
height, err := number(values, "height", 256, 1, 2048)
if err != nil { return err }
if operation == "resize" {
// govips expects scale factors, not output pixel dimensions.
return source.ResizeWithVScale(float64(width)/float64(source.Width()),
float64(height)/float64(source.Height()), vips.KernelLanczos3)
}
left, err := number(values, "left", 0, 0, 4096)
if err != nil { return err }
top, err := number(values, "top", 0, 0, 4096)
if err != nil { return err }
if width > source.Width() || height > source.Height() ||
left > source.Width()-width || top > source.Height()-height {
return invalid
}
return source.ExtractArea(left, top, width, height)
case "watermark":
overlay, err := loadImage(form.File["watermark"][0])
if err != nil { return err }
defer overlay.Close()
if overlay.Width() > source.Width() || overlay.Height() > source.Height() {
return invalid
}
return source.Composite(overlay, vips.BlendModeOver,
source.Width()-overlay.Width(), source.Height()-overlay.Height())
case "convert":
return nil
}
return invalid
}
func encode(source *vips.ImageRef, format string) ([]byte, error) {
// Older libvips exporters can retain EXIF despite the strip option.
if err := source.RemoveMetadata(); err != nil { return nil, err }
var output []byte
var err error
switch format {
case "jpeg":
if source.HasAlpha() {
if err := source.Flatten(&vips.Color{R: 255, G: 255, B: 255}); err != nil {
return nil, err
}
}
params := vips.NewJpegExportParams()
params.StripMetadata = true
output, _, err = source.ExportJpeg(params)
case "png":
params := vips.NewPngExportParams()
params.StripMetadata = true
output, _, err = source.ExportPng(params)
case "webp":
params := vips.NewWebpExportParams()
params.StripMetadata = true
output, _, err = source.ExportWebp(params)
default:
return nil, invalid
}
return output, err
}
func processImage(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Cache-Control", "no-store")
w.Header().Set("X-Content-Type-Options", "nosniff")
select {
case slots <- struct{}{}:
defer func() { <-slots }()
default:
http.Error(w, "Image processor is busy.", http.StatusServiceUnavailable)
return
}
values, err := url.ParseQuery(r.URL.RawQuery)
if err != nil {
http.Error(w, "Invalid parameters.", http.StatusBadRequest)
return
}
operation := values.Get("operation")
allowed := map[string]bool{"operation": true, "format": true}
switch operation {
case "resize", "crop":
allowed["width"], allowed["height"] = true, true
if operation == "crop" { allowed["left"], allowed["top"] = true, true }
case "convert", "watermark":
default:
http.Error(w, "Unsupported operation.", http.StatusBadRequest)
return
}
for key, entries := range values {
if !allowed[key] || len(entries) != 1 {
http.Error(w, "Invalid parameters.", http.StatusBadRequest)
return
}
}
format := values.Get("format")
if _, present := values["format"]; !present { format = "png" }
if format != "png" && format != "jpeg" && format != "webp" {
http.Error(w, "Unsupported format.", http.StatusBadRequest)
return
}
r.Body = http.MaxBytesReader(w, r.Body, maxBytes+64*1024)
err = r.ParseMultipartForm(1 << 20)
if r.MultipartForm != nil { defer r.MultipartForm.RemoveAll() }
// Multipart parsing stops at its final boundary; count any remaining request bytes too.
if err == nil { _, err = io.Copy(io.Discard, r.Body) }
if err != nil {
code := http.StatusBadRequest
var tooLarge *http.MaxBytesError
if errors.As(err, &tooLarge) { code = http.StatusRequestEntityTooLarge }
http.Error(w, "Invalid or oversized upload.", code)
return
}
form := r.MultipartForm
expected := 1
if operation == "watermark" { expected = 2 }
if len(form.Value) != 0 || len(form.File) != expected || len(form.File["file"]) != 1 ||
(operation == "watermark" && len(form.File["watermark"]) != 1) {
http.Error(w, "Provide the required image files.", http.StatusBadRequest)
return
}
source, err := loadImage(form.File["file"][0])
if err != nil {
http.Error(w, "Unsupported image.", http.StatusBadRequest)
return
}
defer source.Close()
if err := transform(source, operation, values, form); err != nil {
http.Error(w, "Image operation could not be completed.", http.StatusBadRequest)
return
}
output, err := encode(source, format)
if err != nil {
http.Error(w, "Image encoding failed.", http.StatusUnprocessableEntity)
return
}
w.Header().Set("Content-Type", "image/"+format)
w.Write(output)
}
func run() error {
if err := vips.Startup(&vips.Config{ConcurrencyLevel: 1, MaxCacheSize: 0}); err != nil {
return err
}
defer vips.Shutdown()
address := os.Getenv("LISTEN_ADDR")
if address == "" { address = "127.0.0.1:8080" }
listener, err := net.Listen("tcp", address)
if err != nil { return err }
mux := http.NewServeMux()
mux.HandleFunc("POST /process", processImage)
server := &http.Server{Handler: mux, ReadHeaderTimeout: 5*time.Second,
ReadTimeout: 15*time.Second, WriteTimeout: 30*time.Second, IdleTimeout: 30*time.Second}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
served := make(chan error, 1)
go func() { served <- server.Serve(listener) }()
select {
case err := <-served:
if errors.Is(err, http.ErrServerClosed) { return nil }
return err
case <-ctx.Done():
deadline, cancel := context.WithTimeout(context.Background(), 35*time.Second)
defer cancel()
if err := server.Shutdown(deadline); err != nil {
// Never shut libvips down while a native handler is still running.
log.Print("Image server shutdown deadline exceeded.")
os.Exit(1)
}
return nil
}
}
func main() {
if err := run(); err != nil {
log.Printf("Image server failed: %v", err)
os.Exit(1)
}
}
go run . を image-api から実行し、そのターミナルは開いたままにしてください。デフォルトのアドレスは
127.0.0.1:8080 です。ポートが使用中の場合は、LISTEN_ADDR を設定して別のアドレスを使用してください。各ファイルの上限は 8 MiB、各辺 4,096 ピクセル、総画素数は四百万ピクセルです。両方のファイルとマルチパートのオーバーヘッドを合わせて、リクエストの上限である
8 MiB + 64 KiB に収める必要があります。マルチパート終端の後に続くバイトも含まれます。マルチパートデータは一時ディスクに書き出されることがあります。遅延実行される RemoveAll() は、リクエストの成功時と失敗時のどちらもそのデータを削除します。プロセスが突然終了すると、一時ファイルが残る場合があります。
一般的な画像処理の実装
別のターミナルで、自分で用意した photo.jpg、photo.png、logo.png があるディレクトリを使用します。切り抜きの例では、向きの補正後に少なくとも 110 × 90 ピクセルある写真が必要です。出力は静止画像です。この API はアニメーションを保持するワークフローではありません。これらの cURL コマンドは、指定された名前の出力ファイルを上書きします。--fail-with-body を使うと、HTTP エラー時に出力がエラーテキストに置き換わる場合があります。画像として開く前に終了ステータスを確認してください。ローカルの入力ファイルが見つからない場合は、既存の出力が置き換わる前に失敗することがあります。
curl --fail-with-body -F 'file=@photo.jpg' \
'http://127.0.0.1:8080/process?operation=resize&width=320&height=180' -o resized.png
リサイズでは、指定したサイズに合わせて画像を引き伸ばします。幅と高さは水平方向と垂直方向の拡大縮小率に変換します。ピクセル数をそのまま ResizeWithVScale に渡すと、非常に大きな画像が生成されます。
画像の切り抜き
切り抜き座標は、EXIF の向き補正後の画像に適用します。
curl --fail-with-body -F 'file=@photo.jpg' \
'http://127.0.0.1:8080/process?operation=crop&left=10&top=10&width=100&height=80' -o crop.png
切り抜き領域は、入力画像の内側に完全に収まる必要があります。減算による検証で、信頼できないオフセットとサイズの加算によるオーバーフローを防ぎます。
透かしの追加
ベース画像より小さい JPEG または透過 PNG を指定します。右下に配置されます。
curl --fail-with-body -F 'file=@photo.jpg' -F 'watermark=@logo.png' \
'http://127.0.0.1:8080/process?operation=watermark' -o watermarked.png
画像形式の変換
JPEG 出力では、透過部分を白い背景に合成します。PNG と WebP では透過を保持できます。ローダーは処理前に、16 ビット PNG のサンプル値を 8 ビット sRGB に変換します。白い背景の値 255 は、画像と同じ範囲で指定する必要があります。libvips の色変換とアルファのフラット化のドキュメントを参照してください。JPEG と WebP のエクスポートは、デフォルトで非可逆圧縮を使用します。これは可逆圧縮によるアーカイブ保存用のワークフローではありません。
curl --fail-with-body -F 'file=@photo.png' \
'http://127.0.0.1:8080/process?operation=convert&format=jpeg' -o converted.jpg
パフォーマンスとメモリ使用量の最適化
Libvips 設定の調整
この例では、処理ごとに一つのネイティブスレッドを割り当て、処理キャッシュを無効にしています。実測値に基づいてこれらの設定を調整してください。リサイズと切り抜きでは、出力の各辺を最大 2,048 ピクセルまで指定できます。そのため、リサイズでは 2,048 × 2,048 ピクセルの画像を生成でき、入力の上限である四百万ピクセルをわずかに上回ります。形式変換と透かし追加ではベース画像のサイズを保持するため、片辺が 2,048 を超える場合があります。これらの検証と同時リクエスト数を二つに制限する仕組みだけでは、すべてのネイティブメモリ割り当てやエンコード後の出力サイズを制限できません。
ワーカープールの実装
容量制限付きチャネルはセマフォであり、無制限のジョブキューではありません。同時に届いた三つ目のリクエストには、直ちに 503 を返します。これにより、画像読み込みとエクスポート用の関数を別途用意せずに、バックプレッシャーを明示できます。大規模なデプロイでは、フリート全体の制限と、適切に分離されたワーカーが必要です。
リソース使用量の監視
Go ヒープの使用量だけでなく、プロセスの RSS も測定してください。libvips によるネイティブメモリ割り当ては Go ヒープの外部で行われます。一時ディスク使用量、拒否されたリクエスト、デコーダーの失敗、レイテンシも測定します。HTTP の期限に達しても、ネイティブ処理はキャンセルされません。CPU とメモリの厳格な上限を適用するには、プロセスを分離してください。
不正なヘッダーやデコーダーの失敗はエラーになりますが、デコードの成功は完全性の検証ではありません。不慣れなファイルを受け付ける場合は、端の部分も含めて出力全体を確認してください。古い libvips エクスポーターでは、strip オプションだけでは入力の EXIF が残る場合があるため、このプログラムではエクスポート前に削除します。govips は一部の技術的なメタデータを内部で保持します。これにはカラープロファイルも含まれます。この例は、プライバシー情報を網羅的に除去するツールでも、任意の埋め込みカラープロファイルを正確に再現するワークフローでもありません。
Docker でのデプロイ
ビルド用と実行時用のライブラリには、同じ Debian リリースを使用してください。これを Dockerfile として
image-api 内に保存します。go.mod、go.sum、main.go と同じ場所に置いてください。
FROM golang:1.26-bookworm AS build
RUN apt-get update && apt-get install -y --no-install-recommends libvips-dev \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY main.go ./
RUN CGO_ENABLED=1 go build -o /image-api .
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends libvips42 ca-certificates \
&& rm -rf /var/lib/apt/lists/*
COPY --from=build /image-api /usr/local/bin/image-api
USER 65534:65534
ENV LISTEN_ADDR=0.0.0.0:8080
EXPOSE 8080
CMD ["/usr/local/bin/image-api"]
同じポートでコンテナーを公開する前に、ローカルの go run サーバーを停止してください。image-api からイメージをビルドし、ローカルテスト用にループバックのみに公開します。
docker build -t image-api . &&
docker run --rm --stop-timeout=45 --memory=512m --cpus=2 -p 127.0.0.1:8080:8080 image-api
SIGINT または SIGTERM を受信すると、プログラムは接続の受け付けを停止し、実行中のハンドラーを最大 35 秒待ちます。コンテナーの停止猶予は 45 秒なので、この終了処理の時間を確保できます。Docker の Linux でのデフォルトの猶予時間は 10 秒です。ネイティブ処理がアプリケーションの期限を超えると、通常のクリーンアップを行わずにプロセスが終了します。
公開環境へデプロイする前に、TLS、認証と認可、プロキシでのボディサイズ制限、不正利用対策、レビュー済みのデコーダーポリシーを追加してください。このコンテナーの例はパッケージ化を示すもので、テナントを完全に分離するものではありません。マネージド処理については、Transloadit の画像処理サービスをご覧ください。
