简介

本文件聚焦于系统级配置与运行期环境，围绕以下目标展开：

• 解释 config/system.php 的系统常量与路由/小程序相关固定清单。
• 说明日志、缓存驱动、语言包等系统级配置在框架中的加载与作用域。
• 阐述 PHP 运行环境相关设置（如调试开关、协议判定）及其对行为的影响。
• 给出性能优化建议与安全加固要点。
• 提供错误处理与异常捕获的配置方法。
• 说明第三方服务连接参数（云服务 API、文件系统存储）的配置方式。

项目结构

系统配置由多个配置文件共同构成，职责清晰、分层明确：

• 应用基础常量与数据库连接：config/config.php
• 系统固定模块与路由保留段：config/system.php
• 安全栈（可信代理、Host 白名单、响应头、限流、会话 Cookie）：config/security.php
• 云服务能力基地址：config/cloud.php
• 磁盘与上传默认策略：config/file.php
• 引导与入口：core/bootstrap.php、index.php、front/init/Init.php

graph TB
A["入口 index.php"] --> B["引导 core/bootstrap.php"]
B --> C["应用配置 config/config.php"]
B --> D["系统常量 config/system.php"]
B --> E["安全栈 config/security.php"]
B --> F["云服务 config/cloud.php"]
B --> G["文件系统 config/file.php"]
A --> H["前端初始化 front/init/Init.php"]
H --> I["站点配置与运行时参数装配"]

核心组件

• 应用基础配置（config/config.php）
  • 定义数据库连接变量、表前缀、字符集、应用签名、端目录常量、应用密钥与调试开关。
  • 这些常量在引导阶段被 bootstrap 读取并用于后续核心对象实例化。
• 系统固定清单（config/system.php）
  • 定义前台固定内建模块、小程序内置模块、保留 URL 首段、小程序额外页面、不参与小程序生成的 single 模块、后台隐藏 single 模块等。
  • 该清单由框架层读取后注入 Config 的 system.* 命名空间，与“用户可调模块账本”分离。
• 安全栈（config/security.php）
  • 可信反向代理、可信 Host、安全响应头、限流存储路径与会话 Cookie 硬化策略。
• 云服务（config/cloud.php）
  • 主站与豆壳云服务 API 的基础地址与下载白名单。
• 文件系统（config/file.php）
  • 默认磁盘、上传默认策略（大小、扩展名、图片质量、缩略图目录）、各磁盘覆盖项。

架构总览

引导流程将配置逐步合并到全局配置容器，并在请求生命周期早期完成关键能力初始化：

• 入口 index.php 设置路由委托、解析语言前缀、调用 Init::boot。
• 引导 core/bootstrap.php 定义根路径、协议、加载应用配置、注册自动加载、DI 容器、门面别名、Request 单例等。
• 前端 Init 装配站点配置、语言、日志运行时、调试 ini 并定义站点常量。

sequenceDiagram
participant U as "浏览器"
participant I as "入口 index.php"
participant B as "引导 core/bootstrap.php"
participant F as "前端 Init"
participant R as "路由/调度"
U->>I : HTTP 请求
I->>B : require bootstrap
B-->>I : 定义常量/加载配置/注册服务
I->>F : Init : : boot()
F-->>I : 站点配置/日志/调试/常量就绪
I->>R : Route : : dispatch()
R-->>U : Response

详细组件分析

系统固定清单（config/system.php）

• 作用：声明框架层固定的模块短名与路由保留段，确保前台路由与小程序生成的一致性。
• 关键点：
  • 前台固定内建模块：不依赖模块启用判定，仅用于路由判定。
  • 小程序内置模块：始终注册进 app.json，需具备对应 API 控制器。
  • 保留 URL 首段：不可被模块短名占用。
  • 小程序专属页：无业务模块，直接登记进 app.json。
  • 不参与小程序 app.json 的 single 模块：系统型/容器型，无小程序页面。
  • 后台隐藏 single 模块：不在后台菜单/工作台/首页统计中显示。

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

• 数据库连接：host、name、user、pass、prefix。
• 字符集与应用标识：DOU_CHARSET、SYSTEM_SIGN。
• 端目录常量：ADMIN_DIR、API_DIR、MINIPROGRAM_DIR。
• 应用密钥与调试开关：DOU_APP_KEY、DOU_DEBUG。
• 注意：bootstrap 会在早期将这些变量收敛为 DOU_DB_CONFIG 供核心对象使用。

安全栈（config/security.php）

• 可信代理 trusted_proxies：空表示不信任任何代理；部署在负载均衡/Nginx 反代时，需填入代理出口 IP/CIDR，否则 Request::ip() 仅采信 REMOTE_ADDR。
• 可信主机 trusted_hosts：精确域名或子域通配；为空不校验；非空未命中回落到首项，防止 Host 头污染对外 URL。
• 安全响应头 headers：X-Frame-Options、X-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/cloud.php）

• cloud.api_base：云服务 API 基础地址（无末尾斜杠），本地开发可按需修改。
• cloud.download_base：下载白名单基础地址，用于校验 install-resolve 返回的 download_url。
• 若未配置或未生效，CloudApi 不会向云服务发起请求。

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

• filesystems.default：默认磁盘名。
• filesystems.upload_defaults：全局上传默认策略（upload_max_kb、allow_extensions、image_quality、thumb_directory）。
• filesystems.disks：按磁盘名覆盖默认策略或显式声明 root/url/driver。
• 约定推导：{module}_icon → images/{module}/icon/；标准名 → images/{name}/。
• 业务侧通过 Storage 门面访问磁盘；上传走 attachment()->store(...) / Validator 做门禁。

日志与调试

• 调试开关：DOU_DEBUG（config/config.php）控制是否输出调试信息。
• 未捕获异常渲染：入口根据 site.debug 与请求类型（JSON/HTML）选择调试页或统一错误响应。
• 日志写入：未捕获异常会记录至 error_log；具体日志级别与轮转策略由运行环境与中间件决定。

flowchart TD
S["请求进入"] --> D{"site.debug 开启?"}
D --> |是| J{"是否 JSON 请求?"}
J --> |是| E1["发送 API 500 调试响应"]
J --> |否| E2["渲染 HTML 调试页"]
D --> |否| N{"是否已启动(booted)?"}
N --> |是| M["message 提示页"]
N --> |否| X["JSON 500 或通用错误"]

语言包与国际化

• 语言契约在 Init 早期实例化并注册 Provider，随后 SiteBootstrap 从 Locale 单例读取当前语言并装配站点配置。
• 语言资源位于 languages 目录，按语言代码组织。

缓存驱动选择

• 安全限流 store 指向 storage/cache/throttle/ 下的文件后端。
• 其他缓存（如模板编译、配置缓存）由框架内部机制管理；如需扩展自定义缓存驱动，可通过扩展点注册。

邮件服务与第三方服务

• 邮件：框架集成 PHPMailer SMTP 传输类，实际连接参数通常由站点参数或模块配置注入；此处不直接暴露 SMTP 服务器配置项。
• 云服务：通过 config/cloud.php 配置 api_base 与 download_base，作为与豆壳云服务交互的唯一配置点。

依赖关系分析

• 引导阶段依赖顺序：入口 → bootstrap → 应用配置 → 自动加载/容器 → 门面 → Request 单例。
• 前端 Init 依赖：语言契约、Provider 注册、站点配置装配、日志运行时、调试 ini、站点常量。
• 文件系统依赖：config/file.php → FilesystemManager → Disk → LocalAdapter（默认）。

graph LR
I["index.php"] --> B["core/bootstrap.php"]
B --> C["config/config.php"]
B --> S["config/system.php"]
B --> K["config/security.php"]
B --> L["config/cloud.php"]
B --> F["config/file.php"]
I --> H["front/init/Init.php"]
H --> A["附件服务 AttachmentService"]
A --> FM["FilesystemManager"]

性能考虑

• 调试模式：生产环境关闭 DOU_DEBUG，避免调试页与额外日志开销。
• 安全响应头：启用 content_type_options、referrer_policy、permissions_policy，必要时启用 HSTS（HTTPS 且 enabled）。
• 限流：合理配置 throttle.store 与默认限流策略，保护敏感接口。
• 文件系统：限制 upload_max_kb、收紧 allow_extensions、调整 image_quality 以平衡体积与质量。
• 协议判定：仅在可信代理下信任转发头，避免误判 HTTPS。

故障排查指南

• 未安装跳转：若 storage/install.lock 不存在且非安装路径，将重定向至安装程序。
• 未捕获异常：
  • 始终记录到 error_log。
  • site.debug 开启时，按请求类型输出调试页或 API 500。
  • 关闭时，返回通用错误或 message 提示页。
• 安全相关：
  • 检查 trusted_proxies/trusted_hosts 是否正确，避免 IP/Host 伪造。
  • 检查会话 Cookie 的 httponly/samesite/secure/use_strict_mode。

结论

• config/system.php 负责框架层固定模块与路由保留段的声明，保障前后端一致性与安全性。
• 系统配置由多文件协同组成：应用基础、安全栈、云服务、文件系统与引导流程。
• 日志与异常处理遵循“先记录、再按调试模式输出”的原则，便于开发与运维。
• 性能与安全可通过调试开关、安全头、限流、上传策略与协议信任策略进行精细化调优。
• 第三方服务（云服务 API、文件系统）通过独立配置文件集中管理，便于环境隔离与迁移。

附录

• 常用路径与常量：
  • ROOT_PATH、CONFIG_PATH、STORAGE_PATH：由 bootstrap 定义。
  • HTTP/IS_HTTPS：由 bootstrap 基于服务器变量判定。
  • ROOT_URL/HOME_URL/PLUGIN_URL：由前端 Init 装配站点配置后定义。