安全配置

框架把上传大小、远程重定向次数、登录锁定、CSRF、Host 白名单、外部调用超时等安全参数统一收在配置节 Security 下,避免它们以魔法数字散落在代码各处。

全部可选:不配置时使用下表的默认值,行为与引入配置项之前完全一致。

{
  "Security": {
    "MaxUploadSize": 10485760,
    "MaxRemoteRedirects": 3,
    "LoginFailureLimit": 5,
    "LoginLockout": "00:10:00",
    "AllowedHosts": [],
    "AntiforgeryEnabled": true,
    "AntiforgeryHeaderName": "X-CSRF-TOKEN",
    "RateLimitEnabled": true,
    "RateLimitPermitLimit": 60,
    "RateLimitWindow": "00:01:00",
    "ExternalApiTimeout": "00:00:10"
  }
}

配置项

配置项 类型 默认值 生效位置与说明
MaxUploadSize long 10485760(10MB) 单文件最大字节数。HTTP 层(FormOptions.MultipartBodyLengthLimit,multipart 解析前就拦截)与业务层(FileService)共用同一个值,不会出现"HTTP 放行、业务层拒绝"的口径不一致
MaxRemoteRedirects int 3 远程图片下载(编辑器保存远程图片、封面定时下载)允许的最大重定向次数
LoginFailureLimit int 5 连续登录失败多少次后锁定账号。非正值视为误配置,回退到默认值
LoginLockout TimeSpan 00:10:00 登录锁定持续时间。非正值视为误配置,回退到默认值
AllowedHosts string[] [] 允许访问的 Host 白名单。支持精确匹配 example.com、带端口 example.com:8080、通配子域 *.example.com;为空表示不限制,* 表示全部放行。不在白名单的请求直接返回 400
AntiforgeryEnabled bool true 是否启用 CSRF 校验。关闭后框架标记的写接口不再校验 Antiforgery 令牌(不推荐)
AntiforgeryHeaderName string X-CSRF-TOKEN 无 Cookie 场景(如富文本编辑器的 JS 上传)存放 Antiforgery 令牌的请求头名称
RateLimitEnabled bool true 是否启用匿名接口限流。当前由微信扩展的匿名接口消费(登录换 openid、数据解密、二维码)
RateLimitPermitLimit int 60 限流阈值的全局收紧上限:与各端点自身阈值取较小值,只会更严格,不会放宽端点安全上限。非正值视为"未配置"
RateLimitWindow TimeSpan 00:01:00 限流窗口长度。非正值视为"未配置",回退到 1 分钟
ExternalApiTimeout TimeSpan 00:00:10 外部接口(微信等第三方接口)调用超时时间。框架自身的图片下载客户端超时固定为 30 秒,不受此项影响

几点说明

  • 多租户部署务必配置 AllowedHosts:租户是按请求 Host 解析的,而 Host 头由客户端控制;不做白名单校验,攻击者可以伪造 Host 切到别的租户的库
  • 上传大小是两层、但同源:HTTP 层在 multipart 解析前拦截,业务层再校验一次,两处读的是同一个 MaxUploadSize,改一处即可
  • CSRF 只保护框架标记的接口:宿主项目自己的接口没有标记,一律放行;校验失败统一返回 400,不会冒泡成 500
  • 登录锁定不会被写错配置锁死:LoginFailureLimit / LoginLockout 写成 0 或负数时回退到默认值
  • 限流只能收紧不能放宽:RateLimitPermitLimit 调小会让所有微信匿名接口一起收紧;调大不会放宽端点自身的上限(例如二维码接口 10 次/分钟是防止耗尽 access_token 配额的红线)
  • TimeSpan 写法:"00:10:00"(时:分:秒)、"1.00:00:00"(天.时:分:秒)

相关文档

  • 文件管理 — 上传、目录分组、图片处理限制
  • 多租户 — 租户隔离与 Host 白名单
  • 部署上线 — Nginx、HTTPS、Windows 服务等生产部署