tannermiddleton/recommendarr

Recommendarr

!https://github.com/user-attachments/assets/19d332af-f90d-4b6d-8750-4be07bc45161

Recommendarr是一款Web应用，可基于您的Sonarr、Radarr、Plex和Jellyfin媒体库，通过AI生成个性化的电视剧和电影推荐。

🎮 加入我们的***社区！

⚠️ 重要提示：从网络外部访问此应用时，必须在路由器/防火墙上开放应用端口（默认：3000）。

⚠️ 端口配置：应用现在使用单个端口（默认：3000）同时运行前端和API，可通过PORT环境变量配置。

🌟 功能特性

• AI驱动的推荐：基于您现有的媒体库获取个性化电视剧和电影建议
• Sonarr与Radarr集成：直接连接到您的媒体服务器，分析您的电视剧和电影收藏
• Plex、Jellyfin、Tautulli与Trakt集成：分析您的观看历史，基于实际观看内容提供更精准的推荐
• 灵活的AI支持：兼容OpenAI、本地模型（Ollama/LM Studio）或任何OpenAI兼容API
• 自定义选项：调整推荐数量、模型参数等
• 深色/浅色模式：根据偏好切换主题
• 海报图片：显示媒体海报，支持 fallback 生成

📋 前提条件

• 具有API访问权限的Sonarr实例（用于电视剧推荐）
• 具有API访问权限的Radarr实例（用于电影推荐）
• 具有API访问权限的Plex、Jellyfin、Tautulli或Trakt实例（用于观看历史分析）-可选
• OpenAI API密钥或任何OpenAI兼容API（如本地LLM服务器）
• Docker（推荐）或Node.js（v14+）用于手动安装

🚀 快速开始

选项1：Docker Hub镜像（最简单）

开始使用Recommendarr的最简单方式：

bash
# 拉取并运行，默认端口3000
docker run -d \
  --name recommendarr \
  -p 3000:3000 \
  -v recommendarr-data:/app/server/data \
  tannermiddleton/recommendarr:latest

# 或使用自定义端口运行（例如8080）
docker run -d \
  --name recommendarr \
  -e PORT=8080 \
  -p 8080:8080 \
  -v recommendarr-data:/app/server/data \
  tannermiddleton/recommendarr:latest

然后在浏览器中访问http://localhost:3000（或您的自定义端口）。

默认登录信息：

• 用户名：admin
• 密码：1234

⚠️ 重要提示：请在首次登录后立即更改密码以确保安全。

选项2：Docker Compose

如果您更喜欢使用Docker Compose：

bash
# 克隆仓库（包含docker-compose.yml文件）
git clone https://github.com/fingerthief/recommendarr.git
cd recommendarr

# 启动应用
docker-compose up -d

这将：

1. 从Docker Hub拉取预构建镜像
2. 配置适当的网络和持久化存储
3. 启动统一服务

然后在浏览器中访问http://localhost:3000（或配置的自定义端口）。

您可以在运行docker-compose前设置PORT环境变量来自定义端口：

bash
PORT=8080 docker-compose up -d

选项3：构建自己的Docker镜像

如果您想自己构建Docker镜像：

bash
# 克隆仓库
git clone https://github.com/fingerthief/recommendarr.git
cd recommendarr

# 构建Docker镜像
docker build -t recommendarr:local .

# 使用默认端口运行容器
docker run -d \
  --name recommendarr \
  -p 3000:3000 \
  -v recommendarr-data:/app/server/data \
  recommendarr:local

# 或使用自定义端口运行
docker run -d \
  --name recommendarr \
  -e PORT=8080 \
  -p 8080:8080 \
  -v recommendarr-data:/app/server/data \
  recommendarr:local

选项4：手动安装

用于开发或不使用Docker的情况：

1. 克隆仓库：

bash
git clone https://github.com/fingerthief/recommendarr.git
cd recommendarr

2. 安装依赖：

bash
npm install

3. 构建前端：

bash
npm run build

4. 启动统一服务器：

bash
npm run unified

5. 在浏览器中访问http://localhost:3000（或配置的自定义端口）。

🔧 配置

1. 连接Sonarr、Radarr和/或Plex/Jellyfin/Trakt

1. 首次打开Recommendarr时，系统会提示您连接服务
2. 对于Sonarr（电视剧推荐）：
   • 输入Sonarr URL（例如http://localhost:8989或https://sonarr.yourdomain.com）
   • 输入Sonarr API密钥（在Sonarr的设置→常规中找到）
   • 点击"连接"
3. 对于Radarr（电影推荐）：
   • 输入Radarr URL（例如http://localhost:7878或https://radarr.yourdomain.com）
   • 输入Radarr API密钥（在Radarr的设置→常规中找到）
   • 点击"连接"
4. 对于Plex（可选-观看历史）：
   • 输入Plex URL（例如http://localhost:32400或https://plex.yourdomain.com）
   • 输入Plex令牌（可按照这些说明查找）
   • 点击"连接"
5. 对于Jellyfin（可选-观看历史）：
   • 输入Jellyfin URL（例如http://localhost:8096或https://jellyfin.yourdomain.com）
   • 输入Jellyfin API密钥（在Jellyfin的控制台→API密钥中找到）
   • 输入Jellyfin用户ID（在Jellyfin用户设置中找到）
   • 点击"连接"
6. 对于Tautulli（可选-观看历史）：
   • 输入Tautulli URL（例如http://localhost:8181或https://tautulli.yourdomain.com）
   • 输入Tautulli API密钥（在Tautulli的设置→Web界面→API中找到）
   • 点击"连接"
7. 对于Trakt（可选-观看历史）：
   • 在Trakt连接页面点击"连接"
   • 使用您的Trakt.tv账户授权Recommendarr
   • 完成认证过程以连接您的Trakt观看历史

您可以根据需要连接这些服务的任意组合。

2. 设置AI服务

1. 导航至设置
2. 选择AI服务选项卡
3. 输入您的AI服务详情：
   • API URL：对于OpenAI，使用https://api.openai.com/v1。对于本地模型，使用服务器URL（例如http://localhost:1234/v1）
   • API密钥：您的OpenAI API密钥或其他服务的相应密钥（某些本地服务器不需要）
   • 模型：从列表中选择模型或保留默认值
   • 参数：根据需要调整最大令牌数和温度
4. 点击"保存设置"

3. 获取推荐

1. 导航至电视剧推荐或电影推荐页面
2. 使用滑块调整您想要接收的推荐数量
3. 如果已连接Plex、Jellyfin或Tautulli，选择是否在推荐中包含您的观看历史
4. 点击"获取推荐"
5. 查看带有海报和描述的个性化媒体建议

🌐 使用反向代理设置

如果您想在反向代理（如Nginx、Traefik或Caddy）后运行Recommendarr，请按照以下步骤操作：

1. 使用您的公共URL构建自定义镜像：

bash
# 使用公共URL构建
docker build -t recommendarr:custom \
  --build-arg PUBLIC_URL=https://recommendarr.yourdomain.com \
  --build-arg BASE_URL=/ \
  .

# 使用反向代理配置运行
docker run -d \
  --name recommendarr \
  -p 3000:3000 \
  -e PUBLIC_URL=https://recommendarr.yourdomain.com \
  -e FORCE_SECURE_COOKIES=true \
  -v recommendarr-data:/app/server/data \
  recommendarr:custom

2. 配置反向代理以将请求转发到Recommendarr：

对于Nginx：

nginx
server {
    listen 443 ssl;
    server_name recommendarr.yourdomain.com;

    # SSL配置
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

对于Docker Compose：

yaml
services:
  recommendarr:
    build:
      context: .
      args:
        - PUBLIC_URL=https://recommendarr.yourdomain.com
        - BASE_URL=/
    ports:
      - "3000:3000"
    # 允许访问主机上的服务
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - NODE_ENV=production
      - DOCKER_ENV=true
      - PORT=3000
      - PUBLIC_URL=https://recommendarr.yourdomain.com
      # 在HTTPS反向代理后启用安全Cookie
      - FORCE_SECURE_COOKIES=true
    volumes:
      - recommendarr-data:/app/server/data
    restart: unless-stopped

volumes:
  recommendarr-data:

🔧 环境变量

🖥️ 兼容的AI服务

Recommendarr适用于各种AI服务：

• OpenAI API：与GPT-3.5和GPT-4等模型的标准集成
• Ollama：带有OpenAI兼容API的自托管模型
• LM Studio：在您的计算机上本地运行模型
• Anthropic Claude：通过OpenAI兼容端点
• 自托管模型：任何具有OpenAI兼容聊天完成API的服务

推荐模型

以下是一些与Recommendarr配合良好的模型推荐：

通过OpenRouter的免费/低成本选项

• Meta Llama 3.3 70B Instruct：免费且性能出色
• Gemini 2.0模型（Flash/Pro/Thinking）：卓越的推荐质量
• DeepSeek R1模型：各变体均表现强劲

高级模型（通过OpenRouter经济实惠）

• Claude 3.7/3.5 Haiku：在理解您的库偏好方面表现出色
• GPT-4o mini：性能和成本的绝佳平衡
• Grok Beta：价格合理，推荐效果好
• Amazon Nova Pro：强大的媒体理解能力

本地模型

• DeepSeek R1 7B Qwen Distill：小型模型中的良好表现（通过LM Studio）

为获得最佳结果，尝试将最大令牌数设置为4000，温度根据模型在0.6-0.8之间调整。

🔧 故障排除

反向代理的Cookie错误

如果您使用HTTPS反向代理并遇到类似以下的错误：

cookie "auth_token" has been rejected because a non-https cookie can't be set "secure"

这是因为您的反向代理终止了HTTPS，但将请求作为HTTP转发到容器。要解决此问题：

1. 将FORCE_SECURE_COOKIES=true环境变量添加到docker-compose.yml或docker run命令中：

yaml
environment:
  - FORCE_SECURE_COOKIES=true

2. 确保反向代理转发正确的头信息。对于Nginx，添加：

proxy_set_header X-Forwarded-Proto $scheme;

端口映射

• 始终确保内部和外部端口匹配（例如3000:3000）
• 更改端口时，同时更新端口映射和PORT环境变量

开发环境设置

出于开发目的，您可以分别运行前端和后端：

bash
# 在开发模式下同时运行前端和后端
npm run dev

# 或单独运行它们：
# 带有热重载的前端开发服务器
npm run serve

# 后端API服务器
npm run api

开发服务器将使用端口8080运行带有热重载的前端，使用端口3050运行API。在生产环境中，两者都在单个端口上运行。

📄 许可证

本项目采用MIT许可证 - 详见LICENSE文件。

🙏 致谢

• Vue.js - 渐进式JavaScript框架
• Sonarr - 为电视剧推荐提供强大API支持
• Radarr - 为电影推荐提供API支持
• Plex - 提供观看历史数据的API
• Jellyfin - 提供额外观看历史数据的API
• Tautulli - 提供详细Plex观看统计的API
• Trakt - 提供观看历史和评分数据的API
• OpenRouter - 为基于AI的建议提供API支持