API Firewall环境变量与apifw.yaml配置完整参考：30+参数逐项讲解-二趣网

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-firewall

API Firewall（Wallarm 开源 API 防火墙）是一款快速、轻量的 API 代理防火墙，核心功能是基于 OpenAPI 规范对请求和响应做双重校验。它的每个配置项都支持三种等价写法：apifw.yaml 配置文件、环境变量（APIFW_前缀）和命令行参数。本文带你逐项读懂 30+ 个参数，一次配通。

配置三件套：apifw.yaml、环境变量、命令行

方式	特点	适用场景
`apifw.yaml`	结构化、可读性好	本地部署、Docker 挂载卷
环境变量	无需落盘、易被容器识别	K8s、Helm 部署
命令行参数	优先级最高、便于调试	临时覆盖单个参数

📌 所有环境变量的键名 = 配置项名转大写 + 下划线，并加APIFW_前缀。例如Mode→APIFW_MODE，URL→APIFW_URL。

全局参数：选择工作模式与日志

参数	环境变量	默认值	说明
`Mode`	`APIFW_MODE`	`PROXY`	运行模式：`PROXY`（代理校验）/`API`（API 校验）/`GRAPHQL`
`LogLevel`	`APIFW_LOG_LEVEL`	`INFO`	日志级别：`TRACEDEBUGINFOWARNINGERROR`
`LogFormat`	`APIFW_LOG_FORMAT`	`TEXT`	日志格式：`TEXT`或`JSON`（方便 ELK 采集）

💡 新手建议：先用DEBUG级别跑一遍，确认无误后切回INFO。

Server 组：监听端口与连接控制

源码定义见internal/config/server.go，共 10 个参数：

参数	环境变量	默认值	说明
`APIHost`	`APIFW_URL`	`http://0.0.0.0:8282`	防火墙监听地址
`HealthAPIHost`	`APIFW_HEALTH_HOST`	`0.0.0.0:9667`	健康检查端口（K8s liveness 用）
`ReadTimeout`	`APIFW_READ_TIMEOUT`	`5s`	读请求超时
`WriteTimeout`	`APIFW_WRITE_TIMEOUT`	`5s`	写响应超时
`ReadBufferSize`	—	`8192`	读缓冲区大小（字节）
`WriteBufferSize`	—	`8192`	写缓冲区大小（字节）
`MaxRequestBodySize`	—	`4194304`	最大请求体 4MB，防大文件打爆内存
`DisableKeepalive`	—	`false`	关闭长连接（调试抓包时有用）
`MaxConnsPerIP`	—	`0`（不限）	单 IP 最大并发连接数
`MaxRequestsPerConn`	—	`0`（不限）	单连接最大请求数

Backend 组：保护的后端 API 怎么连

这是参数最多的一组（源码见internal/config/backend.go），决定流量如何转发到你的真实 API：

参数	默认值	说明
`Backend.URL`	`http://localhost:3000/v1/`	后端 API 根地址
`Backend.RequestHostHeader`	空	转发时替换 Host 头
`Backend.InsecureConnection`	`false`	跳过 TLS 证书校验（自签证书环境）
`Backend.RootCA`	空	自定义根证书路径
`Backend.MaxConnsPerHost`	`512`	与后端的最大并发连接
`Backend.DialTimeout`	`200ms`	建连超时，调低可快速摘除故障节点
`Backend.MaxResponseBodySize`	`0`（不限）	限制从后端读取的响应体大小
`Backend.DeleteAcceptEncoding`	`false`	删除 Accept-Encoding，避免压缩体干扰校验
`Backend.HealthCheckInterval`	`30s`	后端健康检查间隔
`Backend.MaxIdleConnDuration`	`10s`	空闲连接保活时长

🛡️ 令牌校验（Oauth 子组）

参数	默认值	说明
`Oauth.ValidationType`	`JWT`	校验方式：`JWT`或`Introspection`（RFC 7662）
`Oauth.JWT.SignatureAlgorithm`	`RS256`	JWT 签名算法
`Oauth.JWT.PubCertFile`	空	RS 类算法的公钥证书文件
`Oauth.JWT.SecretKey`	空	HS 类算法的密钥
`Oauth.Introspection.Endpoint`	空	内省服务地址
`Oauth.Introspection.RefreshInterval`	`10m`	内省令牌缓存刷新周期

校验模式三参数：BLOCK / LOG_ONLY / DISABLE

这是 API Firewall 最核心的三个开关（定义于internal/config/proxy.go）：

RequestValidation（必填）：请求校验模式
ResponseValidation（必填）：响应校验模式
CustomBlockStatusCode：拦截时返回的状态码，默认403
AddValidationStatusHeader：在响应头标记校验结果，便于灰度观察

✅ 经典灰度路径：先设LOG_ONLY观察日志 → 确认无误后切BLOCK。

其他高频参数：

参数	环境变量	默认值	说明
`APISpecs`	`API_SPECS`	必填	OpenAPI 规范文件路径
`APISpecsCustomHeader`	`API_SPECS_CUSTOM_HEADER`	空	从请求头动态取规范（多租户）
`PassOptionsRequests`	`PASS_OPTIONS`	`false`	放行 CORS 预检请求
`SpecificationUpdatePeriod`	`APIFW_SPECIFICATION_UPDATE_PERIOD`	`0`	热更新规范的周期，如`1m`

ModSecurity WAF 规则接入

在 API 校验之外叠加 OWASP 核心规则集（源码见internal/config/modsec.go）：

参数	环境变量	说明
`ModSecurity.ConfFiles`	`MODSEC_CONF_FILES`	WAF 配置文件列表
`ModSecurity.RulesDir`	`MODSEC_RULES_DIR`	自动加载目录下所有`*.conf`规则
`ModSecurity.RequestValidation`	`MODSEC_REQUEST_VALIDATION`	WAF 请求拦截模式
`ModSecurity.ResponseValidation`	`MODSEC_RESPONSE_VALIDATION`	WAF 响应拦截模式

安全四件套：IP 白名单与 Token 黑名单

参数	默认值	说明
`Denylist.Tokens.File`	空	泄露 Token 黑名单文件（.db）
`Denylist.Tokens.HeaderName`/`CookieName`	空	从哪个头 / Cookie 取 Token 比对
`Denylist.Tokens.TrimBearerPrefix`	`true`	自动剥离`Bearer`前缀
`AllowIP.File`	空	IP 白名单文件
`AllowIP.HeaderName`	空	从自定义头取真实客户端 IP（防 CDN 后 IP 失真）

DNS 缓存与 TLS 证书

源码见internal/config/dns.go与internal/config/config.go：

参数	默认值	说明
`DNS.Nameserver.Host`	系统默认	指定上游 DNS
`DNS.Nameserver.Port`/`Proto`	`53`/`udp`	可改`tcp`防丢包
`DNS.Cache`	`false`	开启后降低解析延迟
`DNS.FetchTimeout`	`1m`	批量拉取缓存超时
`DNS.LookupTimeout`	`1s`	单次解析超时
`TLS.CertsPath`	`certs`	证书目录
`TLS.CertFile`	`localhost.crt`	证书文件名
`TLS.CertKey`	`localhost.key`	私钥文件名

GraphQL 模式专属参数

进入GRAPHQL模式后，以下参数变为必填（源码见internal/config/graphql.go），专门防 GraphQL 常见攻击：

参数	说明
`MaxQueryComplexity`	查询复杂度上限，防组合爆炸
`MaxQueryDepth`	最大嵌套深度，防深层 DoS
`MaxAliasesNum`	最大别名数，防别名轰炸
`NodeCountLimit`	单次查询最大字段节点数
`BatchQueryLimit`	批量查询数量上限
`DisableFieldDuplication`	禁止重复字段
`Introspection`	是否允许 Schema 自省
`Playground`/`PlaygroundPath`	开启内置调试页面及路径
`WSCheckOrigin`/`WSOrigin`	WebSocket 来源白名单校验

API 模式专属参数

API模式不代理流量，只做校验（定义于internal/config/api.go）：

参数	环境变量	默认值	说明
`UnknownParametersDetection`	`APIFW_API_MODE_UNKNOWN_PARAMETERS_DETECTION`	`true`	检测规范外的未知参数
`DBVersion`	`APIFW_API_MODE_DB_VERSION`	`0`	内部规范库版本
`MaxErrorsInResponse`	`APIFW_API_MODE_MAX_ERRORS_IN_RESPONSE`	`0`	响应中最多返回的错误条数

监控与其他参数

参数	环境变量	默认值	说明
`Metrics.Enabled`	`METRICS_ENABLED`	`false`	开启 Prometheus 指标
`Metrics.Host`	`METRICS_HOST`	`0.0.0.0:9010`	指标暴露端口
`Metrics.EndpointName`	`METRICS_ENDPOINT_NAME`	`metrics`	指标路径
`ShadowAPI.ExcludeList`	`SHADOW_API_EXCLUDE_LIST`	`404`	影子 API 检测忽略的状态码
`ShadowAPI.UnknownParametersDetection`	`SHADOW_API_UNKNOWN_PARAMETERS_DETECTION`	`true`	影子 API 未知参数检测
`Endpoints`	—	空	按端点细化校验：`PATH\\|REQ\\|RESP`

API Firewall 开源项目功能总览

完整配置示例速查

完整 PROXY 模式样例（docs/include/apifw-yaml-example.md）：

mode: "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_ONLY"

Docker 环境变量写法参考demo/docker-compose/docker-compose-api-mode.yml：

environment: 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
✅ 生产环境建议MaxConnsPerIP+MaxRequestBodySize双保险，防慢连接与内存耗尽
✅ 上线路径：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），仅供参考

企业官网建设流程全解析