CloudDrive v3.0.0
选路A · 脚本部署B · 手动部署升级本地开发排障

部署教程

两条路，二选一。#

A · 脚本一键部署（推荐）B · 手动网页部署
适合Linux / macOS / Windows，有终端任何电脑，只会用浏览器
依赖curl（缺 jq 自动装）无，纯网页操作
入口scripts/linux/deploy.sh 或 scripts/windows/deploy.bat复制 scripts/single/worker-single.js → 粘贴发布
做了什么建 D1 / KV / R2 → 初始化表 → 拼接前端 → 上传 Worker → 写密钥 → 开子域 → 配 Cron
无 wrangler.toml、无 npm 依赖：部署只调 Cloudflare API。

A · 脚本部署

一行命令，剩下的自动跑。#

前置要求

项目要求
Cloudflare 账号免费计划即可
认证（二选一）CF_API_TOKEN（推荐）或 CF_EMAIL + CF_API_KEY
Token 权限Workers 脚本读写、D1、KV；启用 R2 则需 R2 权限
本机依赖curl 必需；jq 缺失自动装；openssl / python3 任一用于生成密钥

运行

./scripts/linux/deploy.sh
scripts/windows/deploy.bat

按提示选：认证方式 → Worker 名称 → 是否启用 R2。

脚本自动完成的 5 件事

① 建资源D1 / KV / R2
→
② 初始化表schema 幂等 + 默认配置
→
③ 拼接前端html + css + bundle
→
④ 上传 Worker写 Secrets + 开子域
→
⑤ 配 Cron*/5 并回读校验

资源命名规则

资源命名说明
Worker你输入的 WORKER_NAME访问地址 <name>.<account>.workers.dev
D1（必需）db-<slug>绑定变量 env.DB
KV（可选）kv-<slug>env.KV，缺失自动降级
R2（可选）<slug>-r2env.R2，缺失自动降级
SecretsJWT_SECRET / TICKET_SECRET只写 Cloudflare Secrets，已存在跳过，不落盘

非交互部署（CI / 无终端）

预置环境变量即可：CF_API_TOKEN（或 CF_EMAIL / CF_API_KEY）、WORKER_NAME、ENABLE_R2_INPUT。

B · 手动网页部署

全程点鼠标，约 7 步。#

  1. 复制单文件代码

    打开仓库 scripts/single/worker-single.js（约 1.2MB，网页显示"太大无法预览"属正常）：点 Raw → Ctrl+A 全选 → Ctrl+C 复制。第一行注释有版本号（如 v3.0.0 · 构建于 2026-10-15），确认是最新版。

  2. 创建 Worker 并粘贴

    Cloudflare 控制台 → Workers & Pages → Create Worker → 起名（如 cloud-drive）→ Deploy → Edit code → 删掉示例代码 → 粘贴 → Save and deploy。粘贴后编辑器卡几秒正常。

  3. 创建 D1 和 KV（各点一次）

    • D1：Storage & Databases → D1 SQL → Create（如 db-cloud-drive）。表会自动建好，不用执行 SQL。
    • KV：KV → Create a namespace（如 kv-cloud-drive）。KV 是存文件的，两个都要建；只绑 D1 也能打开页面，但根目录没有可写的本地盘。

  4. 绑定到 Worker（变量名一字不差）

    Worker → Settings → Bindings → Add binding，加两条：D1 变量名 DB，KV 变量名 KV。

    大小写也要一致，DB 写成 db 会导致全站 500。

  5. 填两个密钥（各随便打一串，两串不要一样）

    Worker → Settings → Variables and Secrets → Add secret（类型选 Secret）：

    名称值干什么用
    JWT_SECRET长的乱码登录会话签名根，有效期 7 天。不填也能跑，但任何人都能伪造登录，必须填，部署后不要改（改了全员掉线）。
    TICKET_SECRET另一串不重样的乱码下载凭证 ticket 签名根，有效期 1 小时。下载链接会进浏览器历史，泄露面大，所以和登录密钥分开。

    生成办法（二选一，粘进去就行）：

    openssl rand -hex 16
    python3 -c "import secrets; print(secrets.token_hex(16))"

  6. 打开网址，设置 owner 账号

    • 等约 30 秒（新网址生效延迟，404 就刷几次）。地址在 Worker 页面的 Domains & Routes 里看。
    • 按提示创建账号：用户名 3–32 位（中英数 _ -）；密码至少 12 位且含大小写字母、数字、特殊字符，弱密码会被拒绝。
    • 登录看到文件页后先别走，继续第 7 步（不配关页后自动同步会停）。

  7. 配 Cron 定时任务（必做）

    Worker → Settings → Triggers → Add Cron Trigger，表达式填：

    * * * * *
    • 验证配好了：等 1–2 分钟，打开 https://<你的Worker>/api/health，看 lastCronAt 有时间且 cronStale 为 false。
    • 不配会怎样：存文件、手动同步、开页浏览都正常；但关页后外部同步停、拉取/复制大任务卡住、过期记录越积越多。管理后台的保活 pump 不能代替 Cron。
    • R2 可选：Storage & Databases → R2 建桶 → Bindings 加一条 R2 绑定（变量名 R2）。不加也能用（文件走 KV，单文件上限 20MB）。

升级

保留全部数据。#

脚本方式

UPGRADE=1 ./scripts/linux/deploy.sh --upgrade

只覆盖 Worker 代码，跳过建表与 R2 创建，Secrets 已存在不轮换。

手动方式

新版 worker-single.js 重新复制 → 粘贴覆盖部署即可。D1/KV 数据、密钥、网址全保留。

数据库启动时自动迁移到新版本。当前：程序 v3.0.0，数据结构 v26。

老站如果只填过 JWT_SECRET：去 Variables and Secrets 补一条 TICKET_SECRET（值与 JWT_SECRET 不重样），不用重走部署。

本地开发

改代码前先能跑起来。#

  1. 自建临时配置

    仓库根没有 wrangler.toml，自己建一份临时配置提供 DB / KV / R2 + JWT_SECRET / TICKET_SECRET 后 wrangler dev。不要提交（已被 gitignore 忽略）。

  2. 冒烟顺序

    GET /api/health → bootstrap-status → setup / login → files/list?parentId=root。

两点正常现象：本地分享页无样式（injected-css.mjs 是占位，部署脚本才会写入真实样式）；Sec-Fetch-Site: cross-site 直接 403，属安全策略，用浏览器直接访问。

部署排障

先对号入座。#

现象原因 → 对策
脚本体积超限（Free 1MB）后端新增文件会自动打包，控制总体积
全站 500，提示 D1 绑定缺失B.4 变量名写错，改成大写 DB
刚部署完 404网址生效延迟，等半分钟再刷
上传文件失败KV 没建或没绑定，回去做 B.3–B.4 的 KV 部分
粘贴代码时网页卡死文件约 1.2MB，换个浏览器重试，多等一会
/api/health 心跳滞后看 cronLagSec / lastCronAt，检查 Cron 是否配好
要卸载用仓库 delete/ 下的脚本删 Worker（与部署无关，别混用）