# 安全加固

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [composer.json](file://composer.json)
- [public/.htaccess](file://public/.htaccess)
- [public/themes/.htaccess](file://public/themes/.htaccess)
- [public/themes/.htaccess_apache2.4](file://public/themes/.htaccess_apache2.4)
- [public/upload/.htaccess](file://public/upload/.htaccess)
- [public/api.php](file://public/api.php)
- [public/index.php](file://public/index.php)
- [.example.env](file://.example.env)
- [.workflow/pipeline-20240224.yml](file://.workflow/pipeline-20240224.yml)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能与安全注意事项](#性能与安全注意事项)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向 ThinkCMF 的生产部署与运维团队，围绕“文件与目录权限”、“防火墙与网络层防护”、“Web 服务器安全规则（.htaccess）”、“HTTPS 与传输安全”、“应用层安全（CSRF、输入校验、会话）”、“安全审计与监控”、“漏洞扫描与应急响应”等维度，提供可落地的安全加固方案。内容基于仓库中的公开文件与常见实践进行整理，帮助您构建符合生产标准的安全基线。

## 项目结构
- Web 根目录：public（入口文件位于 public/index.php、public/api.php）
- 应用与数据：app、data
- 第三方依赖：vendor（由 Composer 管理）
- 静态资源与主题：public/static、public/themes、public/upload
- 环境配置：.env（示例文件 .example.env）

```mermaid
graph TB
client["客户端浏览器"] --> web["Web 服务器(Apache/Nginx)"]
web --> public_index["public/index.php"]
web --> public_api["public/api.php"]
public_index --> app["应用层(app)"]
public_api --> api_ns["API 命名空间(api)"]
app --> data_dir["数据目录(data)"]
app --> vendor_dir["第三方库(vendor)"]
public_index --> static_res["静态资源(public/static)"]
public_index --> themes["主题(public/themes)"]
public_index --> upload_dir["上传(public/upload)"]
```

图表来源
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [composer.json:46-56](file://composer.json#L46-L56)

章节来源
- [README.md:96-101](file://README.md#L96-L101)
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [composer.json:46-56](file://composer.json#L46-L56)

## 核心组件
- Web 入口与路由
  - public/index.php：前端入口，负责加载自动加载器并执行 HTTP 应用。
  - public/api.php：API 命名空间入口，定义 API 命名空间后加载自动加载器并执行 HTTP 应用。
- 服务器端安全规则
  - public/.htaccess：启用重写、隐藏真实入口、传递授权头等。
  - public/themes/.htaccess 与 public/themes/.htaccess_apache2.4：限制主题目录内敏感文件访问。
  - public/upload/.htaccess：限制上传目录内危险文件类型访问。
- 环境与配置
  - .example.env：示例环境变量文件，包含调试开关、数据库与认证等示例键位。
- 依赖与自动加载
  - composer.json：PSR-4 自动加载映射，定义应用、API、插件与主题命名空间。

章节来源
- [public/index.php:1-37](file://public/index.php#L1-L37)
- [public/api.php:1-41](file://public/api.php#L1-L41)
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/themes/.htaccess:1-4](file://public/themes/.htaccess#L1-L4)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)
- [.example.env:1-1](file://.example.env#L1-L1)
- [composer.json:46-56](file://composer.json#L46-L56)

## 架构总览
下图展示从客户端到应用层的关键交互路径，并标注安全控制点（如重写、授权头、命名空间隔离、目录访问控制）。

```mermaid
sequenceDiagram
participant C as "客户端"
participant W as "Web服务器"
participant I as "public/index.php"
participant A as "App(HTTP)"
participant D as "应用层(app)"
C->>W : "HTTP 请求"
W->>I : "根据 .htaccess 重写到入口"
I->>A : "加载自动加载器并执行"
A->>D : "路由与控制器处理"
D-->>A : "业务响应"
A-->>W : "响应对象"
W-->>C : "返回响应"
```

图表来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/index.php:27-36](file://public/index.php#L27-L36)
- [composer.json:46-56](file://composer.json#L46-L56)

## 详细组件分析

### 文件与目录权限设置
- Web 根目录（public）
  - 仅允许 Web 服务器读取与执行；禁止直接写入。
  - 上传目录（public/upload）应限制执行能力，避免可执行脚本被执行。
  - 主题目录（public/themes）应限制对敏感文件的直接访问。
- 缓存与日志目录（data）
  - data 目录用于存放应用配置、缓存与日志等，需确保仅应用进程可写，禁止 Web 可写。
  - 建议将 data 目录置于 Web 根之外或通过符号链接指向受控位置。
- 运维建议
  - 使用最小权限原则：Web 用户仅能读取 public，不能写入。
  - 对 data 目录设置严格属主与权限，避免被外部读取或覆盖。
  - 定期审计目录权限与文件属主，确保与安全策略一致。

章节来源
- [README.md:96-101](file://README.md#L96-L101)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)
- [public/themes/.htaccess:1-4](file://public/themes/.htaccess#L1-L4)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)

### 防火墙与网络层防护
- 本地防火墙（iptables）
  - 仅开放必要端口：TCP 80、443；其他端口默认拒绝。
  - 限制来源网段：仅允许特定管理网段访问 SSH/后台。
  - 记录拒绝流量：便于审计与异常检测。
- 云厂商安全组
  - 仅放行 80/443 至 Web 实例。
  - 限制数据库端口仅对内网放行。
  - 定期复核规则，移除过期规则。
- 传输层安全
  - 强制使用 TLS 1.2+，禁用弱加密套件。
  - 启用 HSTS（严格传输安全），提升抗降级与会话劫持能力。

章节来源
- [README.md:84-94](file://README.md#L84-L94)

### Web 服务器安全规则（.htaccess）
- 入口隐藏与重写
  - 通过 public/.htaccess 将未命中文件/目录的请求重写至入口文件，隐藏真实路径。
  - 传递授权头，避免代理场景丢失认证信息。
- 主题与上传目录保护
  - public/themes/.htaccess 与 .htaccess_apache2.4：拒绝对 html/php/json 等敏感文件的直接访问。
  - public/upload/.htaccess：拒绝对 html/php 等可执行文件类型的直接访问。
- 建议补充
  - 在 Apache 2.4+ 环境优先使用新版语法（.htaccess_apache2.4）。
  - 结合目录访问控制模块，限制 .env、.git、备份文件等敏感路径。

章节来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/themes/.htaccess:1-4](file://public/themes/.htaccess#L1-L4)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)

### HTTPS 配置与传输安全
- 证书安装
  - 使用受信任 CA 的证书，优先选择带中间证书链的完整证书包。
  - 证书私钥仅保留于受控服务器，权限最小化。
- 密码套件与协议
  - 禁用 SSLv2/3、TLS 1.0/1.1；仅启用 TLS 1.2/1.3。
  - 采用现代密码套件集合，避免已知弱套件。
- HSTS 头设置
  - 启用 Strict-Transport-Security，设置合理 max-age，支持 includeSubDomains 与 preload（如适用）。
- OCSP Stapling
  - 启用证书状态在线验证 stapling，降低客户端验证延迟与隐私泄露风险。
- 会话安全
  - 强制 HTTPS 下的 SameSite Cookie，避免 CSRF 与会话劫持。
  - 设置 HttpOnly、Secure 属性，减少 XSS 与会话泄露风险。

章节来源
- [README.md:84-94](file://README.md#L84-L94)

### 应用层安全措施
- CSRF 防护
  - ThinkCMF 后台对非 GET 请求强制携带 Token。确保表单与 AJAX 请求均附带令牌并在服务端校验。
- 输入验证与输出编码
  - 对所有用户输入进行白名单校验与长度限制。
  - 输出时使用框架提供的转义机制，防止 XSS。
- 会话管理
  - 使用安全的会话存储（如 Redis/Memcached），设置合理的超时与滑动过期。
  - 登录成功后更换会话 ID，避免固定会话攻击。
- API 安全
  - API 命名空间入口（public/api.php）与应用入口（public/index.php）分离，有助于边界控制与访问限制。
  - 对敏感接口实施速率限制与 IP 黑名单。

章节来源
- [README.md:64-70](file://README.md#L64-L70)
- [public/api.php:27-36](file://public/api.php#L27-L36)
- [public/index.php:27-36](file://public/index.php#L27-L36)

### 安全审计与监控
- 日志策略
  - 启用 Web 服务器访问与错误日志，记录异常请求与失败登录。
  - 应用层记录关键操作日志（登录、权限变更、敏感 API 调用）。
- 异常检测
  - 关注高频 404/403、异常 UA、批量探测、SQL 注入特征（如特殊字符、注入关键字）。
  - 配置告警阈值，结合 SIEM 或日志平台进行集中分析。
- 定期巡检
  - 检查 .htaccess 权限与语法，确认未被意外修改。
  - 审计 data 目录权限与敏感文件暴露风险。

章节来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/themes/.htaccess:1-4](file://public/themes/.htaccess#L1-L4)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)

### 漏洞扫描与修复建议
- 组件扫描
  - 使用 OpenSCA 等工具对 vendor 目录进行开源组件漏洞扫描，按分支触发检测任务。
- 代码安全
  - 集成静态分析工具，关注 SQL 注入、XSS、硬编码密钥等高危问题。
- 修复与回滚
  - 制定补丁发布流程，先在测试环境验证，再灰度到生产。
  - 保留快速回滚方案（版本号与配置回退）。
- 应急响应
  - 明确事件分级与处置流程，包括隔离、取证、修复与复盘。
  - 对外披露遵循最小化原则，避免泄露敏感信息。

章节来源
- [.workflow/pipeline-20240224.yml:1-23](file://.workflow/pipeline-20240224.yml#L1-L23)

## 依赖关系分析
- 自动加载与命名空间
  - composer.json 中定义了 app、api、plugins、themes 的命名空间映射，有助于实现入口隔离与职责边界清晰。
- 入口与命名空间
  - public/index.php 与 public/api.php 分别定义不同命名空间，配合 .htaccess 重写，形成清晰的访问边界。

```mermaid
graph LR
composer["composer.json<br/>PSR-4 映射"] --> app_ns["命名空间: app"]
composer --> api_ns["命名空间: api"]
composer --> plugins_ns["命名空间: plugins"]
composer --> themes_ns["命名空间: themes"]
index_entry["public/index.php"] --> app_ns
api_entry["public/api.php"] --> api_ns
```

图表来源
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/index.php:27-36](file://public/index.php#L27-L36)
- [public/api.php:27-36](file://public/api.php#L27-L36)

章节来源
- [composer.json:46-56](file://composer.json#L46-L56)
- [public/index.php:27-36](file://public/index.php#L27-L36)
- [public/api.php:27-36](file://public/api.php#L27-L36)

## 性能与安全注意事项
- 重写与缓存
  - 合理使用 .htaccess 重写，避免过多正则导致性能下降。
  - 对静态资源启用缓存与压缩，减少不必要的动态请求。
- 会话与并发
  - 会话存储应具备高可用与一致性，避免热点节点压力过大。
- 传输安全
  - 强制 HTTPS，启用 HSTS，减少中间人攻击与会话劫持风险。

## 故障排查指南
- 403/404 异常
  - 检查 public/.htaccess 是否正确启用重写与授权头传递。
  - 确认 data 目录权限与属主，避免因权限不足导致的 403。
- 上传失败或被拦截
  - 检查 public/upload/.htaccess 是否阻止了目标文件类型。
- 主题文件无法访问
  - 确认 public/themes/.htaccess 与 .htaccess_apache2.4 的语法与生效环境。
- 环境变量与调试
  - 参考 .example.env 的键位，确保 .env 文件存在且权限正确，避免调试模式在生产开启。

章节来源
- [public/.htaccess:1-15](file://public/.htaccess#L1-L15)
- [public/upload/.htaccess:1-4](file://public/upload/.htaccess#L1-L4)
- [public/themes/.htaccess:1-4](file://public/themes/.htaccess#L1-L4)
- [public/themes/.htaccess_apache2.4:1-3](file://public/themes/.htaccess_apache2.4#L1-L3)
- [.example.env:1-1](file://.example.env#L1-L1)

## 结论
通过“最小权限”、“边界隔离”、“传输加密”、“输入校验”与“持续审计”的综合手段，ThinkCMF 可以在生产环境中达到更高的安全水平。建议将本文的安全加固清单纳入发布流程与日常巡检，形成闭环的安全治理。

## 附录
- 快速检查清单
  - Web 根目录仅允许读取，data 目录仅允许应用进程写入。
  - .htaccess 已启用重写与访问控制，Apache 2.4+ 使用新版语法。
  - 仅开放 80/443，禁用不必要的端口。
  - HTTPS 已启用，TLS 1.2+/现代套件，HSTS 已配置。
  - CSRF 令牌校验与输入校验已启用。
  - 日志与告警已就绪，定期扫描与应急流程已制定。