GeoKrety Pictures Processor Docker镜像文档

镜像概述

GeoKrety Pictures Processor 是 GeoKrety 项目的内部图片处理守护进程，用于自动化处理用户上传的图片。该服务通过响应 S3 兼容存储的 webhook 事件触发图片处理流程，处理完成后将结果上传回指定存储桶，主要用于支持 GeoKrety.org 平台的图片管理需求。

核心功能与特性

核心功能

图片缩小处理：将上传的图片按配置的最大尺寸进行缩小，确保图片文件大小和分辨率符合平台要求。
缩略图生成：为上传的图片自动创建缩略图，便于快速预览和展示。

特性

事件驱动：通过监听 S3 webhook 事件（如用户上传图片）触发处理流程，实现自动化处理。
闭环处理：处理完成的图片（缩小版及缩略图）自动上传回指定的 S3 存储桶，无需人工干预。
轻量高效：作为守护进程运行，持续监控并处理图片任务，资源占用低。

使用场景与适用范围

主要场景

GeoKrety.org 平台内部服务：用于处理用户上传至平台的图片，确保图片格式、尺寸符合应用规范。
用户上传图片自动化处理：适用于需要对用户上传图片进行标准化处理（如尺寸限制、缩略图生成）的场景。

适用范围

与 S3 兼容的对象存储服务（如 AWS S3、MinIO 等）集成的环境。
需要自动化图片处理流程，减少人工干预的应用场景。

使用方法与配置说明

环境要求

Docker 环境（1.13+）。
可访问的 S3 兼容存储服务（需配置访问权限及 webhook 通知）。

Docker 部署示例

1. 基础运行命令（`docker run`）

bash
docker run -d \
  --name geokrety-pictures-processor \
  -e AWS_ACCESS_KEY_ID="your-s3-access-key" \
  -e AWS_SECRET_ACCESS_KEY="your-s3-secret-key" \
  -e S3_SOURCE_BUCKET="user-uploads-bucket" \
  -e S3_DESTINATION_BUCKET="processed-images-bucket" \
  -e WEBHOOK_SECRET="your-webhook-signature-secret" \
  -e MAX_IMAGE_SIZE="1920x1080" \  # 最大图片尺寸（宽x高）
  -e THUMBNAIL_SIZE="200x200" \     # 缩略图尺寸（宽x高）
  geokrety/geokrety-pictures-processor:latest

2. Docker Compose 配置示例

yaml
version: '3.8'
services:
  pictures-processor:
    image: geokrety/geokrety-pictures-processor:latest
    container_name: geokrety-pictures-processor
    restart: always
    environment:
      - AWS_ACCESS_KEY_ID=your-s3-access-key
      - AWS_SECRET_ACCESS_KEY=your-s3-secret-key
      - S3_SOURCE_BUCKET=user-uploads-bucket
      - S3_DESTINATION_BUCKET=processed-images-bucket
      - S3_REGION=us-east-1
      - WEBHOOK_SECRET=your-webhook-signature-secret
      - MAX_IMAGE_SIZE=1920x1080  # 最大图片分辨率限制
      - THUMBNAIL_SIZE=200x200    # 缩略图分辨率
      - LOG_LEVEL=info            # 日志级别（debug/info/warn/error）

关键配置参数（环境变量）

环境变量	描述	类型	是否必填	默认值
`AWS_ACCESS_KEY_ID`	S3 存储服务的访问密钥 ID	字符串	是	-
`AWS_SECRET_ACCESS_KEY`	S3 存储服务的密钥	字符串	是	-
`S3_SOURCE_BUCKET`	监听图片上传事件的源存储桶名称	字符串	是	-
`S3_DESTINATION_BUCKET`	处理后图片的目标存储桶名称	字符串	是	-
`S3_REGION`	S3 存储服务的区域	字符串	否	`us-east-1`
`WEBHOOK_SECRET`	S3 webhook 事件的签名验证密钥	字符串	是	-
`MAX_IMAGE_SIZE`	缩小后图片的最大分辨率（格式：`宽x高`）	字符串	否	`1920x1080`
`THUMBNAIL_SIZE`	缩略图的分辨率（格式：`宽x高`）	字符串	否	`200x200`
`LOG_LEVEL`	日志输出级别	字符串	否	`info`

处理流程说明

事件触发：用户上传图片至 S3_SOURCE_BUCKET，触发 S3 存储服务发送 webhook 事件。
签名验证：服务使用 WEBHOOK_SECRET 验证事件签名，确保请求合法性。
图片处理：
- 下载源图片并按 MAX_IMAGE_SIZE 缩小尺寸。
- 基于缩小后的图片生成 THUMBNAIL_SIZE 规格的缩略图。
结果上传：将缩小后的图片和缩略图上传至 S3_DESTINATION_BUCKET。
日志记录：按 LOG_LEVEL 输出处理过程日志，便于问题排查。