简介
本文件面向 DouPHP 的数据安全传输，覆盖以下关键主题：
- 敏感数据加密传输：HTTPS、SSL 证书管理、TLS 通道与凭据加密。
- 响应数据脱敏：个人信息隐藏、敏感字段过滤、日志脱敏。
- 数据完整性校验：数字签名与数据指纹验证。
- 安全头配置：CSP、X-Frame-Options、HSTS、Referrer-Policy、Permissions-Policy 等。
- 数据泄露防护与审计日志记录：CSRF、限流、会话硬化、登录失败审计等。
项目结构
DouPHP 在“三端”（前台 front、后台 admin、API）分别挂载安全中间件，统一由基类下发安全响应头；安全策略通过配置文件集中管理；前端通过 CSRF 拦截器自动注入令牌；凭据存储采用带 MAC 的对称加密；邮件发送支持 TLS 升级；审计服务提供统一的日志写入能力。
graph TB
Client["客户端"] --> FrontMW["前台安全头中间件"]
Client --> AdminMW["后台安全头中间件"]
Client --> ApiMW["API 安全头中间件"]
FrontMW --> CoreBase["安全头基类<br/>AbstractSecurityHeadersMiddleware"]
AdminMW --> CoreBase
ApiMW --> CoreBase
Config["安全配置<br/>config/security.php"] --> CoreBase
CSRF_Front["前台 CSRF 中间件"] --> CoreBase
CSRF_Admin["后台 CSRF 中间件"] --> CoreBase
Audit["审计服务<br/>AuditService"] --> CoreBase
Mail["SMTP TLS<br/>Smtp::startTLS"] --> Client
Credential["凭据加密<br/>CredentialCipher"] --> Audit核心组件
- 安全响应头中间件：三端薄壳继承基类，按配置下发 X-Content-Type-Options、X-Frame-Options、Referrer-Policy、Permissions-Policy，并在 HTTPS 且开启时下发 HSTS。
- CSRF 防护：前台/后台中间件配合前端脚本自动注入 X-CSRF-Token，防止跨站请求伪造。
- 凭据加密：AI 凭据使用 AES-256-CBC + HMAC-SHA256 的 MAC 校验，确保机密性与完整性。
- 邮件 TLS：SMTP 通过 STARTTLS 建立加密通道。
- 审计日志：统一写入操作日志，避免将 PII 直接落库，使用标签化 details 提升可读性并降低泄露风险。
架构总览
下图展示一次受保护的 HTTP 请求从进入服务器到返回响应的完整链路，包括安全头下发、CSRF 校验、业务处理与审计记录。
sequenceDiagram
participant C as "客户端"
participant MW as "安全头中间件"
participant CSRF as "CSRF 中间件"
participant CTRL as "控制器/服务"
participant AUD as "审计服务"
C->>MW : 发起 HTTPS 请求
MW->>MW : 读取 config/security.php
MW-->>C : 设置 X-Frame-Options / Referrer-Policy / Permissions-Policy / (可选) HSTS
C->>CSRF : 携带 X-CSRF-Token
CSRF->>CSRF : 校验令牌有效性
CSRF-->>CTRL : 通过则放行
CTRL->>AUD : 写入审计日志不含 PII
CTRL-->>C : 返回响应已含安全头详细组件分析
安全响应头与 HSTS
- 行为：根据配置下发基线安全头；仅在 HTTPS 且启用时下发 HSTS。
- 可配置项：frame_options、content_type_options、referrer_policy、permissions_policy、hsts.enabled/max_age/subdomains。
- 建议：生产环境开启 HSTS，合理设置 max_age 与 includeSubDomains；严格限制权限策略。
flowchart TD
Start(["请求进入"]) --> ReadCfg["读取 security.headers"]
ReadCfg --> SetBase{"是否配置基线头?"}
SetBase -- 是 --> Apply["设置 X-Content-Type-Options / X-Frame-Options / Referrer-Policy / Permissions-Policy"]
SetBase -- 否 --> SkipBase["跳过基线头"]
Apply --> CheckHSTS{"是否启用 HSTS 且为 HTTPS?"}
SkipBase --> CheckHSTS
CheckHSTS -- 是 --> SetHSTS["设置 Strict-Transport-Security"]
CheckHSTS -- 否 --> End(["结束"])
SetHSTS --> EndCSRF 防护（前台/后台）
- 前端：自动从 meta 读取 token，对非幂等方法注入 X-CSRF-Token。
- 后端：前台/后台中间件分别维护一次性令牌或静态令牌模型，并对特定路由进行 GET 校验。
- 建议：保持前端脚本与中间件一致；对外部回调使用声明式豁免。
sequenceDiagram
participant JS as "前端脚本"
participant MW as "CSRF 中间件"
participant Svc as "业务服务"
JS->>JS : 读取 <meta name="csrf-token">
JS->>MW : POST/PUT/PATCH/DELETE 携带 X-CSRF-Token
MW->>MW : 校验令牌一次性或静态
MW-->>Svc : 通过则执行业务
MW-->>JS : 拒绝则返回错误凭据加密与完整性校验（AI 凭据）
- 算法：AES-256-CBC 加密，附带 HMAC-SHA256 的 MAC 校验，解密前必须验证 MAC。
- 作用：保证凭据机密性与完整性，防止篡改。
- 建议：密钥轮换、安全存储、最小化暴露面。
classDiagram
class CredentialCipher {
- macMatches(parts, key) bool
- opensslDecrypt(parts, key) string
}邮件 TLS 加密
- 机制：SMTP 连接后执行 STARTTLS，随后启用 TLS 加密通信。
- 建议：强制 TLS、禁用弱密码套件、定期更新证书。
审计日志与数据脱敏
- 审计服务：统一写入操作日志，包含操作者类型、动作、前后状态、备注、IP 与时间戳。
- 用户日志细节：使用标签字典（如 EMPTY_INPUT、FIELD_INVALID、IP_RATE_LIMITED 等），避免将明文 PII 写入日志。
- 登录失败审计：多分支统一调用审计写入，便于追踪攻击与异常。
- 建议：日志分级、脱敏规则、保留周期、访问控制。
依赖关系分析
- 安全头中间件依赖配置中心读取 headers 策略。
- CSRF 中间件依赖前端脚本注入令牌与后端令牌存储。
- 审计服务依赖 IP 获取与数据库写入。
- 凭据加密依赖 OpenSSL 与安全的密钥管理。
- 邮件 TLS 依赖 SMTP 服务器支持与证书链正确。
graph LR
SecCfg["security.php"] --> HeadMW["安全头中间件"]
CSRFJS["dou.csrf.js"] --> CSRFMW["CSRF 中间件"]
CSRFMW --> Ctrl["控制器/服务"]
Ctrl --> Audit["审计服务"]
Ctrl --> Enc["凭据加密"]
Ctrl --> Mail["SMTP TLS"]性能考虑
- 安全头下发为轻量操作，影响可忽略。
- CSRF 校验为内存/存储查找，注意令牌存储后端容量与过期策略。
- 凭据加解密涉及 CPU 开销，应缓存必要上下文并避免重复计算。
- 审计日志写入可能成为瓶颈，建议异步化与批量写入。
- HSTS 会强制后续请求走 HTTPS，需确保证书与反向代理配置正确。
故障排查指南
- HSTS 未生效：检查是否为 HTTPS 且配置中 hsts.enabled 为 true；确认反向代理终止 SSL。
- CSRF 失败：确认前端脚本加载了正确的 meta 令牌；检查中间件是否被路由豁免；核对表单提交方法。
- 凭据解密失败：检查密钥一致性、IV 与密文格式；确认 MAC 校验通过后再解密。
- 审计缺失：检查审计服务初始化与数据库写入权限；确认日志级别与存储路径。
- 邮件 TLS 失败：检查 STARTTLS 协商与证书链；确认端口与防火墙策略。
结论
DouPHP 通过集中化的安全配置与中间件体系，实现了响应头硬化、CSRF 防护、凭据加密与完整性校验、邮件 TLS 以及审计日志记录。建议在生产环境中：
- 启用 HSTS 并严格配置权限策略。
- 保持 CSRF 令牌机制一致，外部回调声明式豁免。
- 使用强加密算法与密钥管理，定期轮换。
- 实施日志脱敏与分级，结合监控告警。
- 持续评估与加固反向代理与证书链。
附录
- 安全头参考：X-Content-Type-Options、X-Frame-Options、Referrer-Policy、Permissions-Policy、Strict-Transport-Security。
- CSRF 最佳实践：仅对非幂等方法校验；一次性令牌用于匿名流程；GET 特殊场景显式校验。
- 审计日志规范：使用标签化 details，避免 PII；记录必要上下文（操作者、IP、时间）。
- 加密与签名：优先使用现代算法（AES-GCM 或 AES-CBC+HMAC），确保随机 IV 与不可预测 nonce。