不用服务器也能跑网盘聚合：OpenList Worker 部署教程（Cloudflare Workers 详细版）

GitHub：https://github.com/OpenListTeam/OpenList-Worker 官方文档：https://doc.oplist.org.cn/guide/installation/worker 开源协议：AGPL-3.0

一、OpenList Worker 是什么？

OpenList 是流行的开源文件列表 / 网盘聚合程序（AList 的社区延续），但原版是 Go 程序，得跑在服务器或容器里——一台 VPS 又是固定开销。

OpenList Worker（仓库 OpenList-TSWorker）是 OpenList 官方的 TypeScript + Serverless 移植版：后端从 Go 重写为运行在边缘平台上的 TypeScript 服务，前端复用官方 OpenList-Frontend（SolidJS）。无需自备服务器，一键部署，跑在 Cloudflare 免费额度内就行。

各平台能力对比

划重点：Vercel 和 Lambda 默认没有持久化，配置会丢；要长期用请选 Cloudflare Workers 或 EdgeOne / ESA。

下面是 Cloudflare Workers 的详细部署流程——这是官方推荐、也是最适合国内用户的选择（晚点还会说 EdgeOne，它的优势是国内节点）。

二、部署前准备

• 一个 Cloudflare 账号（免费）

• Node.js 18+ 与 pnpm

node -v   # 确认 >= 18
npm i -g pnpm

三、方式一：一键部署（最省事）

点官方文档里的 Deploy to Cloudflare Workers 按钮，Cloudflare 会拉取仓库、引导你填环境变量（至少 JWT_SECRET）并完成部署。

⚠️ 常见坑：如果 Cloudflare 提示「无法获取存储库内容（cannot fetch repository content）」，不是你的错——先 Fork 本项目到你自己的 GitHub 账号，再用「连接到 GitHub 仓库」的方式部署，不要直接用一键部署 URL。

四、方式二：Wrangler 手动部署（推荐，可控性最好）

第 1 步：克隆并安装依赖

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

第 2 步：配置 wrangler.jsonc

这里要配两件事：环境变量（至少 JWT_SECRET）和 KV / D1 绑定。

第 3 步：处理 D1 数据库（推荐用自动预配）

Cloudflare 现在支持 Automatic resource provisioning（自动资源预配）：在 wrangler.d1.jsonc 里省略 database_id，wrangler（需 >= 4.45.0）在部署时会自动创建同名 D1 数据库并把 ID 回写进配置——不用手动建库、不用复制粘贴 UUID。

{
  "vars": { "DB_FORMAT": "sql", "DB_DRIVER": "d1" },
  "d1_databases": [{ "binding": "DB", "database_name": "openlist-data-base" }],
}

注意这里的绑定名是 DB，变量名 DB_FORMAT=sql + DB_DRIVER=d1 是官方推荐的 Cloudflare 组合（SQL 格式与 Go 后端完全兼容）。

第 4 步：部署

# 只部署 worker（前端需另行构建）
pnpm run deploy:worker

# 或：一键（前端构建 + 后端部署）
pnpm run deploy

第 5 步：部署后在 Worker 后台补配置

部署完成后，去 Cloudflare Dashboard 的 Worker 页面配置：

• KV namespace 绑定（如果要用 KV 存数据）

• 环境变量 / Secrets（见第六节）

五、数据存储后端怎么选？（重点）

OpenList Worker 把持久化拆成两个正交的层，理解这一点就不会配错：

• DB_FORMAT —— 数据怎么序列化存

• DB_DRIVER —— 用哪个底层存储系统

DB_FORMAT（存储格式）

DB_DRIVER（数据库驱动）

推荐组合

# Cloudflare Workers + D1（推荐，SQL 格式与 Go 后端完全兼容）
DB_FORMAT=sql
DB_DRIVER=d1

向后兼容：旧的 DB_DRIVER=json 会自动转换为 DB_FORMAT=map + 自动检测驱动。

表名对齐（用 sql 格式时）

sql 格式采用列式表，命名策略与 Go 后端的 GORM 一致：snake_case + 复数表名 + 固定前缀 x_。

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

六、环境变量 / Secrets 全表

💡 JWT_SECRET 是唯一强烈建议配的：不配虽然能跑（自动生成持久化到 KV），但你一旦清空 KV 数据，加密数据就解不开了。生产环境请显式设置一个长随机串。

七、部署后初始化（不用配 ADMIN_PASS）

部署完成后，首次访问站点会自动进入安装向导，在浏览器里设置管理员账号与密码即可完成初始化——无需预先配置 ADMIN_PASS。

配了 ADMIN_PASS 的话则跳过向导直接自动初始化；万一忘了管理员密码，两种补救方式：临时设置 ADMIN_PASS 重新部署，或清空已持久化的配置后重跑向导。

八、定时任务（token 刷新）

JWT_SECRET 同时充当定时任务鉴权密钥：任务入口是 POST /api/task/refresh。

EdgeOne 上用 edgeone.json 配 cron：

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

Cloudflare Workers 侧用 Cron Triggers 触发同一路径，payload 里的 cron_secret 填相同的 JWT_SECRET 即可。

九、本地开发

pnpm install

# 拉取前端并启动后端（统一开发服务器，推荐）
pnpm run dev:unified

# 或只跑 worker（前端需另行构建）
pnpm run dev:worker

十、常见问题

Cloudflare 提示「无法获取存储库内容」 先 Fork 本项目，再通过「连接到 GitHub 仓库」部署，不要直接用一键部署 URL。

保存设置后刷新又恢复原样（ESA / EdgeOne） 通常是 KV/CDN 缓存一致性问题。项目已对 /api/* 的 GET 响应强制 no-cache 并实现了模块级 KV 缓存；若仍复现，检查 KV 命名空间是否正确绑定、是否只读。ESA 的 EdgeKV 是最终一致性的，跨节点同步有延迟属正常。

部署后配置丢了 / 服务起不来 检查存储绑定：Serverless 环境（Workers / EdgeOne / ESA）禁止静默回退到内存存储——没有可用持久化后端时服务会直接报错，而不是"看起来能跑但数据丢"。请确认 D1 或 KV 绑定正确。

想和原版 OpenList 共用数据 用 DB_FORMAT=sql，表名带固定 x_ 前缀，与 Go 后端物理表完全一致，可指向同一个数据库。

十一、总结路线

OpenList Worker 目前仍在活跃开发中（仓库标注 WIP），边缘适配和安全加固的提交很密集。它把「文件列表服务」这类本该常驻的进程彻底 Serverless 化，配合 Cloudflare 的免费额度，基本等于零成本零运维——如果你之前因为不想养 VPS 而放弃自建 OpenList，现在可以重新考虑了。