cloudflare_temp_email 初始化与更新 D1 数据库：wrangler CLI 完整操作指南

cloudflare_temp_email 初始化与更新 D1 数据库wrangler CLI 完整操作指南【免费下载链接】cloudflare_temp_emailCloudFlare free temp domain email 免费收发 临时域名邮箱 支持附件 IMAP SMTP TelegramBot项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare_temp_email本篇指南围绕 cloudflare_temp_email 项目中的 D1 数据库初始化与 schema 升级流程展开完整讲解从 wrangler 登录、创建 D1 数据库、执行 schema.sql到按版本逐个执行 patch 文件的实操命令与背后原理。读完本文你将掌握使用wrangler d1 create/wrangler d1 execute正确搭建与维护该临时域名邮箱系统的数据层并能根据 CHANGELOG.md 判断自己该执行哪些升级脚本。为什么需要单独管理 D1 数据库cloudflare_temp_email 是一个部署在 Cloudflare Workers 上的免费临时域名邮箱服务支持收发邮件、附件、IMAP、SMTP 与 Telegram Bot 推送。Worker 本身是无状态的函数运行时所有邮件原始内容、地址簿、用户体系、发件余额、兑换码等数据都持久化在 Cloudflare D1基于 SQLite 的关系型数据库中。在 worker/wrangler.toml.template 中可以看到 Worker 与 D1 的绑定方式[[d1_databases]] binding DB database_name xxx database_id xxxbinding DB意味着 Worker 代码内部通过env.DB访问该数据库database_name与database_id分别对应你在 Cloudflare 账户下创建的 D1 数据库名称与 ID。因此数据库的创建与 schema 初始化/升级是 Worker 部署之外必须独立完成的一步这也是官方文档专门用一章来讲解 CLI 操作的原因。前置准备登录与配置文件首次执行 wrangler 登录第一次执行 wrangler 命令时CLI 会提示登录。按提示操作即可命令会打开浏览器跳转到 Cloudflare 账户授权页确认后完成 OAuth 登录wrangler 会自动将凭证保存在本地后续命令无需重复登录。wrangler login准备 wrangler.tomlWorker 目录下自带 wrangler.toml.template首次部署前需要复制为实际的wrangler.toml并填写配置cd worker cp wrangler.toml.template wrangler.toml复制完成后需要重点关注[[d1_databases]]段将database_name与database_id替换为你稍后通过wrangler d1 create创建的数据库名称与 ID也可先创建数据库再回填这两个值。初始化数据库初始化包含两个步骤创建 D1 数据库实例然后在远程数据库中执行 schema.sql。cd worker cp wrangler.toml.template wrangler.toml # 创建 D1 并执行 schema.sql wrangler d1 create temp-email-db wrangler d1 execute temp-email-db --file../db/schema.sql --remote第一步wrangler d1 createwrangler d1 create temp-email-db该命令在 Cloudflare 账户下创建一个名为temp-email-db的 D1 数据库命令输出中会返回该数据库的database_id将其回填到wrangler.toml的[[d1_databases]]段即可。第二步wrangler d1 execute 执行 schema.sqlwrangler d1 execute temp-email-db --file../db/schema.sql --remote参数说明参数含义temp-email-db要执行 SQL 的 D1 数据库名称即 create 时使用的名称--file../db/schema.sql指定要执行的 SQL 文件路径这里指向仓库根目录 db/schema.sql--remote在远程D1Cloudflare 生产环境上执行而非本地模拟环境[!tip] 命名建议 数据库名称请使用例如temp-email-db、cloudflare-temp-email-prod这样的名称。清晰、带项目语义的命名便于在账户中管理多个环境dev/prod也避免与其它 Worker 项目混淆。schema.sql 到底建了哪些表db/schema.sql 是系统数据层的基石全部使用CREATE TABLE IF NOT EXISTS与CREATE INDEX IF NOT EXISTS保证重复执行不会报错。它一次性创建了项目当前版本所需的全部核心表表名作用关键字段raw_mails收件原始邮件存储message_id、source、address、raw、raw_blob、metadata、is_unread、created_ataddress邮箱地址域名前缀name唯一、password、source_meta、created_at、updated_atauto_reply_mails自动回复规则source_prefix、name、address唯一、subject、message、enabledaddress_sender发件账户与发件余额address唯一、balance、enabledsendbox已发送邮件address、raw、created_atsettings键值配置存储key主键、valueusers用户体系user_email唯一、password、user_infousers_address用户与地址的关联user_id、address_iduser_roles用户角色user_id唯一、role_textuser_passkeys用户 Passkey 登录凭证passkey_id、passkey、counterredeem_codes兑换码code唯一、redeem_type、value、expires_at等同时 schema 为高频查询字段建立了索引例如idx_raw_mails_address、idx_raw_mails_created_at、idx_raw_mails_message_id、idx_address_name等保障收件列表、地址查询等核心接口的查询性能。在 Cloudflare 控制台确认创建完成后登录 Cloudflare 控制台在 Workers 与 Pages → D1 面板中即可看到刚才创建的数据库如下图为控制台中 D1 数据库的展示界面点击可查看数据表结构、执行 SQL 查询与查看日志。更新数据库 schemapatch 机制项目迭代过程中会不断新增字段与数据表。schema 更新请先确认你之前部署的版本对照 CHANGELOG.md或英文版 CHANGELOG_EN.md找到需要执行的 patch 文件再按时间顺序依次执行。与schema.sql的全量建表不同patch 文件采用增量 ALTER/CREATE方式逐个补齐历史版本与当前版本之间的差异。找到需要执行的patch文件后执行例如cd worker wrangler d1 execute temp-email-db --file../db/2024-01-13-patch.sql --remote wrangler d1 execute temp-email-db --file../db/2024-04-03-patch.sql --remote逐个解读 db/ 目录下的 patch 文件仓库 db/ 目录按日期维护了完整的演进历史理解每个 patch 的含义能帮你判断我到底该跑哪些脚本Patch 文件变更内容对应功能db/2024-01-13-patch.sqlmails表新增message_id TEXT列早期版本邮件表补充 Message-IDdb/2024-04-03-patch.sqladdress表新增updated_at DATETIME地址活动时间跟踪配合 wrangler.toml 中DISABLE_ADDRESS_UPDATED_AT开关db/2024-04-09-patch.sql创建raw_mails表早期结构原始邮件存储从mails迁移到raw_mailsdb/2024-04-12-patch.sql创建address_sender、sendbox表发件地址与发件箱功能db/2024-05-01-patch.sql创建settings表键值配置存储db/2024-05-08-patch.sql创建users、users_address表用户体系与用户-地址绑定db/2024-07-14-patch.sql创建user_roles表角色体系admin/vip 等见 wrangler.toml 的USER_ROLESdb/2024-08-10-patch.sql创建user_passkeys表Passkey 免密登录db/2025-09-23-patch.sqladdress表新增password列地址密码ENABLE_ADDRESS_PASSWORD功能db/2025-12-06-metadata.sqlraw_mails新增metadata TEXT存储 AI 提取结果等 JSON 元数据ENABLE_AI_EMAIL_EXTRACTdb/2025-12-15-message-id-index.sql为raw_mails.message_id建索引加速按 message_id 的查询/更新如 AI 提取结果回填db/2025-12-27-source-meta.sqladdress新增source_meta列及索引记录地址创建来源Web 存 IP、Telegram 存tg:{userId}、后台存admindb/2026-04-03-raw-blob.sqlraw_mails新增raw_blob BLOB列gzip 压缩邮件存储ENABLE_MAIL_GZIP需先执行此迁移db/2026-08-30-mail-read-status.sqlraw_mails新增is_unread INTEGER邮件已读/未读状态ENABLE_MAIL_READ_STATUS官方文档明确要求先执行迁移再开启db/2026-09-01-redeem-codes.sql创建redeem_codes表兑换码功能ENABLE_REDEEM_CODE升级建议按时间顺序执行patch 之间存在依赖关系例如users_address依赖usersraw_mails的metadata/is_unread都基于raw_mails已存在务必从你部署版本对应的最早 patch 依次执行到最新。对照变更日志确认版本每次部署 Worker 前先看 CHANGELOG.md 中该版本是否包含数据库变更若包含则在部署 Worker 前先执行对应的wrangler d1 execute命令。开关类功能务必先跑迁移以 worker/wrangler.toml.template 中的ENABLE_MAIL_READ_STATUS为例配置注释明确写着Track read and unread mail. Run the database migration before enabling.ENABLE_MAIL_GZIP同样要求先执行 db/2026-04-03-raw-blob.sql。跳过迁移直接开启开关会导致 SQL 查询字段不存在而报错。实战排错与注意事项--remote 与本地模拟的区别wrangler d1 execute默认会在本地模拟环境执行用于wrangler dev联调只有显式加上--remote才会真正作用于 Cloudflare 生产数据库。线上部署场景务必带--remote否则 schema 不会生效。工具版本前提本指南中的命令基于 worker/package.json 中锁定的 wrangler 4.xwrangler: ^4.131.1与cloudflare/workers-types5.x。建议在 worker 目录下先安装依赖npm install或项目使用的pnpm install再执行 wrangler 命令避免全局 wrangler 版本与项目不兼容。数据库 ID 回填执行wrangler d1 create后输出的database_id必须回填到 worker/wrangler.toml.template 对应的[[d1_databases]]段否则 Worker 部署后无法通过env.DB找到正确的数据库实例。小结至此你已掌握 cloudflare_temp_email 项目 D1 数据库的完整生命周期管理wrangler login登录 → 复制并配置 worker/wrangler.toml.template →wrangler d1 create创建库 → 执行 db/schema.sql 初始化全量表结构 → 对照 CHANGELOG.md 按顺序执行 db/ 目录下的增量 patch。这套流程同时适用于全新部署只跑 schema.sql与既有实例升级跑对应 patch是该项目上线与维护中最关键、也最容易因跳过迁移而踩坑的一步。【免费下载链接】cloudflare_temp_emailCloudFlare free temp domain email 免费收发 临时域名邮箱 支持附件 IMAP SMTP TelegramBot项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare_temp_email创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考