简介

本指南面向部署与运维人员，围绕 DouPHP 的网络安全配置提供可操作的最佳实践。内容覆盖：

• HTTPS 强制与安全响应头（HSTS、X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy）
• 可信代理与反向代理安全（IP 白名单、Host 校验、请求来源可信化）
• 访问频率限制与防刷（按端点限流、429 响应、存储后端）
• CSRF 防护（后台令牌模型与豁免策略）
• 监控与入侵检测集成建议
• 常见网络攻击防护方案与应急响应流程

项目结构

DouPHP 的安全能力由“配置 + 中间件”构成：

• 统一安全配置位于 config/security.php，集中管理可信代理、可信 Host、安全响应头、限流存储路径与会话 Cookie 硬化参数。
• 三端（前台 front、后台 admin、API）各自挂载 SecurityHeadersMiddleware，行为来自基类 AbstractSecurityHeadersMiddleware。
• TrustProxyMiddleware 在管道最前置设置可信代理，确保后续 ip() 调用正确解析真实客户端 IP。
• 定向限流通过 AbstractThrottleMiddleware 及其子类实现，仅对敏感路由生效。
• 后台 CSRF 由 CsrfMiddleware 统一管理，支持例外令牌与豁免路由。

graph TB
A["客户端"] --> B["Nginx/负载均衡"]
B --> C["DouPHP 入口"]
C --> D["TrustProxyMiddleware<br/>设置可信代理"]
D --> E["SecurityHeadersMiddleware<br/>下发安全响应头"]
E --> F["ThrottleMiddleware<br/>定向限流"]
F --> G["业务控制器/服务"]
G --> H["数据库/缓存"]

核心组件

• 安全响应头中间件：根据配置自动下发 X-Content-Type-Options、X-Frame-Options、Referrer-Policy、Permissions-Policy；仅在 HTTPS 且开启时下发 HSTS。
• 可信代理中间件：将 security.trusted_proxies 注入 Request，使 ip() 能正确识别真实客户端地址。
• 定向限流中间件：对登录、注册、验证码、公共表单等敏感端点按 IP 计数限流，超限返回 429。
• 后台 CSRF 中间件：统一令牌模型与豁免策略，防止跨站请求伪造。
• 会话 Cookie 硬化：httponly、secure、samesite、use_strict_mode 等选项由配置驱动。

架构总览

下图展示一次请求从进入 Nginx 到应用层中间件的完整链路，以及安全头的下发时机与条件。

sequenceDiagram
participant U as "用户浏览器"
participant N as "Nginx/反代"
participant P as "DouPHP 入口"
participant TP as "TrustProxyMiddleware"
participant SH as "SecurityHeadersMiddleware"
participant TH as "ThrottleMiddleware"
participant C as "控制器/服务"
participant R as "Response"
U->>N : HTTP(S) 请求
N->>P : 转发请求
P->>TP : 设置可信代理
TP-->>P : 继续处理
P->>SH : 读取 security.headers
SH-->>R : 下发安全响应头含条件 HSTS
P->>TH : 检查是否命中限流规则
alt 未超限
TH-->>C : 放行
C-->>R : 生成响应
else 超限
TH-->>U : 429 Too Many Requests
end
R-->>U : 响应体 + 安全头

详细组件分析

HTTPS 强制与 HSTS 策略

• 安全头下发逻辑：当当前请求为 HTTPS 且配置中 hsts.enabled 为真时，会下发 Strict-Transport-Security，包含 max-age 与可选 includeSubDomains。
• 建议：
  • 在 Nginx 层强制 301 重定向 http -> https，并启用 TLSv1.2+、禁用旧套件。
  • 在 config/security.php 中开启 hsts.enabled，并根据站点规模设置合理的 max_age（如 31536000），必要时开启 subdomains。
  • 首次上线建议先使用较短 max_age 验证，再逐步提升。

flowchart TD
Start(["请求进入"]) --> CheckHTTPS{"是否为 HTTPS?"}
CheckHTTPS --> |否| NoHSTS["不发送 HSTS"]
CheckHTTPS --> |是| CheckConfig{"hsts.enabled ?"}
CheckConfig --> |否| NoHSTS
CheckConfig --> |是| BuildHSTS["构建 HSTS 值<br/>max-age / includeSubDomains"]
BuildHSTS --> SendHSTS["发送 Strict-Transport-Security"]
NoHSTS --> End(["结束"])
SendHSTS --> End

安全响应头配置

• 已实现的安全头：
  • X-Content-Type-Options: nosniff（content_type_options 为真时）
  • X-Frame-Options: SAMEORIGIN/DENY（frame_options 非空时）
  • Referrer-Policy: strict-origin-when-cross-origin（referrer_policy 非空时）
  • Permissions-Policy: 默认限制 geolocation/microphone/camera（permissions_policy 非空时）
• 建议：
  • 保持 content_type_options 为 true，避免 MIME 嗅探。
  • 根据页面是否需要被 iframe 嵌入选择 frame_options。
  • 对外 API 建议收紧 permissions_policy，关闭不必要的设备权限。
  • 若需 CSP，可在网关或前端模板中补充，框架未内置 CSP。

可信代理与 Host 白名单

• 可信代理：
  • 通过 security.trusted_proxies 配置精确 IP 或 CIDR，Request::ip() 才会采信 X-Forwarded-* 头。
  • TrustProxyMiddleware 在管道最前置设置可信代理，保证审计、限流等模块获取到真实 IP。
• Host 白名单：
  • security.trusted_hosts 用于校验 Host，防止 Host 头注入污染外部链接（邮件、跳转、缓存）。
  • 未命中的 Host 会回落到名单首项，避免错误域名泄露。

classDiagram
class TrustProxyMiddleware {
+handle(next) mixed
}
class Config {
+get(key, default) mixed
}
class Request {
+setTrustedProxies(list) void
+ip() string
}
TrustProxyMiddleware --> Config : "读取 trusted_proxies"
TrustProxyMiddleware --> Request : "设置可信代理"

访问频率限制（限流）

• 机制：
  • 基于 AbstractThrottleMiddleware，仅对显式配额的敏感路由生效。
  • 限流键默认 module.action.ip，依赖 TrustProxy 之后获取的真实 IP。
  • 超限返回 429，并附带 Retry-After 提示。
• 端点示例：
  • API 端：登录、注册、手机登录、找回密码、短信验证码、公共匿名写接口、防伪查询、LLM 相关端点。
  • 前台端：登录、注册、手机号登录、找回密码、短信验证码、公共表单提交、聊天流等。
• 存储：
  • 使用 security.throttle.store 指定文件后端目录，落盘为 .json 文件。

flowchart TD
S(["进入 Throttle"]) --> GetRoute["解析 module/action/sub/ip"]
GetRoute --> Lookup{"是否命中配额?"}
Lookup --> |否| Next["放行到下一中间件"]
Lookup --> |是| CheckStore["检查 ThrottleStore"]
CheckStore --> TooMany{"超过阈值?"}
TooMany --> |是| Reject["返回 429 + Retry-After"]
TooMany --> |否| Hit["记录一次 hit"]
Hit --> Next

后台 CSRF 防护

• 令牌模型：登录后下发共享静态令牌 static_admin，各表单页渲染并提交时由中间件自动校验。
• 例外令牌：找回密码提交使用一次性 password_reset 令牌。
• 豁免路由：通过路由级 withoutMiddleware(['csrf']) 声明式豁免（如登录提交、安装 JSON API）。
• 失败处理：抛出 DomainException，由后台统一消息页提示并重定向。

会话 Cookie 硬化

• 通过 security.session 控制：
  • httponly：禁止 JS 读取，防 XSS 窃取 sid。
  • secure：仅 HTTPS 下发，null 表示跟随运行时 IS_HTTPS。
  • samesite：Lax/Strict/None，防御跨站 CSRF。
  • use_strict_mode：拒绝未初始化的外部 sid，防会话固定。

依赖关系分析

• 中间件依赖链：
  • TrustProxyMiddleware → SecurityHeadersMiddleware → ThrottleMiddleware → 业务控制器
  • 安全头与限流均依赖 Request 的 isSecure()/ip()，因此必须置于其前。
• 配置依赖：
  • AbstractSecurityHeadersMiddleware 读取 security.headers。
  • AbstractThrottleMiddleware 读取 security.throttle.store。
  • TrustProxyMiddleware 读取 security.trusted_proxies。

graph LR
CFG["config/security.php"] --> SH["AbstractSecurityHeadersMiddleware"]
CFG --> TH["AbstractThrottleMiddleware"]
CFG --> TP["TrustProxyMiddleware"]
TP --> REQ["Request::ip()/isSecure()"]
SH --> RESP["Response 输出头"]
TH --> STORE["ThrottleStore 文件存储"]

性能考量

• 安全头中间件仅在匹配路由时执行，避免对 404 等无效请求造成额外开销。
• 限流存储为本地文件，生产环境建议：
  • 使用独立磁盘或 SSD 存放 throttle 目录，减少 IO 竞争。
  • 多实例部署时考虑替换为 Redis/Memcached 等共享存储后端（需扩展 ThrottleStore）。
• 可信代理配置应尽可能精确，避免过宽 CIDR 导致误判真实 IP，影响限流与审计准确性。
• HSTS 开启后需谨慎灰度发布，避免回滚困难。

故障排查指南

• 安全头未生效：
  • 确认中间件已挂载至对应端（front/admin/api）的管道。
  • 检查 headers_sent() 是否提前输出（例如调试日志、BOM 字符）。
  • 核对 security.headers 配置是否正确，HSTS 仅在 HTTPS 且 enabled 时下发。
• 限流误拦截：
  • 检查 TrustProxyMiddleware 是否在限流之前执行，确保 request()->ip() 可信。
  • 核对 security.trusted_proxies 是否包含负载均衡/Nginx 出口 IP。
  • 查看 ThrottleStore 目录是否存在写入权限。
• CSRF 失败：
  • 确认表单已渲染 csrf token，且未被缓存。
  • 检查是否有路由通过 withoutMiddleware(['csrf']) 豁免。
  • 关注后台异常页提示，定位具体失败原因。

结论

DouPHP 通过“配置 + 中间件”的组合提供了完善的基础网络安全能力：可信代理、安全响应头、HSTS、定向限流与后台 CSRF。结合 Nginx 层的 HTTPS 强制、TLS 加固与 WAF 防护，可形成纵深防御体系。建议在生产环境严格配置 trusted_proxies/trusted_hosts，开启必要的安全头与 HSTS，并对敏感端点实施细粒度限流。

附录

防火墙与访问控制建议

• 仅开放必要端口（80/443），其他端口通过云厂商安全组或主机防火墙限制。
• 对管理后台（admin）限制来源 IP 白名单（Nginx 层 allow/deny）。
• 对 API 接口启用速率限制与签名校验（结合项目限流中间件与业务鉴权）。

代理服务器配置要点

• 可信代理：将负载均衡/Nginx 出口 IP 加入 security.trusted_proxies，确保 Request::ip() 正确。
• 反向代理安全：
  • 透传 X-Forwarded-Proto/For/Host 时，务必在可信代理范围内才采信。
  • 在 Nginx 层强制 HTTPS、启用 HSTS、关闭不安全协议与弱加密套件。
• 负载均衡：
  • 健康检查与优雅下线，避免流量抖动引发限流误判。
  • 会话亲和性谨慎使用，优先无状态设计。

监控与入侵检测集成

• 日志：
  • 开启访问日志与错误日志，集中收集到日志平台（ELK/阿里云 SLS）。
  • 对 4xx/5xx、限流 429、CSRF 失败进行告警。
• 入侵检测：
  • 结合 WAF（云 WAF 或 ModSecurity）拦截 SQL 注入、XSS、扫描器。
  • 对高频 IP 自动封禁（Fail2ban/云盾）。
• 指标：
  • 监控 QPS、延迟、错误率、限流触发次数、证书过期时间。

常见攻击防护与应急响应

• 常见攻击防护：
  • XSS：启用 X-Content-Type-Options、Referrer-Policy，配合输入输出编码。
  • 点击劫持：X-Frame-Options 设置为 DENY/SAMEORIGIN。
  • 暴力破解：限流中间件 + 账号锁定策略。
  • 重放/CSRF：后台 CSRF 中间件 + SameSite Cookie。
  • 协议降级：强制 HTTPS 与 HSTS。
• 应急响应流程：
  • 发现异常：监控告警、日志分析、WAF 拦截记录。
  • 快速止血：临时封禁恶意 IP、扩大限流阈值、关闭可疑功能。
  • 根因修复：补丁更新、配置加固、代码修复。
  • 复盘改进：更新策略、完善监控、演练预案。