ListSync项目安装与配置完全指南

项目概述

ListSync是一个强大的媒体列表同步工具，能够将IMDb、Trakt、Letterboxd等平台的影视列表自动同步到Overseerr等媒体管理系统中。本指南将详细介绍ListSync的安装与配置方法，帮助用户快速搭建自己的列表同步服务。

系统准备

硬件要求

• 最低配置：2GB内存，1GB存储空间
• 推荐配置：4GB内存，2GB存储空间
• 网络要求：稳定连接IMDb、Trakt等列表源

软件依赖

Docker方式

• Docker 20.10+
• Docker Compose 2.0+

手动安装方式

• Python 3.8+
• Node.js 18+
• Chrome/Chromium浏览器（用于Selenium）

Docker安装（推荐）

Docker安装是最简单快捷的方式，适合大多数用户。

快速开始

1. 获取项目代码

   git clone 项目仓库地址
   cd list-sync
   

2. 配置环境变量

   cp env.example .env
   nano .env
   

   至少需要配置以下参数：

   OVERSEERR_URL=你的Overseerr地址
   OVERSEERR_API_KEY=你的API密钥
   IMDB_LISTS=top  # 初始只同步一个列表
   

3. 启动服务

   docker-compose up -d
   

4. 访问服务

   • 控制面板：http://localhost:3222
   • API接口：http://localhost:4222

高级配置

生产环境部署

使用预构建的容器镜像：

docker-compose up -d

开发环境部署

构建本地开发镜像：

docker-compose -f docker-compose.local.yml up -d

端口自定义

修改docker-compose.yml中的端口映射：

ports:
  - "8080:3222"  # 控制面板端口
  - "8081:4222"  # API端口

手动安装指南

适合需要自定义配置的高级用户。

系统准备

Ubuntu/Debian系统

sudo apt update
sudo apt install python3 python3-pip python3-venv git nodejs npm
sudo apt install google-chrome-stable

后端安装

1. 创建Python虚拟环境
2. 安装依赖包
3. 初始化数据库

前端安装

1. 安装Node.js依赖
2. 构建前端资源

服务管理

使用Systemd

创建服务文件实现开机自启：

[Unit]
Description=ListSync Backend Service
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/list-sync
ExecStart=/path/to/venv/bin/python -m list_sync
Restart=always

[Install]
WantedBy=multi-user.target

使用PM2

Node.js进程管理工具：

pm2 start "python -m list_sync" --name listsync-backend
pm2 start npm --name listsync-frontend -- start

安装后配置

基础设置

1. 测试Overseerr连接

   curl -H "X-Api-Key: your-key" http://your-overseerr/api/v1/status
   

2. 添加同步列表

   • 通过环境变量：IMDB_LISTS=top
   • 通过控制面板：http://localhost:3222/dashboard/lists

3. 设置同步间隔

   SYNC_INTERVAL=24  # 每天同步一次
   

高级功能

Discord通知

在.env中添加：

DISCORD_WEBHOOK_URL=你的Discord Webhook地址

Nginx反向代理

示例配置：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3222;
    }
    
    location /api/ {
        proxy_pass http://localhost:4222;
    }
}

系统验证

健康检查

curl http://localhost:4222/api/system/health

手动触发同步

curl -X POST http://localhost:4222/api/sync/trigger

日志查看

docker-compose logs -f listsync-full
# 或
tail -f data/list_sync.log

常见问题解决

Docker问题

• 端口冲突：修改docker-compose.yml中的端口映射
• 权限问题：将用户加入docker组

手动安装问题

• Python版本过低：安装新版Python
• Chrome/Selenium问题：安装必要依赖库

性能优化

• 减少并发列表数量
• 增加同步间隔时间
• 限制特殊项目数量

维护与更新

Docker更新

docker-compose pull
docker-compose up -d

手动更新

git pull origin main
pip install -r requirements.txt --upgrade
cd listsync-web && npm install && npm run build
systemctl restart listsync-*

通过本指南，您应该能够顺利完成ListSync的安装和基础配置。如需更高级的配置选项，可以参考项目的详细配置文档。