OpenList Worker 部署教程:不买服务器,把网盘聚合搬上 Cloudflare

摘要
OpenList 官方 Serverless 移植版,把网盘聚合跑在 Cloudflare Workers。手动部署已简化为克隆→建 KV→绑定→加 JWT_SECRET 四步,含 2026 环境变量改名对照与排障清单。
家里攒了三四个网盘,每次找文件都要挨个登录翻一遍。想自建聚合又卡在同一个问题上:原版 OpenList 是 Go 程序,得常驻一台 VPS,为一个文件列表服务养一台服务器实在不划算。
OpenList Worker 正好解掉这个死结——它把后端重写成 TypeScript,跑在 Cloudflare Workers 这类边缘运行时上,免费额度就够用。这篇是配置过程中的完整记录,含 2026 年那次环境变量大改名的新旧对照,照着配能少走一遍弯路。
仓库:OpenListTeam/OpenList-Worker | 官方文档:doc.oplist.org.cn | 协议:AGPL-3.0

一、它和原版 OpenList 差在哪
OpenList 是 ALib 系开源文件列表程序(AList 的社区延续)。Worker 版不是套壳,而是面向 Serverless 重构的官方移植:后端用 Hono.js 重写,前端复用官方 OpenList-Frontend(SolidJS)。
项目 | 技术栈 |
|---|---|
后端 | Hono.js(TypeScript) |
运行平台 | Cloudflare Workers / EdgeOne Functions / 阿里云 ESA / Vercel / AWS Lambda |
数据库 | Cloudflare D1(SQLite)、MySQL / MariaDB / PostgreSQL / SQL Server、Cloudflare KV |
前端 | OpenList-Frontend(SolidJS) |
各边缘平台的能力差异,选平台前建议先看这张表:
平台 | 持久化 | 一键部署 | 说明 |
|---|---|---|---|
Cloudflare Workers | D1 / KV / JSON | 支持 | 推荐,全球边缘网络 |
EdgeOne Makers(国际站 / 中国站) | EdgeOne Blob / KV | 支持 | 腾讯云边缘平台,国内节点有优势 |
阿里云 ESA | EdgeKV | 支持 | 阿里边缘函数 |
Vercel | 内存(JSON) | — | 默认无持久化 |
AWS Lambda | 内存(JSON) | — | 用 |
划重点:Vercel 和 Lambda 默认没有持久化,配置重启就丢。要长期用,请选 Cloudflare Workers 或 EdgeOne / ESA。
二、部署前准备
一个 Cloudflare 账号(免费版足够)
Node.js 18+ 与 pnpm
三、方式一:一键部署
点官方文档里的 Deploy to Cloudflare 按钮,Cloudflare 会拉取仓库、引导填写变量(至少 JWT_SECRET)并完成部署。
⚠️ 高频坑:如果报「无法获取存储库内容(cannot fetch repository content)」,不是你的问题——先把项目 Fork 到自己账号,再用「连接到 GitHub 仓库」的方式部署,不要直接用一键部署 URL。
另外注意一个设计变化:新版 wrangler.jsonc 默认只绑定 `ASSETS` 和三个变量(ENVIRONMENT / DB_FORMAT / DB_DRIVER),KV / D1 / DO 存储绑定全部写在注释里按需打开——避免一键部署时重复创建资源导致冲突。所以部署完你需要自己去控制台补绑定(见下文,就三件事:建 KV、绑定、加 JWT_SECRET)。
⚠️ 别手动建名叫 "KV" 的命名空间指望被自动复用:
wrangler.jsonc里的 KV 方案是靠自动预配工作的(首次部署自动创建openlist-tsworkers-kv并绑定,二次部署靠服务端 inherit 复用)。如果你先手动wrangler kv namespace create KV建一个同名空间,wrangler 的预配链路无法按 title 复用它,会另建一个,手动建的那个变成从未被使用的孤儿资源(Issue #34)。想用账户里已有的 KV,正确做法是把它的 id 填进kv_namespaces,或者在 Dashboard 手动绑定(变量名填KV)。
四、方式二:Wrangler 手动部署(推荐)
手动部署比想象中简单得多——克隆、建 KV、绑定、加 `JWT_SECRET`,就完事了。DB_DRIVER 保持默认 auto,绑定好 KV 后自动探测就会用它,不需要写任何存储配置。
第 1 步:克隆并安装依赖
第 2 步:创建 KV namespace
Dashboard 里 Storage & Databases → KV → Create namespace 建一个,名字随意(比如 openlist)。
变量名(绑定名)必须恰好是 `KV`。另外不要用命令行
wrangler kv namespace create KV手动建名叫 "KV" 的空间指望被自动复用——原因见上文第三节末尾的 Issue #34 警告。
第 3 步:部署
pnpm run deploy 背后是 scripts/deploy.js:拉取官方前端构建产物,然后 wrangler deploy。如果你没动过 wrangler.jsonc 里的 kv_namespaces(默认注释着),wrangler 会自动创建并绑定 openlist-tsworkers-kv——这种情况下想用自己第 2 步建的空间,就到 Dashboard 把绑定换成它(下一步)。
第 4 步:绑定 KV、添加 JWT_SECRET
部署完到 Worker 的 Settings 页补两件事:
Bindings → Add → KV namespace:变量名填
KV,指向第 2 步建的命名空间Variables and Secrets → Add → Secret:名称
JWT_SECRET,值用 16 字符以上的随机串(推荐openssl rand -hex 32生成)
JWT_SECRET 是 JWT 签名密钥,兼作可选的字段加密密钥与定时任务鉴权。不配也能跑(自动生成并持久化到 KV),但一旦清空 KV,加密数据就再也解不开,生产环境务必显式配。
改完绑定与 Secret 即时生效,不需要重新部署。
第 5 步:验证
访问 https://<你的域名>/api/health,返回 OpenList 即部署成功;首次打开站点会自动进入安装向导(见第七节)。
五、存储后端怎么选(最容易配错的地方)
OpenList Worker 把持久化拆成两个正交的层,理解这点就不会配错:
DB_FORMAT—— 数据怎么序列化DB_DRIVER—— 用哪个底层存储
DB_FORMAT(格式)
值 | 说明 |
|---|---|
| 整个对象序列化为单个 JSON 值,适合 KV / Blob |
| 分 key 存储,每实体一条记录(避免大 JSON) |
| 列式表结构,与 Go 后端 GORM 表结构兼容 |
DB_DRIVER(驱动)
值 | 说明 | 适用平台 |
|---|---|---|
| 自动检测可用驱动 | 通用 |
| Blob 存储(仅支持 `map` 格式) | EdgeOne / ESA |
| Cloudflare KV REST API | Cloudflare |
| KV 绑定 | 通用 |
| Cloudflare D1 | Cloudflare |
| Durable Objects | Cloudflare |
| MySQL / MariaDB | 自托管 |
DB_DRIVER=auto的探测顺序是mysql → d1 → kv → cfkv → blob → do。 一个容易踩的设计:一旦你显式指定了DB_DRIVER,它就永不自动回退 —— 驱动不可用时会直接报DRIVER_UNAVAILABLE类错误,而不是偷偷切到别的存储。这样能避免"看着能跑、数据其实写丢了"。排查时可以访问/api/public/env_check与/api/public/init_status,会直接给出当前用的驱动和一行修复建议。
推荐组合
不想折腾就什么都不设:DB_DRIVER=auto(默认)+ 绑定好 KV,自动探测就会用 KV。想明确一点:
追求关系型存储、或想和 Go 后端共享数据库时再上 D1(DB_FORMAT=sql + DB_DRIVER=d1,绑定名 DB)。
表名对齐
用 sql 格式时,表名策略与 Go 后端的 GORM 一致:snake_case + 复数 + 固定前缀 x_。
Go 结构体 | 表名 |
|---|---|
|
|
|
|
前缀固定 x_,无需额外配置就能和 Go 后端共用同一个物理数据库——如果你想把原版 OpenList 平滑迁到 Worker 版,这是关键设计。
六、环境变量全表(2026 改名对照)
这一节是本文最该收藏的部分。 项目在 2026 年做了一轮环境变量规范化,大量变量改了名。照老教程填,配置不会生效:
变量 | 必填 | 默认 | 说明 |
|---|---|---|---|
| 推荐 | — | 签名 + 数据加密 + 定时任务鉴权三合一。未配置时自动生成并持久化到 KV |
| 可选 |
| 存储格式 |
| 可选 |
| 存储驱动 |
| 可选 | — | 管理员密码(配了则跳过安装向导) |
| 可选 | — | 允许的来源 |
| 可选 | 26214400 | 单次整体上传上限(字节,默认 25MB) |
| 可选 | 16777216 | 单个分片上限(字节,默认 16MB) |
| 可选 | — | 前端静态资源 CDN 地址 |
| 可选 |
| 敏感字段落盘加密算法。2026-09 起默认不加密(旧版默认加密),升级已有部署见下方说明 |
| 可选 | — | 走 Cloudflare KV REST API 时使用 |
| 可选 | — | MySQL 连接 |
`DB_CIPHER` 加密算法可选值:none(默认)/ aes-256-gcm(推荐)/ aes-256-gcm-pbkdf2(历史 enc:v1,每字段约 27ms,慢)/ aes-256-cbc-hmac / chacha20-poly1305 / des-cbc-hmac(不安全)/ 3des-cbc-hmac(已弃用)。加密只作用于网盘凭据、敏感 settings、用户密码等字段;密文带 enc:vN: 前缀,改回 none 不会导致既有数据不可读。从旧版本升级且原本有加密数据的,保持 DB_CIPHER=aes-256-gcm 与既有写入形态一致。
⚠️ 新旧名对照(旧教程里全是左边的写法):
旧名(已废弃) | 新名 |
|---|---|
|
|
| 合并为 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
已彻底移除的变量:DATABASE_JSON、TABLE_PREFIX(固定为 x_)、DB_JSON_BACKEND、DATABASE_URL、RAW_PROXY_OVERFLOW、DB_DRIVER_STRICT。填了不但无效,还可能误导排查方向。
💡 `JWT_SECRET` 是唯一强烈建议显式配置的。不配也能跑(自动生成并持久化到 KV),但一旦你清空 KV,加密数据就再也解不开了。生产环境请设一个长随机串。
七、部署后初始化
首次访问站点会自动进入安装向导,在浏览器里设置管理员账号密码即可——不必预先配置。
如果你提前配了 ADMIN_PASS,则跳过向导直接初始化。忘了管理员密码时两种补救:临时设 ADMIN_PASS 重新部署,或清空已持久化的配置后重跑向导。
八、定时任务(token 刷新)
定时任务的入口是 POST /api/task/refresh,用 JWT_SECRET 鉴权。
EdgeOne 用 edgeone.json 配 cron:
Cloudflare 侧用 Cron Triggers 触发同一路径,payload 里的 cron_secret 填相同的 JWT_SECRET。
九、本地开发
只想快速看效果也可以用 wrangler dev --local。
十、排障清单
现象 | 排查方向 |
|---|---|
提示「无法获取存储库内容」 | 先 Fork 项目,再用「连接到 GitHub 仓库」部署 |
配置项不生效 | 对照第六节的新旧名表,大概率还在用废弃的旧变量名 |
部署后配置丢了 / 服务起不来 | 检查存储绑定。Serverless 环境禁止回退到内存存储,没有可用持久化时会直接报错,而不是"看起来能跑"。访问 |
报 | 显式指定的 |
账户里多出一个没用的 KV | 手动 |
保存设置后刷新又恢复原样 | KV/CDN 缓存一致性。项目已对 |
想和原版 OpenList 共用数据 | 用 |
大文件上传失败 | 受 Workers 请求体上限与你配置的存储限制约束;大文件更适合走原生网盘客户端 |
写在最后
你的情况 | 建议路线 |
|---|---|
只想最快跑起来 | 一键部署(记得先 Fork) |
要可控、要长期维护 | Wrangler 手动部署:克隆 → 建 KV → 绑定(变量名 |
要关系型存储 / 平滑迁移原版数据 | 加配 D1: |
在意国内访问速度 | 考虑 EdgeOne Makers |
这个项目目前仍在活跃开发(仓库标注 WIP),边缘适配和安全加固的提交很密集——本文核对到的最近提交是 2026-09-25。部署前建议再对一眼仓库的 Release 与 `.env.example`,环境变量是它变动最频繁的部分。
它把「文件列表服务」这类本该常驻的进程彻底 Serverless 化,配上 Cloudflare 免费额度,基本等于零成本零运维。如果你之前因为不想养 VPS 而放弃自建,现在可以重新考虑了。
最后提醒:聚合网盘请遵守各存储服务商与版权规则,仅聚合你有权访问的内容;配好权限与只读分享后,它更像家庭私有门户,而不是公网网盘。
