简介

本章节面向部署与运维人员，系统说明 DouPHP 的应用安全配置要点，包括：

• 应用密钥 DOU_APP_KEY 的生成方式、长度与复杂度要求、更换策略
• 系统标识 SYSTEM_SIGN 的作用与配置
• 调试模式 DOU_DEBUG 的环境差异与生产环境关闭建议
• 应用密钥的安全存储与加密方案
• 会话安全、CSRF 保护等关键安全选项
• HTTPS 与 HSTS 相关设置

项目结构

DouPHP 将“应用常量”和“安全栈配置”分置在不同配置文件：

• 应用常量与入口开关位于 config/config.php，包含 DOU_APP_KEY、SYSTEM_SIGN、DOU_DEBUG 等
• 安全栈配置位于 config/security.php，涵盖可信代理、可信 Host、响应安全头、限流与会话 Cookie 硬化
• 请求对象 Request 在早期阶段加载安全配置，确保 IP/Host 判定先于业务逻辑生效
• 中间件层提供 CSRF 校验与安全响应头下发

graph TB
A["config/config.php<br/>定义 DOU_APP_KEY / SYSTEM_SIGN / DOU_DEBUG"] --> B["core/web/http/Request.php<br/>读取安全配置并设置可信代理/Host"]
C["config/security.php<br/>安全栈配置代理/Host/头/限流/会话"] --> B
B --> D["前端/后台/API 中间件<br/>CSRF / 安全头 / 限流"]
D --> E["控制器/服务"]

图示来源

• config.php:33-52
• security.php:51-87
• Request.php:72-97

章节来源

• config.php:33-52
• security.php:51-87
• Request.php:72-97

核心组件

• 应用密钥 DOU_APP_KEY：用于签名、加密派生等安全用途。安装/升级流程会生成或保留该值。
• 系统标识 SYSTEM_SIGN：用于站点识别与上报，便于云服务等场景区分实例。
• 调试模式 DOU_DEBUG：控制错误输出与调试信息，生产环境必须关闭。
• 安全栈 security.*：可信代理、可信 Host、安全响应头、限流与会话 Cookie 硬化。
• CSRF 中间件：前台与后台分别实现，覆盖一次性令牌与静态令牌模型。
• 安全响应头中间件：统一下发 X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy，以及可选 HSTS。

章节来源

• config.php:33-52
• security.php:51-87
• CsrfMiddleware.php（前台）:24-53
• CsrfMiddleware.php（后台）:24-66
• AbstractSecurityHeadersMiddleware.php:23-49

架构总览

下图展示从请求进入、安全配置加载到 CSRF 校验与安全头下发的整体流程。

sequenceDiagram
participant Client as "客户端"
participant Request as "Request.php"
participant SecCfg as "security.php"
participant Csrf as "CSRF 中间件"
participant SecHdr as "安全头中间件"
participant App as "控制器/服务"
Client->>Request : 发起 HTTP 请求
Request->>SecCfg : 读取 trusted_proxies / trusted_hosts
Request-->>Client : 基于可信代理/Host 解析真实 IP/域名
Client->>Csrf : 提交表单/敏感操作
Csrf-->>Client : 校验令牌静态/一次性通过或拒绝
Client->>SecHdr : 获取响应
SecHdr-->>Client : 下发安全响应头含 HSTS 条件
SecHdr->>App : 继续处理业务

图示来源

• Request.php:72-97
• security.php:51-87
• CsrfMiddleware.php（前台）:24-53
• CsrfMiddleware.php（后台）:24-66
• AbstractSecurityHeadersMiddleware.php:23-49

详细组件分析

应用密钥 DOU_APP_KEY

• 生成与长度
  • 安装器会写入 define('DOU_APP_KEY', ...)，且断言其为 64 位十六进制字符串。
  • 升级器会保留已提供的 app_key，保证幂等稳定。
• 复杂度与强度
  • 64 位十六进制等价于 256 位随机性，满足现代密码学对对称密钥/签名的强度要求。
• 定期更换策略
  • 建议结合密钥轮换流程：生成新密钥 -> 更新配置 -> 重新签发/刷新依赖该密钥的令牌或缓存 -> 旧密钥宽限期后下线。
  • 若使用基于该密钥派生的会话或签名，需评估影响面并制定回滚预案。
• 安全存储
  • 仅保存在服务器可访问的配置文件中，禁止纳入版本库；配合文件系统权限与最小化访问原则。
  • 对于第三方集成密钥（如 AI 提供商），框架在落盘前进行加密存储，避免明文持久化。

flowchart TD
Start(["开始"]) --> Gen["安装器生成 64 位十六进制 DOU_APP_KEY"]
Gen --> Write["写入 config/config.php"]
Write --> Upgrade{"是否升级?"}
Upgrade --> |是| Preserve["升级器保留已有 app_key"]
Upgrade --> |否| End(["完成"])
Preserve --> End

图示来源

• config-app-key-smoke.php:65-106
• config.php:48-52

章节来源

• config-app-key-smoke.php:65-106
• config.php:48-52
• AiKey.php:53-65

系统标识 SYSTEM_SIGN

• 作用
  • 作为站点/实例的唯一标识，参与系统信息上报，便于云服务统计与诊断。
• 配置
  • 在 config/config.php 中定义，可按企业/租户维度区分。
• 使用位置
  • 云端更新状态服务会将 system_sign 打包进系统信息中上报。

章节来源

• config.php:33-34
• UpdateStateService.php:73-89

调试模式 DOU_DEBUG

• 含义
  • 控制运行时是否输出调试信息与详细错误堆栈。
• 环境建议
  • 开发/测试：可开启以便定位问题。
  • 生产：必须关闭，避免泄露内部路径、SQL、变量等敏感信息。
• 当前默认
  • 示例配置中为开启，部署至生产环境时应改为关闭。

章节来源

• config.php:51-52

安全栈配置 security.*

• 可信代理 trusted_proxies
  • 空表示不信任任何代理，仅使用 REMOTE_ADDR；当部署在 Nginx/负载均衡后，需将出口 IP 加入白名单，以正确采信 X-Forwarded-*。
• 可信 Host trusted_hosts
  • 非空时仅放行命中项，未命中回落至首项，防止 Host 头注入污染对外 URL。
• 安全响应头 headers
  • X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy 由中间件统一下发。
  • HSTS：仅在 HTTPS 且 enabled 时下发，可配置 max_age 与 subdomains。
• 限流 throttle
  • 支持文件后端存储与全局默认限流策略，用于抵御暴力破解与滥用。
• 会话 session
  • httponly：建议恒 true，防 XSS 窃取 sid。
  • secure：null 表示跟随 IS_HTTPS；true/false 可强制。
  • samesite：Lax/Strict/None，防御跨站 CSRF。
  • use_strict_mode：建议恒 true，拒绝未初始化外部 sid，防会话固定。

flowchart TD
S["请求进入"] --> P["Request 读取 trusted_proxies/trusted_hosts"]
P --> R["解析真实 IP/规范 Host"]
R --> M["中间件链：CSRF / 安全头 / 限流"]
M --> H["根据 security.headers 下发安全头"]
H --> O["返回响应"]

图示来源

• Request.php:72-97
• AbstractSecurityHeadersMiddleware.php:23-49
• security.php:51-87

章节来源

• security.php:51-87
• Request.php:72-97
• AbstractSecurityHeadersMiddleware.php:23-49

CSRF 保护

• 前台
  • 登录会员使用共享静态令牌 static_user；匿名表单使用一次性令牌抗重放。
  • 部分 GET 链接也携带 token 并校验（如取消预约、导出报表等）。
• 后台
  • 登录后统一下发静态令牌 static_admin；找回密码等匿名流程使用一次性令牌 password_reset。
  • 备份/导入/报表导出等带 token 的 GET 链接同样校验。
• 豁免机制
  • 完全不需要 CSRF 的路由通过路由级声明式豁免，不在中间件内硬编码名单。

sequenceDiagram
participant U as "用户"
participant F as "前台 CSRF 中间件"
participant A as "后台 CSRF 中间件"
U->>F : 提交表单携带 token
F-->>U : 校验通过/失败
U->>A : 管理端提交携带 token
A-->>U : 校验通过/失败

图示来源

• CsrfMiddleware.php（前台）:24-53
• CsrfMiddleware.php（后台）:24-66

章节来源

• CsrfMiddleware.php（前台）:24-53
• CsrfMiddleware.php（后台）:24-66

HTTPS 与 HSTS 配置

• HSTS
  • 由 security.headers.hsts 控制：enabled 为 true 且当前为 HTTPS 时才下发 Strict-Transport-Security。
  • 可配置 max_age 与 subdomains（是否包含子域）。
• 证书与传输
  • 建议在反向代理（Nginx/CDW）终止 TLS，并将 X-Forwarded-Proto 透传给应用；同时在 trusted_proxies 中登记代理出口 IP。
  • 邮件发送通道支持 STARTTLS 加密连接，保障凭证与内容传输安全。

flowchart TD
C["客户端 HTTPS"] --> T["反向代理终止 TLS"]
T --> A["应用接收 X-Forwarded-Proto=https"]
A --> H["安全头中间件检测 isSecure()"]
H --> |HSTS 启用| S["下发 HSTS 头"]
H --> |未启用| N["不下发 HSTS"]

图示来源

• security.php:62-72
• AbstractSecurityHeadersMiddleware.php:23-49

章节来源

• security.php:62-72
• AbstractSecurityHeadersMiddleware.php:23-49

密钥与凭据的加密存储

• 应用密钥 DOU_APP_KEY
  • 安装器生成 64 位十六进制；升级器保留已有值，保证幂等。
• 第三方凭据（AI Key 等）
  • 写入数据库前进行加密，读取时解密，避免明文落盘。
• 最佳实践
  • 将 DOU_APP_KEY 与第三方密钥分离管理；使用最小权限的文件系统访问控制；定期轮换并记录审计日志。

章节来源

• config-app-key-smoke.php:65-106
• AiKey.php:53-65

依赖关系分析

• config/config.php 提供 DOU_APP_KEY、SYSTEM_SIGN、DOU_DEBUG 等基础常量。
• config/security.php 提供安全栈配置，被 Request 与安全中间件消费。
• Request 在早期阶段加载安全配置，确保后续所有模块基于正确的 IP/Host 上下文运行。
• 中间件层（CSRF、安全头、限流）依赖上述配置，形成端到端的安全防护链。

graph LR
CFG["config/config.php"] --> REQ["Request.php"]
SEC["config/security.php"] --> REQ
REQ --> CSRF["CSRF 中间件"]
REQ --> HDR["安全头中间件"]
CSRF --> APP["业务控制器"]
HDR --> APP

图示来源

• config.php:33-52
• security.php:51-87
• Request.php:72-97
• CsrfMiddleware.php（前台）:24-53
• CsrfMiddleware.php（后台）:24-66
• AbstractSecurityHeadersMiddleware.php:23-49

章节来源

• config.php:33-52
• security.php:51-87
• Request.php:72-97

性能与安全注意事项

• 在生产环境务必关闭 DOU_DEBUG，减少敏感信息泄露风险。
• 合理配置 trusted_proxies 与 trusted_hosts，避免误判真实 IP 与 Host。
• 启用 HSTS 时需确保全站 HTTPS 且证书有效，避免降级攻击。
• 对高并发场景，谨慎开启全局限流，优先针对敏感接口定向限流。
• 会话 Cookie 建议 httponly=true、secure 跟随 HTTPS、samesite=Lax/Strict。

故障排查指南

• CSRF 校验失败
  • 常见原因：页面停留过久导致令牌失效、跨站请求未携带 token、GET 续跑链接未带 token。
  • 处理建议：刷新页面重新获取 token；检查表单与 AJAX 是否注入 token；确认路由未错误豁免 csrf。
• Host/IP 异常
  • 检查 trusted_proxies 是否包含代理出口 IP；trusted_hosts 是否包含实际域名。
• HSTS 不生效
  • 确认当前为 HTTPS 且 security.headers.hsts.enabled=true；检查反向代理是否正确透传协议。
• 调试信息泄露
  • 确认 DOU_DEBUG 在生产环境已关闭；检查日志级别与输出渠道。

章节来源

• CsrfMiddleware.php（后台）:68-79
• security.php:51-87
• config.php:51-52

结论

DouPHP 提供了完善的安全配置体系：通过 DOU_APP_KEY 保障签名与加密强度，SYSTEM_SIGN 实现实例识别，DOU_DEBUG 控制调试输出；借助 security.* 实现可信代理/Host、安全响应头、限流与会话硬化；前后端 CSRF 中间件覆盖静态与一次性令牌；HSTS 与 SMTP TLS 进一步加固传输安全。按本文建议完成配置与加固，可在不同环境下获得一致的安全基线。

附录

• 快速核对清单
  • 生产环境关闭 DOU_DEBUG
  • 配置 trusted_proxies 与 trusted_hosts
  • 启用 HSTS（全站 HTTPS）
  • 会话 Cookie 设置为 httponly=true、secure 跟随 HTTPS、samesite=Lax/Strict
  • 定期轮换 DOU_APP_KEY 与第三方凭据，并使用加密存储
  • 审查 CSRF 豁免路由，确保最小化暴露面