OpenList Worker

What is OpenList Worker ​

OpenList Worker 是什么 ​

OpenList Worker（仓库 OpenList-TSWorker）是 OpenList 官方的 TypeScript + Serverless 移植版。后端由 Go 重写为运行于边缘平台上的 TypeScript 服务，前端复用官方 OpenList-Frontend（SolidJS），无需自备服务器即可一键部署。

• 后端：Hono.js（TypeScript）
• 运行平台：Cloudflare Workers / EdgeOne Functions / Alibaba Cloud ESA / Vercel / AWS Lambda
• 数据库：Cloudflare D1（SQLite）、MySQL / MariaDB / PostgreSQL / SQL Server、Cloudflare KV
• 许可证：AGPL-3.0

OpenList Worker（仓库 OpenList-TSWorker）是 OpenList 官方的 TypeScript + Serverless 移植版。后端由 Go 重写为运行于边缘平台上的 TypeScript 服务，前端复用官方 OpenList-Frontend（SolidJS），无需自备服务器即可一键部署。

• 后端：Hono.js（TypeScript）
• 运行平台：Cloudflare Workers / EdgeOne Functions / 阿里云 ESA / Vercel / AWS Lambda
• 数据库：Cloudflare D1（SQLite）、MySQL / MariaDB / PostgreSQL / SQL Server、Cloudflare KV
• 许可证：AGPL-3.0

Supported Platforms ​

支持平台 ​

One-click Deploy ​

一键部署 ​

Click the button below to deploy to the corresponding platform:

点击下方按钮，即可将本项目一键部署到对应平台：

If Cloudflare prompts 无法获取存储库内容（cannot fetch repository content）, fork this project first, then deploy by connecting to the GitHub repository. :::

若 Cloudflare 提示 无法获取存储库内容，则您需要先 Fork 本项目，再通过连接到 GitHub 仓库功能部署。 :::

Initialization ​

部署后初始化 ​

提示

After deployment, the first visit to the site automatically enters an installation wizard. Set the admin account and password in the browser to complete initialization — no pre-configured ADMIN_PASS is required.

提示

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

Environment Variables ​

环境变量 / Secrets ​

Data Backend（DB_FORMAT & DB_DRIVER） ​

数据存储后端（DB_FORMAT 与 DB_DRIVER） ​

OpenList Worker separates persistence into two orthogonal layers:

• DB_FORMAT — how data is serialized and stored
• DB_DRIVER — which underlying storage system is used

DB_FORMAT（data storage format） ​

DB_DRIVER（database driver） ​

Recommended combinations ​

bash

Cloudflare Workers + D1 (recommended, SQL format compatible with Go backend)

DB_FORMAT=sql
DB_DRIVER=d1

Backward compatibility: the legacy DB_DRIVER=json auto-converts to DB_FORMAT=map + auto-detected driver.

Table naming (SQL format) ​

The sql format uses columnar tables with the same naming strategy as the Go backend’s GORM: snakecase + pluralized table names, plus the fixed x prefix.

The prefix is fixed to x_ (matching the Go backend default), so no extra configuration is needed to share the same physical database with the Go backend.

OpenList Worker 将持久化拆分为两个正交的层：

• DB_FORMAT — 决定数据的序列化与存储方式
• DB_DRIVER — 决定底层的存储系统

DB_FORMAT（数据存储格式） ​

DB_DRIVER（数据库驱动） ​

推荐组合 ​

bash

Cloudflare Workers + D1（推荐，SQL 格式与 Go 后端完全兼容）

DB_FORMAT=sql
DB_DRIVER=d1

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

表名对齐（SQL 格式） ​

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

前缀固定为 x_（与 Go 后端默认值一致），无需额外配置即可与 Go 后端共享同一物理数据库。

Deploy to Cloudflare Workers ​

部署到 Cloudflare Workers ​

Prerequisites ​

• A Cloudflare account
• Node.js 18+ and pnpm

Option 1: One-click deploy ​

Click the Deploy to Cloudflare Workers button above. If it prompts that the repository cannot be fetched, fork the project first and deploy via the GitHub repository connection.

Option 2: Manual deploy with Wrangler ​

bash

1. Clone and install dependencies

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

2. Configure wrangler.jsonc (JWT_SECRET, KV / D1 bindings)

3. Deploy to Cloudflare Workers

pnpm run deploy:worker

or: pnpm run deploy (builds frontend + deploys backend)

D1 database ​

Use Cloudflare’s Automatic resource provisioning: omit database_id in wrangler.d1.jsonc, and wrangler (>= 4.45.0) auto-creates a D1 database with the same name and writes back the ID on deploy:

jsonc

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

After deployment, configure the KV namespace binding and environment variables in the Worker dashboard.

前置要求 ​

• 一个 Cloudflare 账号
• Node.js 18+ 与 pnpm

方式一：一键部署 ​

点击上方的 Deploy to Cloudflare Workers 按钮。若提示无法获取存储库内容，请先 Fork 本项目，再通过连接到 GitHub 仓库功能部署。

方式二：使用 Wrangler 手动部署 ​

bash

1. 克隆并安装依赖

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

2. 配置 wrangler.jsonc（填写 JWT_SECRET、KV / D1 绑定）

3. 部署到 Cloudflare Workers

pnpm run deploy:worker

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

D1 数据库 ​

使用 Cloudflare 的 Automatic resource provisioning：在 wrangler.d1.jsonc 中省略 database_id，部署时 wrangler（>= 4.45.0）会自动创建同名 D1 库并回写 ID：

jsonc

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

部署完成后，请在 Worker 后台 配置 KV namespace 绑定与环境变量。

Deploy to EdgeOne ​

部署到 EdgeOne ​

One-click deploy ​

Click the EdgeOne deploy button above, choose the international or China site:

• International console
• China console

Persistence ​

EdgeOne Makers uses @edgeone/pages-blob for persistence. The default auto driver auto-detects Blob. You can also explicitly set DB_DRIVER = “blob” (with DB_FORMAT = “map”) or DB_DRIVER = “kv” (with DB_FORMAT = “key”).

Scheduled tasks ​

EdgeOne supports scheduled refresh via edgeone.json. Set cron_secret in the payload to your JWT_SECRET value, and configure the schedule:

jsonc

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

一键部署 ​

点击上方的 EdgeOne 部署按钮，选择国际站或中国站：

• 国际站后台
• 中国站后台

持久化 ​

EdgeOne Makers 使用 @edgeone/pages-blob 进行持久化。默认的 auto 驱动会自动探测 Blob，您也可以显式设置 DB_DRIVER = “blob”（配合 DB_FORMAT = “map”）或 DB_DRIVER = “kv”（配合 DB_FORMAT = “key”）。

定时任务 ​

EdgeOne 通过 edgeone.json 支持定时刷新。将 payload 中的 cron_secret 设为你的 JWT_SECRET 值，并配置定时规则：

jsonc

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

Deploy to Alibaba Cloud ESA ​

部署到阿里云 ESA ​

OpenList Worker ships a dedicated ESA edge function entry (esa-entry.ts), which adapts Alibaba Cloud EdgeKV into the project’s KV interface.

Build & deploy ​

bash

1. Install dependencies

pnpm install

2. Build (produces dist/esa-entry.js)

pnpm run build

esa.jsonc defines the edge function entry, install/build commands, and static assets directory:

jsonc

{
“name”: “openlist”,
“entry”: “./dist/esa-entry.js”,
“installCommand”: “pnpm install –no-frozen-lockfile”,
“buildCommand”: “pnpm run build”,
“assets”: { “directory”: “./dist” },
}

KV namespace ​

Configure the EdgeKV namespace via the KV_NAMESPACE environment variable (default openlist).

提示

ESA EdgeKV is eventually consistent. The entry implements a module-level TTL cache (60s) to avoid “saved settings revert after refresh” caused by cross-node sync delay.

:::

OpenList Worker 内置了专用的 ESA 边缘函数入口（esa-entry.ts），将阿里云 EdgeKV 适配为项目的 KV 接口。

构建与部署 ​

bash

1. 安装依赖

pnpm install

2. 构建（产出 dist/esa-entry.js）

pnpm run build

esa.jsonc 定义了边缘函数入口、安装/构建命令与静态资源目录：

jsonc

{
“name”: “openlist”,
“entry”: “./dist/esa-entry.js”,
“installCommand”: “pnpm install –no-frozen-lockfile”,
“buildCommand”: “pnpm run build”,
“assets”: { “directory”: “./dist” },
}

KV 命名空间 ​

通过 KV_NAMESPACE 环境变量配置 EdgeKV 命名空间（默认 openlist）。

提示

ESA EdgeKV 是最终一致性的。入口实现了带 TTL（60 秒）的模块级缓存，避免跨节点同步延迟导致的「保存设置后刷新复原」问题。

:::

Local Development ​

本地开发 ​

bash

1. Install backend dependencies

pnpm install

2. Fetch frontend and run the backend (unified dev server)

pnpm run dev:unified

Or run the worker directly (frontend built separately)

pnpm run dev:worker

bash

1. 安装后端依赖

pnpm install

2. 拉取前端并启动后端（统一开发服务器）

pnpm run dev:unified

或单独运行 worker（前端需另行构建）

pnpm run dev:worker

Production Deploy ​

生产部署 ​

bash

One-click deploy (frontend build + backend deploy to Cloudflare Workers)

pnpm run deploy

bash

一键部署（前端构建 + 后端部署到 Cloudflare Workers）

pnpm run deploy

Troubleshooting ​

常见问题 ​

Cloudflare prompts “cannot fetch repository content”

Fork the project first, then deploy by connecting to the GitHub repository instead of the direct one-click URL.

Settings revert after save (ESA / EdgeOne)

This is usually a KV/CDN cache consistency issue. The entry already forces no-cache on /api/* GET responses and implements a module-level KV cache. If it persists, check that your KV namespace is correctly bound and not read-only.

How do I reset the admin password?

The admin password is set during the install wizard. To reset, you can set ADMIN_PASS temporarily and redeploy, or clear the persisted config and re-run the wizard.

:::

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

请先 Fork 本项目，再通过连接到 GitHub 仓库功能部署，而不是直接使用一键部署 URL。

保存设置后刷新又恢复原样（ESA / EdgeOne）

通常是 KV/CDN 缓存一致性问题。入口已对 /api/* 的 GET 响应强制 no-cache，并实现了模块级 KV 缓存。若仍存在，请检查 KV 命名空间是否正确绑定且非只读。

如何重置管理员密码？

管理员密码在安装向导中设置。如需重置，可临时设置 ADMIN_PASS 并重新部署，或清空已持久化的配置后重新运行向导。

:::

Repository ​

项目仓库 ​

• OpenListTeam/OpenList-Worker

以下为ai整理：

OpenList Worker 部署教程：Cloudflare Workers、EdgeOne 与阿里云 ESA

本文根据 OpenList Worker 官方文档整理，以便中文读者理解和部署。项目的版本、平台规则和控制台界面可能变化，实际操作时请以官方文档和项目仓库的最新说明为准。

官方文档：https://doc.oplist.org.cn/guide/installation/worker
项目仓库：https://github.com/OpenListTeam/OpenList-Worker

一、OpenList Worker 是什么？

OpenList Worker 是 OpenList 的 TypeScript / Serverless 版本。它将服务端逻辑移植到边缘计算平台运行，并复用 OpenList 官方前端，因此通常不需要自行购买和维护一台传统服务器。

项目主要采用以下技术：

• 服务端框架： Hono.js 与 TypeScript。
• 前端： OpenList 官方前端（SolidJS）。
• 运行环境： Cloudflare Workers、腾讯云 EdgeOne、阿里云 ESA，也提供面向 Vercel、AWS Lambda 等环境的适配方式。
• 数据存储： 可根据部署平台使用 D1、KV、Blob、EdgeKV 或外部数据库等方案。
• 许可证： AGPL-3.0。

需要注意：Serverless 并不等于完全不需要配置。持久化存储、环境变量、访问控制和平台配额仍然需要根据实际部署情况确认。

二、支持的平台与存储方式

官方文档提供了 Cloudflare Workers、EdgeOne 国际站、EdgeOne 中国站等一键部署入口。若一键部署时提示无法获取仓库内容，可以先 Fork 项目，再从平台控制台关联自己的 GitHub 仓库进行部署。

三、部署后首次初始化

部署成功后，打开服务地址。首次访问通常会进入安装向导，按照页面提示设置管理员账号和密码即可完成初始化。

一般情况下，不必提前设置 ADMIN_PASS。只有希望通过环境变量预先指定管理员密码、跳过安装向导时，才考虑配置该变量。

安全建议：

1. 使用强度足够且没有在其他网站重复使用的管理员密码。
2. 不要把数据库连接串、API Token、签名密钥等敏感信息写进公开仓库。
3. 部署后检查平台上的环境变量和存储绑定是否正确。
4. 如果服务用于公开分享文件，应另外检查分享权限、访问控制和平台使用规则。

四、常用环境变量

下表列出官方文档中介绍的主要配置项。并非每一种部署方式都需要全部填写。

如果使用 MySQL，可以按项目支持的方式提供完整的 MYSQL_URL，也可以分别填写 MYSQL_HOST、MYSQL_PORT、MYSQL_USER、MYSQL_PASS 和 MYSQL_NAME。请结合当前版本的配置要求填写，不要把真实密码发布在博客或截图中。

五、理解数据格式与数据库驱动

OpenList Worker 将“数据如何组织”与“数据保存在哪里”分开配置，因此 DB_FORMAT 和 DB_DRIVER 不是同一个概念。

1. DB_FORMAT：数据组织格式

2. DB_DRIVER：底层存储驱动

一个常见的 Cloudflare Workers + D1 配置组合如下：

DB_FORMAT=sql
DB_DRIVER=d1

选择配置时要同时考虑运行平台和数据迁移需求。若希望与 OpenList 的 Go 后端共用兼容的关系型数据结构，可以重点参考 sql 模式及项目当前版本的数据库迁移说明。

3. SQL 模式下的表名

文档说明，SQL 格式采用与 Go 后端 GORM 命名习惯相近的表名规则，使用蛇形命名、复数形式以及固定的 x_ 前缀。例如：

虽然命名策略保持兼容，但在共用数据库或迁移数据前，仍建议先备份数据，并确认两个版本对表结构和字段的要求一致。

六、部署到 Cloudflare Workers

准备条件

• 一个 Cloudflare 账号。
• Node.js 18 或更新版本。
• pnpm 包管理器。
• 如果采用手动部署，还需要能访问项目仓库并具备配置 Worker、KV 或 D1 的权限。

方式 A：一键部署

1. 打开官方 Worker 文档。
2. 点击 Cloudflare Workers 对应的部署入口。
3. 按照 Cloudflare 控制台的提示完成仓库关联和部署。
4. 若控制台提示无法获取仓库内容，先 Fork 官方项目，再通过 GitHub 仓库连接方式部署。
5. 部署完成后，检查 Worker 的变量、KV Namespace 绑定以及数据库绑定。

方式 B：使用 Wrangler 手动部署

先克隆项目并安装依赖：

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

然后按照仓库中的配置文件说明，编辑 wrangler.jsonc 等配置，设置需要的密钥、KV 或 D1 绑定。配置完成后运行：

pnpm run deploy:worker

如果需要先构建前端，再一并部署前后端，可以使用：

pnpm run deploy

具体脚本名称和配置字段可能随项目版本调整，执行前请核对仓库中的 package.json 与 Wrangler 配置文件。

D1 数据库配置

项目文档介绍了 Wrangler 的 D1 自动创建能力。在符合对应 Wrangler 版本要求时，可以按项目配置示例省略 database_id，让 Wrangler 在部署过程中创建同名 D1 数据库并回写 ID。

配置结构示意如下，具体字段请以当前仓库的 wrangler.d1.jsonc 为准：

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

官方文档指出，该自动资源配置需要 Wrangler 版本满足相应要求（文档提及 4.45.0 或更新版本）。部署后还应在 Worker 控制台核对 KV Namespace 绑定和环境变量。

七、部署到腾讯云 EdgeOne

一键部署

打开官方文档，选择 EdgeOne 部署入口，并根据需求进入国际站或中国站控制台，按照平台指引完成部署。

持久化设置

EdgeOne Makers 可通过 @edgeone/pages-blob 实现数据持久化。通常可以先让 DB_DRIVER=auto 自动识别 Blob 存储，也可以根据所选存储方式明确配置驱动。

例如，使用 Blob 并以整对象 JSON 方式保存数据时，可以考虑：

DB_FORMAT=map
DB_DRIVER=blob

若采用 KV 方式，则需结合项目支持的格式与平台绑定进行配置，例如：

DB_FORMAT=key
DB_DRIVER=kv

请先确认当前 EdgeOne 项目实际提供了哪些绑定和存储能力，再选择对应组合。

定时任务

文档示例使用 edgeone.json 配置定时请求。下面是结构示意，部署时应把 cron_secret 的值替换为与 JWT_SECRET 相同的秘密值，并根据需要调整执行时间：

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

不要把实际使用的密钥原样发布到博客、公开代码仓库或公开截图中。

八、部署到阿里云 ESA

项目提供了适配 ESA 的边缘函数入口 esa-entry.ts，用于将阿里云 EdgeKV 接入项目的 KV 接口。

构建步骤

在项目目录中安装依赖：

pnpm install

执行构建：

pnpm run build

项目配置中的 esa.jsonc 用于指定入口文件、依赖安装命令、构建命令和静态资源目录。文档示例的结构如下：

{
“name”: “openlist”,
“entry”: “./dist/esa-entry.js”,
“installCommand”: “pnpm install –no-frozen-lockfile”,
“buildCommand”: “pnpm run build”,
“assets”: {
“directory”: “./dist”
}
}

配置 EdgeKV

可以通过 KV_NAMESPACE 环境变量指定 EdgeKV 命名空间；文档所述默认值为 openlist。请在 ESA 控制台中确认命名空间、权限和环境变量配置正确。

一致性提示： 文档说明，ESA EdgeKV 具有最终一致性特征。项目入口使用约 60 秒 TTL 的模块级缓存，降低跨节点同步延迟造成设置保存后短时间内看似恢复旧值的问题。因此，刚修改配置后若不同节点显示不一致，应先考虑同步延迟，并检查命名空间绑定和权限。

九、本地开发与生产部署

本地开发

安装依赖：

pnpm install

启动统一开发服务器（会拉取前端并启动后端）：

pnpm run dev:unified

也可以单独启动 Worker 后端：

pnpm run dev:worker

使用后一种方式时，需要根据项目说明单独准备或构建前端。

生产部署

如果要构建前端并将后端部署到 Cloudflare Workers，可按项目脚本使用：

pnpm run deploy

如果只需要部署 Worker 后端，则可使用：

pnpm run deploy:worker

请以当前仓库的脚本定义为准；不同版本可能调整构建和部署流程。

十、常见问题排查

1. Cloudflare 提示无法获取仓库内容

可以先 Fork 官方项目，然后在 Cloudflare 控制台通过连接 GitHub 仓库的方式部署，不要反复使用无法读取仓库的一键部署入口。

2. 保存设置后刷新又恢复了

在 EdgeOne 或 ESA 环境下，可能与 KV / CDN 缓存或数据最终一致性有关。建议依次检查：

1. 确认 KV 或 Blob 命名空间已经正确绑定。

2. 检查对应存储是否有写入权限，而不是只读。

3. 核对部署时使用的 DB_DRIVER 与平台实际提供的存储能力是否匹配。

4. 如果刚刚保存配置，稍等片刻再刷新，排除跨节点同步延迟。

5. 检查 CDN 或代理是否缓存了不应缓存的 API 响应。

6. 如何处理管理员密码问题？

管理员密码通常在首次安装向导中设置。若需要重设，可以参考项目当前版本的管理说明；官方文档提及的处理思路包括临时设置 ADMIN_PASS 后重新部署，或清理已持久化的配置并重新运行初始化向导。

操作前务必确认影响范围并备份数据。 清理持久化配置可能影响管理员设置以及其他数据，不要在没有备份的情况下直接清空数据库或 KV。

十一、部署前检查清单

☐ 已确认平台支持的运行时和存储类型。
☐ 已完成管理员账号初始化。
☐ 已正确配置数据库或 KV / Blob 绑定。
☐ 已检查 DB_FORMAT 与 DB_DRIVER 是否匹配。
☐ 已保护 JWT_SECRET、数据库密码和 API Token。
☐ 已确认数据确实能在重新部署或实例重启后保留。
☐ 已测试上传、下载、分享和管理员登录等核心功能。
☐ 已了解所用平台的免费额度、限制、服务条款和数据备份方式。

参考链接

• OpenList Worker 官方部署文档：https://doc.oplist.org.cn/guide/installation/worker
• OpenList Worker 项目仓库：https://github.com/OpenListTeam/OpenList-Worker

本文为便于阅读的中文整理与改写版本，不是官方原文的逐字转载。部署前请查看官方文档和仓库中的最新配置，避免因版本变化导致命令或字段不再适用。