跳到主要内容

设计图片处理 CDN 服务

问题​

如何从零设计一个图片处理 CDN 服务？要求支持裁剪、缩放、格式转换、水印、质量压缩等操作，同时满足低延迟、高吞吐、成本可控的非功能需求。

答案​

图片处理 CDN 服务的核心思路：客户端通过 URL 参数声明式地描述图片处理需求，请求经过 CDN 边缘节点缓存加速，未命中时回源到图片处理服务，处理服务从对象存储拉取原图，经过 Sharp/libvips 管线处理后返回结果并写入多级缓存。这种架构将计算推迟到首次请求（按需处理），后续请求直接命中缓存，兼顾了灵活性与性能。

一、需求分析​

1.1 功能需求​

功能说明参数示例
裁剪指定区域裁剪、居中裁剪、智能裁剪crop,w_300,h_200,g_center
缩放等比缩放、强制缩放、限制最大尺寸resize,w_800,h_600,m_lfit
格式转换JPEG/PNG/WebP/AVIF 互转format,webp
水印文字水印、图片水印、位置/透明度可控watermark,text_hello,g_se
质量压缩有损/无损压缩、指定质量系数quality,q_80
自适应格式根据 Accept 头自动选择 WebP/AVIF自动协商，无需参数
旋转/翻转任意角度旋转、水平/垂直翻转rotate,v_90 / flip
模糊高斯模糊，支持指定半径blur,r_20

1.2 非功能需求​

维度目标关键指标
低延迟CDN 命中时 < 50ms，回源处理 < 500msP99 延迟
高吞吐单节点 500+ QPS（CPU 密集型上限）处理 QPS
高可用99.9%+ SLA多节点冗余 + 自动扩缩
成本控制缓存命中率 > 95%，减少重复处理和回源CDN 命中率
安全防盗链、防恶意请求、防 SSRF签名验证 + 限流
核心设计原则

按需处理 + 多级缓存 是图片处理 CDN 的核心策略。相比预生成所有尺寸，按需处理只在首次请求时消耗计算资源，配合 CDN 缓存可以覆盖 95%+ 的后续请求，大幅降低存储成本和计算成本。

二、整体架构​

2.1 请求链路全景图​

2.2 请求处理时序​

三、核心模块设计​

3.1 URL 参数 DSL 设计​

URL 参数 DSL（Domain Specific Language）是整个系统的"入口协议"，它将图片处理指令编码在 URL 中，天然适配 CDN 缓存。

3.1.1 DSL 语法规范​

主流云厂商的图片处理 URL 有两种风格：

风格示例代表服务
查询参数式?x-image-process=resize,w_400/format,webp阿里云 OSS
路径式/w_400,h_300,c_fill,f_webp/img/photo.jpgCloudinary

本方案采用阿里云 OSS 风格（查询参数式），因为：

  • CDN 友好：同一图片不同处理参数对应不同 URL，天然作为 CDN 缓存 Key
  • RESTful 兼容：不改变资源路径，处理指令作为查询参数传递
  • 前端零依赖：拼接字符串即可使用，无需 SDK

语法定义：

?x-image-process=<action1>,<param1_key>_<param1_value>,<param2_key>_<param2_value>/<action2>,<params>...
  • / 分隔不同操作（管线风格，从左到右依次执行）
  • , 分隔操作名和参数键值对
  • _ 分隔参数的 key 和 value

完整示例：

# 裁剪 → 缩放 → 格式转换 → 质量压缩
?x-image-process=crop,w_800,h_600,g_center/resize,w_400,m_lfit/format,webp/quality,q_80

3.1.2 操作参数速查表​

操作参数含义取值范围
resizew目标宽度1-4096
resizeh目标高度1-4096
resizem缩放模式lfit(等比) / fill(裁剪填充) / fixed(强制)
resizel是否允许放大0(不放大) / 1(允许)
cropw,h裁剪区域宽高1-原图尺寸
cropx,y裁剪起始坐标0-原图尺寸
cropg裁剪基准点nw/north/ne/west/center/east/sw/south/se
format第一个参数目标格式jpeg/png/webp/avif/gif
qualityq质量系数1-100
watermarktext文字水印内容URL 编码字符串
watermarkimage图片水印 URLBase64 编码的 OSS 路径
watermarkg水印位置九宫格位置
watermarkt透明度0-100
rotatev旋转角度0-360
blurr模糊半径1-50

3.1.3 URL 解析器实现​

src/parser/url-parser.ts
/** 单个处理操作 */
interface ProcessAction {
  name: string;
  params: Record<string, string>;
}

/** 解析结果 */
interface ParseResult {
  actions: ProcessAction[];
  originalPath: string;
}

/**
 * 解析图片处理 URL 参数
 * 输入: "resize,w_400,h_300/format,webp/quality,q_80"
 * 输出: [{ name: 'resize', params: { w: '400', h: '300' } }, ...]
 */
function parseImageProcess(processString: string): ProcessAction[] {
  if (!processString) return [];

  return processString.split('/').map((segment) => {
    const parts = segment.split(',');
    const name = parts[0]; // 第一个元素是操作名

    const params: Record<string, string> = {};
    for (let i = 1; i < parts.length; i++) {
      const underscoreIdx = parts[i].indexOf('_');
      if (underscoreIdx > 0) {
        const key = parts[i].substring(0, underscoreIdx);
        const value = parts[i].substring(underscoreIdx + 1);
        params[key] = value;
      } else {
        // 无 key 的参数（如 format,webp 中的 webp）
        params[parts[i]] = 'true';
      }
    }

    return { name, params };
  });
}

/** 从完整 URL 中提取处理参数和原始路径 */
function parseRequestUrl(url: string): ParseResult {
  const urlObj = new URL(url, 'http://localhost');
  const processString = urlObj.searchParams.get('x-image-process') ?? '';

  return {
    actions: parseImageProcess(processString),
    originalPath: urlObj.pathname,
  };
}

3.2 图片处理管线​

图片处理管线是系统的计算核心，负责按照 DSL 解析出的操作序列，依次对图片执行变换。

3.2.1 为什么选择 Sharp​

方案底层引擎性能内存占用动图支持适用场景
Sharplibvips (C)极高低（流式/按需解码）支持服务端实时处理
Jimp纯 JS低高（全量加载）不支持简单场景
ImageMagickC中高支持批量离线处理
PillowPython (C)中中支持Python 生态
CanvasSkia/Cairo中中不支持绘图/合成场景
Sharp 性能优势的根本原因

Sharp 底层的 libvips 采用 demand-driven 架构：它不会一次性将整张图片解码到内存，而是只解码当前需要处理的像素区域。对于"缩放一张 4000x3000 的图片到 400x300"这样的操作，libvips 只需要解码少量像素就能完成，内存占用远低于全量加载方案。这使得 Sharp 在高并发场景下表现优异。

3.2.2 策略模式的处理引擎​

每种图片操作封装为一个独立的策略对象，包含参数校验和处理逻辑：

src/pipeline/actions.ts
import sharp, { type Sharp, type ResizeOptions } from 'sharp';

interface ActionHandler {
  /** 校验参数合法性 */
  validate(params: Record<string, string>): boolean;
  /** 执行处理操作 */
  execute(image: Sharp, params: Record<string, string>): Sharp;
}

/** 缩放操作 */
const resizeAction: ActionHandler = {
  validate(params) {
    const w = Number(params.w);
    const h = Number(params.h);
    // 宽高至少指定一个，且在合法范围内
    const hasSize = (!isNaN(w) && w > 0) || (!isNaN(h) && h > 0);
    const inRange = (isNaN(w) || w <= 4096) && (isNaN(h) || h <= 4096);
    return hasSize && inRange;
  },

  execute(image, params) {
    const w = Number(params.w) || undefined;
    const h = Number(params.h) || undefined;
    const enlarge = params.l !== '0'; // 默认允许放大

    const fitMap: Record<string, ResizeOptions['fit']> = {
      lfit: 'inside',    // 等比缩放，不超过目标尺寸
      fill: 'cover',     // 裁剪填充
      fixed: 'fill',     // 强制拉伸
      contain: 'contain', // 包含，可能留白
    };

    return image.resize(w, h, {
      fit: fitMap[params.m] ?? 'inside',
      withoutEnlargement: !enlarge,
      background: { r: 255, g: 255, b: 255, alpha: 0 }, // 透明背景
    });
  },
};

/** 裁剪操作 */
const cropAction: ActionHandler = {
  validate(params) {
    const w = Number(params.w);
    const h = Number(params.h);
    return w > 0 && h > 0;
  },

  execute(image, params) {
    const region = {
      left: Number(params.x) || 0,
      top: Number(params.y) || 0,
      width: Number(params.w),
      height: Number(params.h),
    };
    return image.extract(region);
  },
};

/** 格式转换操作 */
const formatAction: ActionHandler = {
  validate(params) {
    const validFormats = ['jpeg', 'jpg', 'png', 'webp', 'avif', 'gif'];
    const format = Object.keys(params).find((k) => validFormats.includes(k));
    return !!format;
  },

  execute(image, params) {
    const validFormats = ['jpeg', 'jpg', 'png', 'webp', 'avif', 'gif'];
    const format = Object.keys(params).find((k) => validFormats.includes(k));
    if (!format) return image;

    const normalized = format === 'jpg' ? 'jpeg' : format;
    return image.toFormat(normalized as keyof sharp.FormatEnum);
  },
};

/** 质量压缩操作 */
const qualityAction: ActionHandler = {
  validate(params) {
    const q = Number(params.q);
    return q >= 1 && q <= 100;
  },

  execute(image, params) {
    const q = Number(params.q);
    // Sharp 的 quality 参数通过各格式的选项设置
    return image.jpeg({ quality: q }).png({ quality: q }).webp({ quality: q }).avif({ quality: q });
  },
};

/** 水印操作 */
const watermarkAction: ActionHandler = {
  validate(params) {
    return !!(params.text || params.image);
  },

  execute(image, params) {
    if (params.text) {
      // 文字水印：使用 SVG 叠加
      const text = decodeURIComponent(params.text);
      const opacity = Number(params.t) || 100;
      const svg = Buffer.from(`
        <svg width="300" height="50">
          <text x="10" y="35" font-size="24" fill="white" opacity="${opacity / 100}">
            ${text}
          </text>
        </svg>
      `);

      return image.composite([{ input: svg, gravity: mapGravity(params.g) }]);
    }
    return image;
  },
};

/** 操作注册表 —— 新增操作只需在此注册 */
const actionRegistry: Record<string, ActionHandler> = {
  resize: resizeAction,
  crop: cropAction,
  format: formatAction,
  quality: qualityAction,
  watermark: watermarkAction,
};

/** 九宫格位置映射 */
function mapGravity(g?: string): sharp.Gravity {
  const gravityMap: Record<string, sharp.Gravity> = {
    nw: 'northwest', north: 'north', ne: 'northeast',
    west: 'west', center: 'center', east: 'east',
    sw: 'southwest', south: 'south', se: 'southeast',
  };
  return gravityMap[g ?? 'se'] ?? 'southeast';
}

3.2.3 管线编排与执行​

src/pipeline/processor.ts
import sharp from 'sharp';

interface ProcessResult {
  buffer: Buffer;
  format: string;
  width: number;
  height: number;
  size: number;
}

/**
 * 图片处理管线
 * 按照用户指定的操作顺序依次执行（而非策略注册顺序）
 */
async function processImage(
  inputBuffer: Buffer,
  actions: ProcessAction[],
  acceptHeader?: string
): Promise<ProcessResult> {
  // 检测是否为动图
  const metadata = await sharp(inputBuffer).metadata();
  const isAnimated = metadata.pages != null && metadata.pages > 1;

  let pipeline = sharp(inputBuffer, { animated: isAnimated });

  // 格式自动协商：如果用户未指定 format，根据 Accept 头选择最优格式
  const hasFormatAction = actions.some((a) => a.name === 'format');
  if (!hasFormatAction && acceptHeader) {
    const autoFormat = negotiateFormat(acceptHeader);
    if (autoFormat) {
      actions.push({ name: 'format', params: { [autoFormat]: 'true' } });
    }
  }

  // 按用户指定的顺序执行操作链
  for (const action of actions) {
    const handler = actionRegistry[action.name];
    if (handler && handler.validate(action.params)) {
      pipeline = handler.execute(pipeline, action.params);
    }
  }

  const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });

  return {
    buffer: data,
    format: info.format,
    width: info.width,
    height: info.height,
    size: data.byteLength,
  };
}

/**
 * 根据 Accept 头协商最优格式
 * 优先级：AVIF > WebP > 原格式
 */
function negotiateFormat(acceptHeader: string): string | null {
  if (acceptHeader.includes('image/avif')) return 'avif';
  if (acceptHeader.includes('image/webp')) return 'webp';
  return null;
}
操作顺序很重要

管线必须按用户指定的顺序执行操作，而非按策略注册顺序。例如"先缩放再裁剪"和"先裁剪再缩放"会产生完全不同的结果。这是一个容易踩坑的实现细节。

3.3 多级缓存策略​

缓存是图片处理 CDN 的性能命脉。合理的多级缓存可以让 95%+ 的请求在不触发图片处理的情况下完成响应。

3.3.1 缓存层级架构​

缓存层存储介质命中率延迟容量TTL
L1: CDN 边缘CDN 节点磁盘/内存~95%< 50msTB 级s-maxage=604800（7天）
L2: Redis 分布式Redis Cluster~3%< 10ms数十 GB24h
L3: 进程内 LRUNode.js 内存~1%< 1ms100-200MB/进程1h
为什么需要三级缓存？
  • CDN 覆盖全球用户，但不同边缘节点各自独立，存在冷启动问题
  • Redis 跨节点共享，解决多实例/多 CDN 节点首次回源的重复处理问题
  • LRU 避免热点图片频繁查询 Redis，降低网络开销

3.3.2 Cache Key 设计​

Cache Key 必须唯一标识一个处理结果，需要考虑：

src/cache/cache-key.ts
import { createHash } from 'crypto';

/**
 * 生成缓存 Key
 * 格式: img:<hash>
 * hash = SHA256(原图路径 + 排序后的操作参数 + 协商格式)
 */
function generateCacheKey(
  originalPath: string,
  actions: ProcessAction[],
  negotiatedFormat?: string
): string {
  // 将操作序列序列化为稳定字符串（操作顺序保留，参数排序）
  const actionsStr = actions
    .map((a) => {
      const sortedParams = Object.keys(a.params)
        .sort()
        .map((k) => `${k}_${a.params[k]}`)
        .join(',');
      return `${a.name},${sortedParams}`;
    })
    .join('/');

  const raw = `${originalPath}|${actionsStr}|${negotiatedFormat ?? ''}`;
  const hash = createHash('sha256').update(raw).digest('hex').slice(0, 16);

  return `img:${hash}`;
}

3.3.3 缓存中间件实现​

src/cache/cache-middleware.ts
import { LRUCache } from 'lru-cache';
import Redis from 'ioredis';

interface CachedImage {
  buffer: Buffer;
  format: string;
  width: number;
  height: number;
}

// L3: 进程内 LRU 缓存
const localCache = new LRUCache<string, CachedImage>({
  maxSize: 200 * 1024 * 1024, // 200MB 上限
  sizeCalculation: (value) => value.buffer.byteLength,
  ttl: 60 * 60 * 1000, // 1h
});

// L2: Redis 分布式缓存
const redis = new Redis({
  host: process.env.REDIS_HOST ?? 'localhost',
  port: Number(process.env.REDIS_PORT) ?? 6379,
  maxRetriesPerRequest: 3,
});

const REDIS_TTL = 24 * 60 * 60; // 24h

/** 多级缓存查询 */
async function getFromCache(key: string): Promise<CachedImage | null> {
  // L3: 查进程内缓存
  const local = localCache.get(key);
  if (local) return local;

  // L2: 查 Redis
  try {
    const redisData = await redis.getBuffer(key);
    if (redisData) {
      const metaKey = `${key}:meta`;
      const meta = await redis.get(metaKey);
      if (meta) {
        const parsed = JSON.parse(meta) as Omit<CachedImage, 'buffer'>;
        const cached: CachedImage = { ...parsed, buffer: redisData };
        localCache.set(key, cached); // 回填 L3
        return cached;
      }
    }
  } catch {
    // Redis 不可用时降级，不影响请求
  }

  return null;
}

/** 写入多级缓存 */
async function setToCache(key: string, data: CachedImage): Promise<void> {
  // 写 L3
  localCache.set(key, data);

  // 写 L2
  try {
    const meta = JSON.stringify({
      format: data.format,
      width: data.width,
      height: data.height,
    });
    await Promise.all([
      redis.setex(key, REDIS_TTL, data.buffer),
      redis.setex(`${key}:meta`, REDIS_TTL, meta),
    ]);
  } catch {
    // Redis 写入失败不影响响应
  }
}

3.3.4 HTTP 缓存头设置​

src/middleware/cache-headers.ts
import { createHash } from 'crypto';

interface CacheHeaderOptions {
  buffer: Buffer;
  format: string;
  isPublic?: boolean;
}

/** 生成缓存相关的 HTTP 响应头 */
function setCacheHeaders(
  ctx: { set: (key: string, value: string) => void },
  options: CacheHeaderOptions
): void {
  const { buffer, format, isPublic = true } = options;

  // ETag: 基于内容的哈希
  const etag = `"${createHash('md5').update(buffer).digest('hex')}"`;
  ctx.set('ETag', etag);

  // Cache-Control
  if (isPublic) {
    // max-age: 浏览器缓存 1 天
    // s-maxage: CDN 缓存 7 天
    // stale-while-revalidate: 过期后 1 天内先返回旧缓存，后台异步更新
    ctx.set(
      'Cache-Control',
      'public, max-age=86400, s-maxage=604800, stale-while-revalidate=86400'
    );
  } else {
    ctx.set('Cache-Control', 'private, max-age=3600');
  }

  // Content-Type
  ctx.set('Content-Type', `image/${format}`);

  // Vary: 告诉 CDN 根据 Accept 头缓存不同版本（格式协商）
  ctx.set('Vary', 'Accept');
}
Vary: Accept 的重要性

当启用格式自动协商（根据 Accept 头选择 WebP/AVIF）时，必须设置 Vary: Accept。否则 CDN 可能将 WebP 版本返回给不支持 WebP 的浏览器，导致图片无法显示。

3.4 安全防护​

3.4.1 安全威胁分析​

威胁描述影响
盗链第三方网站直接引用图片 URL流量费用增长
恶意处理构造超大尺寸/超多操作的请求CPU/内存耗尽
URL 篡改修改处理参数获取未授权的图片变体安全/版权风险
SSRF利用回源机制访问内网资源内网信息泄露
DDoS大量不同参数的请求绕过缓存服务不可用

3.4.2 URL 签名防盗链​

src/security/url-signer.ts
import { createHmac } from 'crypto';

const SECRET_KEY = process.env.IMAGE_SIGN_SECRET ?? '';
const SIGN_TTL = 3600; // 签名有效期 1 小时

/**
 * 生成签名 URL
 * 格式: ?x-image-process=...&sign=<signature>&t=<timestamp>
 */
function signUrl(originalUrl: string): string {
  const timestamp = Math.floor(Date.now() / 1000);
  const urlObj = new URL(originalUrl);

  // 待签名字符串: 路径 + 处理参数 + 时间戳
  const processParam = urlObj.searchParams.get('x-image-process') ?? '';
  const stringToSign = `${urlObj.pathname}|${processParam}|${timestamp}`;

  const signature = createHmac('sha256', SECRET_KEY)
    .update(stringToSign)
    .digest('hex')
    .slice(0, 16);

  urlObj.searchParams.set('t', String(timestamp));
  urlObj.searchParams.set('sign', signature);

  return urlObj.toString();
}

/** 验证签名 */
function verifySign(
  pathname: string,
  processParam: string,
  timestamp: string,
  signature: string
): boolean {
  const now = Math.floor(Date.now() / 1000);
  const ts = Number(timestamp);

  // 检查时间戳有效期
  if (isNaN(ts) || now - ts > SIGN_TTL) {
    return false;
  }

  const stringToSign = `${pathname}|${processParam}|${ts}`;
  const expected = createHmac('sha256', SECRET_KEY)
    .update(stringToSign)
    .digest('hex')
    .slice(0, 16);

  return signature === expected;
}

3.4.3 安全限制中间件​

src/security/guard-middleware.ts
/** 图片处理安全限制 */
interface SecurityLimits {
  maxWidth: number;          // 最大输出宽度
  maxHeight: number;         // 最大输出高度
  maxInputSize: number;      // 最大原图大小 (bytes)
  maxActions: number;        // 最大操作数
  processTimeout: number;    // 处理超时 (ms)
}

const DEFAULT_LIMITS: SecurityLimits = {
  maxWidth: 4096,
  maxHeight: 4096,
  maxInputSize: 20 * 1024 * 1024,  // 20MB
  maxActions: 10,                    // 最多 10 个操作
  processTimeout: 10_000,            // 10s 超时
};

/** 校验处理参数是否在安全范围内 */
function validateActions(
  actions: ProcessAction[],
  limits: SecurityLimits = DEFAULT_LIMITS
): { valid: boolean; error?: string } {
  // 操作数限制
  if (actions.length > limits.maxActions) {
    return { valid: false, error: `Too many actions: ${actions.length} > ${limits.maxActions}` };
  }

  for (const action of actions) {
    // 尺寸限制
    if (action.name === 'resize' || action.name === 'crop') {
      const w = Number(action.params.w) || 0;
      const h = Number(action.params.h) || 0;
      if (w > limits.maxWidth || h > limits.maxHeight) {
        return { valid: false, error: `Dimensions exceed limit: ${w}x${h}` };
      }
    }

    // 模糊半径限制（大半径高斯模糊非常消耗 CPU）
    if (action.name === 'blur') {
      const r = Number(action.params.r) || 0;
      if (r > 50) {
        return { valid: false, error: `Blur radius too large: ${r}` };
      }
    }
  }

  return { valid: true };
}

/** 原图大小校验 */
function validateInputSize(
  buffer: Buffer,
  limits: SecurityLimits = DEFAULT_LIMITS
): boolean {
  return buffer.byteLength <= limits.maxInputSize;
}

3.4.4 Rate Limiting​

src/security/rate-limiter.ts
/**
 * 令牌桶限流器
 * 适合图片处理场景：允许短时突发，但限制持续高频请求
 */
class TokenBucket {
  private tokens: number;
  private lastRefill: number;

  constructor(
    private readonly capacity: number,      // 桶容量
    private readonly refillRate: number,     // 每秒补充令牌数
  ) {
    this.tokens = capacity;
    this.lastRefill = Date.now();
  }

  consume(count: number = 1): boolean {
    this.refill();

    if (this.tokens >= count) {
      this.tokens -= count;
      return true;
    }

    return false; // 限流
  }

  private refill(): void {
    const now = Date.now();
    const elapsed = (now - this.lastRefill) / 1000;
    this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate);
    this.lastRefill = now;
  }
}

// 每个 IP 独立限流：每秒 50 次请求，突发上限 100
const buckets = new Map<string, TokenBucket>();

function getRateLimiter(ip: string): TokenBucket {
  let bucket = buckets.get(ip);
  if (!bucket) {
    bucket = new TokenBucket(100, 50);
    buckets.set(ip, bucket);
  }
  return bucket;
}

四、关键技术实现​

4.1 完整的请求处理流程​

将上述模块组装成完整的请求处理链路：

src/service/image-service.ts
import sharp from 'sharp';
import axios from 'axios';

interface ImageServiceConfig {
  ossBaseUrl: string;
  signRequired: boolean;
  limits: SecurityLimits;
}

class ImageService {
  constructor(private readonly config: ImageServiceConfig) {}

  async handleRequest(
    path: string,
    processString: string,
    acceptHeader: string,
    clientIp: string,
    signParams?: { t: string; sign: string }
  ): Promise<{ buffer: Buffer; format: string; headers: Record<string, string> }> {
    // 1. 限流检查
    const limiter = getRateLimiter(clientIp);
    if (!limiter.consume()) {
      throw new HttpError(429, 'Too Many Requests');
    }

    // 2. 签名验证（如果启用）
    if (this.config.signRequired && signParams) {
      const valid = verifySign(path, processString, signParams.t, signParams.sign);
      if (!valid) {
        throw new HttpError(403, 'Invalid signature');
      }
    }

    // 3. 解析处理参数
    const actions = parseImageProcess(processString);

    // 4. 安全校验
    const validation = validateActions(actions, this.config.limits);
    if (!validation.valid) {
      throw new HttpError(400, validation.error ?? 'Invalid parameters');
    }

    // 5. 查询缓存
    const cacheKey = generateCacheKey(path, actions, negotiateFormat(acceptHeader) ?? undefined);
    const cached = await getFromCache(cacheKey);
    if (cached) {
      return {
        buffer: cached.buffer,
        format: cached.format,
        headers: this.buildHeaders(cached.buffer, cached.format),
      };
    }

    // 6. 回源拉取原图
    const originalBuffer = await this.fetchOriginal(path);

    // 7. 原图大小校验
    if (!validateInputSize(originalBuffer, this.config.limits)) {
      throw new HttpError(413, 'Image too large');
    }

    // 8. 执行图片处理管线（带超时控制）
    const result = await Promise.race([
      processImage(originalBuffer, actions, acceptHeader),
      this.timeout(this.config.limits.processTimeout),
    ]);

    // 9. 写入缓存
    await setToCache(cacheKey, {
      buffer: result.buffer,
      format: result.format,
      width: result.width,
      height: result.height,
    });

    return {
      buffer: result.buffer,
      format: result.format,
      headers: this.buildHeaders(result.buffer, result.format),
    };
  }

  /** 从 OSS 拉取原图 */
  private async fetchOriginal(path: string): Promise<Buffer> {
    const url = `${this.config.ossBaseUrl}${path}`;

    try {
      const response = await axios.get<Buffer>(url, {
        responseType: 'arraybuffer',
        timeout: 5000, // 5s 超时
        maxContentLength: 30 * 1024 * 1024, // 30MB 上限
      });
      return Buffer.from(response.data);
    } catch (error) {
      if (axios.isAxiosError(error)) {
        if (error.response?.status === 404) {
          throw new HttpError(404, 'Image not found');
        }
        if (error.code === 'ECONNABORTED') {
          throw new HttpError(504, 'Origin timeout');
        }
      }
      throw new HttpError(502, 'Failed to fetch original image');
    }
  }

  /** 处理超时控制 */
  private timeout(ms: number): Promise<never> {
    return new Promise((_, reject) =>
      setTimeout(() => reject(new HttpError(504, 'Processing timeout')), ms)
    );
  }

  /** 构建 HTTP 响应头 */
  private buildHeaders(buffer: Buffer, format: string): Record<string, string> {
    const etag = `"${createHash('md5').update(buffer).digest('hex')}"`;
    return {
      'Content-Type': `image/${format}`,
      'Cache-Control': 'public, max-age=86400, s-maxage=604800, stale-while-revalidate=86400',
      'ETag': etag,
      'Vary': 'Accept',
    };
  }
}

class HttpError extends Error {
  constructor(public readonly status: number, message: string) {
    super(message);
  }
}

4.2 Stream 流式处理（大图优化）​

对于超大图片，将整个 Buffer 加载到内存可能导致 OOM。可以使用 Stream 流式处理：

src/pipeline/stream-processor.ts
import { Readable, PassThrough } from 'stream';
import sharp from 'sharp';
import axios from 'axios';

/**
 * 流式图片处理 —— 适用于大图场景
 * 原图不完全加载到内存，边读边处理边输出
 */
async function processImageStream(
  ossUrl: string,
  actions: ProcessAction[]
): Promise<{ stream: Readable; format: string }> {
  // 从 OSS 获取可读流（不等待完全下载）
  const response = await axios.get(ossUrl, {
    responseType: 'stream',
    timeout: 10_000,
  });

  const inputStream: Readable = response.data;

  // 构建 Sharp 管线
  let pipeline = sharp();

  for (const action of actions) {
    const handler = actionRegistry[action.name];
    if (handler && handler.validate(action.params)) {
      pipeline = handler.execute(pipeline, action.params);
    }
  }

  // 管道连接：OSS Stream → Sharp Transform → Output
  const outputStream = inputStream.pipe(pipeline);

  return {
    stream: outputStream,
    format: getOutputFormat(actions),
  };
}

function getOutputFormat(actions: ProcessAction[]): string {
  const formatAction = actions.find((a) => a.name === 'format');
  if (formatAction) {
    const fmt = Object.keys(formatAction.params).find((k) =>
      ['jpeg', 'jpg', 'png', 'webp', 'avif'].includes(k)
    );
    return fmt === 'jpg' ? 'jpeg' : (fmt ?? 'jpeg');
  }
  return 'jpeg';
}

4.3 并发限制（Semaphore）​

Sharp 处理是 CPU 密集型操作，需要限制并发数以避免服务过载：

src/utils/semaphore.ts
/**
 * 信号量 —— 控制并发数
 * 防止过多图片同时处理导致 CPU 打满
 */
class Semaphore {
  private queue: Array<() => void> = [];
  private current = 0;

  constructor(private readonly maxConcurrent: number) {}

  async acquire(): Promise<void> {
    if (this.current < this.maxConcurrent) {
      this.current++;
      return;
    }

    // 超过并发上限，排队等待
    return new Promise<void>((resolve) => {
      this.queue.push(resolve);
    });
  }

  release(): void {
    this.current--;
    const next = this.queue.shift();
    if (next) {
      this.current++;
      next();
    }
  }

  /** 包装异步函数，自动管理信号量 */
  async run<T>(fn: () => Promise<T>): Promise<T> {
    await this.acquire();
    try {
      return await fn();
    } finally {
      this.release();
    }
  }
}

// CPU 核心数决定并发上限（留 1 核给事件循环）
const cpuCount = require('os').cpus().length;
const processSemaphore = new Semaphore(Math.max(1, cpuCount - 1));

// 使用示例
async function handleImageRequest(/* ... */): Promise<Buffer> {
  return processSemaphore.run(async () => {
    // Sharp 处理逻辑
    return processImage(buffer, actions);
  });
}

五、性能优化​

5.1 处理优化​

优化策略说明收益
Stream 流式处理大图不全量加载到内存内存占用降低 60%+
并发限制 (Semaphore)控制同时处理的图片数防止 CPU 过载
Sharp 管线复用多个操作在一次 Sharp 管线中完成减少解码/编码次数
Worker ThreadsCPU 密集操作放到工作线程不阻塞主线程事件循环
预计算 metadata缓存原图 metadata 避免重复读取减少 IO 开销
关键性能数据

Sharp 基于 libvips 的 demand-driven 架构，处理一张 2000x2000 的 JPEG 图片缩放到 200x200 仅需 20-50ms，内存占用约 10-20MB。相比之下，基于 ImageMagick 的方案可能需要 200ms+ 且占用 100MB+ 内存。

5.2 缓存命中率优化​

URL 参数标准化：将语义等价的参数统一化，避免不同写法导致缓存失效：

src/cache/normalize.ts
/**
 * 标准化处理参数，提升缓存命中率
 * 示例: "resize,h_300,w_400" → "resize,h_300,w_400"（参数排序）
 * 示例: "resize,w_400.0" → "resize,w_400"（去除无效小数）
 */
function normalizeActions(actions: ProcessAction[]): ProcessAction[] {
  return actions.map((action) => {
    const normalizedParams: Record<string, string> = {};

    // 参数 key 排序 + 值标准化
    Object.keys(action.params)
      .sort()
      .forEach((key) => {
        let value = action.params[key];
        // 数字标准化：去除前导零、无效小数点
        const num = Number(value);
        if (!isNaN(num) && value !== 'true') {
          value = String(num);
        }
        normalizedParams[key] = value;
      });

    return { name: action.name, params: normalizedParams };
  });
}

5.3 CDN 回源优化​

策略实现方式效果
合并回源相同 URL 的并发请求只回源一次（请求合并/coalescing）减少回源 QPS
分层回源CDN 边缘 → CDN 中心 → 源站减少源站压力
源站分组不同路径前缀路由到不同源站负载均衡
回源预热新图片上传后主动推送到 CDN消除首次请求延迟
失败缓存缓存 404/500 响应（短 TTL）防止错误请求反复回源

请求合并（Request Coalescing）：避免热点图片同时被多个 CDN 节点回源：

src/cache/request-coalescing.ts
/**
 * 请求去重 / 合并
 * 相同 Cache Key 的并发请求，只有第一个真正执行处理，其余等待复用结果
 */
class RequestCoalescing {
  private inflight = new Map<string, Promise<ProcessResult>>();

  async getOrProcess(
    cacheKey: string,
    processFn: () => Promise<ProcessResult>
  ): Promise<ProcessResult> {
    // 如果已有相同请求正在处理中，直接等待其结果
    const existing = this.inflight.get(cacheKey);
    if (existing) {
      return existing;
    }

    // 首个请求：执行处理并注册到 inflight
    const promise = processFn().finally(() => {
      this.inflight.delete(cacheKey);
    });

    this.inflight.set(cacheKey, promise);
    return promise;
  }
}

const coalescing = new RequestCoalescing();

5.4 成本优化：按需处理 vs 预处理​

策略适用场景优势劣势
按需处理参数组合多、长尾图片多只处理被请求的组合，存储成本低首次请求有处理延迟
预处理固定规格、高频图片首次请求也能命中缓存存储成本高，规格变更需重新生成
混合策略生产环境推荐兼顾性能和成本实现复杂度较高
推荐的混合策略
  • 头像、Banner 等高频图片：上传时预处理常用规格（48x48、200x200、800x800），写入 CDN 预热
  • UGC 内容图片：按需处理，首次请求后缓存
  • 历史冷数据：按需处理，缓存 TTL 可以更短

六、扩展设计​

6.1 AI 智能裁剪​

传统裁剪需要手动指定坐标，AI 智能裁剪可以自动识别图片主体并裁剪到最佳区域：

src/extensions/smart-crop.ts
import sharp from 'sharp';

interface FocalPoint {
  x: number;  // 焦点 x 坐标（0-1 归一化）
  y: number;  // 焦点 y 坐标（0-1 归一化）
}

/**
 * 基于 Sharp 的 attention 策略实现智能裁剪
 * Sharp 内置了基于显著性检测的注意力裁剪
 */
async function smartCrop(
  buffer: Buffer,
  targetWidth: number,
  targetHeight: number
): Promise<Buffer> {
  // Sharp 的 attention 策略会自动检测图片中最"引人注目"的区域
  return sharp(buffer)
    .resize(targetWidth, targetHeight, {
      fit: 'cover',
      position: sharp.strategy.attention, // 基于注意力的智能裁剪
    })
    .toBuffer();
}

/**
 * 基于外部 AI 服务的人脸检测裁剪
 * 适合头像场景，确保人脸始终在裁剪区域内
 */
async function faceCrop(
  buffer: Buffer,
  targetWidth: number,
  targetHeight: number,
  focalPoint: FocalPoint
): Promise<Buffer> {
  const metadata = await sharp(buffer).metadata();
  const origW = metadata.width!;
  const origH = metadata.height!;

  // 以焦点为中心计算裁剪区域
  const cropW = Math.min(origW, Math.round(targetWidth * (origW / targetWidth)));
  const cropH = Math.min(origH, Math.round(targetHeight * (origH / targetHeight)));

  const left = Math.max(0, Math.min(
    Math.round(focalPoint.x * origW - cropW / 2),
    origW - cropW
  ));
  const top = Math.max(0, Math.min(
    Math.round(focalPoint.y * origH - cropH / 2),
    origH - cropH
  ));

  return sharp(buffer)
    .extract({ left, top, width: cropW, height: cropH })
    .resize(targetWidth, targetHeight)
    .toBuffer();
}

6.2 图片审核​

在 UGC 平台中，图片上传后需要经过内容审核：

src/extensions/content-audit.ts
interface AuditResult {
  safe: boolean;
  categories: Array<{
    label: string;       // 'porn' | 'violence' | 'political' | ...
    confidence: number;  // 0-1
  }>;
}

/**
 * 审核状态缓存 —— 避免每次请求都调用审核 API
 * key: 原图路径, value: 审核结果
 */
const auditCache = new Map<string, AuditResult>();

/** 图片审核中间件 */
async function auditMiddleware(
  imagePath: string,
  buffer: Buffer
): Promise<{ allowed: boolean; processedBuffer?: Buffer }> {
  // 查询审核缓存
  let result = auditCache.get(imagePath);

  if (!result) {
    // 调用外部审核 API（如阿里云内容安全、AWS Rekognition）
    result = await callAuditApi(buffer);
    auditCache.set(imagePath, result);
  }

  if (result.safe) {
    return { allowed: true };
  }

  // 违规图片：返回模糊处理版本
  const blurredBuffer = await sharp(buffer)
    .blur(30)
    .modulate({ brightness: 0.5 })
    .toBuffer();

  return { allowed: false, processedBuffer: blurredBuffer };
}

6.3 响应式图片（srcset 生成）​

为前端自动生成多种尺寸的响应式图片 URL：

src/extensions/responsive.ts
interface ResponsiveImageSet {
  src: string;           // 默认 src
  srcset: string;        // srcset 属性值
  sizes: string;         // sizes 属性值
}

/**
 * 生成响应式图片 srcset
 * 前端可直接使用返回值设置 <img> 标签属性
 */
function generateResponsiveUrls(
  baseUrl: string,
  breakpoints: number[] = [320, 640, 768, 1024, 1280, 1920]
): ResponsiveImageSet {
  const srcset = breakpoints
    .map((w) => {
      const url = `${baseUrl}?x-image-process=resize,w_${w}/format,webp`;
      return `${url} ${w}w`;
    })
    .join(', ');

  return {
    src: `${baseUrl}?x-image-process=resize,w_768/format,webp`,
    srcset,
    sizes: '(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw',
  };
}

前端使用：

组件中使用响应式图片
// React 组件示例
function ResponsiveImage({ src, alt }: { src: string; alt: string }) {
  const { src: defaultSrc, srcset, sizes } = generateResponsiveUrls(src);

  return (
    <img
      src={defaultSrc}
      srcSet={srcset}
      sizes={sizes}
      alt={alt}
      loading="lazy"
      decoding="async"
    />
  );
}

6.4 WebP/AVIF 自动降级​

格式压缩率（相对 JPEG）浏览器支持编码速度适用场景
JPEG基准全部快兜底格式
WebP-30~50%Chrome/Firefox/Safari 14+中主流推荐
AVIF-50~80%Chrome 85+/Firefox 93+慢高压缩率需求
AVIF 编码性能注意

AVIF 编码速度比 WebP 慢 5-10 倍。在实时处理场景中，如果 AVIF 编码导致延迟过高，可以考虑：

  1. 仅对缓存命中的图片返回 AVIF，首次请求返回 WebP
  2. 使用异步预生成 AVIF 版本
  3. 通过 Sharp 的 effort 参数降低编码质量换取速度

常见面试问题​

Q1: 为什么选择"按需处理 + CDN 缓存"而不是"上传时预生成所有尺寸"？​

答案：

这是图片处理 CDN 的核心架构决策，需要从多个维度对比：

维度按需处理 + CDN 缓存上传时预生成
存储成本低：只缓存被请求的组合高：每张图 N 种规格
灵活性高：随时调整参数组合低：规格变更需批量重新生成
首次延迟有：需实时处理无：直接返回
计算成本按需消耗上传高峰期集中消耗
实现复杂度中：需要处理服务 + 缓存低：上传钩子 + 批处理

最佳实践是混合策略：高频固定规格（如头像 48x48）预生成，长尾参数组合按需处理。预生成策略只适用于规格有限且固定的场景，而现代前端对图片的尺寸需求越来越多样化（响应式布局、不同 DPR 设备），按需处理是更可持续的方案。

Q2: 如何保证缓存命中率？缓存命中率低会带来什么问题？​

答案：

缓存命中率是图片处理 CDN 最关键的指标。命中率每下降 1%，回源处理量就可能翻倍。

提升命中率的策略：

  1. URL 参数标准化：将 resize,w_400.0 和 resize,w_400 统一为相同的 Cache Key
  2. 合理的 TTL 分层：CDN 7 天、Redis 24 小时、LRU 1 小时
  3. stale-while-revalidate：缓存过期后先返回旧缓存，后台异步刷新
  4. 预热高频图片：新图片上传后主动推送到 CDN
  5. 请求合并（Coalescing）：相同图片的并发回源请求只执行一次处理
缓存头最佳配置
Cache-Control: public, max-age=86400, s-maxage=604800, stale-while-revalidate=86400
Vary: Accept
ETag: "content-hash"

命中率低的后果：

  • 源站 CPU 负载线性增长
  • OSS 出流量费用增加
  • 用户体验下降（延迟增加）
  • 极端情况下服务雪崩

Q3: 如何防止恶意请求？攻击者可能用什么方式攻击图片处理服务？​

答案：

图片处理服务面临的特殊安全威胁：

攻击方式描述防御手段
缓存穿透构造大量不同参数的请求，每次都绕过缓存URL 签名 + 参数白名单
资源耗尽请求超大尺寸（如 resize,w_99999）或高斯模糊大半径尺寸限制 + 参数校验
恶意原图上传超大/超高分辨率的图片原图大小限制（20MB）
DDoS大量请求冲击处理服务Rate Limiting + CDN WAF
SSRF利用回源拉取机制访问内网回源域名白名单
盗链第三方网站直接引用图片Referer 检查 + URL 签名

多层防御体系：

安全防御层级
// 1. CDN 层：WAF + DDoS 防护 + Referer 白名单
// 2. Gateway 层：Rate Limiting（令牌桶 50 QPS/IP）
// 3. 应用层：
//    - URL 签名验证（HMAC-SHA256）
//    - 参数范围校验（宽高 ≤ 4096，模糊半径 ≤ 50）
//    - 原图大小限制（≤ 20MB）
//    - 操作数限制（≤ 10 个操作）
//    - 处理超时（10s 强制中断）
// 4. 系统层：Semaphore 并发限制（CPU 核心数 - 1）

Q4: 图片处理的操作顺序为什么很重要？​

答案：

操作顺序直接影响最终结果。以"先裁剪再缩放"和"先缩放再裁剪"为例：

原图: 1000x1000

方案 A: crop,w_500,h_500 → resize,w_200,h_200
  → 裁剪左上角 500x500 → 缩放到 200x200
  → 结果: 原图左上角区域的 200x200 缩略图

方案 B: resize,w_200,h_200 → crop,w_100,h_100
  → 先整体缩放到 200x200 → 再裁剪 100x100
  → 结果: 整张图缩略后的左上角 100x100 区域

实现要点：管线必须按用户在 URL 中指定的顺序（从左到右）执行，而非按策略注册顺序。常见的错误实现是使用 Object.keys() 遍历策略对象——在 JavaScript 中对象属性的遍历顺序是固定的（按插入顺序），无法反映用户意图。正确做法是按 DSL 解析出的 action 数组顺序遍历：

// 正确：按用户指定顺序
for (const action of actions) {
  pipeline = actionRegistry[action.name].execute(pipeline, action.params);
}

// 错误：按策略注册顺序
Object.keys(actionRegistry).forEach((name) => { /* ... */ });

Q5: 如何实现格式自动协商（Content Negotiation）？​

答案：

格式自动协商是指服务端根据客户端的 Accept 请求头，自动选择最优的图片格式返回，无需前端手动指定。

实现流程：

格式协商逻辑
function negotiateFormat(acceptHeader: string): string | null {
  // 优先级：AVIF > WebP > 原格式
  if (acceptHeader.includes('image/avif')) return 'avif';
  if (acceptHeader.includes('image/webp')) return 'webp';
  return null; // 保持原格式
}

关键注意事项：

  1. 必须设置 Vary: Accept：告诉 CDN 同一 URL 在不同 Accept 头下可能返回不同内容，需要分别缓存
  2. Cache Key 必须包含协商格式：否则 CDN 可能将 WebP 版本返回给不支持 WebP 的旧浏览器
  3. AVIF 编码较慢：可以对首次请求降级返回 WebP，异步预生成 AVIF 版本

主流浏览器的 Accept 头示例：

浏览器Accept 头（图片请求）
Chrome 100+image/avif,image/webp,image/apng,image/*,*/*;q=0.8
Firefox 100+image/avif,image/webp,*/*
Safari 16+image/webp,image/png,image/*;q=0.8,*/*;q=0.5
Safari 14-15image/png,image/*;q=0.8,*/*;q=0.5

Q6: Stream 流式处理相比 Buffer 全量处理有什么优缺点？​

答案：

维度Buffer 全量处理Stream 流式处理
内存占用需要加载完整图片到内存逐块处理，内存占用低
首字节时间必须等完整处理完才能返回可以边处理边输出
缓存方便：Buffer 直接存入 Redis/LRU复杂：需要收集完整流才能缓存
错误处理简单：try/catch 即可复杂：需要监听 stream error 事件
多次读取方便：Buffer 可重复读取不便：流只能消费一次
适用场景中小图片（< 10MB）、需要缓存超大图片（> 10MB）、实时转发

生产建议：默认使用 Buffer 模式（方便缓存），对超过阈值（如 10MB）的大图自动切换到 Stream 模式。Sharp 的 libvips 底层本身就是 demand-driven 的，即使使用 Buffer 输入也不会一次性解码完整图片。

Q7: 如果 CDN 节点缓存过期，大量请求同时回源怎么办？（缓存雪崩）​

答案：

这是经典的缓存雪崩问题。当 CDN 缓存同时到期，大量请求穿透到源站，可能导致处理服务过载。

防御策略：

  1. stale-while-revalidate：缓存过期后先返回旧缓存，后台异步刷新
// CDN 缓存 7 天，过期后的 1 天内仍可返回旧缓存
Cache-Control: public, s-maxage=604800, stale-while-revalidate=86400
  1. TTL 随机化：给 CDN 的 s-maxage 添加随机偏移，避免大量缓存同时过期
// 基准 7 天 ± 随机 0-12 小时
const baseTTL = 7 * 24 * 3600;
const jitter = Math.floor(Math.random() * 12 * 3600);
const ttl = baseTTL + jitter;

  1. 请求合并（Request Coalescing）：源站层面，相同 URL 的并发请求只处理一次

  2. CDN 回源锁：部分 CDN 支持"回源锁"功能（如 Cloudflare 的 Cache Lock），同一资源的并发回源请求只放行一个

  3. 降级策略：源站过载时返回低质量版本或原图，而非直接报错

Q8: 如何估算图片处理服务的容量和成本？​

答案：

容量估算模型：

假设业务日均 1000 万次图片请求：

CDN 命中率 95% → 回源量 = 1000万 × 5% = 50万次/天
每次处理平均耗时 100ms
单核处理能力 = 1000ms / 100ms = 10 QPS
4 核实例处理能力 ≈ 30 QPS（留 1 核给事件循环 + OS）
日均回源 QPS ≈ 50万 / 86400 ≈ 6 QPS（均值）
峰值按 5 倍估算 ≈ 30 QPS

结论: 1 台 4 核实例可支撑，建议部署 2 台保证高可用

成本构成：

成本项估算方式月费用示例
CDN 流量日均 10TB × ¥0.2/GB~¥60,000
云服务器2 台 4C8G~¥1,000
Redis 缓存16GB 集群~¥500
OSS 存储1TB + 出流量~¥300
成本优化关键

提升 CDN 缓存命中率是降低成本的最有效手段。 命中率从 90% 提升到 95%，回源量减半，处理服务器成本和 OSS 出流量成本都能降低 50%。

相关链接​