数据库初始化与已有库升级
数据库操作要按目标库状态选择流程。应用部署脚本不执行数据库迁移或seed；本节是管理员操作说明，本次文档修订未对任何数据库执行这些命令。
空库：先建立可审计基线
仓库历史迁移20260528092850_add_product_image只有ALTER product，但排序早于建product的20260528095111_init。直接在空库运行migrate deploy会失败。不要修改这两份已发布SQL的时间戳/内容，也不要在有数据的库使用以下初始化流程。
前提：新建独立空数据库，DATABASE_URL已设置，账号具有建表权限；安装后端依赖和psql。执行位置yunstack-backend/。下列变量由本地受保护配置注入，不回显连接字符串。
# 只允许新建空库：先确认不存在业务表和历史迁移账本
psql "$DATABASE_URL" -X -v ON_ERROR_STOP=1 -c "SELECT tablename FROM pg_tables WHERE schemaname='public';"
# 输出应无业务表；发现任意现有表立即停止，改走已有库流程。
psql "$DATABASE_URL" -X -v ON_ERROR_STOP=1 -1 -f src/database/prisma/migrations/20260528095111_init/migration.sql -f src/database/prisma/migrations/20260528092850_add_product_image/migration.sql
pnpm exec prisma migrate resolve --applied 20260528095111_init
pnpm exec prisma migrate resolve --applied 20260528092850_add_product_image
pnpm exec prisma migrate deploy
pnpm db:generate
pnpm exec prisma migrate status先建基础表再加image，两份SQL放同一个psql事务；只有实际成功才登记applied。Prisma resolve创建/更新账本，不会替你执行SQL。随后deploy按账本跳过两项，执行剩余认领、出厂身份、OTA、家庭历史、单设备分享和runtime增量，保留SQL中的约束与索引。该流程按SQL依赖与CLI静态核对，尚未在本次审核新建空库演练；新运维环境应先在可丢弃库完整演练并核对schema。
若第一次事务失败，事务回滚后查原因；若SQL成功但resolve失败，先核对两份SQL实际结构，再恢复账本，不能重复执行CREATE。禁止随手把失败迁移标applied掩盖缺表。
初始业务数据
数据库结构完成不代表已有账号、角色或产品。隔离开发库可显式运行pnpm exec prisma db seed。先检查src/database/prisma/seed.ts：它创建初始角色、管理员和产品，包含固定初始化密码并输出日志。确认只针对新库，完成后修改密码再开放网络。
注册服务依赖user角色；空产品库也不能让设备自动凭空定义产品。p_relay_4ch/p_env_sensor必须有与固件一致的物模型。不要把seed当作线上补表或恢复账号方法，不向日志/文档复制密码。
已有数据库升级
- 备份业务库并确认恢复方法，核对目标库/版本、
_prisma_migrations和真实结构。用pnpm exec prisma migrate status检查账本；不要自动重写历史checksum。 - 阅读待执行SQL，尤其OTA迁移会将旧协议未完成任务标失败，runtime/分享迁移有外键和唯一约束。先在独立恢复副本演练。
- 获得环境变更授权后，选择一种已审定路径：账本完整的库可
pnpm exec prisma migrate deploy；既有专项工具可使用显式env路径预检并按其校验应用。不要对同一迁移重复执行两条路径。 - 生成客户端/部署匹配代码，核对迁移完成和业务读写，再开放新功能。应用current回滚不会回滚数据库。
后端专项工具包括migrate-ota.cjs、migrate-family.cjs、migrate-device-sharing.cjs、migrate-device-runtime.cjs；它们要求明确的运行根目录和env路径，默认预检，只有显式--apply才修改。参数以脚本顶部校验为准，例如runtime：
node tools/migrate-device-runtime.cjs /绝对路径/yunstack-backend /安全目录/backend.env成功显示preflight或alreadyApplied和checksum。若提示Untracked schema、账本失配、部分表存在，先排查，不加--apply碰运气。当前在线测试库既有runtime等迁移应用记录不意味着新克隆库也已初始化。
禁止的常规修复
不在在线库使用prisma db push代替受审迁移；不运行migrate reset；不因应用回滚就删表；不重复seed或手改owner/epoch/revision解决配网。失败时保留错误与账本，修复前在恢复副本证明方案。