# 数据库配置

<cite>
**本文引用的文件**
- [.example.env](file://.example.env)
- [AGENTS.MD](file://AGENTS.MD)
- [SystemInfoPlugin.php](file://public/plugins/system_info/SystemInfoPlugin.php)
- [ApiIndexController.php](file://public/plugins/system_info/controller/ApiIndexController.php)
- [common.php](file://vendor/thinkcmf/cmf/src/common.php)
- [composer.lock](file://composer.lock)
- [index.php](file://public/index.php)
- [api.php](file://public/api.php)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向 ThinkCMF 项目，提供数据库配置的权威说明，覆盖以下方面：
- 数据库连接配置：MySQL、MariaDB、PostgreSQL 的参数与兼容性
- 性能优化配置：连接池、超时、字符集与排序规则
- 备份与恢复：mysqldump 与逻辑备份最佳实践
- 监控与分析：慢查询日志与执行计划分析
- 安全配置：用户权限、SSL 连接与防火墙
- 迁移与版本管理：迁移脚本编写与执行
- 故障排除：连接失败、死锁与性能问题诊断

## 项目结构
与数据库配置直接相关的文件与位置如下：
- 环境变量示例与数据库参数：.example.env
- 数据库规范与迁移命令：AGENTS.MD
- 数据库版本探测与系统信息插件：SystemInfoPlugin.php、ApiIndexController.php
- 数据库相关配置读取与使用：vendor/thinkcmf/cmf/src/common.php
- 迁移工具依赖：composer.lock
- 入口文件中的调试开关与环境变量来源：public/index.php、public/api.php

```mermaid
graph TB
A[".example.env<br/>环境变量示例"] --> B["ThinkCMF 配置加载<br/>读取 DATABASE_* 参数"]
B --> C["数据库连接<br/>驱动/主机/端口/库/字符集/前缀"]
D["AGENTS.MD<br/>数据库规范与迁移命令"] --> E["迁移工具 xia/migration"]
F["SystemInfoPlugin.php<br/>VERSION() 查询"] --> G["系统信息面板"]
H["ApiIndexController.php<br/>VERSION() 查询"] --> G
I["common.php<br/>authcode/prefix 使用处"] --> C
J["composer.lock<br/>xia/migration 依赖"] --> E
K["public/index.php / api.php<br/>APP_DEBUG 来源"] --> L[".env 环境变量"]
```

**图表来源**
- [.example.env:1-1](file://.example.env#L1-L1)
- [AGENTS.MD:45-51](file://AGENTS.MD#L45-L51)
- [SystemInfoPlugin.php:41-44](file://public/plugins/system_info/SystemInfoPlugin.php#L41-L44)
- [ApiIndexController.php:45-48](file://public/plugins/system_info/controller/ApiIndexController.php#L45-L48)
- [common.php:289-306](file://vendor/thinkcmf/cmf/src/common.php#L289-L306)
- [composer.lock:1121-1151](file://composer.lock#L1121-L1151)
- [index.php:11-12](file://public/index.php#L11-L12)
- [api.php:11-12](file://public/api.php#L11-L12)

**章节来源**
- [.example.env:1-1](file://.example.env#L1-L1)
- [AGENTS.MD:45-51](file://AGENTS.MD#L45-L51)
- [SystemInfoPlugin.php:41-44](file://public/plugins/system_info/SystemInfoPlugin.php#L41-L44)
- [ApiIndexController.php:45-48](file://public/plugins/system_info/controller/ApiIndexController.php#L45-L48)
- [common.php:289-306](file://vendor/thinkcmf/cmf/src/common.php#L289-L306)
- [composer.lock:1121-1151](file://composer.lock#L1121-L1151)
- [index.php:11-12](file://public/index.php#L11-L12)
- [api.php:11-12](file://public/api.php#L11-L12)

## 核心组件
- 环境变量与数据库参数
  - 通过 .example.env 提供 DATABASE_DRIVER、DATABASE_TYPE、DATABASE_HOSTNAME、DATABASE_DATABASE、DATABASE_USERNAME、DATABASE_PASSWORD、DATABASE_HOSTPORT、DATABASE_CHARSET、DATABASE_PREFIX、DATABASE_DEBUG、DATABASE_AUTHCODE 等参数示例。
- 数据库规范与默认字符集
  - AGENTS.MD 明确支持 MySQL 5.7+、MariaDB 10.2+，默认字符集 utf8mb4，排序规则 utf8mb4_general_ci，存储引擎 InnoDB。
- 迁移与版本管理
  - AGENTS.MD 提供迁移命令（创建、执行、回滚），迁移文件由 xia/migration 包管理，遵循 Phinx 规范；composer.lock 显示该依赖已引入。
- 系统信息与数据库版本探测
  - SystemInfoPlugin.php 与 ApiIndexController.php 通过 SQL 查询 VERSION() 获取数据库版本并在后台或接口中展示。
- 配置读取与使用
  - common.php 中使用 config('database.authcode') 与 config('database.connections.mysql.prefix')，体现数据库相关配置在框架中的实际使用点。

**章节来源**
- [.example.env:1-1](file://.example.env#L1-L1)
- [AGENTS.MD:45-51](file://AGENTS.MD#L45-L51)
- [AGENTS.MD:576-599](file://AGENTS.MD#L576-L599)
- [composer.lock:1121-1151](file://composer.lock#L1121-L1151)
- [SystemInfoPlugin.php:41-44](file://public/plugins/system_info/SystemInfoPlugin.php#L41-L44)
- [ApiIndexController.php:45-48](file://public/plugins/system_info/controller/ApiIndexController.php#L45-L48)
- [common.php:289-306](file://vendor/thinkcmf/cmf/src/common.php#L289-L306)

## 架构总览
下图展示了 ThinkCMF 从环境变量到数据库连接、迁移与监控的整体流程：

```mermaid
sequenceDiagram
participant Env as ".env/.example.env"
participant Loader as "配置加载"
participant Conn as "数据库连接"
participant Migrate as "迁移工具 xia/migration"
participant Sys as "系统信息插件"
participant User as "用户/管理员"
User->>Env : 设置 DATABASE_* 环境变量
Env-->>Loader : 传递数据库参数
Loader->>Conn : 初始化连接(驱动/主机/端口/库/字符集/前缀)
User->>Migrate : 执行迁移命令
Migrate->>Conn : 读取配置并执行迁移
User->>Sys : 访问系统信息页/接口
Sys->>Conn : 查询 VERSION()
Conn-->>Sys : 返回数据库版本
Sys-->>User : 展示版本与环境信息
```

**图表来源**
- [.example.env:1-1](file://.example.env#L1-L1)
- [AGENTS.MD:576-599](file://AGENTS.MD#L576-L599)
- [SystemInfoPlugin.php:41-44](file://public/plugins/system_info/SystemInfoPlugin.php#L41-L44)
- [ApiIndexController.php:45-48](file://public/plugins/system_info/controller/ApiIndexController.php#L45-L48)
- [composer.lock:1121-1151](file://composer.lock#L1121-L1151)

## 详细组件分析

### 数据库连接配置（MySQL、MariaDB、PostgreSQL）
- 连接参数映射
  - 驱动与类型：DATABASE_DRIVER、DATABASE_TYPE
  - 主机与端口：DATABASE_HOSTNAME、DATABASE_HOSTPORT
  - 数据库与凭据：DATABASE_DATABASE、DATABASE_USERNAME、DATABASE_PASSWORD
  - 字符集与排序：DATABASE_CHARSET（默认 utf8mb4）、默认排序规则 utf8mb4_general_ci
  - 表前缀：DATABASE_PREFIX（默认 cmf_）
  - 调试与加密：DATABASE_DEBUG、DATABASE_AUTHCODE
- 兼容性与默认值
  - 支持 MySQL 5.7+、MariaDB 10.2+，默认字符集 utf8mb4，存储引擎 InnoDB
  - 建议生产环境关闭 DATABASE_DEBUG，开启强密码与网络访问控制
- 连接池与超时
  - 项目未内置连接池配置项；可通过 PDO 层面或 Web 服务器/数据库代理设置连接池与超时
  - 建议在数据库侧设置连接超时与空闲回收策略，结合应用侧请求超时统一管理

**章节来源**
- [.example.env:1-1](file://.example.env#L1-L1)
- [AGENTS.MD:45-51](file://AGENTS.MD#L45-L51)

### 性能优化配置
- 字符集与排序规则
  - 默认 utf8mb4 与 utf8mb4_general_ci，满足多语言与表情符号需求
- 存储引擎
  - 默认 InnoDB，具备事务与行级锁优势
- 连接池与超时
  - 无内置配置项，建议通过数据库服务器与 Web 服务器/反向代理层配置连接池与超时
- 索引与查询
  - 遵循 AGENTS.MD 的表命名与字段命名规范，配合索引策略提升查询性能

**章节来源**
- [AGENTS.MD:365-411](file://AGENTS.MD#L365-L411)

### 备份与恢复策略
- mysqldump 与逻辑备份
  - 建议使用逻辑备份（SQL）作为日常备份手段，便于跨平台与增量恢复
  - 备份时指定字符集与存储引擎，确保一致性
- 恢复流程
  - 恢复前先确认目标数据库字符集与排序规则与备份一致
  - 恢复后执行迁移（如有结构变更），并校验数据完整性
- 迁移与备份联动
  - 使用迁移工具维护结构变更，备份包含结构与数据，确保可重复部署

**章节来源**
- [AGENTS.MD:576-599](file://AGENTS.MD#L576-L599)

### 监控与性能分析
- 慢查询日志
  - 在数据库侧启用慢查询日志，设置阈值与日志输出路径
- 执行计划分析
  - 使用 EXPLAIN/ANALYZE 分析慢查询，结合索引与查询重写优化
- 系统信息与版本探测
  - 通过系统信息插件与接口查询数据库版本，辅助运维与升级评估

**章节来源**
- [SystemInfoPlugin.php:41-44](file://public/plugins/system_info/SystemInfoPlugin.php#L41-L44)
- [ApiIndexController.php:45-48](file://public/plugins/system_info/controller/ApiIndexController.php#L45-L48)

### 安全配置
- 用户权限管理
  - 为应用创建专用数据库用户，最小权限原则，限制主机来源
- SSL 连接
  - 在连接字符串中启用 SSL/TLS，确保传输安全
- 防火墙设置
  - 限制数据库端口访问范围，仅允许 Web 服务器与运维地址访问
- 环境变量与敏感信息
  - 将 DATABASE_PASSWORD、DATABASE_AUTHCODE 等放入 .env 并严格控制权限

**章节来源**
- [AGENTS.MD:778-792](file://AGENTS.MD#L778-L792)
- [.example.env:1-1](file://.example.env#L1-L1)

### 迁移与版本管理
- 命令与流程
  - 创建迁移：php think migrate:create
  - 执行迁移：php think migrate:run
  - 回滚迁移：php think migrate:rollback
- 迁移文件与依赖
  - 迁移文件由 xia/migration 包管理，遵循 Phinx 规范
- 结构规范
  - 遵循 AGENTS.MD 的表命名与字段命名规范，确保迁移脚本可读与可维护

**章节来源**
- [AGENTS.MD:576-599](file://AGENTS.MD#L576-L599)
- [composer.lock:1121-1151](file://composer.lock#L1121-L1151)

### 故障排除指南
- 连接失败
  - 检查 DATABASE_HOSTNAME/DATABASE_HOSTPORT 是否可达
  - 核对 DATABASE_USERNAME/DATABASE_PASSWORD 与主机来源限制
  - 确认 DATABASE_CHARSET 与数据库字符集一致
- 死锁
  - 识别热点表与长事务，拆分事务、降低锁粒度、调整隔离级别
- 性能问题
  - 使用 EXPLAIN/ANALYZE 分析慢查询，补充索引或重写查询
  - 结合慢查询日志定位高频慢查询
- 调试与日志
  - 生产环境关闭 DATABASE_DEBUG；必要时开启应用日志与数据库慢查询日志

**章节来源**
- [AGENTS.MD:778-792](file://AGENTS.MD#L778-L792)
- [SystemInfoPlugin.php:41-44](file://public/plugins/system_info/SystemInfoPlugin.php#L41-L44)
- [ApiIndexController.php:45-48](file://public/plugins/system_info/controller/ApiIndexController.php#L45-L48)

## 依赖分析
- 迁移工具依赖
  - xia/migration 作为迁移服务提供者，通过 composer.lock 可见其引入与自动加载配置
- 数据库相关配置使用点
  - common.php 中使用 config('database.authcode') 与 config('database.connections.mysql.prefix')，表明应用在运行时会读取数据库相关配置

```mermaid
graph LR
CMF["vendor/thinkcmf/cmf/src/common.php"] --> DBAuth["config('database.authcode')"]
CMF --> DBPrefix["config('database.connections.mysql.prefix')"]
MIG["xia/migration"] --> |服务提供者| APP["应用容器"]
```

**图表来源**
- [common.php:289-306](file://vendor/thinkcmf/cmf/src/common.php#L289-L306)
- [composer.lock:1121-1151](file://composer.lock#L1121-L1151)

**章节来源**
- [common.php:289-306](file://vendor/thinkcmf/cmf/src/common.php#L289-L306)
- [composer.lock:1121-1151](file://composer.lock#L1121-L1151)

## 性能考虑
- 字符集与排序规则：utf8mb4 与 utf8mb4_general_ci 适合国际化场景，注意排序规则对 LIKE 与索引的影响
- 存储引擎：InnoDB 提供更好的并发与可靠性，适用于高并发写入场景
- 连接池与超时：建议在数据库与 Web 服务器层面统一配置，避免连接泄漏与超时堆积
- 索引与查询：遵循命名规范，合理建立索引，定期分析执行计划

[本节为通用指导，无需特定文件引用]

## 故障排除指南
- 连接失败
  - 检查网络连通性与端口开放情况
  - 核对用户名与密码、主机来源白名单
- 死锁
  - 识别热点表与长事务，拆分事务、缩短持有锁时间
- 性能问题
  - 使用 EXPLAIN/ANALYZE 分析慢查询，补充索引或重写查询
- 调试与日志
  - 生产环境关闭调试；开启数据库慢查询日志与应用日志

**章节来源**
- [AGENTS.MD:778-792](file://AGENTS.MD#L778-L792)
- [SystemInfoPlugin.php:41-44](file://public/plugins/system_info/SystemInfoPlugin.php#L41-L44)
- [ApiIndexController.php:45-48](file://public/plugins/system_info/controller/ApiIndexController.php#L45-L48)

## 结论
- ThinkCMF 的数据库配置以环境变量为中心，结合 AGENTS.MD 的规范与迁移工具，形成完整的配置、迁移与运维闭环
- 生产环境建议严格遵循安全与性能最佳实践，配合监控与备份策略，保障系统稳定与数据安全

[本节为总结性内容，无需特定文件引用]

## 附录
- 环境变量示例与参数说明：参考 .example.env
- 数据库规范与迁移命令：参考 AGENTS.MD
- 系统信息与数据库版本探测：参考 SystemInfoPlugin.php 与 ApiIndexController.php
- 迁移工具依赖：参考 composer.lock

**章节来源**
- [.example.env:1-1](file://.example.env#L1-L1)
- [AGENTS.MD:45-51](file://AGENTS.MD#L45-L51)
- [AGENTS.MD:576-599](file://AGENTS.MD#L576-L599)
- [SystemInfoPlugin.php:41-44](file://public/plugins/system_info/SystemInfoPlugin.php#L41-L44)
- [ApiIndexController.php:45-48](file://public/plugins/system_info/controller/ApiIndexController.php#L45-L48)
- [composer.lock:1121-1151](file://composer.lock#L1121-L1151)