198 lines
5.2 KiB
Markdown
198 lines
5.2 KiB
Markdown
# 数据库初始化
|
||
|
||
本章节介绍如何初始化项目数据库，包括建库、建表、导入种子数据以及后续的数据库迁移管理。
|
||
|
||
项目支持 MySQL、PostgreSQL、SQL Server、SQLite、Oracle 等多种数据库，通过 `.env` 中的 `DB_DRIVER` 切换驱动。
|
||
|
||
:::tip 温馨提示
|
||
数据库初始化前，请确保已完成以下准备工作：
|
||
1. 目标数据库服务已启动（如 MySQL 8.0+）
|
||
2. `.env` 文件中的 `DB_DRIVER` 和数据库连接信息已正确配置
|
||
3. Python 依赖已安装（`poetry install`）
|
||
:::
|
||
|
||
## 方式一：手动初始化（推荐）
|
||
|
||
手动初始化是最直接、最可控的方式，适合开发环境和生产环境。
|
||
|
||
### 第一步：创建数据库
|
||
|
||
根据你使用的数据库类型，手动创建数据库。
|
||
|
||
**MySQL**：
|
||
|
||
```sql
|
||
CREATE DATABASE `djangoadmin.tornado.elevue`
|
||
DEFAULT CHARACTER SET utf8mb4
|
||
COLLATE utf8mb4_general_ci;
|
||
```
|
||
|
||
**PostgreSQL**：
|
||
|
||
```sql
|
||
CREATE DATABASE "djangoadmin.tornado.elevue"
|
||
WITH ENCODING 'UTF8'
|
||
LC_COLLATE = 'zh_CN.UTF-8'
|
||
LC_CTYPE = 'zh_CN.UTF-8';
|
||
```
|
||
|
||
**SQL Server**：
|
||
|
||
```sql
|
||
CREATE DATABASE [djangoadmin.tornado.elevue];
|
||
```
|
||
|
||
### 第二步：导入数据库脚本
|
||
|
||
MySQL 数据库脚本位于 `document/` 目录下：
|
||
|
||
```bash
|
||
# 登录 MySQL
|
||
mysql -uroot -p
|
||
|
||
# 导入脚本
|
||
mysql -uroot -p djangoadmin.tornado.elevue < document/djangoadmin.tornado.elevue.sql
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
`document/djangoadmin.tornado.elevue.sql` 是 MySQL 专用脚本。对于 PostgreSQL / SQL Server / SQLite / Oracle，建议使用 Alembic 方式初始化。
|
||
:::
|
||
|
||
### 第三步：导入字典种子数据
|
||
|
||
```bash
|
||
# 导入业务字典数据（性别、友链类型、通知来源等）
|
||
python scripts/seed_dict.py
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
`seed_dict.py` 是幂等脚本，可重复执行不会产生重复数据。
|
||
:::
|
||
|
||
## 方式二：Alembic 迁移初始化
|
||
|
||
适合非 MySQL 数据库，或需要版本化管理数据库结构的场景。
|
||
|
||
### 第一步：创建数据库
|
||
|
||
同方式一的手动建库步骤。
|
||
|
||
### 第二步：执行迁移
|
||
|
||
```bash
|
||
# 根据 models 定义自动建表
|
||
poetry run alembic upgrade head
|
||
```
|
||
|
||
### 第三步：导入种子数据
|
||
|
||
```bash
|
||
python scripts/seed_dict.py
|
||
```
|
||
|
||
## 方式三：脚本初始化（备选）
|
||
|
||
```bash
|
||
# 自动完成建库、建表、导入种子数据
|
||
python scripts/init_db.py
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
`init_db.py` 会根据 `.env` 中的 `DB_DRIVER` 配置自动初始化数据库。适合快速搭建开发环境。
|
||
:::
|
||
|
||
## 多数据库驱动配置
|
||
|
||
项目通过 `DB_DRIVER` 环境变量切换数据库驱动：
|
||
|
||
| DB_DRIVER | 别名 | Python 驱动 | 安装方式 |
|
||
|:----------|:-----|:------------|:---------|
|
||
| `mysql` | — | pymysql | 默认已安装 |
|
||
| `postgresql` | `postgres` | psycopg2-binary | `poetry install -E postgresql` |
|
||
| `mssql` | `sqlserver` | pymssql | `poetry install -E mssql` |
|
||
| `sqlite` | `sqlite3` | sqlite3 | 内置，无需额外安装 |
|
||
| `oracle` | — | oracledb | `poetry install -E oracle` |
|
||
|
||
### SQLite 配置示例
|
||
|
||
```bash
|
||
# .env
|
||
DB_DRIVER=sqlite
|
||
DB_DATABASE=/path/to/djangoadmin.db
|
||
```
|
||
|
||
:::tip SQLite 说明
|
||
当 `DB_DRIVER=sqlite` 时，`DB_DATABASE` 为数据库文件的完整路径（相对或绝对路径），`DB_HOST`、`DB_PORT`、`DB_USERNAME`、`DB_PASSWORD` 均被忽略。
|
||
:::
|
||
|
||
### PostgreSQL 配置示例
|
||
|
||
```bash
|
||
# .env
|
||
DB_DRIVER=postgresql
|
||
DB_HOST=127.0.0.1
|
||
DB_PORT=5432
|
||
DB_DATABASE=djangoadmin.tornado.elevue
|
||
DB_USERNAME=postgres
|
||
DB_PASSWORD=your_password
|
||
```
|
||
|
||
### Oracle 配置示例
|
||
|
||
```bash
|
||
# .env
|
||
DB_DRIVER=oracle
|
||
DB_HOST=127.0.0.1
|
||
DB_PORT=1521
|
||
DB_DATABASE=XEPDB1 # SERVICE_NAME
|
||
DB_USERNAME=system
|
||
DB_PASSWORD=your_password
|
||
```
|
||
|
||
## 初始化完成后
|
||
|
||
数据库初始化完成后，系统包含以下默认数据：
|
||
|
||
| 数据 | 说明 |
|
||
|:-----|:-----|
|
||
| 管理员账号 | admin / 123456（超级管理员，ID=1，跳过权限校验） |
|
||
| 默认角色 | 超级管理员角色 |
|
||
| 默认菜单 | 系统管理、内容管理、监控管理等菜单及权限节点 |
|
||
| 数据字典 | 性别、状态、类型等系统内置字典数据 |
|
||
| 系统配置 | 系统默认配置项 |
|
||
|
||
## 跨库数据迁移
|
||
|
||
项目提供 `scripts/migrate_db.py` 脚本，支持在不同数据库之间迁移数据（如 MySQL → PostgreSQL）。详细说明请参考 [跨库数据迁移](/zh/volume6/db-cross-migrate) 章节。
|
||
|
||
## 常见问题
|
||
|
||
+ 数据库连接失败
|
||
|
||
```
|
||
1. 检查数据库服务是否已启动
|
||
2. 检查 .env 中的 DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD 是否正确
|
||
3. 检查防火墙是否放行了数据库端口
|
||
4. 检查数据库用户是否有建库/建表权限
|
||
```
|
||
|
||
+ 导入脚本报错
|
||
|
||
```
|
||
1. 确认数据库字符集为 utf8mb4（MySQL）
|
||
2. 确认数据库版本符合要求（MySQL 8.0+）
|
||
3. 检查脚本文件是否完整（未被截断）
|
||
```
|
||
|
||
+ Alembic 迁移失败
|
||
|
||
```
|
||
1. 确认 alembic.ini 中的数据库连接配置正确
|
||
2. 检查是否存在版本冲突：poetry run alembic history
|
||
3. 如需重置：poetry run alembic downgrade base，然后 poetry run alembic upgrade head
|
||
```
|
||
|
||
## 总结
|
||
|
||
本章节介绍了三种数据库初始化方式：手动导入 SQL 脚本（推荐）、Alembic 迁移、脚本自动初始化。项目支持 MySQL / PostgreSQL / SQL Server / SQLite / Oracle 五种数据库，通过 `DB_DRIVER` 环境变量切换。初始化完成后即可启动后端服务。
|