D1 数据库迁移
使用 Actions
正常运行 00 Deploy Worker 即可。新库执行完整 schema 并登记迁移基线，旧库根据结构与迁移记录选择待执行 SQL，验证通过后才发布 Worker。
手动部署前准备
- 使用 Node.js 24，在项目根目录执行
npm ci。 - 确认
wrangler.toml的DB指向目标数据库，保留模板的[build] command = "npm run schema:generate"。 - 在终端环境设置自己的
CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID、EDGECHAT_D1_DATABASE_ID，数据库 ID 与DB一致。 - 升级已有库时先导出备份：
bash
npx wrangler d1 export DB --remote --config wrangler.toml --output .tmp/d1-backup.sql备份可能包含敏感业务数据，请离线保存。规划脚本直接调用 Cloudflare API，使用上述环境凭据。
新库初始化
仅对全新空库执行：
bash
npx wrangler d1 execute DB --remote --config wrangler.toml --file worker/schema.sql随后继续下方迁移流程，登记基线。已有数据库直接进入迁移流程。
规划、执行、验证
逐条执行，上一条成功后再继续：
bash
node .github/scripts/prepare-d1-migrations.mjs
npx wrangler d1 execute DB --remote --config wrangler.toml --file .tmp/edgechat-d1-migrations.sql
node .github/scripts/prepare-d1-migrations.mjs --verify第一条读取结构并生成本地 SQL，第二条应用，第三条验证。新库完整 schema 会登记为 baseline；旧库执行待应用迁移及适用的结构修复。
验证成功后，初始化管理员并部署 Worker。历史迁移由规划脚本选择，勿逐个重放；重跑完整 schema 无法为已有表补齐新列。
迁移检查失败
缺少迁移时先查看日志，重新运行正常部署。校验值不一致、未知迁移或结构漂移时，保留备份和错误报告，核对代码版本及数据库目标；已发布 SQL 的调整使用新增迁移完成。
迁移记录在 edgechat_schema_migrations。检查范围包括表、列、索引和触发器是否存在，后台也使用同一份结构清单。
误跑旧 private-groups 迁移
若在完整 schema 后执行 2026-04-05-private-groups.sql，出现 add_new_user_to_general: no such table: main.channels，先停止后续 SQL，执行只读查询：
bash
npx wrangler d1 execute DB --remote --config wrangler.toml --command "SELECT type,name FROM sqlite_master WHERE name IN ('channels','channels_new','add_new_user_to_general'); PRAGMA table_info(channels); PRAGMA table_info(channel_members);"将结果、报错和备份情况交给维护者。先确认实际表结构，再制定恢复步骤，保留触发器与临时表供核对。
详细背景见仓库中的D1 维护说明。