升级
在保留产品配置、资源身份与数据的前提下审查上游改动、迁移和发布。
升级不是覆盖目录
Flare 是独立源码仓库。你的品牌、业务和配置会逐渐与上游不同，应使用 Git 比较、合并和审查，而不是重新下载覆盖生产项目。先记录当前提交、部署目标与待发布改动，确保本地工作已保存。
获取上游差异
如果已经添加名为 upstream 的原始源码 remote：
git fetch upstream
git log --oneline HEAD..upstream/main
git diff --stat HEAD...upstream/main
git switch -c chore/flare-upgrade根据实际获得的更新分支选择目标；不要假设开发分支已经合并进 main。审查后选择 merge 或明确 commit 的 cherry-pick。冲突处理保留两边业务意图，尤其不能机械接受一边的 schema、订单或权限逻辑。
按风险检查文件
| 范围 | 升级检查 |
|---|---|
| config / i18n overrides / MDX | 保留自己的产品名、价格、商品映射及内容 |
| auth / server API | 检查登录行为、权限、Origin、限流及密钥变量 |
| db / migrations | 审查新增 SQL、已有数据和向后兼容性 |
| billing / credits / jobs | 保留账本、签名、幂等、补偿与 outbox |
| components / styles | 跟进当前别名、Base UI 与主题实现 |
| CLI / target-resources | 保留已部署资源名和账户，审查新的 plan 行为 |
本轮 UI 更新把视觉组件移入 apps/web/src/components/ui，packages/ui 只保留工具。默认登录也从密码改为邮箱验证码，密码入口为 /auth/password。合并相关提交后同步产品帮助和测试，不保留旧的导入路径或登录教程。
本机和生产配置
.env、.dev.vars、.muse 状态不随 Git 更新。将新 .env.example 与已有变量名做差异比较，只补新增项，不重置生产 AUTH_SECRET。资源名改动需要特别审查；已有数据库与 R2 不能因模板默认名变化被替换。
更新依赖时使用锁文件对应版本，执行 pnpm install --frozen-lockfile。首次缺生成文件先 build。schema 改动必须附迁移；不要在生产直接运行 db:generate 生成未审查 SQL。
升级验证与发布
先按 测试指南 完成本地检查及编译 Worker 回归，重点验证本次改变的登录、支付和任务流程。然后运行 doctor 与 --plan，确认没有意外新资源及高风险迁移，再按自己的发布流程执行。
保留回滚代码版本，同时单独评估数据库回滚。发布后检查公开 smoke 和真实服务。升级记录写清提交范围、迁移、执行结果与待验收项，不能照抄旧版测试数量。