# 数据库变更规范(DDL) > **所有表结构变更只允许通过 sequelize-cli 迁移脚本执行,禁止直接连库改表。** ## 为什么 - 迁移记录在 `SequelizeMeta` 表里,换环境(开发 / 测试 / 生产)按同一条命令重放,不会漏表、漏字段; - 直接 `ALTER TABLE` 无法回溯,环境之间会悄悄不一致; - 回滚有据可依(每个迁移都有 `down`)。 ## 目录与配置 ``` backend/ ├─ .sequelizerc # sequelize-cli 路径配置 ├─ database/ │ ├─ config.cjs # 连接信息(与环境变量 / config.local.js 同源) │ ├─ migrations/ # ★ DDL 脚本放这里 │ └─ seeders/ # 初始数据(可选) ``` 连接信息由 `scripts/db-config.js` 统一解析:**环境变量 > `config/config.local.js` > 默认值**, 与运行时服务完全一致,避免「迁移改 A 库、服务连 B 库」。 ## 常用命令 ```bash npm run db:migrate # 执行全部未执行的迁移 npm run db:migrate:status # 查看哪些执行过 npm run db:migrate:undo # 回滚最后一条 npm run db:migration:generate -- create_xxx_tables # 生成迁移骨架 ``` ## 写迁移的约定 - 表名/字段名用**下划线**,与既有表保持一致; - 主键统一 `BIGINT UNSIGNED` 自增; - 时间字段统一 `created_at` / `updated_at` / `deleted_at`(软删除),`status` 用 `TINYINT UNSIGNED`; - 不建物理外键(与 `users`、`scanners` 等既有表一致),只建索引; - `up()` 必须能重复执行前先看 `SequelizeMeta`(由 CLI 保证只跑一次),`down()` 必须能干净回滚。 ## 已执行过的迁移 | 迁移 | 内容 | |---|---| | `20261018100000-create-nvr-camera-workstation-tables` | `nvrs` / `cameras` / `workstations` / `workstation_cameras` / `workstation_scan_channels` | | `20261018150000-add-channel-name-to-cameras` | `cameras.channel_name`(设备通道名,与业务别名分开) | | `20261018180000-add-has-ptz-to-cameras` | `cameras.has_ptz`(是否支持云台) | | `20261018200000-add-workstation-layout` | `workstations.canvas_width/height` + `workstation_cameras.x/y/width/height/stream_type/z_index` | | `20261018200100-backfill-workstation-camera-layout` | 回填已有绑定关系的画布位置(第 1 条铺满 / 第 2 条右上 / 其余左下) | | `20261018210000-add-workstation-type` | `workstations.ws_type`(1 散单 / 2 团购) | | `20261018220000-add-workstation-record-range` | `workstations.record_before_sec/record_after_sec/record_max_sec`(录制范围与最大录制时长) | | `20261018230000-create-subject-tables` | 新表 `subjects` / `subject_members`;`scanners`/`nvrs`/`cameras`/`workstations`/`scan_channels`/`scan_records` 加 `subject_id`,并把已有数据回填到「每人一个主体」 || `20261019233000-drop-has-ptz-from-cameras` | 删除 `cameras.has_ptz`(预览统一显示云台面板,后端不再标记是否支持云台) | > 历史遗留的 `sql/schema.sql` + `sql/migrations/*.sql`(用 `npm run db:init` 执行)是接入 sequelize-cli 之前的做法, > 只用于初始化老表;**新变更一律写 `database/migrations/*.js`**。