简介

本指南面向首次部署或升级DouPHP的工程师，详细说明如何正确导入系统的数据库表结构。内容涵盖：

• SQL文件的组织结构与各模块表的作用
• 导入前的准备工作（数据库、字符集、权限）
• 多种导入方式（命令行mysql客户端、phpMyAdmin、Navicat等）
• 导入过程中的错误处理与回滚策略
• 导入后的验证步骤，确保所有表正确创建

项目结构与SQL文件组织

DouPHP将“系统级表结构”和“各模块表结构”分别存放：

• 系统级表结构：位于 _'\doc\开发手册\系统表结构.sql，包含管理后台、AI、文章、预约、商品、订单等核心表的DDL语句，统一使用utf8mb4字符集与InnoDB引擎。
• 模块级表结构：每个功能模块在各自目录下提供备份/建表脚本，例如 area、product、order 等模块的 storage/backup/*.sql。

graph TB
A["系统表结构<br/>_'\doc\开发手册\系统表结构.sql"] --> B["模块表结构<br/>_'\module/*/storage/backup/*.sql"]
B --> C["数据库实例<br/>douphp_dou"]
A --> C

核心组件与表结构概览

• 系统表结构（示例）
  • 管理员与安全：dou_admin、dou_admin_log
  • AI能力：dou_ai、dou_ai_key、dou_ai_model、dou_ai_provider、dou_ai_task、dou_ai_usage_log
  • 内容与分类：dou_article、dou_article_category
  • 预约服务：dou_book、dou_book_class、dou_book_item、dou_book_rule、dou_book_schedule、dou_book_log、dou_book_notify
  • 聊天与知识：dou_chat、dou_chat_knowledge、dou_chat_message、dou_chat_daily_stats、dou_chat_package、dou_chat_quota
  • 区域：dou_area
• 模块表结构（示例）
  • 区域模块：dou_area
  • 商品模块：dou_product、dou_product_category
  • 订单模块：dou_order、dou_order_address、dou_order_cart、dou_order_coupon、dou_order_invoice、dou_order_item、dou_order_payment、dou_order_refund、dou_order_status_log

说明

• 所有表默认使用InnoDB引擎与utf8mb4字符集，保证多语言与表情符号支持。
• 表前缀为 dou_，由配置项控制。

架构总览

下图展示从SQL文件到数据库的导入流程，以及不同工具对同一批DDL的执行路径。

sequenceDiagram
participant U as "用户"
participant CLI as "命令行mysql客户端"
participant PMA as "phpMyAdmin"
participant NAV as "Navicat"
participant DB as "MySQL服务器"
U->>CLI : 执行 mysql < 系统表结构.sql
CLI->>DB : 解析并执行DDL
U->>PMA : 选择数据库并导入SQL
PMA->>DB : 解析并执行DDL
U->>NAV : 打开SQL并运行
NAV->>DB : 解析并执行DDL
DB-->>U : 返回执行结果/错误信息

详细组件分析

系统表结构文件（系统表结构.sql）

• 作用：一次性创建系统所需的核心表结构，包括管理、AI、内容、预约、聊天、区域等。
• 关键特性：
  • 设置会话字符集为 utf8mb4，避免中文乱码。
  • 使用 InnoDB 引擎，支持事务与外键（如需）。
  • 定义主键、唯一键与常用索引，提升查询性能。
• 导入建议：
  • 先选择目标数据库，再执行该文件。
  • 若已有同名表，请根据业务需要决定是否先清空或备份。

模块表结构（以 area/product/order 为例）

• area.sql：定义区域基础表，含层级、名称、ISO代码与排序字段。
• product.sql：定义商品与商品分类表，包含价格、促销、库存、SEO字段及索引。
• order.sql：定义订单主表及地址、购物车、优惠券、发票、订单项、支付、退款、状态日志等关联表，覆盖完整交易链路。

字符集与连接适配

• 应用配置中定义了数据库主机、库名、用户名、密码、表前缀与字符集常量。
• MySQL适配器通过SET NAMES设置客户端字符集，确保导入与运行时一致。

依赖关系分析

• 系统表结构是基础，模块表结构依赖系统提供的公共能力（如用户、权限、区域等），因此导入顺序建议：
  1. 先导入系统表结构
  2. 再按模块导入各自的表结构
• 字符集一致性是关键：SQL文件内已设置utf8mb4；应用配置也声明了DOU_CHARSET；导入后应确认数据库与表的字符集一致。

flowchart TD
Start(["开始"]) --> Sys["导入系统表结构"]
Sys --> Modules{"是否需启用模块?"}
Modules --> |是| ModA["导入模块A表结构"]
Modules --> |否| Verify["验证表结构"]
ModA --> Modules
Modules --> |否| Verify
Verify --> End(["结束"])

[无图表来源，因为此图为概念性流程图]

性能注意事项

• 大文件导入优化
  • 调整MySQL参数：增大 max_allowed_packet、net_buffer_length，减少网络包限制导致的失败。
  • 关闭不必要的日志与检查：临时关闭binlog或innodb_flush_log_at_trx_commit可加速导入（生产环境谨慎操作）。
• 索引与存储引擎
  • 系统表结构已定义必要索引；导入后可根据实际查询模式评估是否需要补充索引。
  • 保持InnoDB引擎以获得更好的并发与崩溃恢复能力。
• 批量导入
  • 命令行导入通常比图形界面更快更稳定，适合大型SQL文件。

故障排查指南

常见错误与处理

• 字符集不一致导致乱码
  • 现象：中文显示异常或插入失败。
  • 处理：确认SQL文件中的SET NAMES与数据库/表字符集一致；必要时在导入前后执行SET NAMES utf8mb4。
• 表已存在冲突
  • 现象：导入时报Duplicate table name。
  • 处理：先DROP TABLE IF EXISTS或清空后再导入；或在导入前备份现有数据。
• 权限不足
  • 现象：无法创建表或写入数据。
  • 处理：授予用户对目标库的CREATE、INSERT、ALTER、DROP等权限。
• 超时或内存不足
  • 现象：导入中断或报错。
  • 处理：增加max_allowed_packet、memory_limit、set_time_limit；分批次导入。

回滚策略

• 建议在导入前开启事务或使用外部备份：
  • 命令行：mysqldump导出当前库作为快照；导入失败时恢复。
  • phpMyAdmin/Navicat：在执行前创建数据库快照或备份。
  • 对于单条SQL失败：记录错误行号，修复后重新执行受影响部分。

结论

• 导入顺序：先系统表结构，再模块表结构。
• 字符集：统一使用utf8mb4，确保全链路一致。
• 工具选择：命令行适合大批量与自动化；phpMyAdmin/Navicat适合交互式调试与可视化。
• 验证：导入后核对表数量、关键字段与索引，确保系统可正常初始化。

附录：导入方法清单

导入前准备

• 创建数据库与用户
  • 数据库名：参考配置中的dbname（默认：douphp_dou）。
  • 表前缀：参考配置中的prefix（默认：dou_）。
  • 字符集：数据库、表、列均建议使用utf8mb4。
• 权限检查
  • 确保用户具备CREATE、DROP、ALTER、INSERT、SELECT、INDEX等权限。
• 备份
  • 若为升级场景，请先备份现有数据。

方法一：命令行mysql客户端

• 基本命令
  • 选择数据库：USE douphp_dou;
  • 导入系统表结构：mysql -u root -p douphpdou < "'\doc\开发手册\系统表结构.sql"
  • 导入模块表结构：依次执行各模块的 backup/*.sql
• 注意事项
  • 若SQL中包含SET NAMES，无需重复设置；否则可在导入前执行SET NAMES utf8mb4;
  • 遇到大文件导入失败，调整max_allowed_packet等参数后重试。

方法二：phpMyAdmin

• 步骤
  • 登录phpMyAdmin，选择目标数据库。
  • 点击“导入”，选择系统表结构.sql，设置字符集为utf8mb4，执行。
  • 再逐个导入模块的SQL文件。
• 注意事项
  • 注意最大上传文件大小限制，必要时修改php.ini与nginx/apache配置。
  • 若出现重复表错误，先删除或清空相关表。

方法三：Navicat

• 步骤
  • 新建连接并选择目标数据库。
  • 右键数据库 -> “运行SQL文件”，选择系统表结构.sql，设置编码为UTF-8，执行。
  • 再依次运行模块SQL文件。
• 注意事项
  • 可使用“计划任务”或“批处理”进行自动化导入。
  • 导入过程中如遇错误，查看输出日志定位问题。

导入后验证

• 表数量与命名
  • 核对系统表与模块表是否全部创建，表名前缀是否符合预期。
• 字符集与引擎
  • 检查数据库、表、列的字符集是否为utf8mb4，引擎是否为InnoDB。
• 索引与约束
  • 抽查关键表的主键、唯一键与常用索引是否存在。
• 功能连通性
  • 访问管理后台与前台页面，确认能正常读取表结构并初始化必要数据。