数据库初始化

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

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

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

温馨提示

数据库初始化前，请确保已完成以下准备工作：

目标数据库服务已启动（如 MySQL 8.0+）
.env 文件中的 DB_DRIVER 和数据库连接信息已正确配置
Python 依赖已安装（pip install -r requirements.txt）

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

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

第一步：创建数据库

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

MySQL：

sql

CREATE DATABASE `djangoadmin.fastapi.elevue`
  DEFAULT CHARACTER SET utf8mb4
  COLLATE utf8mb4_general_ci;

PostgreSQL：

sql

CREATE DATABASE "djangoadmin.fastapi.elevue"
  WITH ENCODING 'UTF8'
  LC_COLLATE = 'zh_CN.UTF-8'
  LC_CTYPE = 'zh_CN.UTF-8'
  TEMPLATE = template0;

SQL Server：

sql

CREATE DATABASE [djangoadmin.fastapi.elevue]
  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.fastapi.elevue < document/mysql/djangoadmin.fastapi.elevue.sql

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

PostgreSQL：

bash

# 使用 psql 命令行导入
psql -U postgres -d djangoadmin.fastapi.elevue -f document/postgresql/djangoadmin.fastapi.elevue.sql

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

SQL Server：

bash

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

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

SQLite：

bash

# 使用 sqlite3 命令行导入
sqlite3 ./data/app.db < document/sqlite/djangoadmin.fastapi.elevue.sql

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

Oracle：

bash

# 使用 sqlplus 命令行导入
sqlplus djangoadmin/your_password@127.0.0.1:1521/XE @document/oracle/djangoadmin.fastapi.elevue.sql

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

温馨提示

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.fastapi.elevue   # 数据库名称
DB_USERNAME=root         # 数据库用户名
DB_PASSWORD=your_password  # 数据库密码（请修改为实际密码）

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

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

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

# ------------------------------------------------------------
# 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  # 数据库密码（请修改为实际密码）

配置说明

默认启用 MySQL，如需切换数据库，请注释掉 MySQL 相关配置，并取消对应数据库配置的注释。
所有密码占位符请替换为实际数据库密码。
仅需配置一种数据库即可，多个数据库配置同时启用会导致连接冲突。

第四步：验证

启动后端服务，访问 Swagger 文档验证数据库连接是否正常：

bash

python src/main.py

打开浏览器访问 http://127.0.0.1:8031/docs，尝试调用登录接口，如能正常返回则说明数据库初始化成功。

温馨提示

手动初始化的优势：

可以精确控制导入过程，查看每条 SQL 的执行结果。
可以根据需要只导入部分表或数据。
适合生产环境，配合 DBA 的数据库管理流程。
不依赖 Python 环境，纯 SQL 操作。

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

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

bash

# 执行数据库初始化
python scripts/init_db.py

初始化内容

scripts/init_db.py 脚本按 DB_DRIVER 分方言执行，自动完成以下操作：

创建数据库：检测目标数据库是否存在，不存在则自动创建
- 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 预建）
导入 SQL 种子数据：根据 DB_DRIVER 查找 document/{driver}/ 目录下的 SQL 脚本并执行
补建缺失表：通过 Base.metadata.create_all(engine) 根据 ORM 模型定义补建所有数据表
Alembic 版本标记：调用 alembic stamp head 将当前数据库状态标记为迁移基线

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

初始化输出示例

$ python scripts/init_db.py --drop-first
[INFO] ============================================================
[INFO] 数据库初始化开始
[INFO] ============================================================
[INFO] 检测数据库驱动: mysql
[INFO] 连接 MySQL 服务器: 127.0.0.1:3306
[INFO] 数据库配置: root@127.0.0.1:3306/djangoadmin.fastapi.elevue
[INFO] 数据表前缀: fastapi_
[INFO] 删除已有数据库: djangoadmin.fastapi.elevue
[INFO] 创建数据库: djangoadmin.fastapi.elevue
[INFO] 查找数据库脚本: document\mysql\djangoadmin.fastapi.elevue.sql
[INFO] 导入 SQL 脚本...
[INFO] SQL 脚本导入完成: 784510 条语句
[INFO] 创建数据表...
[INFO] 所有数据表均已存在，无需创建
[INFO] 数据表创建完成: 共 25 张表
[INFO] 标记 Alembic 版本...
2026-09-05 18:12:01,479 | INFO    | alembic.runtime.plugins | setup plugin alembic.autogenerate.schemas
2026-09-05 18:12:01,479 | INFO    | alembic.runtime.plugins | setup plugin alembic.autogenerate.tables
2026-09-05 18:12:01,479 | INFO    | alembic.runtime.plugins | setup plugin alembic.autogenerate.types
2026-09-05 18:12:01,479 | INFO    | alembic.runtime.plugins | setup plugin alembic.autogenerate.constraints
2026-09-05 18:12:01,479 | INFO    | alembic.runtime.plugins | setup plugin alembic.autogenerate.defaults
2026-09-05 18:12:01,479 | INFO    | alembic.runtime.plugins | setup plugin alembic.autogenerate.comments
INFO  [alembic.runtime.migration] Context impl MySQLImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
[INFO] Alembic 版本标记完成
[INFO] ============================================================
[INFO] 数据库初始化完成！
[INFO] ============================================================

注意事项

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

多数据库支持

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

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

温馨提示

切换数据库驱动后，需要安装对应的驱动包（如 pip install psycopg[binary]），然后按照上述步骤重新初始化数据库。

种子数据

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

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

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

bash

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

数据库迁移

项目使用 Alembic 进行数据库版本迁移管理，确保数据库结构与代码模型保持同步。

迁移文件位置

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

生成增量迁移

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

bash

# 自动生成迁移脚本（Alembic 会对比当前模型与数据库的差异）
alembic revision --autogenerate -m "描述本次变更"

执行迁移

bash

# 应用所有待执行的迁移
alembic upgrade head

版本标记

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

bash

# 标记当前数据库为最新版本
alembic stamp head

迁移工作流

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

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

Makefile 数据库命令速查

Windows 用户注意

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

命令	对应命令	说明
`make db-init`	`python scripts/init_db.py`	初始化数据库（建库 + 建表 + 种子数据 + alembic stamp）
`make seed-dict`	`python scripts/seed_dict.py`	初始化业务字典数据（幂等，按 code 判重）
`make migrate-revision`	`alembic revision --autogenerate`	生成增量迁移脚本
`make migrate-upgrade`	`alembic upgrade head`	应用所有待执行的迁移
`make migrate-stamp`	`alembic stamp head`	标记当前数据库为最新版本
`make db-migrate ARGS="..."`	`python scripts/migrate_db.py ...`	跨库数据迁移
`make db-migrate-dry-run ARGS="..."`	`python scripts/migrate_db.py ... --dry-run`	跨库迁移干跑（只核对计划，不写入目标库）

数据库备份与恢复

MySQL 备份

bash

# 备份数据库
mysqldump -uroot -p djangoadmin.fastapi.elevue > backup.sql

# 恢复数据库
mysql -uroot -p djangoadmin.fastapi.elevue < backup.sql

PostgreSQL 备份

bash

# 备份数据库
pg_dump -U postgres djangoadmin.fastapi.elevue > backup.sql

# 恢复数据库
psql -U postgres djangoadmin.fastapi.elevue < backup.sql

SQL Server 备份

bash

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

# 恢复数据库
sqlcmd -S localhost -U sa -P your_password -Q "RESTORE DATABASE [djangoadmin.fastapi.elevue] 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/init_db.py（自动完成建库、建表、导入种子数据、Alembic 标记）

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

🔐 认证与安全

📊 数据与配置

📝 日志与监控

🛡️ 防护与治理

📁 文件处理

🔧 核心工具

🧩 辅助工具

数据库初始化

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

第一步：创建数据库

第二步：导入数据库脚本

第三步：配置 .env

第四步：验证

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

多数据库支持

种子数据

数据库迁移

Makefile 数据库命令速查

数据库备份与恢复

总结

Become a sponsor

企业级中台解决方案

企业级中台解决方案

数据库初始化 ​

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

第一步：创建数据库 ​

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

第三步：配置 .env ​

第四步：验证 ​

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

多数据库支持 ​

种子数据 ​

数据库迁移 ​

Makefile 数据库命令速查 ​

数据库备份与恢复 ​

总结 ​

数据库初始化

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

第一步：创建数据库

第二步：导入数据库脚本

第三步：配置 .env

第四步：验证

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

多数据库支持

种子数据

数据库迁移

Makefile 数据库命令速查

数据库备份与恢复

总结