简介

本章节面向 DouPHP 的环境变量与运行期配置体系，说明：

• 环境变量的概念与作用：将“随环境变化”的配置从代码中剥离，实现开发、测试、生产环境的差异化。
• 当前项目的加载机制：通过引导脚本在应用启动早期加载配置文件，并定义关键常量（如数据库连接、调试开关、应用密钥等）。
• 安全与敏感信息：结合现有安全配置与加密工具，给出敏感信息的存储与管理建议。
• 部署最佳实践：容器化与云平台的配置注入方式。
• 工具链支持：IDE、CI/CD 如何配合工作流使用这些配置。
• 常见问题排查：围绕配置缺失、类型错误、代理与 Host 校验等问题提供定位方法。

项目结构

DouPHP 的运行时配置集中在根级 config 目录，由核心引导流程统一加载；安全相关策略集中于 security 配置；入口脚本负责路由与异常处理，并在引导阶段完成配置初始化。

graph TB
A["入口 index.php"] --> B["核心引导 core/bootstrap.php"]
B --> C["站点配置 config/config.php"]
B --> D["安全配置 config/security.php"]
A --> E["前端 Init 与路由调度"]
E --> F["业务模块与服务"]

核心组件

• 引导加载器（core/bootstrap.php）
  • 定义应用根路径、配置目录与存储目录。
  • 判断 HTTPS 协议，决定是否跳转安装程序。
  • 加载站点配置（config/config.php），聚合数据库连接参数为 DOU_DB_CONFIG。
  • 注册自动加载、门面别名、DI 容器、Request 单例等基础能力。
• 站点配置（config/config.php）
  • 定义数据库主机、库名、用户名、密码、表前缀、字符集、系统标识、管理端目录、API 目录、小程序目录、重写开关、应用密钥、调试开关等。
• 安全配置（config/security.php）
  • 可信反向代理列表、可信 Host 白名单、安全响应头、限流存储位置、会话 Cookie 硬化策略。
• 入口与异常处理（index.php）
  • 设置路由委托、解析语言前缀、执行 Init::boot、分发路由、统一捕获异常并按 site.debug 输出 HTML 或 JSON。

架构总览

下图展示请求进入后，配置与安全策略的加载顺序及影响范围。

sequenceDiagram
participant U as "客户端"
participant I as "入口 index.php"
participant B as "引导 core/bootstrap.php"
participant C as "站点配置 config/config.php"
participant S as "安全配置 config/security.php"
participant R as "路由与业务"
U->>I : HTTP 请求
I->>B : 引入引导脚本
B->>C : 加载站点配置DB、密钥、调试等
B->>S : 加载安全配置代理、Host、Cookie 等
B-->>I : 完成基础能力注册容器、Request、路由
I->>R : 执行 Init : : boot 与路由分发
R-->>U : 返回响应

详细组件分析

引导与配置加载（core/bootstrap.php）

• 作用
  • 定义 ROOT_PATH、CONFIG_PATH、STORAGE_PATH。
  • 根据服务器变量判定 HTTPS，并控制未安装时的安装页跳转。
  • 加载 config/config.php，提取 $dbhost/$dbname/$dbuser/$dbpass/$prefix 并序列化为 DOU_DB_CONFIG，供后续数据库连接使用。
  • 注册自动加载、门面、容器、Request 单例等。
• 关键点
  • 配置加载时机极早，确保后续所有服务均可读取到一致的配置。
  • 数据库配置收敛为单一常量，避免散落的配置源导致不一致。
• 优化建议
  • 若需按环境切换配置，可在 bootstrap 阶段根据环境变量决定 include 不同的配置文件，或在 config/config.php 中依据环境变量覆盖默认值。

站点配置（config/config.php）

• 内容
  • 数据库连接四要素（主机、库名、用户、密码）、表前缀、字符集、系统标识、管理端/API/小程序目录、重写开关、应用密钥、调试开关。
• 使用方式
  • 被引导脚本加载后，其定义的变量会被 bootstrap 收集为 DOU_DB_CONFIG；DOU_APP_KEY、DOU_DEBUG 等常量可直接用于全局逻辑。
• 扩展建议
  • 可将不同环境的差异项（如 DB 连接、调试开关、第三方密钥）抽取为环境变量，在 bootstrap 或 config/config.php 中进行合并与覆盖。

安全配置（config/security.php）

• 内容
  • trusted_proxies：可信反向代理 IP/CIDR，空表示不信任任何代理。
  • trusted_hosts：可信 Host 白名单，非空时未命中域名回落到首项，防止 Host 头污染对外 URL。
  • headers：安全响应头基线（X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy、HSTS）。
  • throttle：限流后端存储目录与默认策略。
  • session：会话 Cookie 硬化（httponly、secure、samesite、use_strict_mode）。
• 作用
  • 在 Request 获取 IP/Host 之前生效，确保代理与 Host 校验正确。
• 部署建议
  • 在负载均衡/Nginx 反代场景下，务必配置 trusted_proxies；在多域或多子域场景下，配置 trusted_hosts 以杜绝 Host 注入。

入口与异常处理（index.php）

• 作用
  • 设置路由委托、解析语言前缀、执行 Init::boot、分发路由。
  • 统一捕获异常，按 site.debug 输出 HTML 调试页或 JSON 错误。
• 与配置的关系
  • 异常渲染受 site.debug 影响；site.debug 通常与 DOU_DEBUG 联动，便于在生产关闭调试输出。

敏感信息加密与安全管理

• 现状
  • 项目中存在 AI 凭据加密工具（devtools/ai-credential-encrypt.php），可用于对敏感信息进行加解密。
• 建议
  • 将数据库密码、第三方 API 密钥、应用密钥等敏感信息通过环境变量注入，不在代码中硬编码。
  • 在 CI/CD 中从密钥管理服务（如云平台 KMS、Secrets Manager）拉取并注入到运行环境。
  • 对静态配置中的敏感字段进行加密存储，并在应用启动时按需解密。

依赖关系分析

• 入口 index.php 依赖引导脚本 core/bootstrap.php。
• 引导脚本依赖站点配置 config/config.php 与安全配置 config/security.php。
• 安全配置影响 Request 的 IP/Host 判定，进而影响后续业务对外 URL 生成与日志审计。
• 数据库连接依赖 bootstrap 聚合的 DOU_DB_CONFIG。

graph LR
Index["index.php"] --> Bootstrap["core/bootstrap.php"]
Bootstrap --> SiteCfg["config/config.php"]
Bootstrap --> SecCfg["config/security.php"]
SecCfg --> Req["Request(IP/Host)"]
SiteCfg --> DB["DOU_DB_CONFIG"]

性能考虑

• 配置加载时机早且集中，减少重复 IO 与解析成本。
• 建议在容器化环境中将配置作为只读挂载或环境变量注入，避免运行时频繁读写磁盘。
• 对于高频访问的外部服务密钥，可考虑在进程内缓存（注意生命周期与安全性）。

故障排查指南

• 症状：数据库连接失败
  • 检查 config/config.php 中的数据库四要素是否正确；确认 bootstrap 是否成功将其聚合成 DOU_DB_CONFIG。
  • 若使用代理，确认 trusted_proxies 已配置，否则 Request::ip() 可能不正确。
• 症状：外部链接 Host 错误或被篡改
  • 检查 trusted_hosts 是否配置；未命中时将回落到首项，避免 Host 注入。
• 症状：HTTPS 识别异常
  • 检查服务器端口与 REQUEST_SCHEME；必要时在负载均衡层正确设置转发头，并将出口 IP 加入 trusted_proxies。
• 症状：调试信息泄露
  • 生产环境关闭 DOU_DEBUG；入口会根据 site.debug 输出 HTML 或 JSON，避免敏感堆栈外泄。
• 症状：会话安全问题
  • 检查 session 的 httponly、secure、samesite、use_strict_mode 是否符合预期。

结论

DouPHP 通过引导脚本在应用启动早期集中加载站点与安全配置，形成统一的配置视图。建议将环境差异项（数据库、密钥、调试开关、代理与 Host 白名单等）通过环境变量注入，并结合 CI/CD 与密钥管理服务实现安全的自动化部署。在生产环境严格关闭调试输出，合理配置安全响应头与会话策略，保障系统的稳定性与安全性。

附录

环境变量与 .env 的使用建议

• 由于当前仓库未包含 .env 解析器，推荐以下两种方案：
  • 在 bootstrap 阶段根据环境变量动态 include 不同配置文件（如 config/config.dev.php、config/config.prod.php）。
  • 在 config/config.php 中读取环境变量并覆盖默认值，保持单一配置入口。
• 常见变量命名约定
  • 数据库：DB_HOST、DB_NAME、DB_USER、DB_PASS、DB_PREFIX
  • 应用：APP_KEY、DEBUG
  • 安全：TRUSTED_PROXIES、TRUSTED_HOSTS
  • 第三方：SMTP*、PAY、AI_ 等
• 类型转换与默认值
  • 在读取环境变量后进行类型转换（布尔、整数、数组），并提供合理的默认值，避免空值导致的运行时错误。
• 继承机制
  • 可通过“基础配置 + 环境覆盖”的方式实现继承：先加载基础配置，再按环境覆盖关键字段。

容器化与云平台部署

• Docker
  • 通过 docker run -e 或 docker-compose environment 注入环境变量；将敏感信息放入 Secrets。
  • 将 storage 目录挂载为持久卷，避免重启丢失状态。
• Kubernetes
  • 使用 ConfigMap 存放非敏感配置，Secret 存放敏感信息；通过 envFrom 或 volume 挂载。
• 云平台
  • 使用平台提供的密钥管理服务（如 AWS Secrets Manager、阿里云 KMS）在启动时注入。

工具链集成

• IDE
  • 在 IDE 的运行配置中添加环境变量，便于本地调试。
• CI/CD
  • 在流水线中注入环境变量与密钥；构建产物不包含敏感信息。
  • 发布前校验必要的环境变量是否存在。