配置数据库连接 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

graph TB
A["config/config.php<br/>定义 $dbhost/$dbname/$dbuser/$dbpass/$prefix"] --> B["core/bootstrap.php<br/>读取配置并定义 DOU_DB_CONFIG"]
B --> C["core/facade/DB.php<br/>DB 门面底层 Connection"]
C --> D["业务代码/模型/服务<br/>通过 DB::table(...) 等调用"]

核心组件

站点配置文件：位于 config/config.php，集中声明数据库主机、端口、库名、用户名、密码、表前缀与字符集等。
引导程序：core/bootstrap.php 在启动时引入站点配置，并将数据库相关变量统一封装为 DOU_DB_CONFIG 常量，供后续初始化数据库连接使用。
ORM门面：core/facade/DB.php 提供静态门面，底层基于 Connection 单例，所有查询均通过该门面发起。

架构总览

下图展示了从配置到连接的完整链路：应用启动 -> 加载配置 -> 生成 DOU_DB_CONFIG -> ORM门面注册 -> 业务通过 DB 门面访问数据库。

sequenceDiagram
participant App as "应用入口"
participant Boot as "core/bootstrap.php"
participant CFG as "config/config.php"
participant ORM as "core/facade/DB.php"
participant DB as "数据库服务器"
App->>Boot : 启动引导
Boot->>CFG : require_once("config/config.php")
Note over Boot,CFG : 读取 $dbhost/$dbuser/$dbpass/$dbname/$prefix
Boot->>Boot : 定义 DOU_DB_CONFIG(序列化后的连接参数)
Boot->>ORM : 注册 DB 门面指向 Connection 单例
App->>ORM : DB : : table(...)->...
ORM->>DB : 建立连接并执行SQL
DB-->>ORM : 返回结果
ORM-->>App : 业务数据

详细组件分析

站点配置文件：config/config.php

作用：集中定义数据库连接所需的基本参数与系统常量。
关键项说明：
- 数据库主机：$dbhost
- 数据库名称：$dbname
- 数据库用户：$dbuser
- 数据库密码：$dbpass
- 表前缀：$prefix
- 字符集：DOU_CHARSET（utf-8）
注意：当前仓库中未定义独立的 DB_PORT 常量；如需指定非默认端口，可参考升级脚本中对 host 的解析方式（见下文）。

引导程序：core/bootstrap.php

作用：在应用启动早期加载站点配置，并将数据库相关变量汇总为 DOU_DB_CONFIG 常量，供后续初始化数据库连接使用。
关键点：
- 先加载 storage/state/admin_dir.php（若存在），再加载 config/config.php。
- 将 $dbhost/$dbuser/$dbpass/$dbname/$prefix 序列化为 DOU_DB_CONFIG。
- 随后注册自动加载、门面与容器等基础能力。

ORM门面：core/facade/DB.php

作用：对外暴露静态门面，内部委托给 Connection 单例。
典型用法：
- 查询：DB::table('xxx')->where(...)->find()
- 事务：DB::beginTransaction()/commit()/rollback()
- 调试：setDebug(true)/lastSql() 等
说明：实际连接细节由底层 Connection 实现，本门面仅做统一入口与便捷方法转发。

端口支持：host:port 形式

行为：升级脚本在尝试直连数据库时，会从 $dbhost 中解析出 host 与 port（形如 host:port），并在无显式端口时使用默认端口。
实践建议：如需指定非默认端口，可在 $dbhost 中附加 :port，例如 127.0.0.1:3307。

依赖关系分析

配置依赖：config/config.php 是唯一的站点级配置源，bootstrap 负责将其转换为框架可用的常量。
运行时依赖：DB 门面依赖底层 Connection，Connection 依赖 DOU_DB_CONFIG 提供的连接信息。
外部依赖：MySQL/MariaDB 或兼容数据库服务，需确保 PHP 扩展可用（mysqli/pdo_mysql）。

graph LR
CFG["config/config.php"] --> BOOT["core/bootstrap.php"]
BOOT --> CONST["DOU_DB_CONFIG"]
CONST --> ORM["core/facade/DB.php"]
ORM --> EXT["PHP数据库扩展<br/>mysqli/pdo_mysql"]

性能与连接池

连接复用：DouPHP 主框架通过 DOU_DB_CONFIG 管理连接，具体持久化连接（长连接）策略取决于底层 Connection 实现与 PHP 扩展设置。
插件侧连接池：仓库内包含第三方 SDK 的连接管理器与适配器（如 PDO/MySQLi/PgSQL/SQLite 等），展示了连接池、TTL、pconnect 等概念，但这些属于插件/SDK 范畴，并非 DouPHP 主框架默认启用。
建议：
- 生产环境优先使用连接池或长连接（根据数据库与中间件能力评估）。
- 合理设置超时与最大连接数，避免耗尽数据库资源。
- 对高频读场景考虑只读副本与读写分离。

故障排除指南

常见错误与排查步骤：

无法连接数据库
- 检查 config/config.php 中的 $dbhost/$dbuser/$dbpass/$dbname 是否正确。
- 如需非默认端口，确认 $dbhost 是否采用 host:port 形式。
- 验证数据库服务是否运行且监听地址/端口可达。
- 查看升级脚本中的连接失败输出，以获取更详细的错误信息。
权限问题
- 确认数据库用户具备对应库的访问权限。
- 检查远程访问白名单/防火墙规则。
网络问题
- 使用 ping/telnet/nc 测试端口连通性。
- 检查云数据库安全组/ACL。
驱动问题
- 确认已启用 mysqli 或 pdo_mysql 扩展。
- 检查 PHP 版本与扩展兼容性。
字符集问题
- 确保数据库与表字段使用 utf8mb4，客户端连接也设置为 utf8mb4。
连接测试方法
- 使用升级脚本的输出作为参考，观察“连接”行打印的主机、端口、库名与前缀，辅助定位配置来源与解析结果。
- 在本地可通过命令行工具（如 mysql/mariadb 客户端）用相同凭据进行直连测试。

结论

DouPHP 的数据库连接配置集中在 config/config.php，由 core/bootstrap.php 在启动时统一汇聚为 DOU_DB_CONFIG，并通过 core/facade/DB.php 提供给业务层使用。对于端口支持，可采用 host:port 的形式。生产环境应结合数据库与中间件能力，评估连接池与长连接策略，并完善监控与告警。

附录：环境配置示例

以下为不同环境的配置要点（以 config/config.php 中的变量为准）：

本地开发
- 主机：127.0.0.1
- 端口：默认 3306（如需非默认，使用 host:port）
- 库名：本地独立库名
- 用户/密码：本地数据库账号
- 表前缀：可按需设置
- 字符集：utf-8（建议数据库端使用 utf8mb4）
测试环境
- 主机：测试数据库地址
- 端口：按测试库实际端口配置
- 库名：隔离的测试库
- 用户/密码：最小权限账号
- 表前缀：可与开发一致或加后缀区分
生产环境
- 主机：高可用地址（VIP/负载均衡/云数据库域名）
- 端口：按生产库实际端口配置
- 库名：正式库名
- 用户/密码：严格权限控制，建议使用专用账号
- 表前缀：保持与部署一致
- 字符集：utf8mb4
- 其他：开启慢查询日志、连接池/长连接、备份与监控

添加日期：2026-10-05