后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载本文围绕 HedgeDoc 官方安全配置文档docs/content/references/config/security.md展开系统讲解 HedgeDoc 内置的速率限制机制它如何按认证级别与端点类型分四层限流、如何通过HD_SECURITY_RATE_LIMIT_*环境变量精细调优以及限流触达后返回的 HTTP 429 响应与响应头。读完本文你将能够为自己的 HedgeDoc 实例配置合理的限流策略抵御暴力破解与滥用攻击并理解限流在源码backend/src/security/rate-limiting.ts中的完整执行链路。HedgeDoc 安全配置的入口环境变量与.env文件与 HedgeDoc 的其他配置一样安全相关配置不依赖配置文件而是通过环境变量注入可以直接在启动进程时设置也可以写入项目根目录下的.env文件官方 Docker 容器中为/usr/src/app/.env格式为KEYvalue的键值对例如HD_BASE_URLhttp://localhost:8080 HD_SESSION_SECRETchange_me_in_production HD_SECURITY_RATE_LIMIT_AUTH_MAX60关于.env的完整约定参见 docs/content/references/config/index.md仓库根目录还提供了 .env.example 作为最小配置样例。本文涉及的所有安全配置项均以HD_SECURITY_为前缀由后端在 backend/src/config/security.config.ts 中统一解析、校验。四层分级限流模型按认证级别与端点类型差异化限流HedgeDoc 的速率限制Rate Limiting用于抵御滥用和暴力破解攻击。其核心思路是按请求的认证级别与端点类型应用不同的限制额度共分四层Public API公开 API使用合法 API Token 访问公开 API/api/v2的请求Authenticated已认证已登录用户对应用私有 API/api/private的请求Unauthenticated未认证未登录用户或访客对应用与 API 的请求Auth认证端点对认证端点登录、注册等的请求用于专门防范暴力破解。从源码 backend/src/security/rate-limiting.ts 的getRateLimitConfigByRequest函数可以清晰看到这套分层逻辑的实际判断顺序路径以 /api/private/auth/logout 或 /api/private/monitoring 开头 → 永不限流max Infinity 路径以 /api/private/auth/ 开头 → 应用 auth 层限制 路径以 /api/v2 开头且已登录 → 应用 publicApi 层限制 路径以 /api/private 开头且已登录 → 应用 authenticated 层限制 其余情况 → 应用 unauthenticated 层限制值得注意的是两个内置例外POST /api/private/auth/logout退出登录和/api/private/monitoring/*监控端点永远不会被限流因为频繁登出与监控抓取是正常行为不应被误伤。限流计数的追踪维度按用户 ID 还是按 IP限流计数根据认证状态采用不同的追踪键key已认证请求会话 Session 或 API Token按用户 ID追踪键形如user:userId未认证请求按IP 地址追踪键形如ip:ip。这一逻辑实现在generateRateLimitKeybackend/src/security/rate-limiting.ts优先从会话中读取userId若存在则生成user:前缀的键否则回退到req.ipIP 的判定受 Fastify 的trustProxy配置影响。按用户而非 IP 追踪的好处是同一个 NAT 出口下的多个已登录用户互不干扰也防止攻击者通过频繁更换 IP 绕过以 IP 为维度的限制。限流环境变量详解MAX 与 WINDOW每一层限流都可以通过两个参数配置*_MAX该层级允许的最大请求次数*_WINDOW限流时间窗口单位为秒。官方文档给出的完整变量表如下默认值即 HedgeDoc 出厂配置环境变量默认值说明HD_SECURITY_RATE_LIMIT_PUBLIC_API_MAX150携带 Token 访问公开 API 的最大请求数HD_SECURITY_RATE_LIMIT_PUBLIC_API_WINDOW300公开 API 限流时间窗口秒HD_SECURITY_RATE_LIMIT_AUTHENTICATED_MAX900已认证请求的最大次数HD_SECURITY_RATE_LIMIT_AUTHENTICATED_WINDOW300已认证请求的时间窗口秒HD_SECURITY_RATE_LIMIT_UNAUTHENTICATED_MAX100未认证请求的最大次数HD_SECURITY_RATE_LIMIT_UNAUTHENTICATED_WINDOW300未认证请求的时间窗口秒HD_SECURITY_RATE_LIMIT_AUTH_MAX40认证端点登录/注册的最大尝试次数HD_SECURITY_RATE_LIMIT_AUTH_WINDOW900认证端点限流时间窗口秒HD_SECURITY_RATE_LIMIT_BYPASS无需要绕过限流的 IP 地址逗号分隔列表将*_MAX设为 0等效禁用该层限流官方文档明确指出将某个层级的*_MAX设置为0会等效禁用该层级的限流不推荐在生产环境使用。这一点在源码中有明确对应——getMaxLimitByRequestWithSecurityConfigbackend/src/security/rate-limiting.ts将max 0解释为Infinity即不限速对应的单测见 backend/src/security/rate-limiting.spec.ts。配置值的合法性校验zod 约束所有安全配置项在 backend/src/config/security.config.ts 中通过 zod schema 严格校验*_MAX必须是非负整数.int().nonnegative()*_WINDOW必须是正整数.int().positive()即窗口不能为 0 或负数HD_SECURITY_RATE_LIMIT_BYPASS逗号分隔后被解析为数组每个元素必须是合法 IP.ipv4()或.ipv6()默认值为空数组。一旦配置非法printConfigErrorAndExit会向控制台输出错误信息并以退出码 1 终止进程见 backend/src/config/utils.ts避免带着错误配置带病运行。这些校验行为均有完整的测试覆盖见 backend/src/config/security.config.spec.ts例如MAX为负数、WINDOW为 0、MAX/WINDOW为非整数、BYPASS含非法 IP如999.999.999.999或invalid-ip都会触发报错并process.exit(1)。实战配置示例调优与豁免场景一收紧认证端点限流防暴力破解默认 900 秒内允许 40 次认证尝试。如果希望更激进地防范暴力破解可以缩短窗口HD_SECURITY_RATE_LIMIT_AUTH_MAX20 HD_SECURITY_RATE_LIMIT_AUTH_WINDOW600场景二放宽内部已认证用户的调用频率若内部工具通过已登录会话高频调用私有 API可单独提高AUTHENTICATED层级HD_SECURITY_RATE_LIMIT_AUTHENTICATED_MAX3000 HD_SECURITY_RATE_LIMIT_AUTHENTICATED_WINDOW300场景三豁免内网监控与健康检查 IPHD_SECURITY_RATE_LIMIT_BYPASS接受逗号分隔的 IPv4 / IPv6 列表按源码实现为直接对字符串按逗号split后逐个校验例如HD_SECURITY_RATE_LIMIT_BYPASS127.0.0.1,::1,192.168.1.10该列表最终会作为fastify/rate-limit的allowList传给限流插件见 backend/src/app-init.ts命中列表的 IP 完全不参与限流计数。配置生效与错误表现安全配置在应用启动阶段由 backend/src/config/security.config.ts 读取并校验随setupApp一起装配进 Fastify 实例因此修改环境变量后需要重启 HedgeDoc 后端进程才能生效。配置非法时进程直接以错误信息退出启动日志中会明确指出是哪一个变量、哪一项校验未通过。限流触达时的响应HTTP 429 与限流响应头当某请求超出所在层级的限流额度时服务器返回HTTP 429Too Many Requests并在响应头中附带限流信息X-RateLimit-Limit当前层级允许的请求上限X-RateLimit-Remaining窗口内剩余可用请求数X-RateLimit-Reset限流窗口重置的时间点Retry-After客户端应在多少秒后重试。对应的响应体由buildRateLimitResponsebackend/src/security/rate-limiting.ts构建结构为{ statusCode: 429, error: Too Many Requests, message: Rate limit exceeded. Please try again later (等待时间)., expiresIn: 窗口剩余毫秒数 }单测 backend/src/security/rate-limiting.spec.ts 验证了该响应结构message中会带上具体的等待时长如10 secondsexpiresIn则给出当前请求的 TTL毫秒。客户端如基于 API Token 的脚本应当解析Retry-After并做指数退避重试而不是立即重发。源码级执行链路从请求到限流判定限流能力基于 Fastify 官方插件fastify/rate-limit在 backend/src/app-init.ts 中注册核心参数如下await app.register(fastifyRateLimit, { global: true, // 全局生效 hook: preHandler, // 在 handler 之前执行 cache: 10000, // 最多缓存 10000 个计数键 skipOnError: true, // 出错时不额外计次 keyGenerator: generateRateLimitKey, // user:ID 或 ip:IP max: getMaxLimitByRequestWithSecurityConfig(securityConfig), timeWindow: getTimeWindowByRequestWithSecurityConfig(securityConfig), errorResponseBuilder: buildRateLimitResponse, // 429 响应体 allowList: securityConfig.rateLimit.bypass, // 豁免 IP 列表 enableDraftSpec: true, // 启用 draft 限流响应头规范 });一次请求的完整判定流程可以概括为请求进入preHandler钩子generateRateLimitKey根据会话判定限流键用户 ID 或 IPgetRateLimitConfigByRequest根据请求路径前缀与认证状态选出对应层级publicApi / authenticated / unauthenticated / authlogout 与 monitoring 直接豁免max与timeWindow两个函数按层级返回限流参数窗口从秒换算为毫秒window * 1000见 backend/src/security/rate-limiting.ts若超出额度buildRateLimitResponse生成 429 响应体与限流响应头。完整的层级选择、键生成与豁免逻辑均有单元测试佐证backend/src/security/rate-limiting.spec.ts包括已认证 v2 请求走publicApi限制、未认证 v2 请求走unauthenticated限制、私有 API 走authenticated限制、登录端点走auth限制、logout 与 monitoring 返回Infinity永不限流等断言。总结HedgeDoc 通过fastify/rate-limit实现了覆盖公开 API、已认证、未认证与认证端点四层的差异化限流已登录用户按用户 ID 计数、访客按 IP 计数登录/注册端点以更紧的额度专门对抗暴力破解logout 与监控端点则天然豁免。所有行为都可以通过HD_SECURITY_RATE_LIMIT_*环境变量MAX / WINDOW / BYPASS在不改代码的情况下调整配合 zod 启动期校验与 429 响应头运维者既能在生产环境保持默认安全基线也能按需为特殊场景放开或收紧额度。建议在生产部署前结合自身用户规模与反向代理出口 IP 的实际情况审慎设定四层限额并保留HD_SECURITY_RATE_LIMIT_BYPASS用于监控探针等可信来源。赞分享后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载相关推荐BullMQ 队列速率限制Rate Limiting完全指南Worker 配置、手动限流与 TTL 查询BullMQ 队列速率限制Rate Limiting完全指南Worker 配置、手动限流与 TTL 查询 速率限制Rate Limiting是 Bul后端消息队列任务调度Epic Stack 中的速率限制Rate Limiting基于 express-rate-limit 的分级限流实战指南Epic Stack 中的速率限制Rate Limiting基于 express rate limit 的分级限流实战指南 导读 本文基于 Epic St后端前端开发工具认证鉴权如何用SAGIRI-BOT实现QQ群自动管理入群验证与系统状态监控指南如何用SAGIRI BOT实现QQ群自动管理入群验证与系统状态监控指南 SAGIRI BOT是一款基于Graia Ariadne和Mirai开发的QQ机器人上一篇告别编辑内容丢失milkdown持久化方案全解析localStorage vs 数据库下一篇超全FlutterUnit资源管理指南从assets配置到性能优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考