banner
约 3,300 字
11 分钟

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

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 官方项目页:一个支持多种存储的文件列表程序,使用 Gin 和 SolidJS
OpenList 官方项目页:一个支持多种存储的文件列表程序,使用 Gin 和 SolidJS

一、它和原版 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)

—

用 serverless.yml

划重点:Vercel 和 Lambda 默认没有持久化,配置重启就丢。要长期用,请选 Cloudflare Workers 或 EdgeOne / ESA。

二、部署前准备

  • 一个 Cloudflare 账号(免费版足够)

  • Node.js 18+ 与 pnpm

bash
node -v          # 确认 >= 18
npm i -g 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 步:克隆并安装依赖

bash
git clone https://github.com/OpenListTeam/OpenList-Worker.git
cd OpenList-Worker
pnpm install

第 2 步:创建 KV namespace

Dashboard 里 Storage & Databases → KV → Create namespace 建一个,名字随意(比如 openlist)。

变量名(绑定名)必须恰好是 `KV`。另外不要用命令行 wrangler kv namespace create KV 手动建名叫 "KV" 的空间指望被自动复用——原因见上文第三节末尾的 Issue #34 警告。

第 3 步:部署

bash
pnpm run deploy          # 一键:拉取官方前端 + 构建 + 部署(推荐)
pnpm run deploy:worker   # 只部署 worker(跳过前端构建)

pnpm run deploy 背后是 scripts/deploy.js:拉取官方前端构建产物,然后 wrangler deploy。如果你没动过 wrangler.jsonc 里的 kv_namespaces(默认注释着),wrangler 会自动创建并绑定 openlist-tsworkers-kv——这种情况下想用自己第 2 步建的空间,就到 Dashboard 把绑定换成它(下一步)。

第 4 步:绑定 KV、添加 JWT_SECRET

部署完到 Worker 的 Settings 页补两件事:

  1. Bindings → Add → KV namespace:变量名填 KV,指向第 2 步建的命名空间

  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(格式)

值

说明

map(默认)

整个对象序列化为单个 JSON 值,适合 KV / Blob

key

分 key 存储,每实体一条记录(避免大 JSON)

sql

列式表结构,与 Go 后端 GORM 表结构兼容

DB_DRIVER(驱动)

值

说明

适用平台

auto(默认)

自动检测可用驱动

通用

blob

Blob 存储(仅支持 `map` 格式)

EdgeOne / ESA

cfkv

Cloudflare KV REST API

Cloudflare

kv

KV 绑定

通用

d1

Cloudflare D1

Cloudflare

do

Durable Objects

Cloudflare

mysql

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。想明确一点:

bash
DB_FORMAT=map
DB_DRIVER=kv        # 绑定名必须恰好是 KV;未绑定却显式写 kv 会直接报错(不做回退)

追求关系型存储、或想和 Go 后端共享数据库时再上 D1(DB_FORMAT=sql + DB_DRIVER=d1,绑定名 DB)。

表名对齐

用 sql 格式时,表名策略与 Go 后端的 GORM 一致:snake_case + 复数 + 固定前缀 x_。

Go 结构体

表名

SettingItem

x_setting_items

SharingDB

x_sharing_dbs

前缀固定 x_,无需额外配置就能和 Go 后端共用同一个物理数据库——如果你想把原版 OpenList 平滑迁到 Worker 版,这是关键设计。

六、环境变量全表(2026 改名对照)

这一节是本文最该收藏的部分。 项目在 2026 年做了一轮环境变量规范化,大量变量改了名。照老教程填,配置不会生效:

变量

必填

默认

说明

JWT_SECRET

推荐

—

签名 + 数据加密 + 定时任务鉴权三合一。未配置时自动生成并持久化到 KV

DB_FORMAT

可选

map

存储格式

DB_DRIVER

可选

auto

存储驱动

ADMIN_PASS

可选

—

管理员密码(配了则跳过安装向导)

ALLOW_URLS

可选

—

允许的来源

MAX_UPLOAD

可选

26214400

单次整体上传上限(字节,默认 25MB)

MAX_UPPART

可选

16777216

单个分片上限(字节,默认 16MB)

ASSET_URLS

可选

—

前端静态资源 CDN 地址

DB_CIPHER

可选

none

敏感字段落盘加密算法。2026-09 起默认不加密(旧版默认加密),升级已有部署见下方说明

CF_KV_UUID / CF_ACCOUNT / CF_API_KEY

可选

—

走 Cloudflare KV REST API 时使用

MYSQL_URLS 或 MYSQL_HOST/PORT/USER/PASS/NAME

可选

—

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 与既有写入形态一致。

⚠️ 新旧名对照(旧教程里全是左边的写法):

旧名(已废弃)

新名

ADMIN_PASSWORD

ADMIN_PASS

ENCRYPTION_SECRET + CRON_SECRET

合并为 JWT_SECRET

ALLOWED_ORIGINS

ALLOW_URLS

MAX_UPLOAD_SIZE

MAX_UPLOAD

MAX_PART_SIZE

MAX_UPPART

CDN_URL

ASSET_URLS

SEED_SOURCE_ALLOWED_HOSTS

ALLOW_SEED

CF_KV_NAMESPACE_ID

CF_KV_UUID

CF_ACCOUNT_ID

CF_ACCOUNT

CF_API_TOKEN

CF_API_KEY

EDGE_KV_BASE_URL

EO_KV_URLS

MYSQL_URL / MYSQL_DATABASE / MYSQL_PASSWORD

MYSQL_URLS / MYSQL_NAME / MYSQL_PASS

已彻底移除的变量: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:

jsonc
{
  "schedules": [
    {
      "name": "token-refresh",
      "cron": "0 2 * * *",
      "path": "/api/task/refresh",
      "method": "POST",
      "payload": { "cron_secret": "你的JWT_SECRET" },
      "timezone": "Asia/Shanghai",
    },
  ],
}

Cloudflare 侧用 Cron Triggers 触发同一路径,payload 里的 cron_secret 填相同的 JWT_SECRET。

九、本地开发

bash
pnpm install

pnpm run dev:unified   # 拉取前端并启动后端(统一开发服务器,推荐)
pnpm run dev:worker    # 只跑 worker,前端需另行构建

只想快速看效果也可以用 wrangler dev --local。

十、排障清单

现象

排查方向

提示「无法获取存储库内容」

先 Fork 项目,再用「连接到 GitHub 仓库」部署

配置项不生效

对照第六节的新旧名表,大概率还在用废弃的旧变量名

部署后配置丢了 / 服务起不来

检查存储绑定。Serverless 环境禁止回退到内存存储,没有可用持久化时会直接报错,而不是"看起来能跑"。访问 /api/public/env_check 可看当前实际用的驱动

报 DRIVER_UNAVAILABLE

显式指定的 DB_DRIVER 不可用时不会自动降级。检查绑定名是否为 KV / DO,D1 是否已建

账户里多出一个没用的 KV

手动 wrangler kv namespace create 建的空间不会被预配链路复用(Issue #34)。删掉即可,想用已有 KV 就把 id 填进 wrangler.jsonc 或在 Dashboard 绑定

保存设置后刷新又恢复原样

KV/CDN 缓存一致性。项目已对 /api/* 的 GET 强制 no-cache;检查 KV 命名空间绑定是否正确、是否只读。ESA 的 EdgeKV 是最终一致性,跨节点同步有延迟属正常

想和原版 OpenList 共用数据

用 DB_FORMAT=sql,表名带固定 x_ 前缀,可指向同一个物理库

大文件上传失败

受 Workers 请求体上限与你配置的存储限制约束;大文件更适合走原生网盘客户端

写在最后

你的情况

建议路线

只想最快跑起来

一键部署(记得先 Fork)

要可控、要长期维护

Wrangler 手动部署:克隆 → 建 KV → 绑定(变量名 KV)→ 加 JWT_SECRET → pnpm run deploy

要关系型存储 / 平滑迁移原版数据

加配 D1:DB_FORMAT=sql + DB_DRIVER=d1,共享带 x_ 前缀的表

在意国内访问速度

考虑 EdgeOne Makers

这个项目目前仍在活跃开发(仓库标注 WIP),边缘适配和安全加固的提交很密集——本文核对到的最近提交是 2026-09-25。部署前建议再对一眼仓库的 Release 与 `.env.example`,环境变量是它变动最频繁的部分。

它把「文件列表服务」这类本该常驻的进程彻底 Serverless 化,配上 Cloudflare 免费额度,基本等于零成本零运维。如果你之前因为不想养 VPS 而放弃自建,现在可以重新考虑了。

最后提醒:聚合网盘请遵守各存储服务商与版权规则,仅聚合你有权访问的内容;配好权限与只读分享后,它更像家庭私有门户,而不是公网网盘。

END