Posterizarr安装与配置完全手册：Windows、Linux与Docker环境一键部署

【免费下载链接】Posterizarr🖼️ Automated poster maker for Plex/Jellyfin/Emby.项目地址: https://gitcode.com/gh_mirrors/po/Posterizarr

Posterizarr是一款强大的自动化海报生成工具，专为Plex、Jellyfin和Emby媒体服务器设计。本指南将帮助你在Windows、Linux和Docker环境中快速部署和配置Posterizarr，轻松打造专业级媒体库海报系统。

📋 准备工作：系统要求与必要组件

在开始安装前，请确保你的系统满足以下要求，并准备好必要的API密钥：

核心依赖

• 媒体服务器：Plex、Jellyfin或Emby
• API密钥：
  • TMDB API Read Access Token（免费获取）
  • Fanart.tv个人API密钥（免费获取）
  • TVDB项目API密钥（免费获取）
• 运行环境：
  • Docker环境（推荐）或
  • PowerShell 7.x+、Python 3.x、Node.js（手动安装需满足）

图像尺寸要求

为获得最佳效果，Posterizarr推荐以下图像尺寸：

• 海报：1000×1500px（基础）或2000×3000px（4K）
• 背景图：1920×1080px（基础）或3840×2160px（4K）
• 标题卡片：1920×1080px（基础）或3840×2160px（4K）

Posterizarr生成的4K分辨率海报示例，展示了自动添加的文本和覆盖层效果

🐳 Docker部署：最简单的一键安装方案

Docker是部署Posterizarr的推荐方式，无需复杂的依赖管理，只需几步即可完成：

步骤1：准备Docker环境

确保你的系统已安装Docker和Docker Compose。如果尚未安装，可以参考Docker官方文档进行安装。

步骤2：创建Docker Compose文件

在你选择的目录中创建docker-compose.yml文件，内容如下：

--- services: posterizarr: hostname: "posterizarr" container_name: "posterizarr" environment: - "TZ=Europe/Berlin" # 替换为你的时区 - "TERM=xterm" - "RUN_TIME=disabled" image: "ghcr.io/fscorrupt/posterizarr:latest" restart: "unless-stopped" user: "1000:1000" # 替换为你的用户ID和组ID ports: - "8000:8000" # Web UI端口 volumes: - "/opt/appdata/posterizarr:/config:rw" - "/opt/appdata/posterizarr/assets:/assets:rw" - "/opt/appdata/posterizarr/assetsbackup:/assetsbackup:rw" - "/opt/appdata/posterizarr/manualassets:/manualassets:rw" networks: proxy: driver: bridge external: true

步骤3：启动容器

在终端中执行以下命令启动Posterizarr：

git clone https://gitcode.com/gh_mirrors/po/Posterizarr cd Posterizarr docker compose up -d

步骤4：访问Web UI

容器启动后，打开浏览器访问http://localhost:8000即可进入Posterizarr的Web管理界面。

Docker Compose部署Posterizarr的完整流程演示

💻 Windows系统手动安装

如果你需要在Windows系统上手动安装Posterizarr，请按照以下步骤操作：

步骤1：安装必要依赖

1. 安装PowerShell 7+
2. 安装Git for Windows
3. 安装Python 3.x和Node.js

步骤2：克隆代码库

打开PowerShell（以管理员身份运行），执行以下命令：

cd C:\Github git clone https://gitcode.com/gh_mirrors/po/Posterizarr cd Posterizarr

步骤3：安装Web UI依赖

cd webui setup.ps1 # 或 setup.bat

步骤4：启动服务

需要在两个独立的终端中分别启动后端和前端服务：

终端1（后端）：

cd webui/backend python -m uvicorn main:app --host 127.0.0.1 --port 8000

终端2（前端）：

cd webui/frontend npm run build

步骤5：首次运行测试

cd C:\Github\Posterizarr pwsh .\Posterizarr.ps1 -Testing

测试模式将在test目录下生成示例海报，帮助你预览效果。

🐧 Linux系统手动安装

Linux用户可以按照以下步骤手动安装Posterizarr：

步骤1：安装系统依赖

# 安装PowerShell sudo apt update && sudo apt install -y wget apt-transport-https software-properties-common wget -q "https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb" sudo dpkg -i packages-microsoft-prod.deb sudo apt update && sudo apt install -y powershell # 安装Git、Python和Node.js sudo apt install -y git python3 python3-pip nodejs npm

步骤2：克隆代码库并安装依赖

cd /opt/appdata git clone https://gitcode.com/gh_mirrors/po/Posterizarr cd Posterizarr # 安装Fanart API模块 pwsh Install-Module -Name Celerium.FanartTV -Scope AllUsers -Force -AllowClobber # 安装Web UI依赖 cd webui chmod +x setup.sh ./setup.sh

步骤3：启动服务

终端1（后端）：

cd /opt/appdata/Posterizarr/webui/backend python -m uvicorn main:app --host 0.0.0.0 --port 8000

终端2（前端）：

cd /opt/appdata/Posterizarr/webui/frontend npm run build

步骤4：设置定时任务

# 每2小时运行一次Posterizarr sudo crontab -e # 添加以下行 0 */2 * * * cd /opt/appdata/Posterizarr && pwsh Posterizarr.ps1 >/dev/null 2>&1

⚙️ 核心配置指南

无论你选择哪种安装方式，都需要进行基本配置才能让Posterizarr正常工作：

步骤1：配置文件准备

1. 将config.example.json复制为config.json：

   cp config.example.json config.json

2. 使用文本编辑器或Web UI编辑配置文件，至少需要填写以下API密钥：

   "ApiPart": { "tvdbapi": "你的TVDB API密钥", "tmdbtoken": "你的TMDB访问令牌", "FanartTvAPIKey": "你的Fanart.tv API密钥", "PlexToken": "你的Plex令牌（如果使用Plex）" }

步骤2：媒体服务器配置

根据你使用的媒体服务器，配置相应部分：

Plex示例：

"PlexPart": { "UsePlex": true, "PlexUrl": "http://192.168.1.100:32400", "LibstoExclude": ["YouTube", "Audiobooks"] }

Jellyfin示例：

"JellyfinPart": { "UseJellyfin": true, "JellyfinUrl": "http://192.168.1.101:8096", "JellyfinAPIKey": "你的Jellyfin API密钥" }

步骤3：自定义海报生成设置

你可以在config.json中调整各种参数来自定义海报效果，例如：

• 文本颜色和字体
• 边框样式和宽度
• 覆盖层效果
• 分辨率和质量设置

Posterizarr Web UI配置界面，可直观调整各种参数

🚀 快速开始：首次运行与测试

完成配置后，建议先运行测试模式来验证设置：

Docker用户：

docker exec -it posterizarr pwsh /app/Posterizarr.ps1 -Testing

手动安装用户：

# Windows pwsh .\Posterizarr.ps1 -Testing # Linux pwsh Posterizarr.ps1 -Testing

测试模式会在test目录下生成示例海报，你可以检查这些海报是否符合预期。如果需要调整，可以修改配置文件后重新运行测试模式。

满意后，即可执行完整运行：

# Docker docker exec -it posterizarr pwsh /app/Posterizarr.ps1 # 手动安装 pwsh Posterizarr.ps1

🔧 常见问题与故障排除

Web UI无法访问

• 检查服务是否正常运行：docker logs posterizarr
• 确认端口映射是否正确，防火墙是否允许8000端口
• 尝试访问http://服务器IP:8000而非localhost

海报生成失败

• 检查API密钥是否正确配置
• 确保媒体服务器可访问且API密钥有效
• 查看日志文件：logs/Scriptlog.log获取详细错误信息

性能优化建议

• 在低配置设备上，将ParallelJobs设置为1或2
• 对于大型媒体库，考虑分批次处理
• 启用DisableHashValidation可加快处理速度（可能重复上传）

📚 进阶资源

• 官方文档：docs/
• 配置示例：config.example.json
• Web UI源代码：webui/frontend/
• 模式说明：docs/modes.md

通过本指南，你已经掌握了Posterizarr在不同环境下的安装与配置方法。现在，你可以开始打造属于自己的专业媒体库海报系统了！如有任何问题，欢迎查阅项目文档或提交issue寻求帮助。

【免费下载链接】Posterizarr🖼️ Automated poster maker for Plex/Jellyfin/Emby.项目地址: https://gitcode.com/gh_mirrors/po/Posterizarr