# 数据库初始化

本章节介绍如何初始化项目数据库，包括建库、建表、导入种子数据以及后续的数据库迁移管理。

项目支持多种数据库，数据库脚本按类型存放在 `document/` 目录下：

```
document/
├── mysql/      # MySQL 脚本
│   └── djangoadmin.flask.antdvue.sql
├── postgresql/ # PostgreSQL 脚本
│   └── djangoadmin.flask.antdvue.sql
├── sqlserver/  # SQL Server 脚本
│   └── djangoadmin.flask.antdvue.sql
├── sqlite/     # SQLite 脚本
│   └── djangoadmin.flask.antdvue.sql
└── oracle/     # Oracle 脚本
    └── djangoadmin.flask.antdvue.sql
```

:::tip 温馨提示
数据库初始化前，请确保已完成以下准备工作：
1. 目标数据库服务已启动（如 MySQL 8.0+）
2. `.env` 文件中的 `DB_DRIVER` 和数据库连接信息已正确配置
3. Python 依赖已安装（`pip install -r requirements.txt`）
:::

## 方式一：手动初始化（推荐）

手动初始化是最直接、最可控的方式，适合开发环境和生产环境。

### 第一步：创建数据库

根据你使用的数据库类型，手动创建数据库。

**MySQL**：

```sql
CREATE DATABASE `djangoadmin.flask.antdvue`
  DEFAULT CHARACTER SET utf8mb4
  COLLATE utf8mb4_general_ci;
```

**PostgreSQL**：

```sql
CREATE DATABASE "djangoadmin.flask.antdvue"
  WITH ENCODING 'UTF8'
  LC_COLLATE = 'zh_CN.UTF-8'
  LC_CTYPE = 'zh_CN.UTF-8'
  TEMPLATE = template0;
```

**SQL Server**：

```sql
CREATE DATABASE [djangoadmin.flask.antdvue]
  COLLATE Chinese_PRC_CI_AS;
```

**SQLite**：

无需手动创建，指定文件路径即可（如 `DB_DATABASE=./data/app.db`），首次启动时自动创建文件。

**Oracle**：

Oracle 没有"建库"概念，schema 即连接用户。需由 DBA 预先创建表空间和用户：

```sql
-- 创建表空间
CREATE TABLESPACE djangoadmin
  DATAFILE 'djangoadmin.dbf' SIZE 100M
  AUTOEXTEND ON NEXT 10M MAXSIZE UNLIMITED;

-- 创建用户并授权
CREATE USER djangoadmin IDENTIFIED BY your_password
  DEFAULT TABLESPACE djangoadmin
  TEMPORARY TABLESPACE temp;
GRANT CONNECT, RESOURCE, CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE TRIGGER TO djangoadmin;
```

### 第二步：导入数据库脚本

进入 `document/` 目录，根据你使用的数据库类型选择对应的脚本文件夹，导入其中的 SQL 文件。

**MySQL**：

```bash
# 使用 mysql 命令行导入
mysql -uroot -p djangoadmin.flask.antdvue < document/mysql/djangoadmin.flask.antdvue.sql

# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件 → 选择 document/mysql/djangoadmin.flask.antdvue.sql
```

**PostgreSQL**：

```bash
# 使用 psql 命令行导入
psql -U postgres -d djangoadmin.flask.antdvue -f document/postgresql/djangoadmin.flask.antdvue.sql

# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件 → 选择 document/postgresql/djangoadmin.flask.antdvue.sql
```

**SQL Server**：

```bash
# 使用 sqlcmd 命令行导入
sqlcmd -S localhost -U sa -P your_password -d djangoadmin.flask.antdvue -i document/sqlserver/djangoadmin.flask.antdvue.sql

# 或使用 Navicat 等工具：右键数据库 → 运行 SQL 文件 → 选择 document/sqlserver/djangoadmin.flask.antdvue.sql
# 或使用 SSMS（SQL Server Management Studio）：打开 SQL 文件 → 执行
```

**SQLite**：

```bash
# 使用 sqlite3 命令行导入
sqlite3 ./data/app.db < document/sqlite/djangoadmin.flask.antdvue.sql

# 或使用 Navicat 等工具：打开数据库文件 → 运行 SQL 文件 → 选择 document/sqlite/djangoadmin.flask.antdvue.sql
```

**Oracle**：

```bash
# 使用 sqlplus 命令行导入
sqlplus djangoadmin/your_password@127.0.0.1:1521/XE @document/oracle/djangoadmin.flask.antdvue.sql

# 或使用 Navicat 等工具：打开连接 → 运行 SQL 文件 → 选择 document/oracle/djangoadmin.flask.antdvue.sql
```

:::tip 温馨提示
Oracle 用户需要有 CREATE TABLE、CREATE SEQUENCE、CREATE TRIGGER 权限。脚本会自动为 Integer 主键补建 sequence + BEFORE INSERT 触发器实现自增。
:::

### 第三步：配置 .env

确保 `.env` 文件中的数据库驱动和连接信息与你使用的数据库一致：

```bash
# ============================================================
# 数据库驱动配置
# 取消对应数据库的注释即可切换，同一时间仅启用一种数据库
# ============================================================

# ------------------------------------------------------------
# MySQL（默认）
# 说明：开源关系型数据库，适用性广泛，为本项目默认数据库
# ------------------------------------------------------------
DB_DRIVER=mysql          # 数据库驱动类型
DB_HOST=127.0.0.1        # 数据库主机地址
DB_PORT=3306             # 数据库端口（MySQL 默认 3306）
DB_DATABASE=djangoadmin.flask.antdvue   # 数据库名称
DB_USERNAME=root         # 数据库用户名
DB_PASSWORD=your_password  # 数据库密码（请修改为实际密码）
DB_PREFIX=flask_         # 数据表前缀

# ------------------------------------------------------------
# PostgreSQL
# 说明：功能强大的开源对象关系型数据库，支持高级特性
# ------------------------------------------------------------
# DB_DRIVER=postgresql   # 数据库驱动类型
# DB_HOST=127.0.0.1      # 数据库主机地址
# DB_PORT=5432           # 数据库端口（PostgreSQL 默认 5432）
# DB_DATABASE=djangoadmin.flask.antdvue   # 数据库名称
# DB_USERNAME=postgres   # 数据库用户名
# DB_PASSWORD=your_password  # 数据库密码（请修改为实际密码）
# DB_PREFIX=flask_       # 数据表前缀

# ------------------------------------------------------------
# SQL Server
# 说明：微软企业级关系型数据库，适用于 Windows 生态场景
# ------------------------------------------------------------
# DB_DRIVER=mssql        # 数据库驱动类型
# DB_HOST=127.0.0.1      # 数据库主机地址
# DB_PORT=1433           # 数据库端口（SQL Server 默认 1433）
# DB_DATABASE=djangoadmin.flask.antdvue   # 数据库名称
# DB_USERNAME=sa         # 数据库用户名
# DB_PASSWORD=your_password  # 数据库密码（请修改为实际密码）
# DB_PREFIX=flask_       # 数据表前缀

# ------------------------------------------------------------
# SQLite
# 说明：轻量级嵌入式文件数据库，适用于本地开发与测试
# ------------------------------------------------------------
# DB_DRIVER=sqlite       # 数据库驱动类型
# DB_DATABASE=./data/app.db  # 数据库文件路径（相对于项目根目录）
# DB_PREFIX=flask_       # 数据表前缀

# ------------------------------------------------------------
# Oracle
# 说明：企业级关系型数据库，适用于大型企业应用场景
# ------------------------------------------------------------
# DB_DRIVER=oracle       # 数据库驱动类型
# DB_HOST=127.0.0.1      # 数据库主机地址
# DB_PORT=1521           # 数据库端口（Oracle 默认 1521）
# DB_DATABASE=XE         # 数据库名称（Oracle 实例名，如 XE、ORCL）
# DB_USERNAME=djangoadmin  # 数据库用户名
# DB_PASSWORD=your_password  # 数据库密码（请修改为实际密码）
# DB_PREFIX=flask_       # 数据表前缀
```

:::tip 配置说明
1. 默认启用 MySQL，如需切换数据库，请注释掉 MySQL 相关配置，并取消对应数据库配置的注释。
2. 所有密码占位符请替换为实际数据库密码。
3. 仅需配置一种数据库即可，多个数据库配置同时启用会导致连接冲突。
4. `DB_PREFIX` 是数据表前缀，默认为 `flask_`，所有业务表名会自动添加此前缀。
:::

### 第四步：验证

启动后端服务，验证数据库连接是否正常：

```bash
python app.py
```

打开浏览器访问 `http://127.0.0.1:8021/api/v1/captcha`，尝试调用验证码接口，如能正常返回则说明数据库初始化成功。

![](/volume1/database/1.png)

![](/volume1/database/2.png)

:::tip 温馨提示
手动初始化的优势：
1. 可以精确控制导入过程，查看每条 SQL 的执行结果。
2. 可以根据需要只导入部分表或数据。
3. 适合生产环境，配合 DBA 的数据库管理流程。
4. 不依赖 Python 环境，纯 SQL 操作。
:::

## 方式二：脚本初始化（备选）

项目提供了 `setup_db.py` 脚本，可以自动完成数据库初始化。脚本会根据 `.env` 中的 `DB_DRIVER` 配置，自动选择对应的数据库方言执行初始化。

```bash
# 执行数据库初始化
python scripts/setup_db.py
```

:::tip 初始化内容
`scripts/setup_db.py` 脚本按 `DB_DRIVER` 分方言执行，自动完成以下操作：

1. **创建数据库**：检测目标数据库是否存在，不存在则自动创建
   - MySQL：`CREATE DATABASE ... DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci`
   - PostgreSQL：连接 `postgres` 维护库执行 `CREATE DATABASE`
   - SQL Server：连接 `master` 库执行 `CREATE DATABASE`
   - SQLite：直接创建数据库文件（`DB_DATABASE` 即文件路径）
   - Oracle：仅校验连通性（schema 由 DBA 预建）
2. **导入 SQL 种子数据**：根据 `DB_DRIVER` 查找 `document/{driver}/` 目录下的 SQL 脚本并执行
3. **补建缺失表**：通过 `Base.metadata.create_all(engine)` 根据 ORM 模型定义补建所有数据表
4. **Flask-Migrate 版本标记**：调用 `flask db stamp head` 将当前数据库状态标记为迁移基线

脚本源码位于 `scripts/setup_db.py`，可通过 `--drop-first` 参数先删除已存在库再重建。
:::

+ 初始化输出示例

```
$ python scripts/setup_db.py --drop-first
[INFO] ============================================================
[INFO] 数据库初始化开始
[INFO] ============================================================
[INFO] 检测数据库驱动: mysql
[INFO] 连接 MySQL 服务器: 127.0.0.1:3306
[INFO] 数据库配置: root@127.0.0.1:3306/djangoadmin.flask.antdvue
[INFO] 数据表前缀: flask_
[INFO] 删除已有数据库: djangoadmin.flask.antdvue
[INFO] 创建数据库: djangoadmin.flask.antdvue
[INFO] 查找数据库脚本: document\mysql\djangoadmin.flask.antdvue.sql
[INFO] 导入 SQL 脚本...
[INFO] SQL 脚本导入完成: 784510 条语句
[INFO] 创建数据表...
[INFO] 所有数据表均已存在，无需创建
[INFO] 数据表创建完成: 共 25 张表
[INFO] 标记 Flask-Migrate 版本...
[INFO] Flask-Migrate 版本标记完成
[INFO] ============================================================
[INFO] 数据库初始化完成！
[INFO] ============================================================
```

:::danger 注意事项
1. **不带 `--drop-first`**（默认）：创建新表和插入种子数据，**不会删除已有数据**，重复执行是安全的（幂等操作）。                                                                                                                                           
+2. **带 `--drop-first`**：会**先删除已有数据库再重建**，所有数据将丢失，仅适用于开发环境或全新部署。                                                                                                                                                       
3. 请确保 `.env` 中的数据库用户具有 `CREATE DATABASE` 和 `CREATE TABLE` 权限。
4. 脚本初始化会根据 `DB_DRIVER` 自动查找 `document/{driver}/` 目录下的 SQL 脚本。
:::

## 多数据库支持

项目通过 `DB_DRIVER` 环境变量切换数据库驱动，无需修改代码。

| 数据库 | DB_DRIVER 值 | 默认端口 | 依赖包 | 脚本目录 |
|:----|:----|:----|:----|:----|
| MySQL | `mysql` | 3306 | PyMySQL | `document/mysql/` |
| PostgreSQL | `postgresql` | 5432 | psycopg2-binary | `document/postgresql/` |
| SQL Server | `mssql` | 1433 | pymssql | `document/sqlserver/` |
| SQLite | `sqlite` | - | 内置 | `document/sqlite/` |
| Oracle | `oracle` | 1521 | oracledb | `document/oracle/` |

:::tip 温馨提示
切换数据库驱动后，需要安装对应的驱动包（如 `pip install psycopg2-binary`），然后按照上述步骤重新初始化数据库。
:::

## 种子数据

初始化完成后，数据库中包含以下默认数据：

| 数据 | 说明 |
|:----|:----|
| 管理员账号 | `admin` / `123456`（超级管理员，ID=1，跳过权限校验） |
| 默认角色 | 超级管理员角色 |
| 默认菜单 | 系统管理、内容管理、监控管理等菜单及权限节点 |
| 数据字典 | 系统内置字典数据 |
| 系统配置 | 系统默认配置项 |

如需额外导入业务字典数据，可执行：

```bash
# 初始化业务字典数据（幂等，按 code 判重，已存在跳过）
python scripts/seed_dict.py
```

## 数据库迁移

项目使用 `Flask-Migrate`（基于 Alembic）进行数据库版本迁移管理，确保数据库结构与代码模型保持同步。

+ 迁移文件位置

```
migrations/
├── env.py               # 迁移环境配置
└── versions/            # 迁移版本文件
    └── 0001_baseline.py # 基线版本
```

+ 生成增量迁移

当修改了 ORM 模型（如新增字段、修改表结构）后，需要生成增量迁移文件：

```bash
# 自动生成迁移脚本（Flask-Migrate 会对比当前模型与数据库的差异）
flask db migrate -m "描述本次变更"
```

+ 执行迁移

```bash
# 应用所有待执行的迁移
flask db upgrade
```

+ 版本标记

如果数据库已经手动同步到最新结构，可以标记当前版本：

```bash
# 标记当前数据库为最新版本
flask db stamp head
```

:::tip 迁移工作流
典型的数据库迁移工作流如下：

```
1. 修改 ORM 模型（src/modules/**/models.py）
2. 生成迁移脚本：flask db migrate -m "描述本次变更"
3. 检查生成的迁移文件（migrations/versions/ 目录）
4. 执行迁移：flask db upgrade
5. 验证数据库结构变更
```
:::

## Makefile 数据库命令速查

:::tip Windows 用户注意
`make` 命令是 Linux / macOS 系统自带的构建工具，Windows 系统默认不包含。Windows 用户可直接执行"对应命令"列所示的原始命令，如 `python scripts/setup_db.py`、`flask db migrate` 等。如需使用 `make`，可通过 `scoop install make` 或 `choco install make` 安装。
:::

| 命令 | 对应命令 | 说明 |
|:----|:----|:----|
| `make db-migrate` | `flask db migrate` | 生成增量迁移脚本 |
| `make db-upgrade` | `flask db upgrade` | 应用迁移到最新 |
| `make db-downgrade` | `flask db downgrade` | 回滚一次迁移 |

:::tip 数据库初始化
数据库初始化使用 `python scripts/setup_db.py`（非 Makefile 命令），详见上方「方式二：脚本初始化」章节。跨库数据迁移使用 `python scripts/migrate_db.py`。
:::

## 数据库备份与恢复

+ MySQL 备份

```bash
# 备份数据库
mysqldump -uroot -p djangoadmin.flask.antdvue > backup.sql

# 恢复数据库
mysql -uroot -p djangoadmin.flask.antdvue < backup.sql
```

+ PostgreSQL 备份

```bash
# 备份数据库
pg_dump -U postgres djangoadmin.flask.antdvue > backup.sql

# 恢复数据库
psql -U postgres djangoadmin.flask.antdvue < backup.sql
```

+ SQL Server 备份

```bash
# 备份数据库
sqlcmd -S localhost -U sa -P your_password -Q "BACKUP DATABASE [djangoadmin.flask.antdvue] TO DISK = 'backup.bak'"

# 恢复数据库
sqlcmd -S localhost -U sa -P your_password -Q "RESTORE DATABASE [djangoadmin.flask.antdvue] FROM DISK = 'backup.bak'"

# 或使用 Navicat 等工具进行备份恢复
# 或使用 SSMS（SQL Server Management Studio）：右键数据库 → 任务 → 备份 / 还原
```

+ SQLite 备份

```bash
# 备份数据库（直接复制文件）
cp ./data/app.db ./data/app_backup.db

# 恢复数据库（替换文件）
cp ./data/app_backup.db ./data/app.db
```

+ Oracle 备份

```bash
# 备份数据库（使用 expdp 数据泵）
expdp djangoadmin/your_password@127.0.0.1:1521/XE directory=DATA_PUMP_DIR dumpfile=backup.dmp full=y

# 恢复数据库（使用 impdp 数据泵）
impdp djangoadmin/your_password@127.0.0.1:1521/XE directory=DATA_PUMP_DIR dumpfile=backup.dmp full=y

# 或使用 Navicat 等工具进行备份恢复
```

## 总结

数据库初始化有两种方式：

```
推荐方式：手动创建数据库 → 导入 document/{driver}/ 目录下的 SQL 脚本 → 配置 .env → 启动验证
备选方式：python scripts/setup_db.py（自动完成建库、建表、导入种子数据、Flask-Migrate 标记）
```

SQL 脚本按数据库类型分目录存放在 `document/` 下，`setup_db.py` 脚本会根据 `.env` 中的 `DB_DRIVER` 自动查找对应目录的脚本文件。后续的模型变更通过 `Flask-Migrate` 迁移工具管理，确保数据库结构与代码保持同步。