xylplm/media-saber-media-cover-generator

By xylplm

•Updated 8 months ago

Image

Integration & delivery

API management

10K+

Overview Tags

xylplm/media-saber-media-cover-generator repository overview

⁠媒体封面生成 API 服务

专为媒体库自动生成美观封面图片的 Docker 服务，支持多种样式，开箱即用。主要服务于 Media Saber，其他工具也可以通过 API 调用使用。

⁠✨ 主要特性

🚀 零配置启动 - 拉取镜像即可运行，无需任何配置
🎨 多种样式 - 单图样式 1、单图样式 2、多图样式 1、多图样式 2、多图样式 3
🖼️ 智能缓存 - 自动缓存图片和字体，提升生成速度
🐳 Docker 部署 - 仅需 Docker，无需安装其他依赖
⚙️ 灵活配置 - 支持环境变量和配置文件自定义

⁠🚀 快速开始

⁠Docker Compose（推荐）

创建 docker-compose.yml：

version: '3.8'
services:
  media-cover:
    image: xylplm/media-saber-media-cover-generator:latest
    ports:
      - "9897:9897"
    volumes:
      - ./config:/app/config
    environment:
      - TZ=Asia/Shanghai

启动服务：

docker-compose up -d

⁠Docker 命令行

docker run -d \
  -p 9897:9897 \
  -v ./config:/app/config \
  -e TZ=Asia/Shanghai \
  xylplm/media-saber-media-cover-generator:latest

⁠验证服务

访问 http://localhost:9897/health 检查服务状态。

⁠⚙️ 配置说明

⁠🎯 零配置启动

默认情况下，服务无需任何配置即可启动使用！ 所有配置项都有合理的默认值。

⁠📋 配置类型

配置分为两类，互相独立，各有默认值：

⁠1️⃣ 环境配置（通过环境变量）

用于控制服务器运行环境：

环境变量	说明	默认值
`PORT`	服务端口	`9897`
`HOST`	服务主机	`0.0.0.0`
`READ_TIMEOUT`	读取超时(秒)	`30`
`WRITE_TIMEOUT`	写入超时(秒)	`300` (5分钟)
`IDLE_TIMEOUT`	空闲超时(秒)	`120` (2分钟)
`CONFIG_DIR`	配置目录	`./config`
`CACHE_MAX_SIZE`	最大缓存大小(字节)	`1073741824` (1GB)
`CACHE_TTL`	缓存过期时间(小时)	`24`
`LOG_LEVEL`	日志级别	`info`
`LOG_FORMAT`	日志格式	`json`
`LOG_OUTPUT`	日志输出	`stdout`

Docker 示例：

docker run -d \
  -p 8080:8080 \
  -e PORT=8080 \
  -e LOG_LEVEL=debug \
  -e WRITE_TIMEOUT=600 \
  -v ./config:/app/config \
  xylplm/media-saber-media-cover-generator:latest

⁠2️⃣ 业务配置（通过配置文件）

用于自定义业务逻辑（字体、图片、模板），在 config/config.yaml 中配置。

重要：

启动时会自动复制 config.example.yaml 到 config/ 目录作为参考
只需配置要自定义的部分，未配置的自动使用默认值
配置文件为 config/config.yaml（可选）

⁠📝 业务配置示例

⁠自定义输出尺寸

创建 config/config.yaml：

template:
  output_width: 3840
  output_height: 2160

⁠使用自定义字体

步骤：

将字体文件放到 ./config/fonts/ 目录（宿主机路径）
创建 config/config.yaml 配置文件：

font:
  chinese:
    local_path: "/app/config/fonts/my-font.ttf"  # 容器内路径
  english:
    local_path: "/app/config/fonts/my-en-font.ttf"

路径说明：

宿主机路径：./config/fonts/my-font.ttf
容器内路径：/app/config/fonts/my-font.ttf（配置文件中使用）
Docker 挂载会自动映射：./config:/app/config

验证配置：

服务启动后会在日志中显示字体加载状态：

✅ 成功加载会显示：✅ 成功加载自定义字体
⚠️ 失败会显示：自定义字体加载失败，将使用预制字体（并说明原因）

查看日志确认字体加载状态：

docker logs <container-name>

注意：如果自定义字体加载失败，服务会自动降级使用预制字体，不会影响正常运行。

⁠添加媒体库映射

template:
  library_mappings:
    "电影": "single_1"
    "电视剧": "multi_1"
    "动漫": "multi_2"

⁠自定义图片处理

image:
  max_size: 52428800  # 50MB
  quality: 90
  download_timeout: 60  # 下载超时60秒

⁠完整配置示例

# 图片处理配置（可选，默认值已优化）
image:
  max_size: 52428800        # 最大图片大小(字节) (默认: 50MB)
  max_width: 4096           # 最大图片宽度 (默认: 4096)
  max_height: 4096          # 最大图片高度 (默认: 4096)
  quality: 90               # 图片质量 1-100 (默认: 85)
  download_timeout: 60      # 下载超时(秒) (默认: 60)
  max_retries: 3            # 最大重试次数 (默认: 3)

# 字体配置（可选，默认使用预制字体）
font:
  chinese:
    name: "自定义中文字体"     # 字体名称
    local_path: "/app/config/fonts/chinese.ttf"  # 容器内路径
    size: 1.0               # 字体大小倍数 (默认: 1.0)
  english:
    name: "自定义英文字体"     # 字体名称
    local_path: "/app/config/fonts/english.ttf"  # 容器内路径
    size: 1.0               # 字体大小倍数 (默认: 1.0)
  download_timeout: 30      # 字体下载超时(秒) (默认: 30)
  max_retries: 3            # 最大重试次数 (默认: 3)

# 模板配置（可选，默认值已优化）
template:
  output_width: 3840        # 输出图片宽度 (默认: 1920)
  output_height: 2160       # 输出图片高度 (默认: 1080)
  default_template: "single_1"  # 默认模板 (默认: single_1)
  
  # 自定义样式配置（可选）
  styles:
    single_1:
      name: "单图样式1"
      description: "简洁风格的单图封面"
      blur_size: 50         # 模糊大小 0-200
      color_ratio: 0.8      # 颜色比例 0-1
      use_primary: false    # 是否使用主色调
    single_2:
      name: "单图样式2"
      blur_size: 30
      color_ratio: 0.6
      use_primary: true
  
  # 媒体库到模板的映射（可选）
  library_mappings:
    "电影": "single_1"
    "电视剧": "multi_1"
    "动漫": "multi_2"

⁠🐳 Docker 部署场景

⁠场景 1：完全默认（推荐新手）

version: '3.8'
services:
  media-cover:
    image: xylplm/media-saber-media-cover-generator:latest
    ports:
      - "9897:9897"
    volumes:
      - ./config:/app/config

无需任何配置，直接启动即可使用。

⁠场景 2：自定义端口和日志级别

version: '3.8'
services:
  media-cover:
    image: xylplm/media-saber-media-cover-generator:latest
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - LOG_LEVEL=debug
    volumes:
      - ./config:/app/config

⁠场景 3：生产环境推荐配置

version: '3.8'
services:
  media-cover:
    image: xylplm/media-saber-media-cover-generator:latest
    ports:
      - "9897:9897"
    environment:
      - LOG_LEVEL=info
      - LOG_FORMAT=json
      - WRITE_TIMEOUT=300
      - CACHE_MAX_SIZE=2147483648  # 2GB
    volumes:
      - ./config:/app/config
    restart: unless-stopped

⁠场景 4：自定义字体和尺寸

将字体文件放到 ./config/fonts/ 目录（宿主机路径）
- 例如：./config/fonts/my-font.ttf
创建 config/config.yaml：

font:
  chinese:
    # 容器内路径，对应宿主机的 ./config/fonts/my-font.ttf
    local_path: "/app/config/fonts/my-font.ttf"
template:
  output_width: 3840
  output_height: 2160

启动服务：

version: '3.8'
services:
  media-cover:
    image: xylplm/media-saber-media-cover-generator:latest
    ports:
      - "9897:9897"
    volumes:
      - ./config:/app/config

⁠📡 API 使用

⁠健康检查

curl http://localhost:9897/health

⁠获取模板列表

curl http://localhost:9897/api/templates

返回示例：

{
  "templates": [
    {
      "id": "single_1",
      "name": "单图样式 1",
      "description": "经典单图布局"
    },
    {
      "id": "single_2",
      "name": "单图样式 2",
      "description": "现代单图布局"
    },
    {
      "id": "multi_1",
      "name": "多图样式 1",
      "description": "3图横向排列"
    },
    {
      "id": "multi_2",
      "name": "多图样式 2",
      "description": "2+1图混合布局"
    },
    {
      "id": "multi_3",
      "name": "多图样式 3",
      "description": "5图横向布局，中间1张左右各2张阶梯倾斜"
    }
  ]
}

⁠生成封面

⁠基础请求示例

curl -X POST http://localhost:9897/api/generate-cover \
  -H "Content-Type: application/json" \
  -d '{
    "library": {
      "name": "电影",
      "titleZh": "示例电影",
      "titleEn": "Sample Movie"
    },
    "images": [
      {
        "url": "https://example.com/poster.jpg",
        "type": "poster"
      }
    ]
  }' \
  --output cover.jpg

⁠多图片请求示例

curl -X POST http://localhost:9897/api/generate-cover \
  -H "Content-Type: application/json" \
  -d '{
    "library": {
      "name": "电视剧",
      "titleZh": "示例电视剧",
      "titleEn": "Sample TV Series"
    },
    "images": [
      {
        "url": "https://example.com/poster1.jpg",
        "type": "poster"
      },
      {
        "url": "https://example.com/backdrop1.jpg",
        "type": "backdrop"
      },
      {
        "url": "https://example.com/backdrop2.jpg",
        "type": "backdrop"
      }
    ]
  }' \
  --output cover.jpg

⁠高级请求示例（指定模板和User-Agent）

curl -X POST http://localhost:9897/api/generate-cover \
  -H "Content-Type: application/json" \
  -d '{
    "library": {
      "name": "电视剧",
      "titleZh": "示例电视剧",
      "titleEn": "Sample TV Series"
    },
    "images": [
      {
        "url": "https://example.com/poster.jpg",
        "type": "poster"
      }
    ],
    "templateId": "multi_1",
    "userAgent": "Media Saber v1.0",
    "lowPerformanceMode": false
  }' \
  --output cover.jpg

⁠请求参数说明

library 对象（必填）：

name (string) - 媒体库名称，必填。如：电影、电视剧、动漫等
titleZh (string) - 中文标题，必填。如：示例电影
titleEn (string) - 英文标题，必填。如：Sample Movie

images 数组（必填）：

至少需要 1 张图片，最多建议 5 张
每张图片包含：
- url (string) - 图片网络地址，必填
- type (string) - 图片类型，可选。支持：
  - poster - 海报（默认值）
  - backdrop - 背景图
  - logo - 标志

其他参数（可选）：

templateId (string) - 指定使用的模板ID。可选值：single_1、single_2、multi_1、multi_2、multi_3。不指定时使用默认模板
userAgent (string) - 自定义 User-Agent 字符串
lowPerformanceMode (boolean) - 低性能模式开关（默认 false），启用时会降低并发和资源占用

⁠返回示例

{
  "success": true,
  "coverImage": "base64编码的图片数据...",
  "format": "jpeg",
  "size": {
    "width": 1920,
    "height": 1080
  }
}

保存返回的图片：

# 方法1：curl 自动保存
curl -X POST http://localhost:9897/api/generate-cover ... --output cover.jpg

# 方法2：使用 jq 提取 base64 并保存
curl -s -X POST http://localhost:9897/api/generate-cover ... | \
  jq -r '.coverImage' | base64 -d > cover.jpg

⁠📂 目录结构

config/                          # Docker 挂载点
├── config.yaml                  # 用户配置文件（可选）
├── config.example.yaml          # 配置示例（自动生成）
├── cache/                       # 缓存目录
│   ├── images/                 # 图片缓存
│   └── fonts/                  # 字体缓存
├── fonts/                       # 自定义字体（可选）
└── logs/                        # 日志文件（可选）

⁠🎨 模板样式说明

⁠single_1 - 单图样式 1

经典单图布局
适合电影、纪录片
突出显示主标题

⁠single_2 - 单图样式 2

现代单图布局
适合电影、动漫
标题居中，设计简洁

⁠multi_1 - 多图样式 1

3图横向排列
适合电视剧、综艺
展示多集/多期内容

⁠multi_2 - 多图样式 2

2+1图混合布局
适合电视剧、动漫
主次分明的图片排列

⁠multi_3 - 多图样式 3

5图横向阶梯布局
中间1张居中，左右各2张阶梯倾斜
适合电视剧、综艺、动漫
展示丰富的剧集内容

⁠🔧 常见问题

⁠Q: 如何更改服务端口？

A: 通过环境变量 PORT：

docker run -e PORT=8080 -p 8080:8080 ...

⁠Q: 如何使用自定义字体？

将字体文件放到 ./config/fonts/ 目录（宿主机路径）
创建 config/config.yaml：

font:
  chinese:
    # 注意：这是容器内路径，Docker会自动映射 ./config -> /app/config
    local_path: "/app/config/fonts/my-font.ttf"

路径映射关系：

宿主机：./config/fonts/my-font.ttf
容器内：/app/config/fonts/my-font.ttf（配置中使用）

⁠Q: 如何调整输出尺寸？

A: 在 config/config.yaml 中配置：

template:
  output_width: 3840
  output_height: 2160

⁠Q: 如何查看日志？

A: 通过 Docker 命令：

docker logs media-cover-generator

或配置日志输出到文件：

docker run -e LOG_OUTPUT=file ...

日志文件位于 config/logs/app.log。

⁠Q: 服务占用多少存储空间？

镜像大小：约 100-200MB
缓存大小：默认最大 1GB（可通过 CACHE_MAX_SIZE 调整）
建议预留：2-5GB 存储空间

⁠Q: 如何清理缓存？

A: 删除缓存目录：

rm -rf ./config/cache/*

或设置缓存过期时间（默认 24 小时）：

docker run -e CACHE_TTL=12 ...  # 12小时过期

⁠Q: 需要配置文件吗？

A: 不需要！所有配置都有默认值，可以零配置启动。只有需要自定义时才创建 config/config.yaml。

⁠Q: 环境变量和配置文件的区别？

环境变量：控制服务器运行环境（端口、日志、缓存等）
配置文件：控制业务逻辑（字体、图片、模板等）
两者互相独立，各有默认值

⁠📊 默认配置参考

⁠环境配置默认值

配置项	默认值
服务端口	9897
服务主机	0.0.0.0
读取超时	30秒
写入超时	300秒（5分钟）
空闲超时	120秒（2分钟）
缓存大小	1GB
缓存过期	24小时
日志级别	info

⁠业务配置默认值

配置项	默认值
输出宽度	1920
输出高度	1080
图片质量	85
图片最大大小	50MB
下载超时	60秒
默认模板	single_1
可用样式	5种（single_1, single_2, multi_1, multi_2, multi_3）

⁠🔄 升级指南

⁠拉取新版本

docker-compose pull
docker-compose up -d

或：

docker pull xylplm/media-saber-media-cover-generator:latest
docker-compose up -d

⁠数据迁移

升级不影响现有数据：

配置文件保持不变
缓存自动继承
无需手动迁移

⁠🛠️ 性能优化建议

⁠1. 调整缓存大小

根据使用频率调整缓存：

# 高频使用：增大缓存
docker run -e CACHE_MAX_SIZE=5368709120 ...  # 5GB

# 低频使用：减小缓存
docker run -e CACHE_MAX_SIZE=536870912 ...   # 512MB

⁠2. 调整超时时间

根据网络环境调整：

# 网络较慢：增加超时
docker run -e WRITE_TIMEOUT=600 ...  # 10分钟

在 config/config.yaml 中：

image:
  download_timeout: 60  # 下载超时60秒

⁠3. 日志级别

生产环境建议使用 info 或 warn：

docker run -e LOG_LEVEL=warn ...

⁠📞 支持

问题反馈：提交 Issue 到项目仓库
功能建议：欢迎提交 Feature Request
文档更新：定期查看最新文档

⁠📄 许可证

MIT License

享受自动化封面生成带来的便利！ 🎉

Tag summary

Recent tags

Content type

Image

Digest

sha256:1d64ce846…

Size

29.6 MB

Last updated

8 months ago

docker pull xylplm/media-saber-media-cover-generator:DEV_202512021056