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 项目，本项目使用官方前端，界面一致。
:::caution 本项目不是 Cloudreve 官方项目，是基于 Cloudreve 的第三方移植，与官方无隶属关系。使用中遇到问题请到本项目仓库提 Issue，不要打扰上游。:::
安装
准备
- 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。数据库建表在第一次打开站点时自动执行，不需要手动迁移。
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，按正常方式启动。
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 绑定状态 |