Warpgate 配置参数详解

目标：逐项讲清 Warpgate v0.30.2 的 /etc/warpgate.yaml 全部配置段与参数（以官方 config-schema.json 与实机生成配置为底本，2026-10-27 实测核对），并区分「文件侧参数」与「数据库侧管理对象」，给出可直接套用的生产配置模板。

一、环境信息

服务器：Debian GNU/Linux 12 (bookworm) 12.15，x86_64（环境明细见《Warpgate 安装与初始化实战》第一节）；
软件版本：Warpgate v0.30.2（2026-10-27 官方最新稳定版）；
配置基线：warpgate unattended-setup 生成的默认配置（全文见安装篇 4.2 节回显），本篇在其上逐项展开；
参数权威依据：仓库 config-schema.json（配置生成时首行即引用该 Schema），本篇全部字段类型与默认值均与该 Schema 及实机配置交叉核对。

二、前置条件

已按安装篇完成 v0.30.2 安装与初始化，存在 /etc/warpgate.yaml 与数据目录 /var/lib/warpgate/；
具备 root 或等价权限（配置文件与数据目录默认权限 600/700，属 root）；
修改前建议备份：cp /etc/warpgate.yaml /etc/warpgate.yaml.bak。

三、参数查看与修改方式

3.1 配置文件与多路径

Warpgate 默认读取 /etc/warpgate.yaml。多实例或自定义路径时可用全局参数覆盖：

warpgate --help

实测回显：

Usage: warpgate [OPTIONS] <COMMAND>

Commands:
  setup             Run first-time setup and generate a config file
  unattended-setup  Run first-time setup non-interactively
  client-keys       Show Warpgate's SSH client keys
  run               Run Warpgate
  check             Perform basic config checks
  create-user       Create a new user
  recover-access    Reset password and auth policy for a user
  copy-database     Copy the current database contents into another database
  migrate-database  Run database migrations
  version           Show version information
  healthcheck       Automatic healthcheck for running Warpgate in a container
  help              Print this message or the help of the given subcommand(s)

Options:
  -c, --config <CONFIG>          [env: WARPGATE_CONFIG=] [default: /etc/warpgate.yaml]
  -d, --debug...                 
      --log-format <LOG_FORMAT>  Log output format (text or json) [possible values: text, json]
      --skip-securing-files      Do not tighten UNIX modes of config and data files
  -h, --help                     Print help

即三种指定方式：-c/--config <路径>、环境变量 WARPGATE_CONFIG、默认 /etc/warpgate.yaml。相对路径以 /etc 为基准解析。

3.2 配置校验

改完配置先跑内置检查：

warpgate check

实测回显：

27.10.2026 07:37:15  INFO warpgate::config: Using config: "/etc/warpgate.yaml"
27.10.2026 07:37:15  INFO warpgate::commands::check: No problems found

3.3 编辑器补全与校验

初始化生成的配置首行带 Schema 引用，VS Code 等编辑器装 YAML 插件后即可对每个字段做补全与悬浮文档：

# Config generated in version v0.30.2
# yaml-language-server: $schema=https://raw.githubusercontent.com/warp-tech/warpgate/refs/heads/main/config-schema.json

3.4 修改生效方式

/etc/warpgate.yaml 在进程启动时读取，改后需重启生效：

systemctl restart warpgate

3.5 文件侧与数据库侧的边界

Warpgate 的配置分两层，务必区分：

文件侧（/etc/warpgate.yaml）：进程级、基础设施级参数——监听器开关与端口、TLS 证书、数据库连接、日志、SSO 提供方；
数据库侧（管理台/API 管理）：业务对象——目标（Target）、用户（User）、角色（Role）、凭证、票据、登录保护策略等，存于 database_url 指向的数据库，不在 yaml 中出现。

四、参数总览

/etc/warpgate.yaml 顶层共 12 个键（config-schema 顶层属性全集，与实机生成配置一致）：

顶层键	类型	默认	作用
`external_host`	string	null	对外主机名/IP，用于构造访问 URL 与 Cookie 域
`database_url`	string	`sqlite:data/db`	元数据库连接（sqlite:/mysql:/postgres:）
`ssh`	SshConfig	见 5.2	SSH 监听器
`http`	HttpConfig	见 5.3	HTTP 监听器（管理台 + Web 代理）
`kubernetes`	KubernetesConfig	enable=false	Kubernetes API 代理监听器
`mysql`	MySqlConfig	enable=false	MySQL 协议代理监听器
`postgres`	PostgresConfig	enable=false	PostgreSQL 协议代理监听器
`vnc`	VncConfig	enable=false	VNC 监听器
`rdp`	RdpConfig	enable=false	RDP 监听器
`recordings`	RecordingsConfig	见 5.10	会话录制存储
`log`	LogConfig	见 5.9	日志
`sso_providers`	array	[]	SSO（OIDC）提供方列表

五、核心参数分类详解

5.1 全局参数：external_host 与 database_url

external_host（string，默认 null）：对外公布的主机名或 IP（不带端口与协议）。影响三处：管理台/登录页展示的连接指引、SSH 接入时打印的拓扑条中的链接、HTTP 会话 Cookie 的作用域。安装篇初始化时传了 10.89.56.10，服务启动日志实测印证了 Cookie 域行为：

27.10.2026 07:25:20  INFO warpgate_protocol_http: Cookie domain configured: .10.89.56.10 (base host: 10.89.56.10) - cookies will work for 10.89.56.10 and all its subdomains

有域名时写成域名（如 bastion.example.com），浏览器访问体验与证书匹配都更好。

database_url（string，默认 sqlite:data/db；本机生成值为 sqlite:/var/lib/warpgate/db）：元数据存储。三种前缀：

前缀	示例	场景
`sqlite:`	`sqlite:/var/lib/warpgate/db`	单机默认，零依赖
`mysql://`	`mysql://user:pass@db-host:3306/warpgate`	多节点集群/外置运维
`postgres://`	`postgres://user:pass@db-host:5432/warpgate`	同上

💡 技术拓展：这里的 database_url 是 Warpgate 自己的元数据库（用户/目标/角色/会话记录），不是被代理的业务数据库——后者配置在管理台的目标（Target）里。切换/迁移元数据库用 warpgate copy-database <目标URL> 整库复制，避免手工导出导入。

5.2 ssh 段

SSH 监听器。字段（类型/默认值依据 config-schema）：

参数	类型	默认	说明
`enable`	bool	false（初始化传 `--ssh-port` 后为 true）	SSH 接入总开关
`listen`	string	`[::]:2222`	监听地址端口
`host_key_verification`	枚举	`prompt`	对目标机主机密钥的校验策略：`prompt`/`auto-accept`/`auto-reject`/`ignore`
`inactivity_timeout`	string	`5m`	会话无活动超时（humantime 格式），到点断开
`keepalive_interval`	string	null	SSH keepalive 间隔，默认不发送
`target_handshake_timeout`	string	`30s`	连向目标机握手超时
`proxy_protocol`	bool	false	是否接受 PROXY protocol 头（置于负载均衡器后时开启）
`external_host` / `external_port`	string/int	null	经 NAT/反代对外暴露的主机与端口，仅用于生成给用户看的连接指引
`keys`	string	''	自定义 SSH 主机密钥路径（默认由内部生成并入库）

实测生成值（本机 /etc/warpgate.yaml）：

ssh:
  enable: true
  listen: '[::]:2222'
  proxy_protocol: false
  external_port: null
  external_host: null
  host_key_verification: auto_accept
  inactivity_timeout: 5m
  keepalive_interval: null
  target_handshake_timeout: 30s

生产建议：目标清单固化后把 host_key_verification 收回 prompt；对外只暴露经 NAT 映射的端口时填 external_port，避免用户照默认端口连接失败。

5.3 http 段

HTTP 监听器同时承载管理台（/@warpgate/admin）、用户门户（/@warpgate）与 HTTP 目标反向代理，参数最丰富：

参数	类型	默认	说明
`listen`	string	`[::]:8888`	监听地址端口（HTTPS，证书见下）
`certificate` / `key`	string	''（生成后指向 `/var/lib/warpgate/tls.*.pem`）	TLS 证书与私钥
`sni_certificates`	array	[]	TLS SNI 多证书列表（每项 `{certificate, key}`），一机多域名时使用
`session_max_age`	string	`30m`	登录会话有效期
`cookie_max_age`	string	`1day`	会话 Cookie 有效期
`trust_x_forwarded_headers`	bool	false	是否信任 X-Forwarded-* 头（置于反代后时开启，配合 `proxy_protocol`）
`proxy_protocol`	bool	false	接受 PROXY protocol 头
`external_host` / `external_port`	string/int	null	对外暴露地址端口（生成指引用）

实测生成值：

http:
  listen: '[::]:8888'
  proxy_protocol: false
  external_port: null
  external_host: null
  certificate: /var/lib/warpgate/tls.certificate.pem
  key: /var/lib/warpgate/tls.key.pem
  trust_x_forwarded_headers: false
  session_max_age: 30m
  cookie_max_age: 1day
  sni_certificates: []

💡 技术拓展：session_max_age 与 cookie_max_age 是两层过期——前者是服务端会话的生命周期（过期后需重新认证），后者是浏览器 Cookie 的存活时间（到期即失效）。二者一般保持 cookie ≥ session；若想「下班即失效」，把两者同步调短（如 8h/8h）即可，无需改代码。

5.4 kubernetes 段

Kubernetes API 代理监听器，客户端（kubectl）把 server 指向 Warpgate 即可纳入审计：

kubernetes:
  enable: true
  listen: '[::]:8443'
  proxy_protocol: false
  external_port: null
  external_host: null
  certificate: /var/lib/warpgate/tls.certificate.pem
  key: /var/lib/warpgate/tls.key.pem
  session_max_age: 30m

参数	默认	说明
`enable`	false	开关（初始化传 `--kubernetes-port` 后为 true）
`listen`	`[::]:8443`	监听端口
`certificate`/`key`	指向共用证书	TLS 证书
`session_max_age`	`30m`	会话有效期

5.5 mysql 段

MySQL 协议代理。特殊参数 advertised_version（默认 8.0.3-Warpgate）：握手时向客户端报告的 MySQL 版本号，个别客户端驱动会按版本决定认证方式与特性，遇到兼容性问题可调整。其余同 ssh/http 段命名规则：

mysql:
  enable: true
  listen: '[::]:33306'
  proxy_protocol: false
  external_port: null
  external_host: null
  certificate: /var/lib/warpgate/tls.certificate.pem
  key: /var/lib/warpgate/tls.key.pem
  advertised_version: 8.0.3-Warpgate

5.6 postgres 段

PostgreSQL 协议代理，结构与 mysql 段一致（无 advertised_version）：

postgres:
  enable: true
  listen: '[::]:55432'
  proxy_protocol: false
  external_port: null
  external_host: null
  certificate: /var/lib/warpgate/tls.certificate.pem
  key: /var/lib/warpgate/tls.key.pem

5.7 vnc 段

VNC 远程桌面监听器：

参数	默认	说明
`enable`	false	开关（`--vnc-port`）
`listen`	`[::]:5900`	监听端口
`enable_ard_auth`	false	Apple Remote Desktop 认证兼容开关
`certificate`/`key`	共用证书	TLS（VNC over WebSocket 场景）

5.8 rdp 段

RDP 远程桌面监听器，字段与 vnc 段同构（无 enable_ard_auth）：

rdp:
  enable: false
  listen: '[::]:3389'
  proxy_protocol: false
  external_port: null
  external_host: null
  certificate: /var/lib/warpgate/tls.certificate.pem
  key: /var/lib/warpgate/tls.key.pem

5.9 log 段

log:
  retention: 7days
  audit_retention: 11months 30days 3h 50m 24s
  send_to: null
  format: text

参数	默认	说明
`retention`	`7days`	普通运行日志保留期
`audit_retention`	`11months 30days 3h 50m 24s`（≈12 个月）	审计/会话记录保留期
`send_to`	null	日志外发目标（syslog 等远程接收端，null=仅本地）
`format`	`text`（枚举 `text`/`json`）	日志格式；接 ELK/Loki 建议改 `json`

所有时长均为 humantime 格式（30m、1day、7days 可自由组合），审计保留期默认近一年，调短可省磁盘、调长需评估 recordings 存储增长。

5.10 recordings 段

会话录制存储（config-schema 定义；unattended-setup --record-sessions 会启用录制，落盘路径为数据目录下 recordings/）：

参数	默认	说明
`enable`	false	录制总开关
`path`	`./data/recordings`	录制文件目录（相对数据目录解析）

实测落盘结构（安装篇 9.10 节）：recordings/<会话ID>/<目标会话ID>/index.ndjson（事件索引）+ data.ndjson（终端/流量数据流），每会话独立目录，便于按会话归档或加密离存。

5.11 sso_providers 段

SSO（OpenID Connect）提供方数组，默认空。每个提供方的关键字段（config-schema SsoProviderConfig）：

参数	默认	说明
`name`	''	提供方标识（登录页按钮名）
`label`	null	显示名
`provider`	—	OIDC 细节：`issuer_url`/`client_id`/`client_secret`/`scopes`（Google Workspace/Azure 等变体含管理域委派邮箱等专字段）
`auto_create_users`	false	SSO 首登自动建用户
`role_mappings`	—	组→角色映射（如 Google 组邮箱映射到 Warpgate 角色，`*` 作兜底键）
`default_credential_policy`	—	该 SSO 用户的默认凭证策略
`return_url_domain` / `return_url_prefix` / `return_domain_whitelist`	`external_host` / `@` / null	回跳 URL 构造规则
`disable_local_logout`	false	禁用本地登出（走 IdP 统一登出）
`kubernetes`	null	K8s 场景的 OIDC 参数（client_id/secret/scopes）

SSO 是文件侧配置的典型代表：改 sso_providers 必须改 yaml 并重启；而普通用户管理在数据库侧完成，两者不要混淆。

六、数据库侧管理对象速览

以下对象不经 yaml 管理，全部在管理台（/@warpgate/admin）或管理 API（/@warpgate/admin/api，规范见 /@warpgate/admin/api/openapi.json）中维护，实测结构如下：

目标（Target）——kind 七选一（Ssh/Http/Kubernetes/MySql/Postgres/Vnc/Rdp），SSH 目标实测创建回显（节选）：

{"name":"web-01","options":{"allow_insecure_algos":false,"auth":{"kind":"Password","password":"q1w2e3r4"},"host":"10.89.56.20","jump_host":null,"kind":"Ssh","port":22,"username":"root"},"rate_limit_bytes_per_second":null,"require_approval":false,"ticket_requests_disabled":false,"ticket_require_approval":false}

关键字段：options.auth（Password/PublicKey/Certificate 等目标侧凭证）、rate_limit_bytes_per_second（带宽限速）、require_approval（连接需审批）、ticket_max_uses/ticket_max_duration_seconds（票据上限）、group_id（目标分组）。

用户（User）——实测创建回显（节选）：

{"allowed_ip_ranges":null,"credential_policy":{"http":null,"kubernetes":null,"mysql":null,"postgres":null,"rdp":null,"ssh":null,"vnc":null},"description":"App developer","id":"7900f03b-127b-4fef-9800-20ce9c233c69","username":"appdev"}

关键字段：allowed_ip_ranges（来源 IP 白名单）、credential_policy（按协议的认证强度要求，如强制 OTP）、凭证体系（passwords/public-keys/otp/sso/api-tokens/certificates 六类，各有独立 API 端点）。

角色（Role）——用户与目标之间的授权媒介：{"name":"ops-team","is_default":false}；绑定关系为「用户↔角色」「目标↔角色」双向挂接（实测安装篇 9.6/9.7 节）。

七、生产配置模板

7.1 最小化模板（SSH + HTTP 门户，单机 SQLite）

适用：10~50 人团队、虚机 2C4G、磁盘 40G 起（录制按需扩）。

external_host: bastion.example.com
database_url: sqlite:/var/lib/warpgate/db
ssh:
  enable: true
  listen: '[::]:2222'
  host_key_verification: prompt
  inactivity_timeout: 15m
http:
  listen: '[::]:8888'
  certificate: /etc/warpgate-tls/fullchain.pem
  key: /etc/warpgate-tls/privkey.pem
  session_max_age: 8h
  cookie_max_age: 8h
kubernetes: { enable: false }
mysql: { enable: false }
postgres: { enable: false }
vnc: { enable: false }
rdp: { enable: false }
log:
  retention: 30days
  audit_retention: 12months
  send_to: null
  format: json
recordings:
  enable: true
  path: ./data/recordings
sso_providers: []

要点：仅开两个监听器缩小暴露面；受信证书替换自签；会话与 Cookie 同步 8h；JSON 日志便于接入采集；host_key_verification 用 prompt 严控目标漂移。

7.2 集群/外置数据库模板（MySQL/PostgreSQL 代理 + 外置 PG 元库）

适用：多节点或需要与既有 DBaaS 运维体系合流的场景，虚机 4C8G、元库用外置 PostgreSQL、磁盘 100G 起（录制大头）。

external_host: bastion.example.com
database_url: postgres://warpgate:CHANGE_ME@pg-db.internal:5432/warpgate
ssh:
  enable: true
  listen: '[::]:2222'
  host_key_verification: prompt
http:
  listen: '[::]:8888'
  certificate: /etc/warpgate-tls/fullchain.pem
  key: /etc/warpgate-tls/privkey.pem
mysql:
  enable: true
  listen: '[::]:33306'
postgres:
  enable: true
  listen: '[::]:55432'
log:
  retention: 30days
  audit_retention: 12months
  format: json
recordings:
  enable: true
sso_providers:
  - name: corp-oidc
    provider:
      issuer_url: https://idp.example.com
      client_id: warpgate
      client_secret: CHANGE_ME
      scopes: [openid, profile, email]
    auto_create_users: true

模板中 CHANGE_ME 类敏感值上线前务必替换为环境变量注入或密钥管理产物；Warpgate 自身支持 Vault/OpenBao 密钥后端（管理台 Secret backends 模块）托管目标凭证。

八、常见问题

Q1：改了 yaml 不生效？ 进程启动时读取配置，需 systemctl restart warpgate；重启前先 warpgate check 校验（实测回显见 3.2 节）。

Q2：listen 写 [::]:8888 会监听 IPv6，IPv4 能连吗？ 能。[::] 双栈监听（实测服务启动后 IPv4 客户端直连 8888/2222 均正常，见安装篇 9.8/9.9 节）；仅 IPv4 可写 0.0.0.0:8888。

Q3：时长格式怎么写？ humantime 风格，可组合：30s、5m、8h、1day、11months 30days 等；非法值会在 warpgate check 或启动时报错。

Q4：把自签证书换成正式证书后浏览器仍告警？ 确认 http.certificate 指向包含中间链的 fullchain，且 external_host 与证书 CN/SAN 匹配；Chrome 会把 http.certificate 与访问域名做严格匹配，SNI 多域名场景改用 sni_certificates。

Q5：MySQL 客户端连不上代理？ 优先核对客户端驱动的认证插件兼容性，必要时调整 mysql.advertised_version（默认 8.0.3-Warpgate）；再用 ss -ltnp | grep 33306 确认监听存在。

Q6：录制文件占满磁盘怎么办？ 三管齐下：调短 log.audit_retention、把 recordings.path 指到大容量分区（或独立挂载）、对历史会话目录做离线归档压缩（录制为纯 ndjson 文本流，可压缩比高）。

九、参考链接

本专栏：《Warpgate 介绍与选型指南》、《Warpgate 安装与初始化实战》、后续《Warpgate 常用 CLI 命令详解》；
配置 JSON Schema（字段权威定义）：https://github.com/warp-tech/warpgate/blob/main/config-schema.json
官方文档站首页（各专题入口）：https://warpgate.null.page/
SSO 配置（官方）：https://warpgate.null.page/sso/
会话录制（官方）：https://warpgate.null.page/session-recordings/