Cloudreve-Worker

Cloudreve-Worker 是 Cloudreve v4 后端的 TypeScript 重写版，运行在 Cloudflare Workers 上。不是 Go 编译移植，而是按上游行为重写，当前对齐上游 4.19.1。

运行环境：Cloudflare Workers，无需服务器
数据库：Neon serverless Postgres
缓存与会话：Workers KV
前端：官方前端，随 Worker 一起发布
存储：R2 / S3 / OSS / COS / OBS / KS3 / 七牛 / OneDrive / 又拍云，以及从节点本地磁盘

Cloudreve 界面截图

截图来自上游 Cloudreve 项目，本项目使用官方前端，界面一致。

:::caution 本项目不是 Cloudreve 官方项目，是基于 Cloudreve 的第三方移植，与官方无隶属关系。使用中遇到问题请到本项目仓库提 Issue，不要打扰上游。:::

本项目基于 AI 辅助开发。 不愿意使用 AI 产出代码的，可以不用本项目，直接自建官方 Cloudreve。:::

安装

准备

Cloudflare 账号
Neon 账号（可用 GitHub 登录）
GitHub 账号（用于 Fork）

1. 创建 Neon 数据库

打开 neon.tech，新建项目，区域选离你近的。
复制 Dashboard 首页的 Connection string，它就是 DATABASE_URL：

postgresql://user:pass@ep-xxx.aws.neon.tech/neondb?sslmode=require

免费档够用。

2. Fork 并部署（推荐）

在 GitHub 上 Fork 本项目仓库。
Cloudflare 控制台 → Workers & Pages → Create，选你 Fork 的仓库。
按下表填写构建配置：

配置项	填写
构建命令	`npm install`
部署命令	`npm run deploy`
输出目录	留空

项目设置 → 环境变量，添加 DATABASE_URL，保存后重新部署。

:::warning构建命令不要填 npm run build。它是 CI 的 dry-run 检查，放在构建阶段会多打一遍包、多拉一遍前端，构建时间会从一两分钟涨到八九分钟。:::

npm run deploy 会自动创建 KV namespace 和 R2 bucket（账号里已有同名的直接复用），并把资源 ID 写回 wrangler.toml。数据库建表在第一次打开站点时自动执行，不需要手动迁移。

通过 Fork 部署，之后在 GitHub 上点 Sync fork 就能拿到本项目的更新，Workers Builds 会自动重新部署。:::

3. 首次访问

打开 Worker 地址，注册第一个账号，第一个注册的用户自动成为管理员。

管理员权限丢失时，同时配置 ADMIN_EMAIL 和 ADMIN_PASSWORD，Worker 会保证该邮箱存在、密码一致且在管理员组。恢复后建议删除这两个变量。

备选：一键部署

:::note一键部署生成的是独立副本，不会跟随本项目更新，仅适合快速体验。:::

点击部署按钮后，在部署页把 DATABASE_URL 填成 Neon 连接串，其余留空，点 Deploy。

配置

部署完成后，必须先完成下面两项，否则无法正常使用。

设置站点地址

在 Cloudflare → Worker → 设置 → 变量和机密中，把 SITE_URL 设成站点对外地址，例如 https://pan.example.com。分享短链和下载直链依赖它生成。

然后到管理后台 → 设置 → 站点，把 siteURL 填成同一个地址。多个地址用英文逗号分隔，每一段都要带 https://，否则会报 Invalid siteURL。

添加存储策略

默认没有任何存储后端，不添加就无法上传文件。进入管理后台 → 存储策略 → 添加：

存储类型	策略类型与填写
Cloudflare R2	选 `s3`（R2 兼容 S3 协议）。Endpoint 填 `https://<accountid>.r2.cloudflarestorage.com`，区域填 `auto`，再填桶名与 AK / SK
S3 / OSS / COS / OBS / KS3 / 七牛	选对应类型，填桶名、Endpoint、AK / SK、区域
OneDrive / SharePoint	选 `onedrive`，在策略页点击授权并登录微软账号；授权过期后需重新授权
又拍云	选 `upyun`，填空间名、操作员、密码、加速域名
从节点本地磁盘	选 `remote`，并绑定节点，见下文「节点存储」
负载均衡	选 `load_balance`，按权重在多个策略间分流

:::warning添加策略后，必须到 用户组 → 编辑 把策略绑定给用户组，否则上传会报 No policy selected。:::

环境变量

位置：Cloudflare → Worker → 设置 → 变量和机密。只有 DATABASE_URL 必填。

变量	必填	说明
`DATABASE_URL`	是	Neon 连接串，主库，唯一可写
`SITE_URL`	建议	站点对外地址；不设则回落到后台 siteURL
`JWT_SECRET`	否	令牌签名密钥，32 位以上随机串；不设则自动生成并入库
`ADMIN_EMAIL`	否	兜底管理员邮箱，须与 `ADMIN_PASSWORD` 一起配置
`ADMIN_PASSWORD`	否	兜底管理员密码，建议存成 Secret
`FRONTEND_URL`	否	前端单独部署到别处时才填，反代优先于内置资源
`CORS_ALLOW_ORIGINS`	否	允许跨域的源，逗号分隔；前后端同源无需配置
`R2_PUBLIC_BASE`	否	R2 公共域名，配置后直链不带签名
`KV_COUNT`	否	KV namespace 数量，1 到 5，默认 1
`DATABASE_URL_2` 至 `DATABASE_URL_5`	否	备库连接串，每次构建从主库整库同步
`DB_FAILOVER`	否	填 `1` 开启主库故障切换，仅作应急
`DB_SYNC_SKIP`	否	全量同步时跳过的表，逗号分隔

KV_COUNT 不能填在「变量和机密」里。那是运行时变量，而 KV 绑定数量在构建时就要确定，读不到时会静默回落成 1，且不会报错。请配置在 Workers Builds 的环境变量中，或在仓库根目录放一个名为 KV_COUNT 的文件。:::

邮件、全文检索、用户组权限、WebDAV 账号都在管理后台配置。

邮件

管理后台 → 设置 → 邮件，填写 SMTP 主机、端口、用户名、密码、加密方式和发件人。

:::caution 开启「注册需邮件激活」后，新用户必须收到邮件才能登录。SMTP 没配好会导致所有人无法注册。:::

WebDAV

用户组 → 编辑 → 勾选 WebDAV 权限。
用户在「连接与挂载」中创建 WebDAV 账号，得到的是专用密码，不是登录密码。
客户端连接地址填 https://你的域名/dav。

Windows 映射网络驱动器、MT 管理器、Alist / OpenList、rclone、Cyberduck 均已验证可用。

:::warning单文件上传上限为 100 MB，这是 Cloudflare 套餐限制：Free / Pro 为 100 MB，Business 为 200 MB，Enterprise 可在 zone 的 Network → Maximum Upload Size 调到 5 GB。超限请求在到达 Worker 前就会被 Cloudflare 以 413 拒绝。大文件请使用网页端上传。:::

节点存储

Worker 没有硬盘，若要把文件放在自己机器的磁盘上，需要一台从节点：Worker 作为主站，通过签名 RPC 向从节点读写文件。从节点可以是官方 Cloudreve 从机，也可以是仓库自带的 agent/cloudreve-node-agent.mjs，两者协议相同，可混用。

1. 启动从节点

自带 agent：

node agent/cloudreve-node-agent.mjs --root /data/cloudreve --port 8666 --secret 你的密钥

参数	环境变量	默认值	说明
`--root`	`NODE_ROOT`	`./data`	文件落盘根目录
`--port`	`NODE_PORT`	`8666`	监听端口
`--secret`	`NODE_SECRET`	必填	主到从的签名密钥，须与后台一致
`--host`	`NODE_HOST`	`0.0.0.0`	监听地址

官方从机则在 conf.ini 中设置 [System] Mode = slave 和 [Slave] Secret，按正常方式启动。

通过 nginx 或 Caddy 反代时：使用 HTTPS；放开 PUT 和 DELETE；client_max_body_size 设为 0 或不小于分片大小（默认分片 25MB，nginx 默认 1MB 会导致分片 413）。:::

2. 在后台添加节点

管理后台 → 节点 → 新建，类型选 slave，填写名称、地址（如 https://node.example.com，不带 /api/v4/slave）和密钥，保存后点击测试确认密钥匹配。

3. 创建策略并绑定用户组

存储策略 → 添加 → 类型选 remote → 选择刚添加的节点 → 保存，再到用户组里绑定。

4. 让节点接离线下载（可选）

节点 → 编辑 → 能力位，勾选「远程下载」。离线下载会分派到该节点执行：没有 200MB 单文件限制，也不占用 Worker 的 CPU 预算，状态同步最多延迟一分钟。「打包」「解压」能力位目前仅对官方 Cloudreve 从机有效。

多 KV 与备库

多 KV：KV_COUNT 设为 2 到 5 后，KV 按角色拆分，缓解并发写入限速。

绑定	用途
`KV_1`	站点设置缓存
`KV_2`	会话、验证码、2FA
`KV_3`	上传会话、打包、WebDAV 锁
`KV_4`	外部凭据缓存
`KV_5`	自举标记
`KV`	兜底绑定，未配置 `KV_n` 时所有角色回落到它

备库：在 Neon 另建项目，把连接串依次填入 DATABASE_URL_2 到 DATABASE_URL_5。主库挂了，把 DB_FAILOVER 设为 1 临时切换。

:::danger备库是只读冷备，不是双活。切换期间写入备库的数据，会在下次同步时被主库覆盖。:::

更新

在你 Fork 的仓库页面点击 Sync fork，Workers Builds 会自动重新部署，也可以在 Cloudflare 手动 Retry deployment。

排错

现象	原因与处理
打开是「后端已就绪」纯文本页	前端构建失败。查看构建日志中的 fetch-frontend 步骤，重新部署
登录后立刻被登出	检查 `DATABASE_URL` 是否可连；配置了多库时确认没有误开 `DB_FAILOVER`
上传报 `No policy selected`	用户组没有绑定存储策略
报 `Invalid siteURL`	站点地址每一段都要带 `https://`
WebDAV 提示「位置不可用」	`wrangler.toml` 的 `run_worker_first` 中必须包含 `/dav/*`
大文件上传报 413	触发 Cloudflare 的 100 MB 请求体限制，改用网页端上传
构建耗时异常增长	构建命令被改成了 `npm run build`，应使用 `npm install`
定时任务没运行	Cloudflare → Worker → 触发器，确认 Cron 存在，可手动触发

运行状态检查地址：

地址	内容
`/api/v4/site/ping`	服务是否可达
`/api/v4/site/db-status`	数据库状态
`/api/v4/site/kv-status`	KV 绑定状态

安装​

准备​

1. 创建 Neon 数据库​

2. Fork 并部署（推荐）​

3. 首次访问​

备选：一键部署​

配置​

设置站点地址​

添加存储策略​

环境变量​

邮件​

WebDAV​

节点存储​

多 KV 与备库​

更新​

排错​

安装

准备