签入版本

2026-09-16 13:28:20 +08:00
parent 6cd5e80de0
commit c97d87847f
410 changed files with 68726 additions and 0 deletions
@@ -0,0 +1,197 @@
+# 数据库初始化
+
+本章节介绍如何初始化项目数据库，包括建库、建表、导入种子数据以及后续的数据库迁移管理。
+
+项目支持 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` 环境变量切换。初始化完成后即可启动后端服务。