简介

本指南面向部署与运维人员，系统化说明 DouPHP 的配置文件体系与最佳实践。重点覆盖：

• config/config.php：数据库连接、应用密钥、路径常量、调试开关等关键配置
• config/module.php：模块管理（栏目型/单页型模块清单）
• config/route.php：URL 路由风格规则（支持多风格与短地址）
• config/system.php：系统级固定模块与保留段
• 安全与存储相关：config/security.php、config/file.php、config/cloud.php、config/ai.php
• 不同环境的配置模板与安全建议
• 配置变更的热重载机制与验证方法

项目结构

DouPHP 在启动早期加载核心引导与配置，随后进入路由与业务处理。关键流程如下：

• 入口 index.php 引入 core/bootstrap.php
• bootstrap.php 定义根路径、配置与存储目录，并加载 config/config.php
• bootstrap.php 统一读取 module.php 并序列化缓存为常量，供后续复用
• bootstrap.php 收敛 DB 配置为 DOU_DB_CONFIG，供后续初始化数据库连接使用
• 前端入口对请求进行语言前缀解析后，调用 Init::boot 完成框架启动，再执行路由分发

graph TB
A["index.php"] --> B["core/bootstrap.php"]
B --> C["config/config.php<br/>定义DB/路径/密钥/调试"]
B --> D["config/module.php<br/>模块清单"]
B --> E["常量与自动加载/容器/路由绑定"]
A --> F["前端Init::boot + Route::dispatch()"]

核心组件

• 应用基础配置（config/config.php）
  • 数据库连接：主机、库名、用户名、密码、表前缀
  • 字符集与系统标识：DOU_CHARSET、SYSTEM_SIGN
  • 路径常量：ADMIN_DIR、API_DIR、MINIPROGRAM_DIR
  • 应用密钥：DOU_APP_KEY（用于签名、加密等）
  • 调试开关：DOU_DEBUG
• 模块管理（config/module.php）
  • column_module：栏目型模块集合
  • single_module：单页型模块集合
  • 其他关联列表：AI 链接、用户中心、工作台、订单项、菜单隐藏等
• 路由规则（config/route.php）
  • 多风格 URL 规则：page/column/simple
  • 支持命名参数、正则、分页段、短地址家族
• 系统常量（config/system.php）
  • 前台固定模块、小程序内置模块、保留首段、额外页面、隐藏模块等
• 安全与存储（config/security.php、config/file.php、config/cloud.php、config/ai.php）
  • 可信代理/Host、响应头、限流、会话 Cookie 硬化
  • 磁盘驱动、上传限制、允许扩展名、图片质量、缩略图目录
  • 云服务 API 基址与下载白名单
  • AI 提示词、图像尺寸策略、素材上限等

架构总览

配置加载与运行时装配的关键链路：

• 启动阶段：bootstrap.php 加载 config/config.php 与 config/module.php，并生成 DOU_DB_CONFIG、DOU_MODULE_SETTING 等常量
• 站点配置装配：SiteBootstrap 将 site 与 param 写入 Config，供业务层读取
• 路由与中间件：根据 route.php 的规则匹配 URL，结合 system.php 的保留段与内置模块进行调度
• 安全与存储：security.php 影响 Request 可信代理与 Host 校验；file.php 控制上传与磁盘行为；cloud.php 控制云服务通信；ai.php 控制 AI 能力

sequenceDiagram
participant U as "客户端"
participant I as "index.php"
participant B as "core/bootstrap.php"
participant S as "config/config.php"
participant M as "config/module.php"
participant R as "Route/Init"
U->>I : HTTP 请求
I->>B : require bootstrap
B->>S : 加载数据库/路径/密钥/调试
B->>M : 加载模块清单并序列化
B-->>I : 常量/自动加载/容器就绪
I->>R : 设置路由委托并 dispatch
R-->>U : 响应

详细组件分析

应用基础配置（config/config.php）

• 数据库连接
  • 主机、库名、用户名、密码、表前缀：由 bootstrap.php 收敛为 DOU_DB_CONFIG，供数据库连接初始化使用
• 字符集与系统标识
  • DOU_CHARSET：统一字符集
  • SYSTEM_SIGN：区分系统类型（如公司站、API 等）
• 路径常量
  • ADMIN_DIR、API_DIR、MINIPROGRAM_DIR：决定后台、API、小程序目录
  • 可通过 storage/state/admin_dir.php 动态覆盖 admin 目录
• 应用密钥
  • DOU_APP_KEY：用于签名、加密等安全场景，生产环境必须更换为高强度随机值
• 调试开关
  • DOU_DEBUG：开启时输出更详细的错误信息，生产环境应关闭

模块管理（config/module.php）

• 栏目型模块（column_module）：产品、文章、文档、专业、方案、支持、课程、下载、图库、案例、视频等
• 单页型模块（single_module）：订单、用户、服务、售后、健康、碎片、语言、VIP、积分、资金、提现、分享、属性、评论、证书、插件、收藏、优惠券、招聘、问答、工作区、区域、序列号、表单、投票、咨询、链接、门店、一图等
• 关联映射
  • link_ai：可被 AI 功能关联的内容模块
  • link_user_center / link_work_center / link_order_item：用户中心、工作台、订单项关联
  • no_show_menu / no_show_nav：后台菜单与前台导航隐藏项

路由配置（config/route.php）

• 路由风格
  • page：单页面（固定加载 page.php），支持后缀、前缀、ID 风格
  • column：栏目模块（product/article/doc 等），支持分类别名嵌套、ID 后缀、日期归档等
  • simple：简单模块（user/service/book 等），支持分组、操作页、ID 访问
• 规则要素
  • pattern：URL 模式，支持 {param}、{param:regex}、[/optional]
  • params：参数默认正则
  • target：目标文件名模板（默认 {module}.php）
  • module_fixed：固定模块名（当 URL 不含模块段时使用）
  • short_rules：短地址模块专用规则族（仅 column 风格），顶级分类别名取代模块名段
• 短地址模块
  • 分类段取全链或顶级祖先别名，详情段按风格选择 ID/slug/日期归档

系统设置（config/system.php）

• 前台固定模块：index、page、search、captcha、sitemap、llms
• 小程序内置模块：index、page、search
• 保留首段：llms、sitemap、captcha、search、category、index、plugin
• 小程序额外页面：pages/debug/debug
• 不参与小程序 app.json 生成的 single 模块：plugin、box、fragment、language、data、weixin、attribute、email
• 不进前台主导航目标的 single 模块：plugin、box、fragment、language
• 后台菜单/工作台/首页统计隐藏的系统级 single 模块：box、fragment、language

安全配置（config/security.php）

• 可信反向代理（trusted_proxies）
  • 空表示不信任任何代理；部署在负载均衡/Nginx 反代后需填入代理出口 IP/CIDR
• 可信 Host（trusted_hosts）
  • 精确域名或子域通配；非空时未命中 Host 回落到名单首项，防止 Host 头注入污染对外 URL
• 安全响应头（headers）
  • frame_options、content_type_options、referrer_policy、permissions_policy、hsts（enabled/max_age/subdomains）
• 限流（throttle）
  • store：文件后端目录；default：全局默认限流（null 表示默认不限流，仅敏感端点配额）
• 会话 Cookie 硬化（session）
  • httponly、secure（null 跟随 IS_HTTPS）、samesite、use_strict_mode

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

• 默认磁盘与上传默认值
  • default：local
  • upload_defaults：upload_max_kb、allow_extensions、image_quality、thumb_directory
• 磁盘声明
  • local：images/upload/
  • avatar_admin：继承约定路径 images/avatar_admin/，仅覆盖上传上限
• 注意事项
  • 默认不包含 svg（存在存储型 XSS 风险），确需在具体 disk 显式开启
  • 上传请走 attachment()->store(...) 或 Validator，避免直接使用 Disk::putFile 做门禁

云服务与 AI（config/cloud.php、config/ai.php）

• 云服务 API（cloud.php）
  • api_base：云服务 API 基础地址（无末尾斜杠）
  • download_base：下载白名单（仅校验 install-resolve 返回的 download_url）
• AI 创作（ai.php）
  • prompts：系统提示词、指令、标签、横幅风格、素材用法
  • image_input：支持图生图的模型代码通配
  • image_size：按模型族/协议默认的尺寸归一化策略（separator/range/presets/fallback）
  • banner：弹窗素材张数上限与单张字节上限

依赖关系分析

• bootstrap.php 依赖 config/config.php 与 config/module.php 提供运行期常量与模块清单
• SiteBootstrap 负责将站点配置与参数写入 Config，供业务层读取
• 路由层依赖 route.php 的规则与 system.php 的保留段/内置模块进行调度
• 安全与存储依赖 security.php 与 file.php 控制请求与文件行为
• 云服务与 AI 依赖 cloud.php 与 ai.php 控制外部能力

graph LR
B["bootstrap.php"] --> C["config/config.php"]
B --> M["config/module.php"]
B --> R["config/route.php"]
B --> S["config/system.php"]
B --> SEC["config/security.php"]
B --> F["config/file.php"]
B --> CL["config/cloud.php"]
B --> AI["config/ai.php"]
SB["SiteBootstrap.php"] --> CFG["Config(site/param)"]

性能考虑

• 数据库连接
  • 合理设置 DOU_DB_CONFIG（host/user/pass/name/prefix），确保网络与权限正确
  • 生产环境建议使用独立数据库账号与最小权限原则
• 模块清单
  • module.php 会被序列化并作为常量缓存，减少重复 IO，保持精简有效
• 路由规则
  • 合理使用短地址与正则，避免过于复杂的匹配导致性能下降
• 安全与限流
  • 启用 HSTS、严格 SameSite、可信 Host 白名单，降低攻击面
  • 针对登录、支付等敏感接口启用限流，防止滥用
• 文件上传
  • 限制 allow_extensions 与 upload_max_kb，避免大文件与危险类型上传
  • 图片压缩 quality 与缩略图目录策略平衡清晰度与体积

故障排查指南

• 无法连接数据库
  • 检查 config/config.php 中的 dbhost/dbname/dbuser/dbpass/prefix
  • 确认 bootstrap.php 已正确收敛为 DOU_DB_CONFIG
• 后台目录异常
  • 检查 storage/state/admin_dir.php 是否覆盖 ADMIN_DIR
• 路由不生效
  • 核对 config/route.php 的 pattern/params/target/module_fixed
  • 确认 system.php 的 reserved_first_segment 未被占用
• 安全报错（Host/IP 校验）
  • 检查 security.php 的 trusted_proxies/trusted_hosts
  • 若使用 Nginx/负载均衡，确保真实 IP 透传且代理可信
• 上传失败或受限
  • 检查 file.php 的 upload_defaults/disks 配置
  • 确认存储目录权限与磁盘根路径正确
• 云服务/AI 不可用
  • 检查 cloud.php 的 api_base/download_base
  • 核对 ai.php 的 image_input/image_size/banner 配置

结论

DouPHP 的配置体系围绕“启动即加载、按需装配”的原则设计：

• config/config.php 提供运行必需的基础常量与数据库连接
• config/module.php 与 config/route.php 共同决定功能范围与 URL 形态
• config/system.php 保障系统级模块与保留段的稳定性
• config/security.php、config/file.php、config/cloud.php、config/ai.php 分别覆盖安全、存储、云服务与 AI 能力 通过遵循本文的最佳实践与环境模板，可在不同部署场景中实现安全、稳定、高效的配置管理。

附录

不同部署环境的配置模板与建议

• 开发环境
  • 数据库：本地 MySQL，宽松权限
  • 调试：开启 DOU_DEBUG，便于定位问题
  • 安全：trusted_hosts 可为空或包含 localhost；HSTS 关闭
  • 上传：适当放宽 upload_max_kb，允许常见格式
• 测试环境
  • 数据库：独立实例，数据脱敏
  • 调试：关闭 DOU_DEBUG，启用日志记录
  • 安全：启用 trusted_hosts 白名单；开启 HSTS（max_age 较短）
  • 上传：限制 allow_extensions，启用图片压缩
• 生产环境
  • 数据库：最小权限账号，强密码，只读分离（如有）
  • 调试：关闭 DOU_DEBUG，集中日志
  • 安全：严格 trusted_hosts；启用 HSTS（长 max_age，subdomains）；SameSite=Strict/Lax；httponly=true；use_strict_mode=true
  • 上传：严格 allow_extensions；限制大小；禁用 SVG 或仅在受控 disk 开启
  • 云服务：api_base 指向正式地址；download_base 白名单严格校验
  • AI：image_size 策略按供应商调整；banner 素材上限合理设置

配置变更的热重载机制

• 模块清单热重载
  • bootstrap.php 会读取 config/module.php 并序列化为 DOU_MODULE_SETTING，供 autoload/Common/Router 复用
  • 修改 module.php 后，新请求将重新加载并更新模块映射
• 站点配置与参数
  • SiteBootstrap 将 site 与 param 写入 Config，通常在 Init::boot 阶段完成
  • 修改站点参数后，下一次请求将重新装配
• 路由与系统常量
  • route.php 与 system.php 在每次请求中由路由层读取，修改后立即生效
• 安全与存储
  • security.php 与 file.php 在请求早期加载，修改后即时生效
• 云服务与 AI
  • cloud.php 与 ai.php 在请求早期加载，修改后即时生效

配置验证方法

• 启动阶段校验
  • bootstrap.php 在加载 config/config.php 之前检查安装锁，未安装则跳转安装程序
  • 收敛 DOU_DB_CONFIG，确保数据库连接可用
• 运行时校验
  • 路由层依据 route.php 的规则匹配 URL，结合 system.php 的保留段与内置模块进行调度
  • 安全层依据 security.php 校验可信代理与 Host，防止伪造
  • 文件层依据 file.php 校验上传类型与大小，防止恶意上传
• 建议的自检步骤
  • 检查 config/config.php 的数据库与密钥是否正确
  • 检查 config/module.php 的模块清单是否符合预期
  • 检查 config/route.php 的 URL 规则是否覆盖所有场景
  • 检查 config/system.php 的保留段与内置模块是否冲突
  • 检查 config/security.php 的安全头与会话策略是否满足合规要求
  • 检查 config/file.php 的上传限制与磁盘路径是否正确
  • 检查 config/cloud.php 与 config/ai.php 的外部服务地址与策略