Web 服务

按域名提供反向代理、重定向、静态文件与固定文本，是 Gately 的统一 Web 入口。菜单位置：侧边栏「Web → Web 服务」。

结构：监听、站点与默认站点

配置分三层：

监听：一个监听端口。字段包括网络（tcp 双栈、tcp4、tcp6）、监听地址（留空为所有地址）、端口、HTTPS 开关、最低 TLS 版本（1.0 / 1.1 / 1.2 / 1.3）、是否接收 PROXY 协议。
站点：监听下按域名匹配的一个站点。域名支持精确域名、*.example.com（匹配任意级子域名）与 *（匹配所有）；匹配优先级为精确域名、通配、*。
默认站点：没有站点匹配时使用，未启用时返回 404。

修改站点或默认站点并保存时，站点列表会原地替换：监听保持运行，已建立的连接（含 WebSocket）不会断开，各站点的统计数据也会保留。新配置无效时继续使用原来的站点。修改监听自身的设置（网络、地址、端口、HTTPS、最低 TLS、HTTP/3、PROXY 协议）会重启该监听。

站点类型

类型	说明
反向代理	转发到一个或多个后端，后端地址格式为 `http(s)://主机:端口`，支持 WebSocket
重定向	跳转到完整 URL，状态码 301 / 302 / 307 / 308（默认 302），可选保留原路径与查询串。URL 中可以写 `{host}`，会替换为访客使用的域名：`https://{host}` 加上「保留路径」，就能把所有 HTTP 请求跳到同一域名的 HTTPS
静态文件	目录需为绝对路径；关闭「目录列表」时，目录请求只在存在 `index.html` 时返回。「无扩展名地址」在文件不存在时再尝试 `路径.html` 与 `路径/index.html`（适用于 VitePress 等生成器，相当于 nginx 的 `try_files $uri $uri.html $uri/index.html`）；「404 页面」填写目录内的路径，如 `404.html`，以 404 状态返回
固定文本	自定义内容、`Content-Type`（默认 `text/plain; charset=utf-8`）与状态码（100-599，默认 200）

反向代理站点的其他选项：

使用后端 Host：Host 头改为后端地址，关闭时保留客户端请求的 Host；
跳过后端证书校验、关闭 Keep-Alive；
向后端发送 PROXY 协议（v2 头，传递真实客户端 IP，需要后端支持）；
添加 X-Forwarded-For / X-Forwarded-Proto / X-Forwarded-Host / X-Forwarded-Port 与 X-Real-IP；
使用访问域名作为 SNI（仅 HTTPS 后端）：握手时发送访客使用的域名，并按它校验证书，相当于 nginx 的 proxy_ssl_server_name on; proxy_ssl_name $host。后端按 SNI 分流时（例如 frp 的 vhost_https）需要开启。每个后端使用独立的连接池，不同域名的连接不会互相复用。

所有类型的站点均可设置访问日志、跨域（CORS）、自定义请求头与响应头（每行 Key: Value，Value 留空表示删除该头），并可引用一个 WAF 防火墙实例（实例不存在或停用时放行）。

传输与协议

HTTPS：使用 SSL 证书模块中覆盖该域名的证书；
HTTP/3（QUIC）：在开启 HTTPS 的监听中打开，同一端口号的 UDP 上同时提供 HTTP/3，并通过 Alt-Svc 响应头通告浏览器；需要在防火墙与端口映射中放行该 UDP 端口；
WebSocket：反向代理自动支持；
PROXY 协议：监听可接收上游（如 haproxy、frp）发送的 PROXY 头，仅信任「全局设置 → 可信 PROXY 来源」中列出的 IP 或网段，留空表示不信任任何来源；反向代理可向后端发送 PROXY 头。

认证

在站点编辑框的「安全」页配置：

网页认证：浏览器显示登录页；
基本认证：HTTP Basic；
用户：每行 用户名:密码，密码可填 bcrypt 哈希。启用基本认证时至少需要一个用户；启用网页认证时至少需要一个用户或第三方登录身份；
第三方登录：支持 GitHub、Google、QQ、OIDC，使用自己的 OAuth 应用。允许的身份每行一条，格式 提供方标识:账号，例如 github:octocat、google:me@gmail.com，行尾可用 # 加备注，github:* 表示该提供方的任意账号。

第三方登录的提供方在「全局设置」中配置：填写自己的 Client ID / Secret 并启用，同时设置回调地址（需由 Gately 的某个监听提供，例如 https://auth.example.com）。登记到 GitHub / Google / QQ 的回调 URL 为：

text

https://auth.example.com/__gately_auth/oauth/callback

管理后台自身的第三方登录在「设置 → 账号与安全」中单独配置。

转发认证（Authelia 等）

把认证交给外部服务，相当于 nginx 的 auth_request 或 Traefik 的 forwardAuth。在「安全」页勾选「转发认证」；同一站点不能同时启用基本认证或网页认证。

字段	说明
`url`	校验接口，例如 Authelia 的 `http://127.0.0.1:9091/api/authz/auth-request`
`loginUrl`	接口返回 401 时把访客跳转到的地址，例如 `https://auth.example.com/?rd={url}&rm={method}`；`{url}` 为原始地址（已编码），`{method}` 为请求方法。留空时原样返回接口的响应
`copyHeaders`	校验通过后从接口响应复制到后端请求的身份头，默认 `Remote-User`、`Remote-Groups`、`Remote-Email`、`Remote-Name`

工作方式：

每个请求先以不带请求体的 GET 发到 url，带上访客的请求头（Cookie、Authorization 等），以及 X-Original-Method、X-Original-URL、X-Forwarded-Method、X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-Uri、X-Forwarded-For 与 X-Real-Ip，超时 10 秒；
返回 2xx 即放行，并带上身份头；返回 401 时跳转到 loginUrl（状态码 302）；其他结果（如 403 或跳转）原样返回给访客；接口无法连接时返回 502；
访客自带的身份头一律删除，无法伪造；
可与路径规则和「认证范围」配合，只让部分路径（如 /admin）需要登录，也可与临时分享链接配合。

共享用户：TOTP 与单点登录

账号只需定义一次，就能用于多个站点，并可选启用 TOTP 二次验证，覆盖了很多人使用 Authelia 的主要目的。

在「全局设置 → 共享用户」中：

添加用户名与密码；密码以 bcrypt 哈希保存，接口不会返回。要启用 TOTP，点「启用 TOTP」，用验证器 App（Google Authenticator、1Password 等）扫描二维码并保存；重新生成会使旧密钥失效；
单点登录域，例如 example.com：在该域或其子域名下的任一站点登录后，其他站点无需再登录。它使用父域 Cookie（gately_sso，有效期 7 天），不会转发给后端。留空则每个站点单独登录。

在站点的「安全」页，在网页认证或基本认证旁勾选「使用共享用户」；站点自有的用户仍然可用。

行为说明：

只要有共享用户启用了 TOTP，登录页就会显示验证码输入框，每个验证码只能使用一次；
修改用户的密码或 TOTP 密钥后，该用户已有的会话立即失效；
基本认证只接受未启用 TOTP 的共享用户，因为浏览器的密码弹窗没有地方输入验证码；
失败次数与其他登录共用同一套限流与自动封禁。

访问控制

IP 黑白名单

站点「安全」页的「IP 访问控制」可选关闭、白名单、黑名单，列表每行一个 IP 或网段（如 192.168.1.0/24），还可以同时引用订阅的 IP 列表。

订阅 IP 列表

在「全局设置 → 订阅 IP 列表」添加列表：填写下载地址与刷新间隔（默认 24 小时），Gately 会定时下载并缓存到配置目录，重启后无需联网即可使用。内容每行一个 IP、CIDR 或 起始-结束 范围，#、;、// 之后为注释。例如省市 IP 段可使用 metowolf/iplist 的 https://metowolf.github.io/iplist/data/cncity/440000.txt（广东省）。

站点与路径规则的白名单、黑名单可以引用多个列表，与手填的 IP 段一起判断，命中任意一项即视为在名单中；
下载内容无法识别（例如返回了错误页面）时保留上次的列表，并在列表上显示原因，一小时后重试；
列表下载成功前按空列表处理：白名单因此拒绝访问，黑名单不额外拦截；
仍被站点引用的列表不能删除。

路径规则

在「安全」页的「路径规则」中，按路径前缀覆盖站点的认证与 IP 设置：

字段	取值
`prefix`	以 `/` 开头的路径前缀，如 `/admin`
`auth`	沿用站点（空）、`off`（无需认证）、`on`（必须认证）
`ipMode` / `ipList`	沿用站点（空）、`whitelist`、`blacklist`，并附 IP 或网段列表

匹配规则：

最长前缀优先；
按路径段边界匹配，/admin 匹配 /admin 与 /admin/x，/administrator 不匹配；
请求路径先规范化（消除 .、.. 与重复斜杠）再匹配，/public/../admin 按 /admin 处理；
同一前缀只能配置一条规则。

「认证范围」选项（authOptional）：勾选后，认证只作用于规则中标记为「必须认证」的路径，其余路径公开。该选项需要先启用基本认证或网页认证。

临时分享链接

启用基本认证或网页认证后，可为站点创建分享链接，让访客免账号访问：

字段	说明
名称	备注名，如「给张三」
过期时间	留空为不过期
可用次数 `maxUses`	最多可被兑换的次数，0 为不限；重启后计数清零
路径限制 `pathPrefix`	非空时，链接只能访问该前缀下的路径，需以 `/` 开头

访客访问 https://域名/任意路径?_gs=令牌 即可兑换会话。兑换成功后服务端设置免登录 Cookie 并跳转到去掉 _gs 参数的地址，会话最长 24 小时，且不超过链接的过期时间。令牌无效时按普通访问处理，不透露失败原因。删除链接后已发出的会话立即失效。令牌在保存后生成（至少 16 位），可在界面复制完整链接。

认证失败限流与自动封禁

同一来源 IP 在 15 分钟内认证失败累计 10 次后，暂时拒绝继续尝试；
「全局设置 → 自动封禁 → 认证失败封禁」填写分钟数（0 至 43200），达到 10 次失败时封禁来源 IP；填 0 表示不封禁，仅限流；
自动封禁触发时发布 AuthBanned 事件，可经通知中心推送；
IPv6 地址按 /64 网段聚合计数与封禁。

封禁列表

「全局设置」中的封禁列表显示当前被封禁的 IP、原因（认证连续失败或手动封禁）和到期时间，可点击「解除」。也可手动封禁：填写 IP 与小时数（1 至 720，即最长 30 天），接口默认时长为 24 小时。

封禁列表与入侵防护共用同一张表：开启入侵防护模块时，这里只显示封禁数量，并跳转到入侵防护页面管理。封禁同样对端口转发、STUN 等服务生效，开启防火墙同步后会在系统防火墙中丢弃；开启「忽略内网地址」时，内网地址不会被自动封禁。

GeoIP 国家过滤

站点「国家过滤」有三种模式：关闭、仅允许、拒绝，并填写两位 ISO 国家代码（逗号分隔，如 CN, HK, US）。启用时至少填写一个国家。

过滤依赖 GeoIP 数据库，需先在「全局设置 → GeoIP 数据库」导入：上传 .mmdb 文件，或填写下载地址。支持 MaxMind GeoLite2、DB-IP 等国家库或城市库；上传限制 129 MB；
数据库未加载时过滤不生效（放行所有访客），界面会提示；
内网地址始终放行；
「拒绝」模式下，库中查不到国家的地址放行。

按路径分流后端

为反向代理站点把某个路径前缀下的请求发到其他后端，相当于 nginx 的 location /api/ { proxy_pass ...; }。在站点编辑框「基本」页的「分路径后端」中添加。

字段	说明
`prefix`	路径前缀，如 `/api/`。按路径段边界匹配：`/api` 与 `/api/` 都匹配 `/api` 和 `/api/x`，不匹配 `/apix`
`targets`	该路径的后端，写法与站点后端相同；留空时使用站点后端，只追加下面的请求头
`requestHeaders`	该路径追加的请求头，每行 `Key: Value`；在站点请求头之后应用，同名时以路径的为准

最长前缀优先，路径原样转发（不会去掉前缀）；
站点的其他设置，如 Host 选项、证书校验、转发头、PROXY 协议、负载均衡策略与健康检查，对每个路径后端同样生效；
压缩、限流、缓存与重写作用于整个站点。

反向代理增强

这些选项位于站点编辑框的「流量」页。

后端、权重与备用

后端列表每行一个地址，地址后可附参数：

text

http://10.0.0.2:8080 weight=3
http://10.0.0.3:8080 backup

weight=N：权重，1 至 100 的整数，默认 1；
backup：备用后端，仅在所有非备用后端都不可用时启用；全部后端都不可用时回退到所有非备用后端继续尝试。

负载均衡策略

界面选项	`lbPolicy`	说明
轮询（按权重）	空	默认
随机（按权重）	`random`
IP 哈希（会话保持）	`ip_hash`	同一客户端 IP 落到同一后端
最少连接	`least_conn`	按「连接数 / 权重」选择最小者

健康检查

主动检查开关默认关闭。启用后的字段与默认值：

字段	默认值	范围
方式 `mode`	`http`	`http`（请求检查路径，状态码小于 400 视为健康）或 `tcp`（只测试连接）
路径 `path`	`/`	以 `/` 开头，仅 http 方式
间隔 `interval`	10 秒	1 至 3600
超时 `timeout`	3 秒	1 至 60
连续失败 `fails`	3 次判不可用	1 至 20
连续成功 `passes`	2 次恢复	1 至 20

启用向后端发送 PROXY 协议时，HTTP 检查自动改用 TCP。

被动检查始终生效：多个后端中，连续 3 次连接失败的后端暂停 30 秒后再试探（只有一个后端且未启用主动检查时不摘除）。启用主动检查后，恢复完全由检查结果决定。后端状态变化时发布上游不可用 / 已恢复事件，可经通知中心推送。

压缩

对反向代理、静态文件、固定文本站点可启用压缩（重定向站点除外）。按 Accept-Encoding 优先选择 br，其次 gzip。

仅压缩文本类内容：text/*、JSON、JavaScript、XML、XHTML、RSS / Atom、WebAssembly、SVG；text/event-stream 排除在外；
声明的 Content-Length 小于 256 字节的响应保持原样；
已有 Content-Encoding 的响应保持原样；WebSocket 升级请求直接放行；
压缩后强校验 ETag 改为弱校验。

按 IP 限流

按客户端 IP 的令牌桶限流，字段：

字段	说明
`rate`	每秒允许的请求数
`burst`	突发容量；设置了 `rate` 而 `burst` 为 0 时自动取 `rate` 取整加 1
`maxConns`	单个 IP 的并发请求上限，0 为不限

启用限流时 rate 与 maxConns 至少设置一项。

内存响应缓存

仅对反向代理站点生效，缓存存放在内存中，LRU 淘汰。

字段	默认值	范围
`ttl` 默认时长	0	0 至 30 天（秒）。上游未声明缓存指令时，200 响应缓存这么久；0 表示只缓存上游明确允许的响应
`maxMb` 缓存容量	64	1 至 4096 MB

缓存规则：

仅缓存 GET 请求，且请求不含 Authorization、Cookie、Range 头，也不含 Cache-Control: no-cache；
仅缓存状态码 200 的响应；响应含 Set-Cookie、Vary: *，或 Cache-Control 为 no-store / private / no-cache 时跳过；
遵循 s-maxage，其次 max-age；
单个条目上限为 4 MB，同时不超过总容量的四分之一；
命中时返回头 X-Cache: HIT 与 Age，未命中为 X-Cache: MISS；
缓存键包含 Host、完整请求 URI 与 Accept-Encoding。

路径重写与重定向

规则按顺序匹配，命中第一条即停止。

字段	说明
`pattern`	匹配请求路径的正则表达式，如 `^/old/(.*)$`
`to`	替换结果，可用 `$1` 引用分组
`redirect`	关闭为内部重写（重写后的路径发往后端，目标需以 `/` 开头）；开启为重定向
`code`	重定向状态码 301 / 302 / 307 / 308，默认 302

重定向会保留原查询参数。重定向目标中可以写 {host}，表示访客使用的域名。重定向规则先于认证执行，相当于 nginx 的 location = / { return 302 ...; }，所以 / 这类路径可以直接把访客送走，不要求先登录。

访问统计与监控

站点统计

运行中的监听，在站点行点击「统计」打开统计窗口，可选最近 1 小时、6 小时、24 小时：

分钟级访问统计：每分钟一个点，保留最近 24 小时，包含请求数曲线与 4xx / 5xx 错误曲线；
状态码分布 2xx / 3xx / 4xx / 5xx，累计响应流量；
来源 IP Top 10 与国家 Top 10（国家统计需要已导入 GeoIP 数据库）；
反向代理站点显示每个后端的健康状态、权重、是否备用与当前连接数。

统计保存在内存中，重启或修改该监听自身的设置后重新计数；修改站点会保留其计数。排行榜最多统计 5000 个不同来源。

Prometheus 指标

全局指标端点 GET /api/metrics 汇总了全部模块的指标，见监控指标。下面的模块端点只包含 Web 服务的指标。

指标端点为 GET /api/webservice/metrics，Prometheus 文本格式，需携带登录凭据或 API 令牌。

bash

curl -H "Authorization: Bearer gtl_xxxx" http://localhost:16680/api/webservice/metrics

指标	类型	说明
`gately_site_requests_total`	counter	站点累计请求数
`gately_site_errors_total`	counter	站点后端错误数
`gately_site_active_requests`	gauge	进行中的请求数
`gately_site_response_bytes_total`	counter	累计响应字节数
`gately_site_responses_total`	counter	按状态类别（标签 `class`：`2xx` 至 `5xx`）统计的响应数
`gately_upstream_up`	gauge	后端是否健康，1 健康、0 不可用（附标签 `upstream`）

所有指标带标签 listener（监听名称#监听 key）与 site（站点名称，未命名时取第一个域名）。

导入 nginx 配置

页面顶部的「导入 nginx」可以把现有 nginx 站点转换为 Gately 的监听与站点。推荐在 nginx 所在主机执行 nginx -T，把完整输出粘贴进来：输出中包含 include 的所有文件，Gately 会像 nginx 一样展开 include。

先预览：按监听端口分组列出每个站点的类型、后端或目录、来源文件与行号，以及需要注意的地方（使用了变量的指令、正则 location、缺少证书的域名等），无法转换的站点会说明原因；
相同端口的站点合并到已有监听，否则新建监听；已存在的域名会跳过，可以重复导入；
默认导入为停用状态，便于与 nginx 并行逐个核对后再启用；勾选「导入后立即启用」则立即生效（nginx 仍占用同一端口时新建的监听会启动失败）；
能转换的内容：proxy_pass（含 upstream 的权重、备用与负载均衡策略）、root / alias 静态目录（autoindex、try_files $uri.html、error_page 404）、return 跳转与固定内容、整站 rewrite 跳转、add_header、proxy_set_header、gzip、allow / deny、location 级的分路径后端、访问控制与跳转、listen ... proxy_protocol 与 quic；
auth_request 会转换为转发认证：认证地址取自认证子请求 location 的 proxy_pass（支持 set 变量），登录跳转取自 error_page 401 =302，Authelia 的常见写法可以直接转换；只在部分 location 启用时转换为「仅对指定路径认证」；
auth_basic 转换为使用共享用户的基本认证，nginx 的用户文件不会被读取，补齐用户前任何人都无法通过；
stream 中的 TCP/UDP 转发请在端口转发中配置；证书不会导入，HTTPS 站点缺少证书时预览会列出 nginx 使用的证书文件，可在证书页按文件路径添加。

替换 haproxy 与 nginx

端口转发加 Web 服务可以替代 haproxy + nginx 的组合。常见布局是：在 443 上放一条 SNI 分流规则，把 VPN 等 TLS 服务直接送到各自的后端，其余域名送到一个接收 PROXY 协议的 Web 服务监听；再在 80 端口放一个 Web 服务监听，用重定向站点（https://{host}）跳转到 HTTPS。

nginx 配置的对应关系：

nginx	Gately
带 `server_name` 的 `server`	使用这些域名的站点
`proxy_pass` 不同的 `location`	分路径后端
`auth_request`（Authelia）	转发认证，或带 TOTP 的共享用户
`proxy_ssl_name $host`	使用访问域名作为 SNI
`return 301 https://$host$request_uri`	重定向站点，`https://{host}` 并勾选「保留路径」
`location = /` 里的 `return 302 /admin`	重写规则，开启「重定向」，pattern 为 `^/$`
`try_files $uri $uri.html $uri/index.html` 与 `error_page 404`	静态文件的无扩展名地址与 404 页面
`add_header`	响应头

部署提示

Web 服务需要监听宿主机的 80 / 443 等端口，Docker 部署推荐使用 --network host。

Web 服务 ​

结构：监听、站点与默认站点 ​

站点类型 ​

传输与协议 ​

认证 ​

转发认证（Authelia 等） ​

共享用户：TOTP 与单点登录 ​

访问控制 ​

IP 黑白名单 ​

订阅 IP 列表 ​

路径规则 ​

临时分享链接 ​

认证失败限流与自动封禁 ​

封禁列表 ​

GeoIP 国家过滤 ​

按路径分流后端 ​

反向代理增强 ​

后端、权重与备用 ​

负载均衡策略 ​

健康检查 ​

压缩 ​

按 IP 限流 ​

内存响应缓存 ​

路径重写与重定向 ​

访问统计与监控 ​

站点统计 ​

Prometheus 指标 ​

导入 nginx 配置 ​

替换 haproxy 与 nginx ​

部署提示 ​