API Firewall环境变量与apifw.yaml配置完整参考30参数逐项讲解【免费下载链接】api-firewallFast and light-weight API proxy firewall for request and response validation by OpenAPI specs.项目地址: https://gitcode.com/gh_mirrors/ap/api-firewallAPI FirewallWallarm 开源 API 防火墙是一款快速、轻量的 API 代理防火墙核心功能是基于 OpenAPI 规范对请求和响应做双重校验。它的每个配置项都支持三种等价写法apifw.yaml 配置文件、环境变量APIFW_前缀和命令行参数。本文带你逐项读懂 30 个参数一次配通。配置三件套apifw.yaml、环境变量、命令行方式特点适用场景apifw.yaml结构化、可读性好本地部署、Docker 挂载卷环境变量无需落盘、易被容器识别K8s、Helm 部署命令行参数优先级最高、便于调试临时覆盖单个参数 所有环境变量的键名 配置项名转大写 下划线并加APIFW_前缀。例如Mode→APIFW_MODEURL→APIFW_URL。全局参数选择工作模式与日志参数环境变量默认值说明ModeAPIFW_MODEPROXY运行模式PROXY代理校验/APIAPI 校验/GRAPHQLLogLevelAPIFW_LOG_LEVELINFO日志级别TRACEDEBUGINFOWARNINGERRORLogFormatAPIFW_LOG_FORMATTEXT日志格式TEXT或JSON方便 ELK 采集 新手建议先用DEBUG级别跑一遍确认无误后切回INFO。Server 组监听端口与连接控制源码定义见internal/config/server.go共 10 个参数参数环境变量默认值说明APIHostAPIFW_URLhttp://0.0.0.0:8282防火墙监听地址HealthAPIHostAPIFW_HEALTH_HOST0.0.0.0:9667健康检查端口K8s liveness 用ReadTimeoutAPIFW_READ_TIMEOUT5s读请求超时WriteTimeoutAPIFW_WRITE_TIMEOUT5s写响应超时ReadBufferSize—8192读缓冲区大小字节WriteBufferSize—8192写缓冲区大小字节MaxRequestBodySize—4194304最大请求体 4MB防大文件打爆内存DisableKeepalive—false关闭长连接调试抓包时有用MaxConnsPerIP—0不限单 IP 最大并发连接数MaxRequestsPerConn—0不限单连接最大请求数Backend 组保护的后端 API 怎么连这是参数最多的一组源码见internal/config/backend.go决定流量如何转发到你的真实 API参数默认值说明Backend.URLhttp://localhost:3000/v1/后端 API 根地址Backend.RequestHostHeader空转发时替换 Host 头Backend.InsecureConnectionfalse跳过 TLS 证书校验自签证书环境Backend.RootCA空自定义根证书路径Backend.MaxConnsPerHost512与后端的最大并发连接Backend.DialTimeout200ms建连超时调低可快速摘除故障节点Backend.MaxResponseBodySize0不限限制从后端读取的响应体大小Backend.DeleteAcceptEncodingfalse删除 Accept-Encoding避免压缩体干扰校验Backend.HealthCheckInterval30s后端健康检查间隔Backend.MaxIdleConnDuration10s空闲连接保活时长️ 令牌校验Oauth 子组参数默认值说明Oauth.ValidationTypeJWT校验方式JWT或IntrospectionRFC 7662Oauth.JWT.SignatureAlgorithmRS256JWT 签名算法Oauth.JWT.PubCertFile空RS 类算法的公钥证书文件Oauth.JWT.SecretKey空HS 类算法的密钥Oauth.Introspection.Endpoint空内省服务地址Oauth.Introspection.RefreshInterval10m内省令牌缓存刷新周期校验模式三参数BLOCK / LOG_ONLY / DISABLE这是 API Firewall 最核心的三个开关定义于internal/config/proxy.goRequestValidation必填请求校验模式ResponseValidation必填响应校验模式CustomBlockStatusCode拦截时返回的状态码默认403AddValidationStatusHeader在响应头标记校验结果便于灰度观察✅ 经典灰度路径先设LOG_ONLY观察日志 → 确认无误后切BLOCK。其他高频参数参数环境变量默认值说明APISpecsAPI_SPECS必填OpenAPI 规范文件路径APISpecsCustomHeaderAPI_SPECS_CUSTOM_HEADER空从请求头动态取规范多租户PassOptionsRequestsPASS_OPTIONSfalse放行 CORS 预检请求SpecificationUpdatePeriodAPIFW_SPECIFICATION_UPDATE_PERIOD0热更新规范的周期如1mModSecurity WAF 规则接入在 API 校验之外叠加 OWASP 核心规则集源码见internal/config/modsec.go参数环境变量说明ModSecurity.ConfFilesMODSEC_CONF_FILESWAF 配置文件列表ModSecurity.RulesDirMODSEC_RULES_DIR自动加载目录下所有*.conf规则ModSecurity.RequestValidationMODSEC_REQUEST_VALIDATIONWAF 请求拦截模式ModSecurity.ResponseValidationMODSEC_RESPONSE_VALIDATIONWAF 响应拦截模式安全四件套IP 白名单与 Token 黑名单参数默认值说明Denylist.Tokens.File空泄露 Token 黑名单文件.dbDenylist.Tokens.HeaderName/CookieName空从哪个头 / Cookie 取 Token 比对Denylist.Tokens.TrimBearerPrefixtrue自动剥离Bearer前缀AllowIP.File空IP 白名单文件AllowIP.HeaderName空从自定义头取真实客户端 IP防 CDN 后 IP 失真DNS 缓存与 TLS 证书源码见internal/config/dns.go与internal/config/config.go参数默认值说明DNS.Nameserver.Host系统默认指定上游 DNSDNS.Nameserver.Port/Proto53/udp可改tcp防丢包DNS.Cachefalse开启后降低解析延迟DNS.FetchTimeout1m批量拉取缓存超时DNS.LookupTimeout1s单次解析超时TLS.CertsPathcerts证书目录TLS.CertFilelocalhost.crt证书文件名TLS.CertKeylocalhost.key私钥文件名GraphQL 模式专属参数进入GRAPHQL模式后以下参数变为必填源码见internal/config/graphql.go专门防 GraphQL 常见攻击参数说明MaxQueryComplexity查询复杂度上限防组合爆炸MaxQueryDepth最大嵌套深度防深层 DoSMaxAliasesNum最大别名数防别名轰炸NodeCountLimit单次查询最大字段节点数BatchQueryLimit批量查询数量上限DisableFieldDuplication禁止重复字段Introspection是否允许 Schema 自省Playground/PlaygroundPath开启内置调试页面及路径WSCheckOrigin/WSOriginWebSocket 来源白名单校验API 模式专属参数API模式不代理流量只做校验定义于internal/config/api.go参数环境变量默认值说明UnknownParametersDetectionAPIFW_API_MODE_UNKNOWN_PARAMETERS_DETECTIONtrue检测规范外的未知参数DBVersionAPIFW_API_MODE_DB_VERSION0内部规范库版本MaxErrorsInResponseAPIFW_API_MODE_MAX_ERRORS_IN_RESPONSE0响应中最多返回的错误条数监控与其他参数参数环境变量默认值说明Metrics.EnabledMETRICS_ENABLEDfalse开启 Prometheus 指标Metrics.HostMETRICS_HOST0.0.0.0:9010指标暴露端口Metrics.EndpointNameMETRICS_ENDPOINT_NAMEmetrics指标路径ShadowAPI.ExcludeListSHADOW_API_EXCLUDE_LIST404影子 API 检测忽略的状态码ShadowAPI.UnknownParametersDetectionSHADOW_API_UNKNOWN_PARAMETERS_DETECTIONtrue影子 API 未知参数检测Endpoints—空按端点细化校验PATH\|REQ\|RESPAPI Firewall 开源项目功能总览完整配置示例速查完整 PROXY 模式样例docs/include/apifw-yaml-example.mdmode: PROXY RequestValidation: BLOCK ResponseValidation: LOG_ONLY # 灰度期先只记日志 CustomBlockStatusCode: 403 APISpecs: openapi.yaml PassOptionsRequests: true Server: APIHost: http://0.0.0.0:8282 HealthAPIHost: 0.0.0.0:9667 Backend: URL: http://localhost:3000/v1/ DialTimeout: 200ms HealthCheckInterval: 30s TLS: CertsPath: certs CertFile: localhost.crt CertKey: localhost.key ModSecurity: RulesDir: /etc/coraza RequestValidation: LOG_ONLYDocker 环境变量写法参考demo/docker-compose/docker-compose-api-mode.ymlenvironment: APIFW_MODE: api APIFW_URL: http://0.0.0.0:8080 APIFW_HEALTH_HOST: 0.0.0.0:9667 APIFW_LOG_LEVEL: info新手避坑清单⚠️RequestValidation与ResponseValidation是必填项漏写会直接启动失败⚠️GRAPHQL模式下复杂度、深度等 6 个限制参数均为必填✅ 后端用自签证书时记得同时设置InsecureConnection: true或提供RootCA✅ 生产环境建议MaxConnsPerIPMaxRequestBodySize双保险防慢连接与内存耗尽✅ 上线路径LOG_ONLY观察 1~2 天 →BLOCK全量拦截掌握以上 30 参数你就能把 API Firewall 从能跑调到跑得好。先按官方示例跑通 PROXY 模式再按业务逐个叠加 WAF、白名单与监控配置即可。【免费下载链接】api-firewallFast and light-weight API proxy firewall for request and response validation by OpenAPI specs.项目地址: https://gitcode.com/gh_mirrors/ap/api-firewall创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考