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

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. :::

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 ​

# 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: snake*case + 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（数据库驱动） ​

推荐组合 ​

# 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 后端默认值一致），无需额外配置即可与 Go 后端共享同一物理数据库。

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 ​

# 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:

{
  "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 手动部署 ​

# 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：

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

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

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:

{
  "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 值，并配置定时规则：

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

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 ​

# 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:

{
  "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).

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

构建与部署 ​

# 1. 安装依赖
pnpm install

# 2. 构建（产出 dist/esa-entry.js）
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" },
}

KV 命名空间 ​

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