DefGuard 2.1.1 配置参数详解

目标：系统梳理 DefGuard 2.1.1 Core / Edge / Gateway 三组件的全部运行时配置项（环境变量），说明每一项的含义、默认值与取值范围，并通过「改配置 → 重启 → 验证」的实测回显证明生效方式。部署步骤见《DefGuard 2.1.1 Docker Compose 部署指南》，API 调用见《DefGuard 2.1.1 API 使用详解》。

一、环境信息

本篇在已部署的 DefGuard 2.1.1 实例上实测配置项，环境与部署篇一致：

• Core 版本：defguard 2.1.1+bbc29a1
• Gateway 版本：2.1.0+d3a2e9a
• Edge 版本：2.1.0+34d4a9f
• 数据库：PostgreSQL 18-alpine
• 配置载体：环境变量（.env 文件 + 编排文件 environment 段）

二、前置条件

• 已按部署篇完成四组件编排并启动；
• 知道 docker compose restart <服务> 能让环境变量变更生效；
• 知道 defguard --help 可列出 Core 全部 CLI 选项（同时也是环境变量清单）。

三、参数查看与修改方式

3.1 查看全部可用参数

docker compose exec core /app/defguard --help

实测回显（节选，每个选项都标注了对应的环境变量与默认值）：

      --log-level <LOG_LEVEL>
          [env: DEFGUARD_LOG_LEVEL=] [default: info]
      --database-host <DATABASE_HOST>
          [env: DEFGUARD_DB_HOST=] [default: localhost]
      --database-port <DATABASE_PORT>
          [env: DEFGUARD_DB_PORT=] [default: 5432]
      --http-port <HTTP_PORT>
          [env: DEFGUARD_HTTP_PORT=] [default: 8000]
      --grpc-port <GRPC_PORT>
          [env: DEFGUARD_GRPC_PORT=] [default: 50055]
...

💡 说明：每个参数都同时支持「命令行 --xxx」与「环境变量 DEFGUARD_XXX」两种写法；编排部署用环境变量，命令行调试用 --xxx。

3.2 查看当前生效配置

把日志级别调到 debug，Core 启动时会把完整配置打印到日志（敏感字段已脱敏）：

# docker-compose.yaml 中 core.environment 追加
      DEFGUARD_LOG_LEVEL: debug

重启后查看日志：

docker compose restart core
docker compose logs core | grep "Using config"

实测回显（节选）：

DEBUG  defguard: message=Using config: DefGuardConfig { log_level: "debug",
  database_host: "db", database_port: 5432, database_name: "defguard",
  database_user: "defguard", database_password: SecretBox<str>([REDACTED]),
  http_port: 8000, grpc_port: 50055, ... check_period: Duration(43200s),
  check_period_no_license: Duration(86400s), check_period_renewal_window: Duration(3600s),
  rate_limit_per_second: 0, rate_limit_burst: 0 }

这是验证「某个环境变量是否真的被 Core 读到」的最直接方法——改完值后用 debug 日志核对。验证完记得把 DEFGUARD_LOG_LEVEL 改回 info 或删除，避免日志量过大。

3.3 修改方式与生效

1. 在编排文件对应服务的 environment 段追加或修改变量；
2. 执行 docker compose up -d <服务名>（仅重建该服务）；
3. 用 debug 日志或功能验证确认生效。

四、参数总览

DefGuard 配置分属三个组件，下表按组件归类：

五、Core 参数分类详解

5.1 数据库连接

编排中通过 DEFGUARD_DB_HOST: db 指向同栈的 db 服务。密码与 POSTGRES_PASSWORD 保持一致。

5.2 监听端口

⚠️ 注意：修改 DEFGUARD_HTTP_PORT 后，编排文件的 ports 映射也要同步改（如 "8001:8001"），否则宿主机无法访问。

5.3 密钥与签名

💡 技术拓展：JWT 签名算法不止 HS256。

算法	特点	适用场景
HS256	对称密钥，签名与验签用同一密钥	单体服务、密钥不外泄
RS256	非对称，私钥签名、公钥验签	多方验签、密钥需分发
ES256	椭圆曲线，密钥更短	资源受限场景

DefGuard OIDC 支持 HS256 与 RS256，由 DEFGUARD_OPENID_KEY 的类型决定。

5.4 URL 与外部地址

这些 URL 在首启向导中也可配置，环境变量优先级更高。

5.5 自动采纳

不设置这两项时，需在 Web UI 手工添加 Edge 与 Gateway 并拷贝令牌。

5.6 会话与令牌超时

5.7 Cookie

5.8 限流

💡 技术拓展：限流算法不止令牌桶。

算法	特点	适用场景
令牌桶	允许突发，平均速率受控	API 网关、需容忍短时峰值
漏桶	严格匀速，不允许突发	需绝对平滑的场景
固定窗口	实现简单，边界有突刺	粗粒度限流
滑动窗口	平滑，无边界突刺	精确限流

DefGuard 采用令牌桶，PERSECOND 是速率、BURST 是桶容量。

5.9 统计与清理

5.10 许可检查

开源核心无许可，这些参数影响企业版功能的检查频率。

六、Gateway 参数详解

Gateway 的 WireGuard 行为由以下环境变量控制：

实测 Gateway 配置（来自启动日志）：

Starting Defguard Gateway version 2.1.0+d3a2e9a with configuration:
Config { log_level: "info", grpc_port: 50066, userspace: false,
  stats_period: 10, core_disconnect_grace_period: 30, ifname: "wg0",
  health_port: Some(55003), masquerade: true, cert_dir: "/etc/defguard/certs", ... }

⚠️ 注意：userspace: false 表示当前使用内核态 WireGuard（性能更好）。若宿主内核无 wireguard 模块，需设 DEFGUARD_USPACE=true 回退用户态。

七、Edge 参数详解

Edge（defguard-proxy）的主要参数：

Edge 的 TLS 证书由 Core 在自动采纳时签发，存放在 /etc/defguard/certs。

八、生产配置模板

以下模板适用于「2 核 4 GiB、单节点、内网 HTTP + 前置反向代理终止 TLS」的中小团队场景：

  core:
    environment:
      DEFGUARD_DB_HOST: db
      DEFGUARD_DB_PORT: 5432
      DEFGUARD_DB_NAME: defguard
      DEFGUARD_DB_USER: defguard
      DEFGUARD_DB_PASSWORD: ${DEFGUARD_DB_PASSWORD}
      DEFGUARD_SECRET_KEY: ${DEFGUARD_SECRET_KEY}
      DEFGUARD_OPENID_KEY: ${DEFGUARD_OPENID_KEY}
      DEFGUARD_URL: https://defguard.example.com
      DEFGUARD_ENROLLMENT_URL: https://enroll.example.com
      DEFGUARD_ADOPT_EDGE: "edge:50051"
      DEFGUARD_ADOPT_GATEWAY: "gateway:50066"
      DEFGUARD_SESSION_TIMEOUT: "24h"
      DEFGUARD_RATELIMIT_PERSECOND: 10
      DEFGUARD_RATELIMIT_BURST: 20
      DEFGUARD_LOG_LEVEL: info

  gateway:
    environment:
      DEFGUARD_STATS_PERIOD: 10
      HEALTH_PORT: 55003
      DEFGUARD_MASQUERADE: "false"

关键说明：

• DEFGUARD_SECRET_KEY 与 DEFGUARD_OPENID_KEY 务必固定（用 openssl rand -hex 32 生成），否则重启后所有会话与 OIDC 令牌失效；
• 前置反向代理终止 TLS 时，DEFGUARD_COOKIE_INSECURE 保持默认（false），由代理把 HTTPS 转发到 Core 的 HTTP；
• DEFGUARD_MASQUERADE: "false" 配合 ACL 做最小权限放行，避免 VPN 客户端能访问网关所在主机的所有网络。

九、常见问题

9.1 改了环境变量不生效

确认是否重建了对应服务：docker compose up -d <服务> 才会重新读取 environment；单纯 docker compose restart 不会重新读取编排文件中的环境变量。

验证方法：加 DEFGUARD_LOG_LEVEL: debug，重启后看日志里的 Using config 行。

9.2 重启后所有用户被踢下线

原因是 DEFGUARD_SECRET_KEY 未固定，Core 每次启动随机生成新密钥，旧会话签名失效。生产环境务必在 .env 中固定该值。

9.3 OIDC 登录后应用报签名错误

检查 DEFGUARD_OPENID_KEY 是否固定；若用 RS256，需确认 JWKS 端点（/api/v1/oauth/discovery/keys）返回的公钥与签发密钥匹配。

9.4 Gateway 日志显示 userspace: true

说明内核无 WireGuard 模块，已回退用户态。性能会下降，高并发场景建议换用支持 WireGuard 的内核或加载模块。

十、参考链接

• 官方配置文档：https://docs.defguard.net/deployment/environment-variables
• 官方仓库：https://github.com/DefGuard/defguard
• REST API：https://docs.defguard.net/for-developers/rest-api