[开源自荐] Jellyfin / Emby 媒体库封面设计与定时更新工具，附 Compose 部署教程

给 Jellyfin / Emby 的媒体库做封面，通常要自己排图、导出，再逐个上传。想让封面展示最近入库的内容，还得定期重复这一遍。

我做的 LibraryCoverStudio 把模板编辑、海报取材、预览和定时上传接到一起。下面直接从部署开始，配一个每周自动更新电影库封面的任务。

处理的是「电影」「剧集」这些媒体库分类封面。应用通过 API 读取海报，不需要挂载影片目录；普通编辑与自动化不依赖 AI 。

一、用 Docker Compose 启动

需要已有 Docker 和 Compose v2 ，以及可以正常使用的 Jellyfin / Emby 服务器。

新建一个空目录，在里面保存 compose.yaml：

services:
  library-cover-studio:
    image: evanqu/library-cover-studio:latest
    restart: unless-stopped
    environment:
      JWT_SECRET: "REPLACE_WITH_RANDOM_JWT_SECRET"
      ENCRYPTION_KEY: "REPLACE_WITH_RANDOM_ENCRYPTION_KEY"
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data

将两处占位文字分别替换成不同的随机密钥，可用 openssl rand -hex 32 分别生成。然后在同目录执行：

docker compose up -d

浏览器打开 http://你的 NAS 地址:8080，点击「立即注册」创建账号，第一个账号成为管理员。本机部署可访问 http://localhost:8080。

网页、API 、封面渲染和定时任务在一个容器里运行，持久化数据保存在同目录的 data 中。

二、连接 Jellyfin / Emby

先在媒体服务器管理后台创建 API 密钥，然后进入工具的「媒体源 → 添加服务器」，填写：

字段	填写内容
名称	自己能区分的名称，例如「家里的 Jellyfin 」
类型	Jellyfin 或 Emby
地址	容器可访问的服务器地址，例如 `http://192.168.1.20:8096`
API 密钥	需要能够读取海报、更新媒体库封面

测试连接，确认状态为「在线」，再点「媒体库」检查能否读到目标分类。

这里容易填错的是地址。 媒体服务器装在 NAS 上时，通常填 NAS 的局域网 IP ；容器里的 localhost 指向容器自身。

三、选择模板，需要改布局再进设计器

内置 7 套模板，可以直接用于任务；需要改排版时，在「模板库」复制一份，再进入设计器调整文字、海报位置、配色和图层。社区模板也可以下载使用，或通过 ZIP 导入导出。

自定义模板时，主、副标题分别使用 {{primary_title}}、{{secondary_title}}，海报使用 post1～post9 占位。这样同一套布局可以给不同媒体库填入各自的标题和素材。

改完先保存模板，任务读取的是已保存的版本。

四、新建任务，先生成真实样张

进入「自动化 → 新建任务」，填写任务名称，选择刚连接的服务器。第一次只勾选一个电影库，方便确认效果。

下一步配置封面，可以先用下面这组：

配置项	示例
封面模板	柔彩扇形
主标题	电影
副标题	MOVIE COLLECTION
素材排序	最近加入

「最近加入」适合展示新入库内容；想周期性换一批素材，可以选「随机选取」。有多个媒体库时，可以先批量应用模板，再逐库调整。

点右侧「生成真实样张」，检查换成自己片库的海报后，标题、素材和布局是否合适。这一步只渲染预览，不上传，也不修改媒体服务器。 改了配置后，需要重新生成样张。

五、设置计划，再手动执行一次验收

以每周一凌晨 04:00 更新为例：选择「按计划运行」，频率选每周，星期选周一，时间设为 04:00 。核对页面显示的调度时区和未来三次执行时间，再勾选「保存后启用此计划」。

也支持每天、每月和自定义 Cron ；只想手动换图，就选择「手动运行」。

最后检查配置并创建任务。保存任务不会立即上传，可以在列表点击「立即执行」验收。执行会读取素材、渲染封面，再替换所选媒体库的分类封面，想保留原图请提前备份。

运行后到「执行历史」查看逐库结果，以及当次生成的封面；再回 Jellyfin / Emby 刷新首页，确认实际显示。

六、几个常见卡点

情况	先检查什么
连接不上媒体服务器	地址能否从容器访问、API 密钥权限，是否误填了 `localhost`
任务里改了标题，成品没变	模板是否使用标题变量，修改后是否已保存
到点没更新	任务是否启用、容器是否运行、页面显示的时区和下次执行时间
渲染成功但上传失败	执行历史的错误信息、媒体服务器 API 权限和网络

定时任务需要容器持续运行，停机错过的执行不会自动补跑；它按计划更新，不是新增影片后立即触发。

升级前备份 compose.yaml 和完整的 data 目录，保留原来的两个密钥，再执行：

docker compose pull
docker compose up -d

更多配置见部署文档和自动化使用指南。

第一次可以先把「一个电影库 → 生成真实样张 → 手动执行 → 查看结果」走通，再扩展到其他媒体库和周期任务。