简介

本指南面向 DouPHP 的数据安全实践，聚焦"敏感数据识别与分类、静态与动态脱敏策略、日志保护、测试数据准备、匿名化算法选择与评估、泄露检测与应急响应"。文档基于仓库现有能力（日志脱敏、安全配置、验证码与 XSS 过滤、认证中间件等）给出可落地的方案与最佳实践。最新更新：新增了Str工具类的智能掩码功能，为手机号和邮箱提供专门的隐私保护方法。

项目结构

DouPHP 的安全与日志相关能力主要分布在以下位置：

• 日志记录与脱敏：core/infra/log/Log.php
• 字符串处理与掩码：core/support/Str.php
• 安全栈配置：config/security.php
• 验证码与令牌：core/infra/security/Captcha.php
• XSS 过滤：core/infra/security/Xss.php
• 认证与授权中间件：admin/middleware/AuthMiddleware.php、front/facade/Auth.php
• API 侧日志配置：_/.api/config/log.php
• 应用引导与安全常量：core/bootstrap.php、config/config.php

graph TB
A["请求入口"] --> B["认证/授权中间件"]
B --> C["业务控制器/服务"]
C --> D["日志记录(Log)"]
C --> E["字符串处理(Str)"]
C --> F["安全工具(XSS/验证码)"]
D --> G["存储: storage/log/*.log"]
E --> H["掩码处理(手机号/邮箱)"]
F --> I["会话/缓存(防重放/限流)"]

图表来源

• core/infra/log/Log.php:289-342
• core/support/Str.php:441-475
• core/infra/security/Xss.php:555-601
• core/infra/security/Captcha.php:226-250
• admin/middleware/AuthMiddleware.php:42-50

章节来源

• core/bootstrap.php:24-66
• config/config.php:15-53

核心组件

• 日志脱敏与分级：提供按级别写入、采样、每分钟限流、自动上下文补全与敏感键掩码；URL 查询串中的敏感参数也会被替换。
• 字符串掩码工具：Str工具类提供通用的mask()方法和专用的maskPhone()、maskEmail()方法，支持智能格式保持的敏感信息隐藏。
• 安全栈配置：可信代理、可信 Host、响应头加固、限流存储路径与会话 Cookie 硬化。
• 验证码与令牌：图形验证码 HMAC 校验、一次性消费、TTL 与最小提交间隔；短信/邮件验证码窗口期控制。
• XSS 过滤：白名单标签与属性、危险标签移除、实体规范化、平衡标签等。
• 认证中间件：后台登录态恢复与未登录拦截；前台会员认证门面用于身份解析与状态注入。

章节来源

• core/infra/log/Log.php:44-71
• core/infra/log/Log.php:289-342
• core/infra/log/Log.php:412-499
• core/support/Str.php:411-475
• config/security.php:51-87
• core/infra/security/Captcha.php:226-250
• core/infra/security/Xss.php:555-601
• admin/middleware/AuthMiddleware.php:42-50
• front/facade/Auth.php:30-63

架构总览

下图展示一次典型请求在 DouPHP 中如何经过认证、业务处理、字符串掩码、日志记录与安全过滤，并在输出前完成敏感信息脱敏。

sequenceDiagram
participant U as "用户"
participant M as "认证中间件"
participant S as "业务服务"
participant STR as "字符串处理(Str)"
participant L as "日志(Log)"
participant X as "XSS/验证码"
U->>M : 发起请求
M->>M : 恢复登录态/鉴权
M-->>U : 未登录则跳转/拒绝
M->>S : 通过鉴权后执行业务
S->>STR : 对敏感数据进行掩码处理
STR->>STR : 手机号/邮箱智能掩码
S->>X : 输出前进行内容净化/验证码校验
S->>L : 记录业务日志(含上下文)
L->>L : 敏感键/URL查询串脱敏
L-->>S : 写入 storage/log/*.log

图表来源

• admin/middleware/AuthMiddleware.php:42-50
• core/support/Str.php:441-475
• core/infra/security/Xss.php:555-601
• core/infra/log/Log.php:289-342
• core/infra/log/Log.php:412-499

详细组件分析

Str工具类掩码功能（新增）

Str工具类提供了完整的字符串掩码功能，专门用于敏感数据的隐私保护：

通用掩码方法

• mask()方法：基础掩码功能，支持指定起始位置和长度进行字符替换
• 参数控制：支持负数起始位置、自定义掩码字符、UTF-8多字节字符处理

专用掩码方法

• maskPhone()方法：智能手机号掩码

  • 11位手机号：保留前3后4（如 138****5678）
  • 较长号码：保留前2后2
  • 短号码：仅保留首字符
  • 支持分隔符和非数字字符的原样占位

• maskEmail()方法：智能邮箱掩码

  • 保留@前本地部分前2个字符（不足2个保留1个）
  • 其余部分以***代替
  • 域名部分原样保留（如 ab***@example.com）

flowchart TD
Start(["输入敏感数据"]) --> CheckType{"数据类型判断"}
CheckType --> |手机号| PhoneMask["手机号掩码处理"]
CheckType --> |邮箱| EmailMask["邮箱掩码处理"]
CheckType --> |其他| GenericMask["通用掩码处理"]
PhoneMask --> PhoneLogic{"长度判断"}
PhoneLogic --> |>=8位| Keep3End4["保留前3后4"]
PhoneLogic --> |>=5位| Keep2End2["保留前2后2"]
PhoneLogic --> |<5位| KeepFirst["仅保留首字符"]
EmailMask --> SplitEmail["分割用户名和域名"]
SplitEmail --> KeepUser["保留用户名前2字符"]
KeepUser --> AddDomain["添加@和域名"]
GenericMask --> ApplyMask["应用掩码规则"]
Keep3End4 --> Output["输出结果"]
Keep2End2 --> Output
KeepFirst --> Output
AddDomain --> Output
ApplyMask --> Output

图表来源

• core/support/Str.php:441-475

章节来源

• core/support/Str.php:411-475

日志脱敏与分级（核心能力）

• 敏感键识别：内置 password、token、secret、authorization、session_id、cookie 等键片段匹配，命中即替换为占位符。
• URL 脱敏：对 request_uri/url/full_url/referer 等承载 URL 的上下文键，解析查询串并对敏感参数名对应的值进行掩码。
• 分级与限流：支持最低级别、级别白名单、场景通道白名单、采样率、每分钟单 key 最大条数。
• 自动上下文：自动补充 request_id、scene、ip、route、module、action、user/admin/work id 等。
• 落盘路径：storage/log/log_YYYY-MM-DD.log。

flowchart TD
Start(["写入日志"]) --> CheckLevel["检查级别/白名单/通道"]
CheckLevel --> |不通过| End(["丢弃"])
CheckLevel --> |通过| AutoCtx["自动补全上下文"]
AutoCtx --> Redact["敏感键/URL查询串脱敏"]
Redact --> Sample["采样/限流判断"]
Sample --> |丢弃| End
Sample --> |保留| Write["写入当日日志文件"]
Write --> End

图表来源

• core/infra/log/Log.php:289-342
• core/infra/log/Log.php:412-499

章节来源

• core/infra/log/Log.php:44-71
• core/infra/log/Log.php:289-342
• core/infra/log/Log.php:412-499

安全栈与会话硬化

• 可信代理与 Host：避免伪造 IP/Host 污染日志与对外链接。
• 响应头加固：X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy、HSTS。
• 会话 Cookie 硬化：HttpOnly、Secure、SameSite、Strict Mode。
• 限流存储：定向限流后端目录。

章节来源

• config/security.php:51-87

验证码与令牌防护

• 图形验证码：HMAC 签名、TTL、最小提交间隔、一次性消费，降低自动化攻击风险。
• 短信/邮件验证码：发送前校验账号格式与存在性，API 返回 verification 包含 ontime 与 code 哈希，配合窗口期验证。
• Token 机制：临时 token 绑定 session，防止跨会话重用。

章节来源

• core/infra/security/Captcha.php:226-250
• core/infra/security/Captcha.php:359-421
• core/infra/security/Captcha.php:428-462

XSS 过滤

• 白名单标签与属性：严格限制可渲染元素与属性，移除危险标签。
• 实体规范化与控制字符清理：防止编码绕过与注入。
• 标签平衡：修复不完整标签，避免 DOM 破坏。

章节来源

• core/infra/security/Xss.php:555-601
• core/infra/security/Xss.php:734-785

认证与授权中间件

• 后台认证中间件：从会话恢复管理员身份，未登录直接重定向到登录页。
• 前台认证门面：统一身份解析与登录状态写入，供业务层使用。

章节来源

• admin/middleware/AuthMiddleware.php:42-50
• front/facade/Auth.php:30-63

依赖关系分析

• 日志模块依赖：
  • 会话：读取 user_id/admin_id/work_id 以补全上下文。
  • 路由/请求：获取 route/module/action/request_uri 等上下文。
  • 文件系统：写入 storage/log 目录。
• 字符串处理模块依赖：
  • UTF-8支持：多字节字符处理确保中文等字符正确显示。
  • 正则表达式：用于格式验证和模式匹配。
• 安全模块依赖：
  • 配置：安全头、限流存储、会话 Cookie 策略。
  • 会话：验证码与临时 token 存储。
• 引导流程：
  • bootstrap 阶段定义路径常量、加载配置、注册 Facade 与容器实例，确保后续安全与日志可用。

graph LR
Log["日志(Log)"] --> Session["会话(Session)"]
Log --> Request["请求(Request)"]
Log --> FS["文件系统(storage/log)"]
Str["字符串处理(Str)"] --> UTF8["UTF-8支持"]
Str --> Regex["正则表达式"]
Sec["安全配置"] --> Headers["响应头/会话Cookie"]
Captcha["验证码(Captcha)"] --> Session
Xss["XSS过滤"] --> Output["输出内容"]
Bootstrap["引导(bootstrap)"] --> All["各模块初始化"]

图表来源

• core/infra/log/Log.php:524-571
• core/infra/log/Log.php:792-800
• core/support/Str.php:411-475
• config/security.php:51-87
• core/bootstrap.php:24-66

章节来源

• core/bootstrap.php:24-66
• config/config.php:15-53

性能考量

• 日志采样与限流：在高并发下通过采样率与每分钟单 key 上限减少 I/O 压力。
• 字符串掩码优化：Str工具类使用高效的字符串操作函数，避免不必要的内存分配。
• 非调试模式截断 trace：生产环境避免过长堆栈影响写入性能。
• 会话与验证码：HMAC 与一次性消费增加少量 CPU 开销，但显著提升安全性。
• XSS 过滤：白名单过滤在可控范围内，建议仅在需要富文本的场景启用。

故障排查指南

• 日志未写入或过大：
  • 检查是否启用了日志、级别白名单、通道白名单、采样率与每分钟上限。
  • 确认 storage/log 目录可写，并定期清理历史日志。
• 敏感信息仍出现在日志：
  • 核对上下文键名是否命中敏感键片段；必要时扩展敏感键清单。
  • 检查 URL 类上下文键是否被正确识别并进行查询串脱敏。
• 验证码失败或频繁过期：
  • 确认 TTL、最小提交间隔设置合理；检查会话是否被清理。
  • 核对 HMAC 密钥来源（应用密钥/Shell 密钥）。
• XSS 输出异常：
  • 调整白名单标签与属性；确认已启用实体规范化与控制字符清理。
• 字符串掩码问题：
  • 检查输入数据格式是否符合预期（手机号位数、邮箱格式）。
  • 确认UTF-8编码设置正确，避免中文等多字节字符处理错误。

章节来源

• core/infra/log/Log.php:289-342
• core/infra/log/Log.php:412-499
• core/infra/security/Captcha.php:226-250
• core/infra/security/Xss.php:555-601
• core/support/Str.php:411-475

结论

DouPHP 已在日志层实现完善的敏感信息脱敏与分级控制，并提供安全栈配置、验证码与 XSS 过滤等基础能力。最新更新：Str工具类新增的智能掩码功能为手机号和邮箱提供了专门的隐私保护方法，支持保持数字格式的同时隐藏敏感信息，适用于管理后台和报表展示场景。结合认证中间件与会话硬化，可在生产环境中有效降低敏感数据泄露风险。建议在业务层遵循"最小必要"原则收集数据，并通过统一的日志接口记录，确保所有落盘数据均经过脱敏。

附录

敏感数据识别与分类方法

• 个人信息：手机号、邮箱、姓名、身份证号、银行卡号、收货地址、登录凭证（密码、token、session_id、cookie）等。
• 商业机密：订单金额、成本价、供应商信息、合同条款、内部报表、AI 模型密钥等。
• 技术敏感：数据库连接串、API Key、私钥、签名、加密密钥、内部域名与端口、错误堆栈等。
• 识别策略：
  • 字段命名约定：如 mobile、email、name、id_card、bank_card、address、password、token、secret、api_key、private_key、authorization、credential、session_id、cookie 等。
  • 正则与类型校验：对手机号、邮箱、身份证、银行卡等进行格式校验与脱敏。
  • 上下文键黑名单：沿用日志模块的敏感键片段匹配，扩展至业务上下文。

数据脱敏策略（静态与动态）

• 静态脱敏（离线批处理）：
  • 适用：导出报表、备份数据、测试数据生成。
  • 方法：对手机号/邮箱做掩码或哈希；对金额做范围化或随机化；对 ID 做映射替换；对文本内容做关键词泛化。
  • 注意：保持统计特征（如分布、关联关系），避免过度失真。
• 动态脱敏（在线实时）：
  • 适用：API 返回、管理端列表、日志输出。
  • 方法：在序列化/输出前对敏感字段进行掩码或截断；对 URL 查询串中的敏感参数进行替换；对富文本进行 XSS 过滤。
  • 新增功能：使用Str工具类的maskPhone()和maskEmail()方法进行智能掩码，保持数据格式的完整性。
  • 保障：通过日志模块的 redactSensitive 与 redactQueryString 实现统一脱敏。

章节来源

• core/infra/log/Log.php:412-499
• core/support/Str.php:441-475
• core/infra/security/Xss.php:555-601

日志记录中的数据保护机制

• 敏感信息过滤：基于敏感键片段匹配与 URL 查询串解析，将敏感值替换为占位符。
• 日志级别控制：支持最低级别、级别白名单、通道白名单、采样率与每分钟单 key 上限。
• 自动上下文：自动补充请求标识、IP、路由、模块、动作与用户身份，便于追踪同时避免泄露明文凭据。

章节来源

• core/infra/log/Log.php:44-71
• core/infra/log/Log.php:289-342
• core/infra/log/Log.php:524-571

测试环境数据准备流程

• 生产数据脱敏：
  • 导出后执行静态脱敏脚本：掩码个人身份信息、泛化商业数据、哈希或替换技术敏感字段。
  • 校验脱敏效果：确保无法反推原始值，且统计特征基本保留。
• 测试数据生成：
  • 使用 Faker 或自定义脚本生成符合规则的假数据（手机号、邮箱、姓名、地址等）。
  • 建立数据种子库：覆盖常见业务场景（下单、支付、售后、分销等）。
• 数据隔离：
  • 测试环境与生产环境物理隔离，禁止混用凭据与密钥。
  • 使用独立数据库与存储路径，避免误写生产数据。

数据匿名化算法选择与隐私保护效果评估

• 算法选择：
  • 掩码/截断：适用于展示型脱敏（如手机号中间四位掩码、邮箱用户名部分隐藏）。
  • 哈希/盐值：适用于不可逆标识（如用户 ID 匿名化）。
  • 泛化/区间化：适用于数值型数据（如年龄区间、金额区间）。
  • 差分隐私/噪声注入：适用于统计分析场景，需权衡精度与隐私。
• 效果评估：
  • 重识别风险：评估通过组合字段重新识别个体的概率。
  • 可用性：评估脱敏后数据的统计特征与下游分析质量。
  • 合规性：满足相关法律法规与行业标准要求。

数据泄露检测与应急响应流程

• 检测：
  • 日志监控：对敏感键出现频率、异常高流量、错误堆栈外泄进行告警。
  • 访问审计：对管理端与 API 的敏感操作进行审计与回放。
  • 外部扫描：定期扫描公开渠道是否存在泄露数据。
• 响应：
  • 立即止损：下线可疑接口、重置凭据、封禁异常 IP。
  • 溯源分析：基于 request_id 与日志上下文定位泄露点。
  • 修复与复盘：修复漏洞、完善脱敏策略、更新安全基线。
  • 通知与合规：按法规要求进行用户通知与监管报备。

与现有能力的集成建议

• 在业务服务中统一通过日志接口记录上下文：避免直接拼接字符串导致遗漏脱敏。
• 对 API 返回对象在序列化前进行字段级脱敏：结合Str工具类的掩码功能和XSS过滤确保前端显示安全。
• 使用安全栈配置强化会话与响应头：降低跨站与劫持风险。
• 在管理端与 API 端分别配置日志通道与级别：避免过度记录。
• 新增Str工具类集成：
  • 在管理后台展示用户信息时，使用Str::maskPhone()和Str::maskEmail()进行敏感信息隐藏。
  • 在报表导出功能中，对包含个人信息的列应用相应的掩码处理。
  • 在API响应中，对敏感字段进行统一的掩码处理，确保数据安全传输。

章节来源

• core/infra/log/Log.php:289-342
• core/support/Str.php:441-475
• core/infra/security/Xss.php:555-601
• config/security.php:51-87
• _/.api/config/log.php:17-47