OpenList-Worker：部署到 Cloudflare Workers

OpenList-Worker 是 OpenList 的 TypeScript + Serverless 移植版，把多种网盘、对象存储和协议服务聚合成一个文件列表、预览、下载与分享入口。它包含前端静态资源和 Workers 后端，适合希望不维护常驻服务器、直接使用 Cloudflare 边缘运行时的个人部署。

这篇文章以 bfb963eeb8d5324b78d4311c22bbb5e67c657342 为源码基线，给出控制台一键部署和 Wrangler CLI 两条路径。重点是把认证密钥、持久化绑定和首次初始化分开处理。本文没有登录 Cloudflare、创建资源、写入 Secret 或执行远程部署，命令需要在你的账号和环境中验证。

GitHub 仓库信息

信息	内容
项目标题	OpenList-Worker
项目描述	OpenList 的 TypeScript / Cloudflare Workers Serverless 移植版，用于聚合多种存储并提供文件浏览、预览、下载与分享
GitHub 仓库	OpenListTeam/OpenList-Worker
官网地址	OpenList 文档
主要开发语言	TypeScript
开源许可证	AGPL-3.0
最近代码更新	2026-09-29（以 GitHub `pushed_at` 核对）

部署前判断

OpenList-Worker 的 Workers 版本适合以下场景：

需要把多个网盘、S3、WebDAV、FTP 或其他驱动汇总到一个界面；
接受前端静态资源和 API 一起发布到 Workers；
能够为 Cloudflare Workers 和持久化存储分别维护配置、备份与访问权限。

它不等于完整的 OpenList Go 服务。依赖本地磁盘、长期后台进程、复杂网络挂载或大文件中转时，应先检查对应驱动在 Workers 运行时的兼容性和请求限制。项目还支持 EdgeOne、ESA 等平台，本篇只覆盖 Cloudflare Workers。

运行架构

Mermaid 流程图

正在准备渲染...

查看源码

flowchart LR
    U[浏览器] --> W[Cloudflare Worker]
    W --> A[ASSETS: dist 前端]
    W --> API[TypeScript API]
    API --> KV[(KV binding: KV)]
    API --> D1[(D1 binding: DB)]
    S[Secrets: JWT_SECRET / ADMIN_PASS] --> W

仓库的 wrangler.jsonc 声明了 Worker 入口 src/backend/worker.ts、dist 静态资源和 nodejs_compat。数据驱动由 DB_DRIVER 选择，格式由 DB_FORMAT 选择：map 适合整对象存储，key 适合分键存储，sql 用于 D1 或 MySQL 关系表。DB_DRIVER=auto 会根据可用配置探测驱动，但生产环境更适合显式配置并在部署后核对实际绑定。

前置条件

Cloudflare 账户，以及创建 Worker、KV 或 D1 的权限。
GitHub 账户；控制台导入失败时需要先 Fork 仓库。
Node.js。仓库 README 写明 Node.js 18+，package.json 固定包管理器为 pnpm@9.15.4；新部署建议使用仍受支持的 Node.js 22 或 24。
一个固定的源码版本。本文使用上面的提交；升级时应改用明确的 release 或经过验收的提交。
为 JWT_SECRET 准备至少 16 个字符的随机值。生产环境不要把它写进仓库、vars、截图或命令历史。

部署路径

路径一：Cloudflare 控制台一键部署

仓库 README 提供了 Deploy to Cloudflare Workers 按钮。

打开部署按钮，登录目标 Cloudflare 账户，并确认账号和区域没有选错。
如果提示“无法获取存储库内容”，先 Fork OpenListTeam/OpenList-Worker，再在 Workers & Pages 中通过 GitHub 连接你的 Fork。
创建完成后，在 Worker 的 Settings > Bindings 检查 ASSETS 和数据绑定。当前固定提交的 wrangler.jsonc 把 KV/D1 配置作为注释示例保留，不能仅凭部署成功就认为 KV 或 DB 已经存在。

在 Settings > Variables and Secrets 中配置：

名称	类型	建议值或作用
`JWT_SECRET`	Secret	随机长字符串；用于 JWT 签名，也参与敏感字段保护
`DB_FORMAT`	Variable	KV 方案用 `map` 或 `key`；D1 方案用 `sql`
`DB_DRIVER`	Variable	KV 方案用 `kv`；D1 方案用 `d1`；不确定时才用 `auto`
`DB_CIPHER`	Variable	默认 `none`；新生产部署可评估 `aes-256-gcm`
`ADMIN_PASS`	Secret	可选；首次初始化时可跳过安装向导并设置管理员密码，已有账号不应假定会被覆盖
`ALLOW_URLS`	Variable	可选的逗号分隔 CORS 允许列表

选择一种持久化方案并完成绑定：
- KV：创建或选择 KV namespace，绑定名必须是 KV；设置 DB_DRIVER=kv，DB_FORMAT=map。仓库脚本描述了 Wrangler 自动预配 KV 的路径，但仍应在 Dashboard 中确认绑定名和 namespace，避免误把数据写入内存。
- D1：创建 D1 数据库，绑定名必须是 DB；设置 DB_DRIVER=d1，DB_FORMAT=sql。本项目源码没有把独立 D1 migration 命令作为部署前提，切换已有数据前应先备份并按当前项目文档确认 schema 初始化方式。
保存配置并重新部署一次，让 Worker 读取最新 Secret、变量和绑定。
打开 Worker 的 workers.dev 地址，按页面提示完成首次安装；如果已经设置 ADMIN_PASS，直接使用该管理员密码登录。

路径二：Wrangler CLI

在本地固定源码并安装依赖：

bash

git clone https://github.com/OpenListTeam/OpenList-Worker.git
cd OpenList-Worker
git checkout bfb963eeb8d5324b78d4311c22bbb5e67c657342
corepack enable
corepack prepare pnpm@9.15.4 --activate
pnpm install --frozen-lockfile

先做不涉及 Cloudflare 账号的本地检查：

bash

pnpm run lint
pnpm run test:deploy
pnpm run build

登录并确认 Wrangler 使用的是目标账号：

bash

pnpm exec wrangler login
pnpm exec wrangler whoami

不要直接执行 pnpm exec wrangler kv namespace create KV 来“预先占位”。固定提交中的 scripts/deploy.js 已明确把 KV 资源交给 Wrangler 配置链路处理，手工创建可能产生未绑定的孤儿 namespace。你可以先在 Dashboard 创建并绑定 KV，或者在自己的 wrangler.jsonc 中填写真实 id；两种方式只能选一种，并在部署后核对绑定结果。

下面的片段只是配置形状，必须合并到仓库现有 wrangler.jsonc，保留原有的 name、main、assets、compatibility_date 和 compatibility_flags；在现有 vars 中新增或修改这些键，不要删除 ENVIRONMENT 等原有变量，也不要用片段直接覆盖整个文件。<kv-namespace-id> 只代表你账户中的真实 ID：

jsonc

{
  "vars": {
    "DB_FORMAT": "map",
    "DB_DRIVER": "kv",
    "DB_CIPHER": "aes-256-gcm"
  },
  "kv_namespaces": [
    { "binding": "KV", "id": "<kv-namespace-id>" }
  ]
}

D1 方案使用关系格式：

jsonc

{
  "vars": {
    "DB_FORMAT": "sql",
    "DB_DRIVER": "d1"
  },
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "openlist",
      "database_id": "<d1-database-id>"
    }
  ]
}

真实 Secret 使用 Wrangler 写入，不要放到上面的 JSON：

bash

pnpm exec wrangler secret put JWT_SECRET
# 按提示粘贴随机值；不要把值写在命令参数中

完成绑定和 Secret 后执行项目脚本：

bash

pnpm run deploy

pnpm run deploy 会先运行 scripts/fetch-frontend.mjs 获取官方前端构建产物，再调用 npx wrangler deploy。只运行 pnpm run deploy:worker 会跳过前端获取；除非 dist 已经存在且来自兼容版本，否则优先使用完整的 deploy。

配置与绑定

选择 KV 还是 D1

方案	配置	绑定名	适合场景	注意事项
KV	`DB_FORMAT=map` 或 `key`，`DB_DRIVER=kv`	`KV`	单实例、部署简单、偏配置型数据	需要确认 namespace 绑定；更换 namespace 不会自动迁移数据
D1	`DB_FORMAT=sql`，`DB_DRIVER=d1`	`DB`	需要关系表格式或与 Go 版本共享数据模型	schema、备份和升级必须单独验收
自动探测	`DB_DRIVER=auto`	由可用资源决定	本地试验或尚未固定方案	绑定缺失时可能退回不可持久化路径，生产不建议依赖猜测

ASSETS 不是业务数据库，它只提供 dist 中的前端文件。JWT_SECRET 也不是数据库绑定；它必须作为 Secret 管理。不要把 CF_API_KEY、数据库连接串或网盘凭据放到公开的 vars 中。DB_CIPHER 改为 aes-256-gcm 前先备份已有数据和 JWT_SECRET，并在测试环境确认旧密文可读；不要把加密算法切换当作数据迁移或密钥轮换的替代品。

首次初始化

Mermaid 流程图

正在准备渲染...

查看源码

flowchart TD
    A[部署 Worker] --> B{ASSETS 与数据绑定可用?}
    B -- 否 --> C[修复 KV 或 D1 绑定]
    B -- 是 --> D{JWT_SECRET 已配置?}
    D -- 否 --> E[写入 Secret 并重新部署]
    D -- 是 --> F[访问 workers.dev 地址]
    F --> G{ADMIN_PASS 已配置?}
    G -- 否 --> H[完成安装向导]
    G -- 是 --> I[使用管理员密码登录]
    H --> J[访问 /api/health 验收]
    I --> J

若使用 D1，首次启动前先确认 DB_FORMAT=sql 与 DB_DRIVER=d1 同时生效。若使用 KV，绑定名必须是 KV，不能只创建一个名字相似但未绑定的 namespace。安装完成后，重新检查 Secret、绑定和数据读写，确认没有把生产配置留在临时 Preview 环境。

验收

本地静态检查

在源码目录执行：

bash

pnpm run lint
pnpm run test:deploy
pnpm run build
pnpm exec wrangler deploy --dry-run

这些命令只能证明 TypeScript、部署约束、前端构建和 Wrangler 配置在当前机器上可解析，不能证明 Cloudflare 账号有权限，也不能证明远程绑定或域名可用。

远程验收清单

部署后按顺序记录以下结果：

访问 https://<worker-domain>/api/health，确认返回成功响应；仓库部署脚本把该地址作为首个健康检查入口。
完成登录或安装向导，确认管理员会话可以保持。
在 OpenList 中添加一个低风险的测试存储，验证目录列表、预览或下载至少一项能力。
新建一条配置后刷新页面，再次读取它，确认数据没有因为缺少绑定而消失。
在 Cloudflare Dashboard 核对当前部署版本、ASSETS、KV 或 DB 绑定，以及 Secret 没有误放入普通变量。
如果配置了自定义域名，再单独验证 DNS、TLS、根路径和 /api/health；域名可访问不等于数据绑定正确。

回滚边界

代码回滚：检出上一个已验收提交，重新构建前端并运行 pnpm run deploy。不要只回滚 Worker 代码而继续使用未兼容的 dist。
KV/D1 数据回滚：重新部署代码不会恢复被修改或删除的数据。保留旧 KV namespace、D1 备份和绑定清单，切换驱动前先导出可恢复副本。
Secret 回滚：回滚代码不会恢复旧的 JWT_SECRET。更换 JWT 密钥可能使现有会话失效，必须提前安排重新登录窗口。
域名回滚：自定义域名、DNS 和 Worker 版本是三个独立变更。先确认旧版本可访问，再调整域名指向。
卸载边界：删除 Worker 不代表 KV namespace、D1 数据库或域名记录自动删除；清理前逐项盘点并保存备份。

常见问题

Cloudflare 无法读取 GitHub 仓库

先 Fork 项目，再通过 Workers & Pages 的 GitHub 连接选择自己的 Fork。Fork 后应固定生产分支或提交，避免后续自动构建把未经验收的变更带入线上。

部署成功但刷新后数据消失

先检查 DB_DRIVER 是否仍为 auto、实际绑定名是否为 KV 或 DB，以及当前请求是否落在 Preview 环境。没有可用持久化绑定时，Worker 响应成功不代表数据已经持久化。

D1 已绑定但请求报存储配置错误

D1 需要同时使用 DB_DRIVER=d1 和 DB_FORMAT=sql。确认变量已经部署到同一环境，并重新检查数据库 ID 与 DB 绑定。不要用 KV 的 map 配置去诊断 D1 的关系表问题。

页面空白或静态文件 404

检查 dist/index.html 是否在部署包中。pnpm run deploy 会先拉取前端；只运行 deploy:worker 时需要自己准备兼容的 dist。同时核对 ASSETS 绑定和 wrangler.jsonc 的入口路径。

如何重置管理员密码

仓库文档建议临时设置 ADMIN_PASS 后重新部署，或清理持久化配置再重新运行安装流程。该变量主要用于首次初始化，已有管理员是否被覆盖要以当前提交的实现和实际日志为准，不能把它当作无条件的密码重置接口。执行前先备份数据，并在完成后删除或轮换临时 Secret；不要把管理员密码写进 vars 或 Git。

OpenList-Worker：部署到 Cloudflare Workers ​

GitHub 仓库信息 ​

部署前判断 ​

运行架构 ​

前置条件 ​

部署路径 ​

路径一：Cloudflare 控制台一键部署 ​

路径二：Wrangler CLI ​

配置与绑定 ​

选择 KV 还是 D1 ​

首次初始化 ​

验收 ​

本地静态检查 ​

远程验收清单 ​

回滚边界 ​

常见问题 ​

Cloudflare 无法读取 GitHub 仓库 ​

部署成功但刷新后数据消失 ​

D1 已绑定但请求报存储配置错误 ​

页面空白或静态文件 404 ​

如何重置管理员密码 ​

参考资料 ​

OpenList-Worker：部署到 Cloudflare Workers

GitHub 仓库信息

部署前判断

运行架构

前置条件

部署路径

路径一：Cloudflare 控制台一键部署

路径二：Wrangler CLI

配置与绑定

选择 KV 还是 D1

首次初始化

验收

本地静态检查

远程验收清单

回滚边界

常见问题

Cloudflare 无法读取 GitHub 仓库

部署成功但刷新后数据消失

D1 已绑定但请求报存储配置错误

页面空白或静态文件 404

如何重置管理员密码

参考资料