配置管理 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

配置管理

简介

本文档为 DouPHP 配置管理的权威参考，面向系统管理员与开发者。内容覆盖配置文件结构、环境变量（常量）、动态配置、路由与安全策略、存储与云服务对接、AI 创作参数等核心配置功能。文档同时说明配置的加载顺序、优先级、继承机制以及安全注意事项，并提供常见问题的定位思路与最佳实践。

项目结构

DouPHP 的配置集中在根目录的 config 文件夹中，由框架引导阶段统一加载并合并到运行时配置容器中。入口流程如下：

应用入口 index.php 引入 core/bootstrap.php。
bootstrap.php 定义路径常量、协议常量，加载数据库与基础常量配置，注册自动加载器、容器、路由与请求对象。
各业务端（前台、后台、API）在 Init::boot 阶段进一步加载安全、文件系统、AI 等专项配置，并初始化相关服务。

graph TB
A["index.php"] --> B["core/bootstrap.php"]
B --> C["config/config.php<br/>数据库/应用密钥/调试开关"]
B --> D["config/system.php<br/>系统恒定常量"]
B --> E["config/module.php<br/>模块清单与分组"]
B --> F["core/autoload.php<br/>自动加载"]
B --> G["DI 容器 / 路由 / Request"]
G --> H["前端 Init::boot<br/>加载 security/file/ai 等配置"]
H --> I["服务初始化<br/>Storage/Route/Language等"]

图表来源

index.php:14-41
core/bootstrap.php:24-165
front/init/Init.php:214-247

章节来源

index.php:14-41
core/bootstrap.php:24-165

核心组件

基础配置：数据库连接、字符集、应用密钥、调试开关、目录别名等。
系统配置：固定内建模块、小程序内置模块、保留 URL 段、隐藏模块等系统级常量。
模块配置：栏目型与单页型模块清单、导航与菜单可见性、小程序内置模块等。
路由配置：URL 风格规则（页面、栏目、简单模块），支持短地址与分页段。
安全配置：可信代理、可信 Host、响应头、限流、会话 Cookie 硬化。
存储配置：磁盘驱动、上传限制、允许扩展名、缩略图策略。
云服务配置：主站与豆壳云 API 基址、下载白名单。
AI 配置：提示词模板、图像输入模型通配、尺寸归一化策略、横幅素材上限。

章节来源

config/config.php:15-52
config/system.php:11-34
config/module.php:1-132
config/route.php:15-356
config/security.php:17-87
config/file.php:17-61
config/cloud.php:18-33
config/ai.php:15-176

架构总览

配置系统在启动早期完成"静态配置 + 运行期配置"的统一装配：

引导阶段（bootstrap）：加载 config/config.php 与 config/module.php，定义 DOU_DB_CONFIG、DOU_MODULE_MAP 等全局常量，供后续服务实例化使用。
初始化阶段（InitTrait）：按职责加载安全、文件系统、AI 等专项配置，注入到 Config 命名空间。
运行时：通过 Facade 与 Service 访问配置，如 Storage、Request、Route 等。

sequenceDiagram
participant U as "用户请求"
participant I as "index.php"
participant B as "core/bootstrap.php"
participant CFG as "Config(多源合并)"
participant INIT as "Init : : boot"
participant S as "服务/中间件"
U->>I : HTTP 请求
I->>B : require bootstrap
B->>CFG : 加载 config/config.php
B->>CFG : 加载 config/module.php
B->>S : 注册容器/路由/Request
I->>INIT : 调用 Init : : boot()
INIT->>CFG : 加载 security/file/ai 等配置
S-->>U : 返回响应

图表来源

index.php:14-41
core/bootstrap.php:59-165
front/init/Init.php:214-247

详细组件分析

基础配置（config/config.php）

数据库连接：主机、库名、用户名、密码、表前缀。
字符集与应用标识：UTF-8、系统签名。
目录别名：admin/api/miniprogram 目录名可配置。
重写与密钥：是否启用 admin 重写、应用密钥。
调试开关：控制异常渲染与调试输出。

建议：

生产环境关闭调试，避免敏感信息泄露。
应用密钥应独立于代码仓库管理。

章节来源

config/config.php:15-52

系统配置（config/system.php）

前台固定内建模块：index、page、search、captcha、sitemap、llms 等不依赖模块启用的路由判定。
小程序内置模块：始终注册进 app.json 的模块集合。
保留 URL 首段：不可被模块短名占用的系统级 URL 段。
小程序专属页：无对应业务模块的直接登记页面。
隐藏模块：不参与前台主导航、后台菜单的系统级 single 模块。

用途：

确保系统级功能的路由稳定性与小程序兼容性。
与 module.php 的用户可调模块账本分离，避免误操作影响核心功能。

章节来源

config/system.php:11-34

模块配置（config/module.php）

栏目型模块：产品、文章、案例、视频等列表类内容。
单页型模块：订单、用户、钱包、积分、表单、投票等。
关联集合：用户中心、工作台、下单商品、隐藏菜单/导航等。

用途：

决定前台路由、导航、后台菜单、小程序内置模块等。
与 system.php 的固定内建模块配合，保证路由稳定性。

章节来源

config/module.php:1-132
config/system.php:11-34

路由配置（config/route.php）

PAGE：单页面规则，支持后缀、前缀、ID 模式。
COLUMN：栏目模块规则，支持分类别名、slug、日期归档、短地址家族。
SIMPLE：简单模块规则，支持 class/action/id 等。

要点：

每条规则包含 pattern、params、target、module_fixed、short_rules。
短地址模块将顶级分类别名替换模块名段，提升 SEO 友好度。
可通过复制 route_custom.php 覆盖部分风格，无需全量复制。

章节来源

config/route.php:15-356

安全配置（config/security.php）

可信代理：仅当 REMOTE_ADDR 命中可信代理时采信 X-Forwarded-*。
可信 Host：防止 Host 头注入对外 URL。
响应头：X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy、HSTS。
限流：文件后端目录与默认配额。
会话 Cookie：httponly、secure、samesite、严格模式。

建议：

生产环境开启 HSTS（HTTPS 且 enabled）。
明确 trusted_hosts，避免混合部署下 URL 污染。
保持 samesite=Lax/Strict，use_strict_mode=true。

章节来源

config/security.php:17-87

存储配置（config/file.php）

默认驱动与上传默认值：大小限制、允许扩展名、图片质量、缩略图目录。
磁盘声明：local 与 avatar_admin 等自定义磁盘。
约定路径：images/{module}/icon/ 等自动推导，减少重复配置。

建议：

谨慎放开 svg 等脚本风险扩展名。
对头像等小图设置更严格的上传上限。

章节来源

config/file.php:17-61

云服务配置（config/cloud.php）

云服务 API 基址：用于在线安装、资源解析等。
下载白名单：校验 install-resolve 返回的 download_url。

建议：

生产环境指向官方域名，避免篡改。
未配置时不发起云服务请求，确保离线可用。

章节来源

config/cloud.php:18-33

AI 配置（config/ai.php）

提示词模板：labels、system、instruction、banner_styles、banner_material。
图像输入模型通配：qwen-image-* 等。
图像尺寸归一化：按模型族或供应商协议设定范围/预设/回退。
横幅素材：张数上限与单张字节上限。

建议：

根据实际模型能力调整 image_size 的 range/presets。
banner 素材上限与上传限制需与前端一致。

章节来源

config/ai.php:15-176

依赖关系分析

bootstrap 阶段依赖 config/config.php 与 config/module.php，生成 DOU_DB_CONFIG 与 DOU_MODULE_MAP。
InitTrait 在 boot 阶段加载 security/file/ai 等配置，注入到 Config。
中间件与服务通过 Facade/Service 读取配置，如 Request、Storage、Route 等。

graph LR
CFG["config/config.php"] --> BOOT["core/bootstrap.php"]
MOD["config/module.php"] --> BOOT
SYS["config/system.php"] --> BOOT
SEC["config/security.php"] --> INIT["Init::boot"]
FIL["config/file.php"] --> INIT
AI["config/ai.php"] --> INIT
INIT --> SVC["服务/中间件"]
BOOT --> SVC

图表来源

core/bootstrap.php:59-165
front/init/Init.php:214-247

章节来源

core/bootstrap.php:59-165

性能与热重载

配置加载时机：
- 基础配置在 bootstrap 阶段一次性加载，并通过常量缓存（如 DOU_DB_CONFIG、DOU_MODULE_MAP）避免重复 include。
- 专项配置在 Init::boot 阶段加载，集中注入 Config。
热重载：
- 当前实现未提供进程内热重载；修改配置后需重启 PHP-FPM/进程以生效。
- 对于频繁变更的运行时参数，建议使用数据库或缓存层进行动态下发，并在服务层按需刷新。
性能建议：
- 避免在高频路径中重复读取大配置；优先通过 Facade/Service 获取。
- 合理设置图片质量与缩略图策略，减少带宽与 IO。

故障排查指南

无法连接数据库：
- 检查 config/config.php 中的主机、库名、用户名、密码、表前缀是否正确。
- 确认 storage/state/admin_dir.php 未干扰 ADMIN_DIR。
- 验证 DOU_DB_CONFIG 常量是否正确序列化数据库连接信息。
路由不生效：
- 核对 config/route.php 的规则与模块名匹配，必要时复制 route_custom.php 覆盖。
- 检查 module.php 中模块是否在 column/single 列表中。
安全相关错误：
- 若 behind 反向代理，需在 security.trusted_proxies 添加代理出口 IP/CIDR。
- 若出现 Host 头问题，配置 security.trusted_hosts。
上传失败：
- 检查 file.upload_defaults.allow_extensions 与磁盘 root 权限。
- 注意 SVG 默认禁用，确需时显式开启。
AI 功能异常：
- 核对 ai.image_input 模型通配与 ai.image_size 策略是否匹配实际模型。
- 检查 banner 素材上限与单张字节限制。

章节来源

config/config.php:15-52
config/route.php:15-356
config/module.php:1-132
config/security.php:17-87
config/file.php:17-61
config/ai.php:15-176

结论

DouPHP 的配置体系采用"引导阶段加载基础配置 + 初始化阶段加载专项配置"的分层设计，结合常量缓存与模块化组织，兼顾灵活性与性能。通过安全、存储、路由、AI 等专项配置，可满足企业级站点在不同部署环境下的需求。建议在生产环境严格管控密钥与敏感配置，遵循最小权限原则，并结合监控与日志快速定位问题。

附录：配置项速查

数据库连接：host、name、user、pass、prefix（config/config.php）。
应用密钥与调试：DOU_APP_KEY、DOU_DEBUG（config/config.php）。
系统常量：front_fixed_module、miniprogram_builtin_module、reserved_first_segment（config/system.php）。
模块清单：column_module、singlemodule、link、noshow（config/module.php）。
路由风格：page/column/simple 及其规则 family（config/route.php）。
安全栈：trusted_proxies、trusted_hosts、headers、throttle、session（config/security.php）。
存储：default、upload_defaults、disks（config/file.php）。
云服务：api_base、download_base（config/cloud.php）。
AI：prompts、image_input、image_size、banner（config/ai.php）。

添加日期：2026-10-05