Image Processing Service API

项目描述

本项目是一个基于 Node.js 和 Express 构建的高性能图片处理 API 服务。它允许用户通过 URL 参数动态地对图片进行各种操作，如调整大小、裁剪、格式转换、质量调整等。服务支持从多种来源（如本地文件系统、用户上传）获取图片，并集成了缓存机制以提高重复请求的响应速度和效率。

主要特性：

• 动态图像处理: 使用 Sharp 库进行高效的图像转换。
• 多图片源: 支持从配置的本地目录或用户上传获取图片，并可扩展至 S3、Minio 等云存储。
• URL 参数驱动: 通过简单的 URL 查询参数控制图像处理选项。
• 缓存策略: 支持文件系统缓存，并可扩展至内存缓存 (LRU) 或 Redis 等分布式缓存。
• 文件上传: 提供图片上传接口，上传后的图片可被动态处理。
• 可配置和可扩展: 设计上考虑了模块化，方便添加新的图片源、缓存策略和处理参数。
• Docker 支持: 提供 Dockerfile 和 Docker Compose 配置，方便本地开发和部署。

项目结构

image-processor-service/
├── config/                   # 应用配置文件
│   └── index.js
├── src/                      # 源代码目录
│   ├── sources/              # 图片源实现 (localFileSource.js, s3Source.js, etc.)
│   │   └── baseSource.js     # 图片源基类/接口
│   ├── caches/               # 缓存策略实现 (fileSystemCache.js, memoryCache.js, etc.)
│   │   └── baseCache.js      # 缓存基类/接口
│   ├── processing/           # 图片处理逻辑 (sharpProcessor.js)
│   ├── middleware/           # Express 中间件 (imageHandler.js, uploadHandler.js)
│   ├── utils/                # 工具函数 (paramParser.js, cacheKeyGenerator.js, fileNameUtils.js)
│   └── app.js                # Express 应用设置和路由初始化
├── original_images/          # 示例: 存放 'local' 源类型的预置图片
├── uploaded_images/          # 示例: 存放通过 '/upload' 源上传的图片 (如果使用本地文件存储)
├── cached_images/            # 示例: 存放文件系统缓存处理后的图片
├── public/                   # (可选) 存放静态资源，如测试上传表单
├── .env.example              # 环境变量示例文件
├── .eslintrc.js              # (可选) ESLint 配置文件
├── .gitignore
├── Dockerfile                # 用于构建 Docker 镜像
├── docker-compose.yml        # 用于本地 Docker 开发环境
├── package.json
├── package-lock.json
├── README.md
└── server.js                 # Node.js 应用入口文件

技术栈

• Node.js: JavaScript 运行时环境。
• Express.js: Web 应用框架。
• Sharp: 高性能图像处理库。
• Multer: Node.js 中间件，用于处理 multipart/form-data，主要用于文件上传。
• dotenv: 用于从 .env 文件加载环境变量到 process.env。
• Docker: 容器化平台。

使用方式

1. 环境准备

• 安装 Node.js (推荐 LTS 版本，请参考 package.json 中的 engines 字段)。
• 安装 Docker 和 Docker Compose (如果使用 Docker 进行本地开发或部署)。
• 克隆项目仓库:

  git clone https://github.com/lovebugss/image-processor.git
  cd image-processor-service

2. 本地开发 (不使用 Docker)

• 安装依赖:

  npm install

• 配置环境变量: 复制 .env.example 文件为 .env，并根据你的本地环境修改其中的值。

  cp .env.example .env
  # 编辑 .env 文件

  至少需要配置 PORT 和图片/缓存目录路径 (如果与默认不同)。
• 启动开发服务器:

  npm run dev

  服务器将启动 (通常在 http://localhost:3000，取决于 .env 中的 PORT 设置)，并使用 nodemon 监控文件更改自动重启。

3. 本地开发 (使用 Docker Compose)

• 配置环境变量: Docker Compose 会自动加载项目根目录下的 .env 文件。确保 .env 文件已根据你的需求配置。
• 构建并启动服务:

  docker-compose up --build

  服务将在 Docker 容器中运行，通常可以通过 http://localhost:3000 访问。
• 查看日志:

  docker-compose logs -f app

• 停止服务:

  docker-compose down

4. API 端点示例

假设服务器运行在 http://localhost:3000。

• 处理图片: GET /<sourceName>/images/<imageFilename>?param1=value1&param2=value2

  • <sourceName>: 图片源的名称 (在 config/index.js 中定义，例如 local, upload)。
  • <imageFilename>: 图片文件名。
  • 示例:
    • 调整 'local' 源的 'nature.jpg' 宽度为 300px: http://localhost:3000/local/images/nature.jpg?w=300
    • 裁剪 'upload' 源的 'myphoto.png' 为 200x150, 并转换为 webp 格式: http://localhost:3000/upload/images/myphoto.png?w=200&h=150&crop=true&format=webp

• 支持的图片处理参数 (示例，具体请参考 src/processing/sharpProcessor.js):

  • w: 宽度 (像素)
  • h: 高度 (像素)
  • crop: 是否裁剪 (true 或 false)。通常与 w 和 h 结合使用。
  • fit: Sharp 的 fit 选项 (如 cover, contain, fill, inside, outside)。
  • gravity: Sharp 的 gravity 选项 (如 north, center, attention, entropy)，用于裁剪焦点。
  • format: 输出图片格式 (如 jpeg, png, webp, gif, tiff)。
  • q: 图片质量 (1-100，主要对 jpeg 和 webp 有效)。
  • (更多参数可根据 sharpProcessor.js 的实现添加)

• 上传图片: POST /<sourceName>/images

  • <sourceName>: 通常是配置为允许上传的源，例如 upload。
  • 请求体需要是 multipart/form-data，包含一个名为 imageFile 的文件字段。
  • 示例 (使用 curl):

    curl -X POST -F "imageFile=@/path/to/your/image.jpg" http://localhost:3000/upload/images

  • 成功后会返回包含上传文件信息的 JSON 对象，包括处理该图片的 URL。
  • 项目可能提供一个简单的 HTML 上传表单，例如访问 http://localhost:3000/upload-form (如果已配置)。

部署方式

1. 使用 Docker (推荐)

• 构建 Docker 镜像:

  docker build -t your-username/image-processor-service:latest .

• 推送到镜像仓库 (可选但推荐):

  docker login your-registry.com # 例如 Docker Hub, AWS ECR, Google GCR
  docker push your-username/image-processor-service:latest

• 部署到生产环境:

  • Kubernetes: 创建 Deployment 和 Service YAML 文件，使用 PersistentVolumeClaims 处理持久化存储 (上传的图片、文件缓存)。通过 Ingress 暴露服务。
  • AWS ECS: 创建 Task Definition 和 Service。使用 EFS 或 S3 (通过应用逻辑) 进行持久化存储。使用 Application Load Balancer。
  • PaaS 平台 (如 Heroku, Render, Fly.io): 如果平台支持从 Docker 镜像部署，按照其文档操作。配置环境变量和持久化存储 (如果平台提供)。
  • 单个 VPS: 可以使用 docker run 命令，或继续使用 docker-compose.yml (调整配置以适应生产)。强烈建议在 Node.js 应用前配置 Nginx 或 Apache 作为反向代理，处理 SSL 终止、静态资源、负载均衡等。

  生产 Docker 运行示例 (简版，假设镜像已构建):

  docker run -d \
    --name image-processor \
    -p 8080:3000 \ # 将主机的 8080 映射到容器的 3000 (假设Nginx在主机80处理请求)
    -v /path/on/host/uploaded_images:/usr/src/app/uploaded_images \ # 持久化上传目录
    -v /path/on/host/cached_images:/usr/src/app/cached_images \   # 持久化缓存目录
    -e NODE_ENV=production \
    -e PORT=3000 \
    -e UPLOAD_IMAGES_PATH=/usr/src/app/uploaded_images \
    -e CACHE_DIR=/usr/src/app/cached_images \
    # ... 其他生产环境变量 (S3 密钥, Redis 连接等) ...
    your-username/image-processor-service:latest

  重要: 对于生产环境中的 uploaded_images 和 cached_images (如果是文件系统缓存)，强烈建议使用云存储服务 (如 AWS S3, Google Cloud Storage) 或分布式缓存 (如 Redis, Memcached) 而不是本地卷挂载，以实现更好的可扩展性和可靠性。

2. 非 Docker 部署 (传统方式)

• 将项目代码（不包括 node_modules）部署到服务器。
• 在服务器上安装 Node.js 和 npm/yarn。
• 安装生产依赖: npm install --production。
• 配置生产环境变量 (例如通过系统环境变量、.bashrc、或特定于部署工具的方式)。
• 使用进程管理器 (如 PM2 或 systemd) 启动和管理 Node.js 应用，确保其在后台运行并在崩溃时自动重启。

  # 使用 PM2 示例
  pm2 start server.js --name image-processor-api -i max # -i max 启动集群模式
  pm2 startup # 设置 PM2 开机自启
  pm2 save    # 保存当前进程列表

• 配置 Web 服务器 (Nginx/Apache) 作为反向代理。

环境变量配置 (生产)

在生产环境中，绝不使用 .env 文件。环境变量应通过部署平台提供的安全机制进行配置。关键环境变量包括：

• NODE_ENV=production
• PORT
• 图片源和缓存目录的路径 (如果使用本地文件系统，应指向持久化存储位置)
• 数据库连接字符串 (如果使用)
• 云服务凭证 (AWS keys, S3 bucket names, Redis connection strings等)
• 任何 API 密钥

贡献

欢迎提交 Pull Requests 或 Issues 来改进此项目！

在提交代码前，请确保：

1. 代码符合项目的 ESLint 规范 (npm run lint)。
2. (如果适用) 添加了必要的测试并通过了所有测试 (npm test)。
3. 更新了相关文档。

许可证

本项目使用 MIT 许可证。