做这个“电影下载网站”起因特别简单我自己的硬盘和NAS里存了一堆电影但命名乱七八糟什么“movie.2020.1080p.mkv”、“某某导演剪辑版最终”想看的时候得一个个翻文件管理器费劲不说还经常找不到想要的那一部。后来我干脆花了两周时间自己搭了一个私人电影下载与管理网站把元数据刮削、搜索、下载任务调度全部串起来网页上看到一个海报墙点一下就能把电影拉到本地或NAS。这篇文章就把整个项目的设计思路、技术选型、核心代码逻辑、部署流程和踩过的坑都摊开来讲适合对这种自用影音服务感兴趣、有Python或Node基础、想自己动手搭一套完整方案的朋友。我需要先把前提说清楚整个项目基于的是你已经有合法渠道获得的视频文件网站的作用是把这些文件整理成可搜索、可下载的媒体库不涉及任何非授权片源也不用于公开分发这点在动手之前就要明确。1. 项目整体设计与技术选型1.1 需求拆解这个网站到底要解决什么问题我给这个项目定的核心目标就六个字整理、搜索、下载。整理是指把散落在各个目录里的电影文件自动识别出电影名和年份并补上海报、简介、评分、演员等元数据搜索是提供一个网页界面让用户通过关键词、年份、类型快速找到目标电影下载是点击一个按钮后系统自动把对应文件从远程存储或本机文件系统拉取到指定目录并实时反馈进度。这个定位决定了它和Jellyfin、Plex这类媒体服务器不一样那些工具侧重在线播放和封面墙展示而我要做的是一个偏“下载引导”的站核心动作是“把文件搬回来”。所以项目的关键路径是扫描文件 - 识别电影名 - 关联元数据 - 展示入库 - 触发下载 - 完成回传。从实际使用场景来看这个站点需要同时支持本机和远端服务因为我的电影文件有一部分在家里的NAS上有一部分在对象存储或另一台服务器上。如果只做本地扫描那下载功能就退化成复制粘贴了没意义。所以方案里必须包含一个下载引擎的抽象层既能处理局域网内文件复制也能处理远程资源的拉取。1.2 技术栈选型为什么最终选了这套组合后端我用了Python的FastAPI没有选Django或Flask。原因很简单FastAPI的异步支持让文件扫描和下载进度推送这类IO密集型操作写起来非常舒服而且自带OpenAPI文档调试接口不用另外装工具。项目里同时用到了Celery来做异步任务队列因为下载任务、元数据抓取这些都是耗时操作不可能在HTTP请求里同步等完必须丢到后台去跑。数据库我选了PostgreSQL没有用SQLite。虽然SQLite单机够用但这个项目里电影信息、任务队列、下载记录之间有比较复杂的关联查询PostgreSQL在这类场景下更稳而且后面如果要加全文搜索或地理位置之类的功能扩展起来不用换库。当然如果只是自己玩SQLite也完全跑得动我一开始就是用SQLite开发的。下载引擎这块我接的是aria2这是我最推荐的一个选择。它自带JSON-RPC接口支持断点续传、限速、多个并发连接能同时处理HTTP和磁力类链接而且不挑平台。我把aria2暴露成一个本地的RPC服务后端通过websocket或http请求就能发起下载任务比自己在Python里写下载逻辑省太多事。前端我用的是Vue3加Element Plus做后台管理类的界面非常快海报墙、任务列表、筛选组件都能直接复用不需要从零造轮子。1.3 项目目录设计一开始就要把每个文件夹规划好这个项目踩过的最大一个坑就是目录结构没提前规划导致后面扫描逻辑改了两版。最终的目录结构大致是movie-download-station/ ├── backend/ │ ├── app/ │ │ ├── main.py # FastAPI入口 │ │ ├── models/ # SQLAlchemy模型 │ │ ├── schemas/ # Pydantic序列化 │ │ ├── services/ │ │ │ ├── scanner.py # 文件扫描与识别 │ │ │ ├── metadata.py # TMDB元数据抓取 │ │ │ └── download.py # aria2任务调度 │ │ ├── api/ # 路由 │ │ └── core/ # 配置、数据库、工具函数 │ ├── requirements.txt │ └── .env ├── frontend/ │ ├── src/ │ │ ├── views/ │ │ ├── components/ │ │ └── api/ ├── download_tmp/ # 下载临时目录 ├── media_library/ # 扫描的媒体根目录 └── docker-compose.yml有个细节很重要下载临时目录和媒体库目录不能是同一个层级否则扫描器会把正在下载的半成品文件当成正式电影识别进去导致海报墙里出现一堆乱码卡片。我在实际使用中把download_tmp设为aria2的下载目录等文件下载完成后再由一个post-download回调脚本把文件移动到media_library里这样扫描器永远只面对完整文件。2. 核心功能模块的详细实现2.1 元数据服务怎么让一部电影自动配上海报和简介这个模块是项目的门面因为海报墙有没有吸引力全看元数据抓得好不好。我用的数据源是TMDB的公开API注册账号拿到一个API Key然后通过电影名和年份去检索返回结果里包含标题、简介、海报路径、评分、上映日期这些字段。关键在于识别这一步因为文件名千奇百怪比如“阿凡达水之道 2022 2160p UHD BluRay x265”需要先清洗再匹配。清洗逻辑我放在scanner.py里思路是这样的先把文件名里的年份提取出来然后把分辨率、编码格式、小组名这些噪声词汇去掉剩下的部分作为搜索关键词。这里有个经验不要直接把整个文件名丢给TMDB的搜索接口因为搜索接口对长字符串的处理不稳定经常出现匹配不上的情况。而是先提取年份再提取主标题最好能拆到只剩四五个核心词匹配成功率会高很多。import re def parse_movie_filename(filename: str): base filename.rsplit(., 1)[0] # 去掉扩展名 year_match re.search(r(19|20)\d{2}, base) year year_match.group(0) if year_match else None # 去掉年份、分辨率、编码、小组名等噪声词 cleaned re.sub(r(19|20)\d{2}, , base) cleaned re.sub(r(2160p|1080p|720p|UHD|BluRay|WEB-DL|HDR|x264|x265|HEVC), , cleaned, flagsre.IGNORECASE) cleaned re.sub(r[._\-\[\]], , cleaned).strip() return cleaned, year拿到搜索词后调TMDB搜索接口用置信度最高的那条结果。如果年份对得上直接取如果年份对不上再看评分取评分最高的那个候选。另外一个非常关键的点是图片代理TMDB的图片地址通常指向一个单独的CDN域名有些网络环境下访问会很慢。我的做法是在后端加一个图片缓存接口前端海报图的src直接指向自己站点的/image/proxy?pathxxx后端去TMDB拉图后缓存到本地目录第一次慢一点之后都是秒开。2.2 文件扫描与识别把硬盘上的散装文件变成有结构的数据扫描模块的作用是定期遍历media_library目录找出所有视频文件把新增的、改名的、删掉的同步到数据库里。这里有一个很现实的问题直接递归扫描整个大目录会非常慢尤其是NAS里可能挂了几千部电影。我的做法是用一个独立的索引表记录每个文件的绝对路径、文件名、大小和修改时间扫描时先快速比对inode信息只有文件列表有变化才去执行深层的元数据抓取。数据库里movie表的字段大致是这样CREATE TABLE movies ( id SERIAL PRIMARY KEY, title VARCHAR(255) NOT NULL, original_title VARCHAR(255), tmdb_id INTEGER UNIQUE, year INTEGER, overview TEXT, poster_path VARCHAR(255), backdrop_path VARCHAR(255), rating NUMERIC(3, 1), file_path TEXT UNIQUE, file_size BIGINT, status VARCHAR(20) DEFAULT ready, created_at TIMESTAMP DEFAULT NOW(), updated_at TIMESTAMP DEFAULT NOW() );扫描完成后每个电影都会对应一个file_path这个路径就是后续下载任务里的source。但你可能会问既然文件已经在本地了还叫下载吗这个项目我实际设计成了“多源模式”也就是同一个电影Id可以对应多个文件源一个指向本机路径一个指向远程服务器的资源链接。用户在网页上选择“下载”时系统会优先匹配速度最快或离自己最近的源。如果源是本地路径就直接执行推送到目标目录如果源是远程URL就走aria2拉取。扫描器的另一个作用是识别“重复文件”比如同一部电影有Remux版和1080p压缩版会让海报墙出现两套一样的卡片。我的方案是优先保留体积最大或资源类型最新的文件其余标记为“重复”在界面上自动折叠。2.3 下载任务调度用Celery加aria2搞定后台任务下载模块是整个网站里最容易出bug的部分因为涉及异步、进度回传和异常恢复。我最终实现的流程是这样的用户在前端点“下载”后端往Celery队列提交一个download_taskworker收到任务后先判断source_type是local还是remote。local类型直接用Python的shutil.copy过程中用回调函数计算速度每秒更新一次Redis里的任务进度remote类型则调用aria2的JSON-RPC接口传入URL、目录、文件名然后轮询aria2返回的gid来查询下载进度。Celery的broker我用的是Redis理由很简单同一个Redis既当broker又当结果后端部署省事。生产环境其实不建议这么干但自用站没那么多流量Redis单进程完全扛得住。任务除了下载还有一类是“元数据刷新”比如一个文件SCAN完之后Celery后台去TMDB抓详细数据如果抓失败就进重试队列重试次数最多3次间隔依次拉长。这里的关键是任务结果要持久化到数据库不能只依赖Celery的result backend因为重启服务会导致内存里的任务状态丢失。celery_app.task(bindTrue, max_retries3, default_retry_delay30) def start_download(self, download_id: int): record db.query(DownloadRecord).get(download_id) try: if record.source_type remote: gid aria2_client.add_uri( uris[record.source_url], options{ dir: record.target_dir, out: record.file_name, max-connection-per-server: 16, split: 16, } ) else: local_copy(record.source_path, record.target_dir, record.file_name) record.status completed except Exception as exc: record.status failed raise self.retry(excexc)有一点要提醒的是aria2的RPC默认是开启的但如果你把它暴露到公网一定要设置一个token密钥否则任何人都能通过6800端口的RPC接口往你的服务器上下载文件那画面太美我不敢看。我是在aria2的配置里设置了rpc-secret一串随机字符然后后端的RPC客户端在调用时带上这个secret。2.4 网页界面从查询框到海报墙前端这块其实没什么特别高深的东西但有几个交互细节很影响体验。列表页默认是一个可筛选的海报墙支持关键字搜索、年份筛选、类型筛选、评分排序。搜索框输入关键词后前端会调用后端的/api/movies/search接口这个接口同时匹配电影标题、原版标题、别名并按照匹配度排序返回结果。一张电影卡片上我会展示海报、片名、年份、清晰度标记和评分评分超过7.5分的加一个绿色圆角标签。点进详情页后能看到完整的简介、演员列表、文件列表和下载按钮。文件列表区域会显示每个文件对应的格式、大小、以及下载这个文件需要用的源标签。下载按钮点下去后页面不会跳转而是弹出一个下载进度会话框前端通过WebSocket连接后端的一个专门频道实时接收progress和speed字段。WebSocket实现的时候踩了个坑FastAPI的WebSocket端点在访问时如果经过了Nginx反向代理需要额外配置proxy_set_header Upgrade和proxy_set_header Connection upgrade否则会一直提示连接失败。我之前部署到服务器上时忽略了这个导致网页上的进度条一直转圈但没有任何数据返回排查了半天才想起来是Nginx配置问题。3. 实际部署与完整运行流程3.1 环境准备依赖项和配置文件因为我平时主要用Ubuntu服务器跑站这里以Ubuntu 22.04为例Mac或Windows的步骤类似但命令会有差异。需要准备的东西有四件Python 3.10、Node.js 18、Redis、aria2。后两者可以直接用apt安装也可以全部走Docker。如果你像我一样想省事推荐直接把aria2和Redis用Docker拉起来docker run -d --name aria2 --restartalways -p 6800:6800 \ -v /opt/aria2-downloads:/downloads \ -v /opt/aria2-config:/config \ p3terx/aria2-pro docker run -d --name redis --restartalways -p 6379:6379 redis:7aria2-pro这个镜像的好处是已经有比较完整的默认配置而且配好了AriaNg前端可以直接在浏览器里打开6800端口旁边的静态页面来可视化管理下载任务。我这里因为要做二次开发所以主要用它的RPC服务AriaNg只是个辅助观察工具。后端的环境变量我用.env文件管理核心配置项包括DATABASE_URLpostgresql://user:passlocalhost/movie_station TMDB_API_KEY你的key TMDB_IMAGE_BASEhttps://image.tmdb.org/t/p/w500 REDIS_URLredis://:6379/0 ARIA2_RPC_URLhttp://127.0.0.1:6800/jsonrpc ARIA2_RPC_SECRET你的随机token MEDIA_LIBRARY_PATH/opt/media_library DOWNLOAD_TMP_PATH/opt/aria2-downloads这些配置在代码里统一用一个Pydantic的Settings类读取启动时校验必填项避免因为漏配环境变量导致运行时炸马。3.2 数据库初始化与表结构设计数据库连接后先用SQLAlchemy的metadata create_all建表。除了前面提到的movies表还需要两张重要的表download_records和task_logs。download_records记录每次下载的来源、目标、状态、进度、错误信息task_logs记录Celery任务执行过程中的日志。这两张表对排查问题非常重要尤其是下载失败的时候没有日志记录很难定位是网络问题、权限问题还是文件名格式问题。CREATE TABLE download_records ( id SERIAL PRIMARY KEY, movie_id INTEGER REFERENCES movies(id) ON DELETE CASCADE, source_url TEXT, source_path TEXT, target_dir TEXT NOT NULL, file_name VARCHAR(255) NOT NULL, status VARCHAR(20) DEFAULT pending, -- pending/running/completed/failed progress INTEGER DEFAULT 0, speed TEXT, created_at TIMESTAMP DEFAULT NOW(), updated_at TIMESTAMP DEFAULT NOW() );另外我自己加了一个“配额控制”功能对于局域网外的远程下载源单个任务最多允许5个并发连接防止一次点十几个下载把家里路由器搞炸。这个是写在任务创建逻辑里的每次提交下载前先检查当前running状态的记录数超过阈值就直接返回提示不进入Celery队列。3.3 后端接口清单与启动流程后端主要提供这些接口POST /api/scan触发一次全量扫描、GET /api/movies获取电影列表、GET /api/movies/{id}获取详情、GET /api/movies/search?qxxx搜索、POST /api/movies/{id}/download创建下载任务、GET /api/tasks/{id}查任务状态、WS /api/ws/progress订阅进度推送。启动流程上我建议在一个终端里先启动Redis和aria2再启动FastAPI然后是Celery worker。因为我用的是开发模式跑所以开三个终端最方便。生产部署的话可以把后端和celery分别打成systemd服务前端构建成静态文件再用Nginx反代后端API和前端静态资源。我本人在本地测试阶段永远都是这种“多终端开窗”的方式不需要额外写supervisor配置。# 终端1启动Redis和aria2Docker方式已省略 # 终端2启动FastAPI uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload # 终端3启动Celery celery -A app.core.celery_app worker --loglevelinfo --poolsoloCelery的worker在Windows上不能用默认的prefork池必须换成--poolsolo否则会报ValueError这点在Mac或Linux上不需要关注但如果你在Windows笔记本上开发一定要记住。3.4 第一次完整使用从一个文件到一张海报卡片第一次跑通整个流程时的成就感其实是最强的。我在/media_library里放了一部电影文件名大约是“The Matrix 1999 1080p.mkv”。然后调一次POST /api/scan扫描器会做三件事解析文件名、判断数据库是否已有该文件、如果有新文件就创建一条movie记录并标记为pending。创建完记录后Celery后台会去TMDB抓元数据几秒后我再刷新网页就能看到海报墙上出现了《黑客帝国》的封面简介、导演、演员全都齐了。此时点进详情页能看到一个“下载到本地NAS”的按钮。因为这部电影我在配置里指定了source_path指向服务器本机目录所以相当于做了一次“把服务器文件复制到NAS共享目录”的任务。进度条从0走到100之后NAS上多了一个整齐命名的文件同时元数据里的file_path会自动更新到新位置。这个过程说起来很短但实际调试时因为跨平台的文件路径分隔符问题来回折腾了好几个小时。4. 上线前遇到的问题与排查清单4.1 TMDB元数据抓不到问题出在图片缓存项目做到一半时我发现海报墙的图片加载特别慢经常转圈好几秒才显示出来甚至直接裂图。排查下来发现是TMDB的图片CDN在本地网络环境下连接不够稳定很多时候请求超时。我的解决方案是加了一层本地图片缓存服务后端在第一次请求海报图时先从TMDB拉取原图然后存到项目目录下的image_cache里并生成一个缩略图用于列表页展示。这样同一个电影的海报只需要远程请求一次之后全都是本地文件速度飞快。这里有一个小技巧缩略图不要直接用原图改个尺寸就完事最好在生成时用JPEG质量70的压缩一张海报可以从200KB缩到30KB左右页面加载明显会更快。我的逻辑是读取TMDB返回的poster_path拼接出完整图片URL然后用requests下载并转存如果图片下载失败就返回一张默认的灰色占位图不影响页面整体布局。4.2 国产电影匹配不准用别名表解决国产电影的英文名经常和中文名对不上比如《让子弹飞》在TMDB里的中文名是“让子弹飞”但它的英文名是“Let the Bullets Fly”如果你直接用文件名里的拼音去搜很容易搜错。我的做法是给movie表加一个aliases字段存电影的中文别名、英文名、以及常见简写。搜索接口同时匹配title、original_title和aliases匹配结果按评分和年份排序。另外在扫描器解析时中文路径和英文路径分开处理中文路径能直接匹配到中文标题英文路径则先用英文标题搜再拿中文翻译结果去匹配。不过这个方法也有局限就是遇到一些冷门独立电影或老黑白电影时TMDB搜索结果不稳定时不时匹配到同名但不同年的片子。针对这种情况我又在管理后台加了一个“手动关联”功能页面上给出一组TMDB搜索结果管理员可以点选正确的那部选择后系统会更新tmdb_id并重新抓元数据这个功能直接覆盖了那些自动匹配的失败案例。4.3 下载任务卡住不结束问题出在Celery的prefork机制有一次我突然发现某个下载任务进度显示到了99%但一直没变成completed状态。去后台看Celery日志发现worker进程卡住了。排查后找到原因我在下载完成后的回调里调用了另一个Celery任务这个任务需要访问数据库但Celery在prefork模式下子进程会继承父进程的数据库连接池多个worker共享一个连接句柄就容易造成连接死锁。解决办法有两个一是改用solo模式简单粗暴但适合单机二是在每个worker启动时重新创建数据库引擎。我最后选了方案二因为在生产环境还是想用多worker并行处理扫描和下载任务。4.4 搜索“电影”没反应数据库排序规则失灵中文搜索一直是个坑因为PostgreSQL默认的排序规则不是按拼音或汉字笔画排序的用LIKE %黑客%这种模糊查询没问题但用ILIKE的时候中文匹配不稳定偶尔还会出现全表扫描导致接口超时。我最终的做法是给搜索框所在的表加了一个GIN索引并把搜索逻辑改成同时对这个索引列做to_tsvector全文搜索虽然中文分词不如专业搜索引擎那么强但应对电影名搜索完全够用。另一个更简单的替代方案是在应用程序层把所有电影标题加载到内存里用一个Trie树做前缀匹配几千部电影的数据量根本不会卡。4.5 文件权限导致扫描不到NAS目录这个问题很隐蔽。我的服务器上有一个挂载到/mnt/nas的SMB共享目录项目启动后一直扫不到里面的电影但服务器上直接访问是没问题的。查了半天发现运行FastAPI进程的用户是www-data它没有/mnt/nas的读取权限。SMB挂载的权限经常会因为uid/gid设置不对而无法被其他用户访问最终我在fstab里加了uidwww-data,gidwww-data,file_mode0664,dir_mode0775然后重新挂载扫描器才正常工作。还有一个常见坑是如果你用Docker跑整个项目容器内的uid和宿主机不一致挂载目录时会出现“Permission denied”或“Operation not permitted”的错误这种情况下要么调整容器用户的uid要么在docker-compose.yml里设置user: uid:gid来匹配宿主机的权限。5. 这套系统还能怎么扩展项目做完之后我经常品味这个网站的意义它不只是解决了我找片难的问题更像是给自己打造的一个“迷你内容管理平台”。后续可扩展的方向非常多比如接入字幕下载模块根据电影年份和片名从字幕站自动拉取中文字幕增加移动端适配让手机浏览器也能方便地触发下载任务或者加一个简单的推荐系统根据你看过的片子和评分推荐同类型的电影这些都会让这个站点的可用性再上一个台阶。实际开发过程中我自己最大的体会是不要一开始就追求大而全把核心链路跑通最重要。先把文件扫描、元数据、下载这三条路打通后面的搜索、前端优化、权限控制都是锦上添花。另外一个建议是在项目初期就要把日志系统做好不管是Celery任务日志还是后端普通access log都要落到文件里因为这种自用服务一旦出了问题没有日志就等于是睁眼瞎只能靠猜。把日志、数据库记录、文件路径验证这三件事做扎实了这个站点基本就能稳定跑很久。