配置字段说明

本页按 .env.example 的分组说明常用字段。复制示例文件后按需修改；留空的密钥类字段表示不启用对应能力。

表中的示例值只用于说明格式，不是推荐值。密码、密钥、加密盐和第三方凭据必须使用随机值，不能沿用默认值或示例值。

conf/runtime.env 由首次运行向导和“运行与升级”页面维护，优先级高于 .env。如果某个字段在向导完成后仍不生效，先检查 runtime.env 是否写入同名配置。

基础运行

变量	说明	示例值
`DATABASE_URL`	控制面数据库连接串。SQLite 使用文件路径；MySQL 使用 `mysql+pymysql://用户:密码@主机:3306/库名`	`sqlite:///./data/waf.db`
`PORT`	控制面服务监听端口。Docker 中容器内部固定为 `8000`，宿主机端口由安装脚本生成	`8015`
`HOST`	控制面监听地址	`0.0.0.0`
`DEBUG_MODE`	调试模式。生产环境保持 `false`，否则会放宽密钥强度校验	`false`
`SYSTEM_VERSION`	后端展示的系统版本号，由发布流程同步	`0.15.8`
`VITE_SYSTEM_VERSION`	前端构建时写入的版本号	`0.15.8`

登录与密钥

变量	说明	示例值
`JWT_SECRET_KEY`	JWT 签名密钥。至少 32 位，且不能使用默认值	`<至少32位随机字符串>`
`JWT_ALGORITHM`	JWT 算法	`HS256`
`ACCESS_TOKEN_EXPIRE_MINUTES`	访问令牌有效期（分钟）	`30`
`REFRESH_TOKEN_EXPIRE_DAYS`	刷新令牌有效期（天）	`7`
`BOOTSTRAP_ADMIN_EMAIL`	初始化管理员邮箱	`admin@example.com`
`BOOTSTRAP_ADMIN_PASSWORD`	初始化管理员密码。首次向导留空；非调试环境显式配置 `change_me` 直接拒启；完成向导后一次性引导密码会清空	空或独立随机密码
`CORS_ORIGINS`	允许跨域的前端来源，逗号分隔。生产环境不要使用 `*`	`http://localhost:5173`
`CONTROL_PLANE_TRUSTED_PROXIES`	可信反向代理地址，用于解析真实客户端 IP	`127.0.0.1,::1`
`CONTROL_PLANE_ALLOWED_HOSTS`	控制面允许的 Host，留空表示不限制	空

品牌与访问验证页

变量	说明	示例值
`BRAND_COMPANY_NAME`	中间校验页显示的公司或产品名称	`HAS-WAF`
`BRAND_LOGO_URL`	校验页 Logo 地址，留空使用默认	空
`BRAND_PRIMARY_COLOR`	校验页主题色	`#2563eb`
`CHALLENGE_PAGE_TITLE`	校验页标题	`正在验证访问安全`
`CHALLENGE_PAGE_DESCRIPTION`	校验页说明文字	`请稍候，验证通过后将自动继续。`
`CHALLENGE_CONTACT_TEXT`	校验页联系信息，可留空	空

限流、任务与备份

变量	说明	示例值
`RATE_LIMIT_DEFAULT`	控制面默认限流，按业务流量调整	按业务调整
`SCHEDULER_ENABLED`	是否启用定时任务：日志采集、证书检查、报表和备份	`true`
`LOG_BACKUP_ENABLED`	是否启用每日日志 ZIP 冷备份	`false`
`LOG_BACKUP_HOUR` / `LOG_BACKUP_MINUTE`	每日备份执行时间，使用 `TIMEZONE`	`2` / `0`
`LOG_BACKUP_RETENTION_DAYS`	ZIP 保留天数	`90`
`LOG_BACKUP_DIR`	ZIP 输出目录	`./data/backups`
`CERT_RENEW_BEFORE_DAYS`	证书提前续签天数	`30`
`LOG_INGEST_INTERVAL_SECONDS`	访问日志采集间隔（秒）	`30`

数据面路径

Docker 部署通常由 Compose 覆盖这些字段；本机部署可按实际安装路径修改。

变量	说明	示例值
`OPENRESTY_NGINX_EXE`	OpenResty 的 nginx 可执行文件	Windows 安装路径
`OPENRESTY_PREFIX`	OpenResty 安装根目录	Windows 安装目录
`WAF_PROJECT_ROOT`	WAF 项目根目录	`.`
`WAF_TRUSTED_PROXY_CIDRS`	数据面可信前置代理，多个 IP/CIDR 逗号分隔；禁止 `0.0.0.0/0`	空
`WAF_AUTO_TRUST_CONTAINER_GATEWAY`	Docker 中自动信任当前容器默认网关，避免所有访客被识别为网关 IP	`true`
`WAF_NGINX_CONF`	Nginx 主配置路径	`./conf/nginx.conf`
`WAF_CONFIG_JSON`	策略配置文件路径	`./conf/waf_config.json`
`WAF_RULES_JSON`	规则文件路径	`./conf/waf_rules.json`
`WAF_LOG_DIR`	访问与拦截日志目录	`./logs`
`WAF_CERTS_DIR`	证书目录	`./certs`
`WAF_UPSTREAM_CA_BUNDLE`	HTTPS 回源使用的 CA PEM 包，留空使用内置 CA	空
`WAF_PUBLIC_CNAME_TARGET`	对外 CNAME 目标，可选	空

数据面安全令牌

变量	说明	示例值
`WAF_ANTI_REPLAY_SECRET`	防重放签名密钥，至少 32 位，必须独立	`<独立随机字符串>`
`WAF_CHALLENGE_SECRET`	浏览器验证签名密钥，至少 32 位	`<独立随机字符串>`
`WAF_CHALLENGE_PROOF_DIFFICULTY`	工作量证明难度，按业务与客户端性能调整	按业务调整
`WAF_CHALLENGE_COOKIE_PATH`	验证通行 Cookie 作用域，建议收敛到业务根路径	`/`
`WAF_STATIC_SITES_ROOT`	静态站点资源根目录，Docker 中建议挂载持久化卷	`./static-sites`

以上密钥必须使用互不相同的随机值，不要复用、留空或从示例复制。

内部字段

以下字段由安装脚本或首次向导生成，仅用于本机组件间通信，通常不需要手工修改：

变量	说明
`WAF_ADMIN_TOKEN`	内部管理接口鉴权令牌，随机生成，不要复用其他密钥
`WAF_INTERNAL_TOKEN`	控制面内部代理鉴权令牌，随机生成，不要复用其他密钥
`NGINX_STATUS_URL`	OpenResty 状态页地址，仅本机访问；Docker 部署固定为 `5233` 端口

控制台地图

变量	说明
`WAF_AMAP_KEY`	高德地图 Web JS API Key；留空不显示地图
`WAF_AMAP_SECURITY_JS_CODE`	高德地图安全密钥
`WAF_GEO_SERVER_LNG` / `WAF_GEO_SERVER_LAT`	控制台飞线图起点经纬度

Redis

变量	说明	示例值
`REDIS_HOST`	Redis 地址。单容器部署可填 `host.docker.internal` 或内网地址	`127.0.0.1`
`REDIS_PORT`	Redis 端口	`6379`
`REDIS_DB`	Redis 数据库编号	`0`
`REDIS_PASSWORD`	Redis 密码。生产环境应启用密码；单容器部署连接外部 Redis 时必须填写	`<强密码>`

ClickHouse

变量	说明	示例值
`CLICKHOUSE_HOST`	ClickHouse 地址	`127.0.0.1`
`CLICKHOUSE_PORT`	ClickHouse HTTP 端口	`8123`
`CLICKHOUSE_USER`	ClickHouse 用户。默认用户仅适合本地测试，生产建议独立账号	`default`
`CLICKHOUSE_PASSWORD`	ClickHouse 密码。生产环境必须设置	`<强密码>`
`CLICKHOUSE_DATABASE`	日志数据库名	`has_waf`
`CLICKHOUSE_LOG_RETENTION_DAYS`	日志保留天数	`30`
`CLICKHOUSE_CONNECT_TIMEOUT_SECONDS`	建连超时（秒）	`2`
`CLICKHOUSE_SEND_RECEIVE_TIMEOUT_SECONDS`	请求超时（秒）	`30`
`CLICKHOUSE_FAILURE_COOLDOWN_SECONDS`	故障后的快速失败冷却时间（秒）	`30`
`CLICKHOUSE_FALLBACK_QUEUE_FILE`	降级队列文件；留空使用持久化配置目录下的默认文件	空
`CLICKHOUSE_FALLBACK_STATUS_FILE`	降级状态文件；留空使用默认路径	空
`CLICKHOUSE_FALLBACK_FLUSH_BATCH_SIZE`	每次冲刷批量条数	`500`
`CLICKHOUSE_FALLBACK_FLUSH_LIMIT`	每次冲刷上限	`5000`

选择 SQLite 日志存储时，使用 LOG_STORAGE_BACKEND=sqlite 和 SQLITE_LOG_DATABASE_PATH，不需要连接 ClickHouse。

时区与日报

变量	说明	示例值
`TZ`	系统时区	`Asia/Shanghai`
`DAILY_REPORT_CRON`	每日报表任务，`分时日月周`，使用 UTC	`5 0 * * *`
`DAILY_REPORT_BACKFILL_DAYS`	启动时补跑最近 N 天缺失日报，`0` 表示不补跑	`7`
`DAILY_REPORT_TOP_LIMIT`	Top 榜单条数	`20`

控制面 HTTPS 与 OpenResty

变量	说明	示例值
`CONTROL_PLANE_HTTPS_ENABLED`	控制面是否启用 HTTPS	`false`
`WAF_PUBLIC_IP`	WAF 对外公网 IP，用于生成站点和证书信息	`127.0.0.1`
`CONTROL_PLANE_OPENRESTY_ENABLED`	是否允许控制面管理 OpenResty	`false`

威胁情报与风险评分

变量	说明	示例值
`ABUSEIPDB_API_KEY`	AbuseIPDB API Key；免费账号有限速	空
`ABUSEIPDB_BASE_URL`	AbuseIPDB 接口地址	`https://api.abuseipdb.com/api/v2`
`ABUSEIPDB_TIMEOUT_SECONDS`	请求超时（秒）	`3`
`ABUSEIPDB_CACHE_TTL_SECONDS`	查询缓存时间（秒）	`21600`
`ABUSEIPDB_JOB_INTERVAL_SECONDS`	后台查询间隔（秒）	`600`
`ABUSEIPDB_GLOBAL_MIN_INTERVAL_SECONDS`	全局最小请求间隔（秒）	`45`
`ABUSEIPDB_COOLDOWN_SECONDS`	失败冷却时间（秒）	`600`
`ABUSEIPDB_MAX_REQUESTS_PER_RUN`	每轮最多请求数	`2`
`ABUSEIPDB_SUSPICIOUS_WINDOW_MINUTES`	可疑 IP 统计窗口（分钟）	`60`
`ABUSEIPDB_SUSPICIOUS_LIMIT`	每轮最多处理的候选 IP 数	`500`
`ABUSEIPDB_MIN_BLOCKED_TO_QUERY`	至少被拦截多少次后才查询，按业务调整	按业务调整
`ABUSEIPDB_AUTO_BAN_SCORE`	自动封禁的风险分阈值，按业务调整	按业务调整
`ABUSEIPDB_AUTO_BAN_MIN_ATTACKS`	自动封禁所需最少攻击次数，按业务调整	按业务调整
`ABUSEIPDB_AUTO_BAN_TTL_SECONDS`	自动封禁时长（秒）	`86400`

AI 规则建议

变量	说明	示例值
`OPENAI_BASE_URL`	兼容 OpenAI 的接口地址	`https://api.openai.com`
`OPENAI_API_KEY`	接口密钥；留空不调用	空
`OPENAI_MODEL`	模型名称	`gpt-4o-mini`
`OPENAI_TIMEOUT_SECONDS`	请求超时（秒）	`120`
`OPENAI_MAX_ITEMS_PER_CALL`	单次最多处理条数	`50`
`THREAT_INTEL_AI_REVIEW_ENABLED`	是否启用威胁情报 AI 复核	`false`
`THREAT_INTEL_AI_REVIEW_INTERVAL_SECONDS`	复核任务间隔（秒）	`900`
`THREAT_INTEL_AI_REVIEW_BATCH_SIZE`	每批复核条数	`20`
`THREAT_INTEL_AI_REVIEW_MIN_CONFIDENCE`	采纳建议的最低置信度，按业务调整	按业务调整
`THREAT_INTEL_AI_REVIEW_BLOCK_TTL_SECONDS`	AI 建议封禁时长（秒）	`86400`

地理服务

变量	说明
`APIHZ_GEO_ID` / `APIHZ_GEO_KEY` / `APIHZ_GEO_TD`	APIHZ 地理信息服务凭据
`APIHZ_GEO_BASE_URL`	地理服务接口地址

指纹与证书

变量	说明	示例值
`JA4_SANDBOX_WEBHOOK_SECRET`	沙箱回传 Webhook 校验密钥，留空不校验	空
`ACME_DIRECTORY_URL`	ACME 服务目录	`https://acme.litessl.com/v2`
`ACME_EAB_KID` / `ACME_EAB_HMAC_KEY`	ACME 外部账户凭据	空
`ACME_ACCOUNT_ENC_KEY`	ACME 账户加密密钥，至少 32 位	`<至少32位随机字符串>`
`ALIDNS_ACCESS_KEY_ID` / `ALIDNS_ACCESS_KEY_SECRET`	阿里云 DNS API 凭据	空

HAS-WAF云

变量	说明	示例值
`CLOUD_CONTROL_URL`	云控服务地址	`https://has-waf-cloud.haser.top`
`CLOUD_CONTROL_ENABLED`	云控总开关	`true`
`CLOUD_SYNC_INTERVAL_SECONDS`	资源拉取基础间隔（秒）	`300`
`CLOUD_PUSH_ENABLED`	是否允许云端下行推送	`false`
`CLOUD_RULES_ENABLED`	是否接收规则同步	`true`
`CLOUD_FINGERPRINTS_ENABLED`	是否接收指纹同步	`true`
`CLOUD_IP_INTEL_ENABLED`	是否接收 IP 情报同步	`true`
`CLOUD_SHARE_ATTACK_IP_ENABLED`	是否共享本地攻击 IP 情报	`false`
`CLOUD_SHARE_BROWSER_FINGERPRINT_ENABLED`	是否共享浏览器指纹情报	`false`
`CLOUD_AUTO_REGISTER`	启动时是否自动注册节点	`false`
`CLOUD_REPORT_INTERVAL_SECONDS`	聚合报表上报间隔（秒）	`900`
`CLOUD_REPORT_IP_SALT`	本地 Top IP 脱敏密钥，必须替换为随机值	`<独立随机字符串>`
`CLOUD_CREDENTIALS_ENC_SALT`	本地节点凭证加密盐，生产环境必须替换为随机值	`<独立随机字符串>`
`UPDATE_ALLOWED_IMAGE_PREFIX`	允许的 WAF 镜像前缀	`registry.haser.top`

安装脚本生成的 Docker 字段

以下字段由 install.sh 写入，普通本机部署不需要手工填写：

变量	说明
`HAS_WAF_IMAGE`	WAF 完整镜像地址，包含版本标签
`HAS_WAF_REGISTRY`	WAF 镜像源域名
`HAS_WAF_DEPLOYMENT`	`full` 或 `standalone`，更新脚本据此选择 Compose 文件
`HAS_WAF_DATABASE`	`sqlite` 或 `mysql`
`HAS_WAF_UI_PORT`	控制台宿主机端口
`HAS_WAF_HTTP_PORT`	WAF HTTP 宿主机端口
`HAS_WAF_HTTPS_PORT`	WAF HTTPS 宿主机端口
`HAS_WAF_SITE_PORT_START` / `HAS_WAF_SITE_PORT_END`	站点端口范围
`SETUP_ACCESS_TOKEN`	首次设置向导使用的初始化令牌
`REDIS_IMAGE` / `CLICKHOUSE_IMAGE` / `MYSQL_IMAGE`	全量部署使用的中间件镜像
`COMPOSE_PROFILES`	全量部署选择 MySQL 时为 `mysql`
`MYSQL_PASSWORD` / `MYSQL_ROOT_PASSWORD`	全量部署 MySQL 的应用用户密码和 root 密码

修改后的生效方式

修改 .env 或 runtime.env 后重启 WAF 容器或服务。
首次向导会维护 runtime.env；同一字段在其中存在时以 runtime.env 为准。
修改端口后同步调整防火墙和 Compose 映射；容器内部端口不要改。
证书、密钥、数据库连接串和第三方 API Key 属于敏感信息，不要提交到版本库或写入公开日志。