简介

本文件面向系统管理员，聚焦 DouPHP 的系统级配置，尤其是 config/config.php 的核心作用与关键参数。内容涵盖数据库连接（主机、端口、用户名、密码、表前缀）、字符集、系统标识符、目录定义、安全与文件存储相关配置项；说明各参数的含义、默认值、修改方法与注意事项；给出生产与开发环境的完整配置示例；解释引导过程中配置的加载顺序与作用域；并提供常见配置问题的排查与解决方案。

项目结构

DouPHP 将“站点运行期配置”集中在 config/ 目录，由框架在启动阶段统一加载并注入到全局配置中。入口 index.php 引入 core/bootstrap.php，后者负责定义根路径、安全协议常量、检查安装状态、载入站点配置文件、合并模块映射、注册自动加载与门面等。

graph TB
A["index.php"] --> B["core/bootstrap.php"]
B --> C["config/config.php<br/>数据库/字符集/目录/应用密钥/调试开关"]
B --> D["config/security.php<br/>可信代理/Host白名单/安全头/限流/会话"]
B --> E["config/file.php<br/>文件系统/上传默认/磁盘映射"]
B --> F["config/system.php<br/>固定模块/保留URL段/小程序页面"]

核心组件

• 站点配置（config/config.php）
  • 数据库连接：主机、库名、用户名、密码、表前缀
  • 字符集：DOU_CHARSET
  • 系统标识：SYSTEM_SIGN
  • 目录定义：ADMIN_DIR、API_DIR、MINIPROGRAM_DIR
  • 管理后台重写：ADMIN_REWRITE
  • 应用密钥：DOU_APP_KEY
  • 调试开关：DOU_DEBUG
• 安全配置（config/security.php）
  • 可信代理、可信 Host、安全响应头、限流、会话 Cookie 硬化
• 文件与上传（config/file.php）
  • 默认驱动、上传限制、允许扩展名、图片质量、缩略图目录、磁盘映射
• 系统常量（config/system.php）
  • 前台固定模块、小程序内置模块、保留 URL 首段、小程序额外页、不参与 app.json 的 single 模块、后台隐藏 single 模块

架构总览

引导流程中，配置加载顺序与作用域如下：

1. 入口 index.php 定义 IN_DOUCO 并引入 core/bootstrap.php
2. bootstrap.php 定义 ROOT_PATH、CONFIG_PATH、STORAGE_PATH、HTTP/IS_HTTPS
3. 若未安装则跳转安装程序
4. 可选读取 storage/state/admin_dir.php（用于覆盖 $admining），再载入 config/config.php
5. 基于 config/config.php 中的 ADMIN_DIR/API_DIR/MINIPROGRAM_DIR 定义 CORE_PATH/LIBRARY_PATH/FRONT_PATH/API_PATH/ADMIN_PATH/MINIPROGRAM_PATH/PLUGIN_PATH
6. 读取并序列化 module.php（模块启用清单）
7. 将数据库变量聚合为 DOU_DB_CONFIG（host/user/pass/name/prefix）供后续 DB 连接使用
8. 注册自动加载、门面别名、DI 容器、路由调度器、Request 单例、全局助手等

sequenceDiagram
participant U as "浏览器"
participant I as "index.php"
participant B as "core/bootstrap.php"
participant CFG as "config/config.php"
participant SEC as "config/security.php"
participant FIL as "config/file.php"
participant SYS as "config/system.php"
U->>I : 发起请求
I->>B : require bootstrap
B->>B : 定义路径/协议常量
B->>B : 检查安装状态
B->>CFG : require config.php
B->>B : 定义路径常量(ADMIN/API/MINI等)
B->>B : 读取module.php并序列化
B->>B : 生成DOU_DB_CONFIG
B->>SEC : 后续Init阶段合并安全配置
B->>FIL : 后续Init阶段合并文件配置
B->>SYS : 后续Init阶段合并系统常量
B-->>I : 完成引导
I-->>U : 路由分发并返回响应

详细组件分析

站点配置（config/config.php）

• 数据库连接
  • 主机：$dbhost，默认 127.0.0.1
  • 库名：$dbname，默认 douphp_dou
  • 用户名：$dbuser，默认 root
  • 密码：$dbpass，默认 123456
  • 表前缀：$prefix，默认 dou_
  • 注意：bootstrap 会将上述变量序列化为 DOU_DB_CONFIG，供数据库连接使用。请确保 PHP 已启用 PDO MySQL 扩展，且目标数据库可访问。
• 字符集
  • DOU_CHARSET，默认 utf-8
  • 注意：需与数据库/表/字段字符集一致，避免中文乱码。
• 系统标识
  • SYSTEM_SIGN，默认 company
  • 用途：区分站点类型或业务线，便于多站点或多租户场景下的差异化处理。
• 目录定义
  • ADMIN_DIR：默认 admin，可通过 storage/state/admin_dir.php 覆盖 $admining 动态设置
  • API_DIR：默认 api
  • MINIPROGRAM_DIR：默认 miniprogram
  • 注意：这些常量会被 bootstrap 用于定义 ADMIN_PATH、API_PATH、MINIPROGRAM_PATH，影响路由与资源路径。
• 管理后台重写
  • ADMIN_REWRITE：默认 false
  • 注意：开启后需配合 Web 服务器重写规则，否则后台路由可能无法访问。
• 应用密钥
  • DOU_APP_KEY：默认提供示例值
  • 注意：生产环境务必更换为唯一且足够长度的随机字符串，用于签名/加密等安全场景。
• 调试开关
  • DOU_DEBUG：默认 true
  • 注意：生产环境建议关闭，以减少敏感信息泄露风险。

安全配置（config/security.php）

• 可信代理 trusted_proxies
  • 空数组表示不信任任何代理；部署在反向代理/负载均衡时，填入代理出口 IP/CIDR，以便正确获取客户端真实 IP。
• 可信 Host trusted_hosts
  • 空表示不校验；非空时仅允许列表内的域名，防止 Host 头注入污染对外链接。
• 安全响应头 headers
  • frame_options/content_type_options/referrer_policy/permissions_policy/hsts
  • HSTS 仅在 HTTPS 且 enabled 时下发，max_age 单位为秒，subdomains 控制是否包含子域。
• 限流 throttle
  • store 指向 storage/cache/throttle/，default 为 null 表示默认不限流，仅敏感端点受中间件配额保护。
• 会话 session
  • httponly=true 防 XSS 窃取 sid；secure=null 跟随 IS_HTTPS；samesite=Lax；use_strict_mode=true 拒绝外部未初始化 sid。

文件与上传（config/file.php）

• 默认驱动 default=local
• 上传默认 upload_defaults
  • upload_max_kb=2048（单文件上限）
  • allow_extensions 默认不含 svg（SVG 存在存储型 XSS 风险，确需时在对应磁盘显式开启）
  • image_quality=100
  • thumb_directory 留空表示与原图同目录
• 磁盘 disks
  • local 指向 images/upload/
  • avatar_admin 继承约定路径 images/avatar_admin/，仅覆盖上传上限

系统常量（config/system.php）

• front_fixed_module：前台固定内建模块（如 index/page/search/captcha/sitemap/llms）
• miniprogram_builtin_module：小程序内置模块（index/page/search）
• reserved_first_segment：前台保留 URL 首段（不可被模块短名占用）
• miniprogram_extra_page：小程序专属页（无业务模块）
• miniprogram_no_handle：不参与小程序 app.json 生成的 single 模块
• nav_hidden_single/admin_hidden_single：不参与导航/后台菜单的 single 模块

依赖关系分析

• 入口与引导
  • index.php 依赖 core/bootstrap.php 完成基础常量、路径、安装检查与配置加载
  • bootstrap.php 依赖 config/config.php 获取数据库与目录等关键配置，并生成 DOU_DB_CONFIG
• 配置与运行时
  • security.php 与 file.php 在 Init 阶段合并入 Config，影响 Request、Session、Storage 等子系统
  • system.php 提供框架层固定模块清单，影响路由判定与小程序构建

graph LR
IDX["index.php"] --> BOOT["core/bootstrap.php"]
BOOT --> CFG["config/config.php"]
BOOT --> MOD["config/module.php"]
BOOT --> DB_CFG["DOU_DB_CONFIG"]
INIT["Init阶段"] --> SEC["config/security.php"]
INIT --> FIL["config/file.php"]
INIT --> SYS["config/system.php"]

性能注意事项

• 数据库连接
  • 合理设置主机与端口，优先使用本地回环或内网地址以降低延迟
  • 确保 PDO 扩展可用，必要时调整 PHP-FPM/MySQL 连接池与超时参数
• 字符集
  • 统一使用 utf-8 或 utf8mb4，避免跨端编码不一致导致的性能损耗与错误
• 安全头与会话
  • HSTS 仅在 HTTPS 下启用，减少重定向开销
  • SameSite 策略根据跨站需求选择，避免不必要的 Cookie 传输
• 文件上传
  • 限制最大文件大小与扩展名，降低恶意文件上传风险与存储压力
  • 图片质量与缩略图策略按业务权衡，平衡清晰度与带宽

故障排查指南

• 数据库连接失败
  • 检查 config/config.php 中的主机、端口、用户名、密码、库名是否正确
  • 确认 DOU_DB_CONFIG 已正确生成（由 bootstrap 从 $dbhost/$dbuser/$dbpass/$dbname/$prefix 聚合）
  • 验证 PHP 已启用 PDO MySQL 扩展，且防火墙/安全组放行数据库端口
  • 若使用代理或云数据库，确认网络可达性与 DNS 解析
• 字符集乱码
  • 确认 DOU_CHARSET 与数据库/表/字段字符集一致
  • 检查数据库连接建立后的 SET NAMES 是否生效（通常由框架内部处理）
• 路径错误
  • 确认 ADMIN_DIR/API_DIR/MINIPROGRAM_DIR 与实际目录一致
  • 若修改了后台目录，需在 storage/state/admin_dir.php 中设置 $admining 以覆盖默认值
  • 检查 Web 服务器根目录与站点根目录是否匹配
• 安全相关问题
  • 反向代理环境下，配置 trusted_proxies 以正确识别客户端 IP
  • 配置 trusted_hosts 防止 Host 头注入导致的外部链接污染
  • 生产环境关闭 DOU_DEBUG，避免错误堆栈泄露
• 文件上传失败
  • 检查 upload_max_kb 与服务器 php.ini 的 upload_max_filesize/post_max_size 限制
  • 确认 images/upload/ 目录存在且可写
  • 如需 SVG，请在对应磁盘配置中显式允许扩展名

结论

DouPHP 的配置体系以 config/config.php 为核心，结合安全、文件与系统常量配置，通过 bootstrap 在启动早期统一加载并注入到全局上下文。管理员应重点关注数据库连接、字符集、目录定义与应用密钥，并根据环境与部署拓扑调整安全与文件策略。遵循本文提供的配置示例与排查步骤，可快速定位并解决常见问题，保障系统稳定与安全。

附录：生产与开发环境配置示例

以下为两类典型环境的配置要点（以 config/config.php 为主，其他配置按需调整）。请勿直接复制代码，参考以下字段与默认值进行变更。

• 开发环境

  • 数据库
    • 主机：127.0.0.1
    • 库名：douphp_dou
    • 用户名：root
    • 密码：123456
    • 表前缀：dou_
  • 字符集：utf-8
  • 系统标识：company
  • 目录：admin/api/miniprogram
  • 管理后台重写：false
  • 应用密钥：可使用默认示例值（不建议用于生产）
  • 调试开关：true
  • 安全
    • 可信代理：[]
    • 可信 Host：[]
    • HSTS：关闭
    • 会话 SameSite：Lax
  • 文件上传
    • 单文件上限：2048 KB
    • 允许扩展：jpg,jpeg,gif,png,webp,ico
    • 图片质量：100

• 生产环境

  • 数据库
    • 主机：使用内网或云数据库地址
    • 库名：独立命名空间（如 prod_douphp）
    • 用户名：专用数据库用户（最小权限）
    • 密码：强密码
    • 表前缀：可按站点隔离（如 site1_）
  • 字符集：utf-8 或 utf8mb4（与数据库一致）
  • 系统标识：按业务线区分
  • 目录：保持默认或自定义并确保路径一致
  • 管理后台重写：根据 Web 服务器能力决定是否启用
  • 应用密钥：替换为唯一且足够长度的随机字符串
  • 调试开关：false
  • 安全
    • 可信代理：填写反向代理出口 IP/CIDR
    • 可信 Host：填写实际域名与通配子域
    • HSTS：开启（HTTPS 环境），合理设置 max_age 与 subdomains
    • 会话 SameSite：根据跨站需求选择 Lax/Strict/None
  • 文件上传
    • 单文件上限：按业务调整（注意与 php.ini 一致）
    • 允许扩展：严格限制，谨慎开启 SVG
    • 图片质量：按展示需求调整