npulidom/giger

Giger

用于图片调整大小/压缩并集成AWS S3上传功能的容器服务（或独立S3上传）。该服务需MongoDB集合存储调整/上传过程信息，支持多配置文件。

核心功能与特性

• 支持多尺寸图片调整
• 验证图片尺寸及宽高比
• 支持大文件（超过100MB）的异步分块上传
• 基于NodeJs和Sharp（libvips图像处理库）构建

支持的图片格式

• webp
• avif
• jpeg
• png

环境变量配置

yml
MONGO_URL: MongoDB连接URL，必填（例如：mongodb://mongo/app）
MONGO_COLLECTION: MongoDB集合名称，默认值为'giger'（可选）
ALLOWED_ORIGINS: CORS跨域访问控制（可选）
AWS_ACCESS_KEY_ID: AWS访问密钥ID（可选）
AWS_SECRET_ACCESS_KEY: AWS密钥（可选）
API_KEY: 基础安全验证的API密钥，需通过请求头'X-Api-Key'传递（可选）
MAX_FILE_SIZE: 上传文件的最大限制（字节），默认无限制（可选）

AWS凭证配置

AWS凭证可通过环境变量加载，但生产环境推荐使用IAM角色。

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY

建议始终限制权限范围至指定存储桶：

json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:GetObjectAcl",
                "s3:PutObject",
                "s3:PutObjectAcl",
                "s3:ListBucket"
            ],
            "Resource": "arn:aws:s3:::my-bucket-name/*"
        }
    ]
}

MongoDB集合结构

需创建名称为{MONGO_COLLECTION}（默认giger）的集合，且至少包含default配置文件。详见https://github.com/npulidom/giger/blob/master/sample/db.json%E3%80%82

javascript
{
    "name": "default", // 必填，配置文件名称
    "bucket": {
        "name": "my-bucket-name", // 存储桶名称
        "basePath": "giger",      // 可选，默认根路径
        "region": "us-east-1",    // 可选，默认"us-east-1"
        "cloudfront": {           // 可选，使用Cloudfront URL覆盖S3 URL
            "url": "https://some.custom.site", // Cloudfront URL
            "excludePath": "giger"             // 可选，从Cloudfront URL中排除s3路径
        }
    },
    "objects": {
        "avatar": { // 对象类型名称，例如"avatar"（头像）
            "bucketPath": "avatars",     // 可选，存储桶子路径前缀
            "mimeTypes": ["image/jpeg"], // 必填，支持的MIME类型，如['image/jpeg','image/png','image/webp']
            "outputFormat": "webp",      // 可选，默认与输入格式相同（若支持）；可选值：webp, avif, jpeg, png
            "acl": "public-read",        // 可选，默认私有（无ACL）
            "maxAge": 86400,             // 可选，默认1年
            "async": false,              // 可选，大文件异步分块上传，输出URL将稍后保存至其他集合
            "constraints": {             // 可选，图片约束条件
                "minWidth": 300,  // 最小宽度
                "minHeight": 300, // 最小高度
                "ratio": "3/2"    // 宽高比约束
            },
            "transforms": [ // 转换规则列表，生成不同尺寸的缩略图
                {
                    "name": "L",  // 缩略图版本名称
                    "width": 300, // 调整宽度，高度按比例自动计算
                    "quality": 90 // 质量（1-100）
                },
                {
                    "name": "M",
                    "width": 150,
                    "quality": 80
                },
                {
                    "name": "S",
                    "width": 100,
                    "quality": 70
                },
                {
                    "name": "B",
                    "width": 100,
                    "quality": 21,
                    "blur": 8      // 可选，模糊效果（像素值）
                }
            ]
        },
        // 支持大文件上传示例
        "video": {
            "bucketPath": "videos/",
            "mimeTypes": ["video/mp4"],
            "maxAge": 86400,
            "async": true
        }
    }
}

使用方法

拉取镜像

bash
docker pull npulidom/giger

运行容器

bash
docker run -p 8080:80 --env-file .env npulidom/giger

API端点

POST ./upload

bash
[POST] multipart/form-data
Content-Disposition: form-data; name="file"; type="image/jpeg"; filename="some-picture.jpeg"

> https://{host}/upload/:profile/:object
> https://{host}/upload/:profile/:object/:tag

# 示例
https://services.some-app.com/giger/upload/default/avatar
https://services.some-app.com/giger/upload/default/avatar/0
https://services.some-app.com/giger/upload/default/avatar/123456

• profile：配置文件名称，例如default。
• object：对象类型名称，例如avatar。
• tag：可选，自定义值替换自动生成的文件名；设为0或省略则保留自动生成文件名。

成功响应

bash
{
    "status": "ok",
    "urls": [
      "https://my-bucket-name.s3.amazonaws.com/giger/avatars/avatar-298434f20f0327aa83a30dc15f880fda.jpg",
      "https://my-bucket-name.s3.amazonaws.com/giger/avatars/avatar-298434f20f0327aa83a30dc15f880fda_L.jpg",
      "https://my-bucket-name.s3.amazonaws.com/giger/avatars/avatar-298434f20f0327aa83a30dc15f880fda_M.jpg",
      "https://my-bucket-name.s3.amazonaws.com/giger/avatars/avatar-298434f20f0327aa83a30dc15f880fda_S.jpg",
      "https://my-bucket-name.s3.amazonaws.com/giger/avatars/avatar-298434f20f0327aa83a30dc15f880fda_B.jpg"
    ],
    "ratio": "1:1"
}

错误响应

bash
{
    "status": "error",
    "error": "SOME_ERROR"
}

GET ./health

服务包含./health端点用于健康检查：

bash
[GET] https://{host}/health

应用负载均衡器（ALB）

服务支持通过服务路径路由转发，例如：

bash
https://services.some.app/giger/health
https://services.some.app/giger/upload/:profile/:object
https://services.some.app/giger/upload/:profile/:object/:tag

测试

使用curl上传文件示例：

bash
# 上传图片
curl -F 'file=@sample/lena.jpg' http://g-giger.localhost/upload/default/avatar

# 上传视频
curl -F 'file=@sample/some-video.mp4;type=video/mp4' http://g-giger.localhost/upload/default/video