网盘资源自动转存系统：基于FastAPI与OAuth2.0的工程实践

去年年底接了个活儿，一个做内容整理的朋友抱着一堆网盘分享链接来找我，说每天要花一两个小时把别人分享的资源转存到自己账号里，有的链接还带提取码、有效期，经常漏转、错转，问能不能做个工具自动化。于是就有了这套“网盘资源转存系统”。

简单来说，它就是一个中间服务，对接网盘开放平台的API，通过OAuth授权拿到用户身份，然后把带提取码的分享链接批量解析、校验、排队，最终自动转存到指定网盘的指定目录，整个过程可以在Web管理页面上看到进度和结果。这套东西听起来不复杂，但真做起来里面有不少坑，尤其是Token续期、链接解析、异步任务状态管理这几个环节。

这篇文章我把完整方案按实际开发顺序拆开讲一遍，从需求梳理、接口对接、代码实现，到常见的报错排查和优化技巧都会涉及。适合准备做网盘自动化、私域资源管理，或者想了解OAuth对接和异步任务队列怎么落地的开发者参考。

1. 项目需求梳理与整体设计思路

1.1 网盘转存场景中真正耗时的三个环节

先说需求本身。朋友每天处理的分享链接有两种来源：一种是微信群里别人直接甩过来的链接，带个四位提取码；另一种是资源导航站每天定时更新的条目，需要准时转存，晚了链接就失效。手动操作一次转存大约需要二十秒，听起来不多，但一天几百条链接就是几个小时，而且这种重复劳动特别容易出错。

我梳理了一下，手动转存流程里真正耗时的其实是三个环节：

链接录入与校验。复制链接、打开分享页、输入提取码、查看文件列表，确认是不是自己要的内容。链接一多，光这一步就占了一半时间。而且有些分享页做了跳转，有些链接带了一堆追踪参数，直接在浏览器里打开没问题，但要做自动化就得把真实链接和提取码精确提取出来。

任务排队与执行。网盘对转存接口有频控限制，不可能一条链接来了就立刻调用，需要把任务排成队列，控制并发，还要处理执行中的失败和重试。手动操作时这一步被人的“思考间隔”掩盖了，但系统化之后必须显式设计。

结果确认与反馈。转存完要确认是不是真的存进去了，是不是完整，有没有重名冲突、容量不足这类问题。手动操作时漏掉一个失败提示很正常，系统要做的是把每次执行结果完整记录，失败原因清清楚楚。

明确这三个环节之后，系统的功能边界就出来了：录入解析、任务调度、执行转存、结果反馈。

1.2 系统功能模块拆解

整体我分了五个模块：

这里我把“网盘API适配层”单独拎出来，是因为网盘开放平台的接口经常调整，而且不同网盘的授权方式和转存语义有差异。把API调用封装成独立模块后，后续接新的网盘服务商只需要实现同一套接口，不需要动任务调度和执行引擎的代码。

1.3 技术选型：为什么选Python + FastAPI + SQLite

技术栈我选的是Python 3.10 + FastAPI + SQLite + APScheduler，消息队列直接用SQLite表轮询，没有引入Redis或RabbitMQ。

选Python是因为网盘API对接本质上是HTTP接口调用，Python的requests/httpx写起来非常顺手；FastAPI自带OpenAPI文档，调试接口时直接在浏览器里看Swagger，省了很多事；SQLite单文件部署，对个人工具来说完全够用。

为什么不一开始就上消息队列？因为这个系统的瓶颈在网盘API的频控，而不在任务吞吐量。几百条任务即使全部排队，SQLite的查询开销也远不是瓶颈。加了Redis反而增加部署复杂度。等到未来任务量到几十万、需要多机消费时再迁移到真正的消息队列也不迟，执行引擎和队列存储这两层本来是解耦的。

2. 核心模块：网盘接口对接与转存链路实现

2.1 授权登录与Token自动续期

网盘转存首先要拿到用户的授权身份。目前主流网盘开放平台普遍走OAuth 2.0的授权码模式，流程是这样的：用户访问授权页，登录并同意授权，然后网盘服务商回调你配置的redirect_uri，带上一个authorization_code；后端用这个code去换access_token和refresh_token。

access_token的有效期通常是一天，refresh_token是三十天或更长。这里最容易踩的坑是只存access_token、不处理过期。用户第二天再点转存，接口返回token失效，系统没有自动刷新机制，任务就卡在“执行中”永远不动了。

我的做法是封装一个TokenManager，每次请求前检查token是否过期，过期了自动用refresh_token刷新，同时把新token持久化。这里给出了核心逻辑：

python复制import time
import requests

class To