Skip to content

站点访问控制与登录认证 ​

站点上线到公网之后,下一步通常是决定「谁能访问」。Gately 在每个站点的「安全」页里提供了两类工具:按来源拦(IP 名单、订阅 IP 列表、国家过滤、敲门准入)和按身份拦(网页认证、基本认证、共享用户、TOTP、Passkey、第三方登录),再用路径规则给个别路径开例外。本文以一个家庭相册为例,把这些功能逐个配上:家人用账号或 Passkey 登录看照片,手机 App 走的 API 免登录,管理页只允许家里内网打开,境外来源和扫描器直接断开。

一个应用一个应用加 HTTPS 与登录已经讲过 Jellyfin、Immich 等应用的基础登录设置与 App 兼容问题,本文讲 Gately 这一侧的全部访问控制选项,两篇可以对照着看。动手前可以先打开在线演示(点「演示账号一键进入」,只读,每小时重置),在「Web 服务」里编辑「相册」站点的「安全」页,对照本文浏览。

适用场景与前提 ​

  • 已经有一个能从外网打开的站点,例如 photos.example.com 反向代理到内网的 http://192.168.1.21:2283。还没有的话先看添加第一个站点;
  • 站点走 HTTPS,证书覆盖站点域名,见申请 HTTPS 证书或泛域名证书。Passkey 和第三方登录都要求 HTTPS 与域名访问;
  • 知道家里内网网段,本文用 192.168.1.0/24,IPv6 前缀用 2001:db8:1234::/48 举例;
  • Gately 前面还有 CDN、云 WAF 或另一层反向代理时,先在「Web 服务 → 全局设置 → 访客真实 IP(CDN / WAF 之后)」里配好「可信代理」,见 Web 服务 · 访客真实 IP。否则 Gately 看到的来源全是代理的地址,IP 名单和国家过滤都会判错。

结果是什么样 ​

text
访客 ──HTTPS──▶ Gately 443 ── photos.example.com ──▶ 相册 http://192.168.1.21:2283
                  │
                  ├─ 1. 封禁列表、优先拒绝名单 ─────── 命中 → 断开连接
                  ├─ 2. IP 访问控制(路径规则可覆盖)── /admin 只放行 192.168.1.0/24
                  ├─ 3. 国家过滤 ─────────────────── 仅允许 CN、HK,内网始终放行
                  ├─ 4. 认证 ─────────────────────── 网页认证 + 共享用户(TOTP / Passkey / GitHub)
                  │                                    /api 无需认证,交给相册 App 自己的令牌
                  └─ 5. WAF ──────────────────────── 已登录的家人跳过(信任已登录用户)

Gately 处理一个请求时按上面的顺序检查:先看来源地址(封禁、优先拒绝名单、IP 访问控制、敲门准入、国家过滤、限流),全部通过后才轮到认证,最后经过 WAF 再转给后端。被来源检查拦下的访客连登录页都看不到;「拒绝方式」决定拦下时返回 403 还是直接断开。

步骤 ​

1. 在「认证用户」页准备共享用户 ​

共享用户只定义一次,多个站点都能用,还能加 TOTP 二次验证和 Passkey。家人的账号建议都放在这里。

  1. 侧边栏打开「Web → 认证用户」。
  2. 在「共享用户」卡片点「添加共享用户」,填写:
    • 「用户名」:如 alice;
    • 「密码」:保存时转成 bcrypt 哈希,之后无法再查看原文;
    • 「邮箱」「显示名」「分组」可选,给按用户分流、传递身份信息和 OIDC 单点登录用;
    • 「备注」写上「家人」之类,方便以后辨认。
  3. 点「确定」回到列表,按同样方法添加其他家人。
  4. 「单点登录域」填 example.com。之后在 example.com 及其子域名下任一开启「使用共享用户」的站点登录一次,其他站点无需再登录(父域 Cookie gately_sso,有效期 7 天)。留空则每个站点各登录一次。
  5. 「Passkey 登录」打开,后面第 4 步用到。需要的话把「自助修改密码」也打开,家人可以在 https://站点域名/__gately_auth/password 自己改密码。
  6. 点页面底部的「保存」。用户、单点登录域与开关在保存后对所有站点立即生效。

认证用户页:共享用户、单点登录域与 Passkey 登录

给某个用户开 TOTP。 在用户行点「编辑」,TOTP 一行点「启用 TOTP」,弹出二维码,让对方用 Google Authenticator、1Password 等验证器 App 扫码(也可以手动输入二维码下方的密钥),点「关闭」后回到编辑框,此时显示「已启用 TOTP」。点「确定」,再点页面底部的「保存」才生效。以后在新手机上添加,用「查看二维码」;「重新生成」会让旧密钥作废;「关闭 TOTP」取消二次验证。

编辑共享用户:启用 TOTP 后的状态

TOTP 的几点行为

  • 只要有一个共享用户启用了 TOTP,登录页在密码通过后会进入「两步验证」,要求输入 6 位动态验证码,每个验证码只能用一次;
  • 基本认证(浏览器弹窗、curl -u)只接受没开 TOTP 的共享用户,因为弹窗里没有地方填验证码;
  • 管理员修改某个用户的密码或 TOTP 密钥并保存后,这个用户各处已登录的会话立即失效,已注册的 Passkey 也会被删除。

2. 给站点开启网页认证 ​

  1. 打开「Web → Web 服务」,在相册站点那一行点「编辑」(铅笔按钮),切到「安全」页。
  2. 「认证」勾选「网页认证(浏览器显示登录页)」。
  3. 出现「共享用户」一行,勾选「使用共享用户(支持 TOTP 与单点登录)」。
  4. 「用户」一栏可以留空。这里填的是只属于本站点的账号,每行 用户名:密码,与共享用户可以同时使用,适合临时给某个站点单独开一个账号。
  5. 点「保存」。

站点安全页:网页认证与共享用户

保存后用浏览器打开 https://photos.example.com,会跳到 /__gately_auth/login 的登录页,标题是「登录以继续访问」。登录成功后回到原来的页面,会话有效期 7 天。退出登录访问 https://photos.example.com/__gately_auth/logout。

也可以反过来操作:在「认证用户」页下方的「使用共享用户的站点」里,按监听找到站点直接勾选。没开认证的站点勾选后会显示「保存后开启网页认证」,保存时一并打开。

网页认证、基本认证和转发认证怎么选。

选项访客看到什么用在哪里
网页认证Gately 的登录页,支持 TOTP、Passkey、第三方登录、单点登录在浏览器里打开的服务。脚本、命令行等非浏览器客户端可以用 HTTP Basic 凭据访问同一站点(判断依据是请求的 User-Agent 含 Mozilla/ 且 Accept 含 text/html)
基本认证浏览器原生的用户名密码弹窗WebDAV、脚本、只认 Basic 的老客户端
转发认证外部认证服务(Authelia、Authentik 等)的页面已经在用这些服务,见 Web 服务 的「转发认证」一节

网页认证与基本认证可以同时勾选;转发认证与前两者互斥。

3. 用 GitHub 或 Google 账号登录(可选) ​

第三方登录用你自己创建的 OAuth 应用,目前支持 GitHub、Google、QQ 与通用 OIDC(Authentik、Keycloak、Casdoor 等)。登录后 Gately 按「允许的身份」逐条比对,只放行列出来的账号。

先选一个回调地址。 回调地址必须由本机 Gately 的某个监听提供,并且有证书覆盖。最省事的是直接用一个已有站点的域名,例如 https://photos.example.com;也可以单独解析一个 auth.example.com 指向 Gately,由泛域名证书覆盖。

在 GitHub 创建 OAuth 应用。

  1. 打开 GitHub → Settings → Developer settings → OAuth Apps → New OAuth App;
  2. 「Homepage URL」填站点地址,「Authorization callback URL」填 https://auth.example.com/__gately_auth/oauth/callback(把域名换成你选的回调地址);
  3. 创建后记下 Client ID,再生成一个 Client Secret。

Google 在 Google Cloud Console 创建「OAuth 客户端 ID」(应用类型选 Web 应用),「已获授权的重定向 URI」填同一个回调地址。

在 Gately 中配置提供方。

  1. 「Web 服务」页右上角点「全局设置」,找到「第三方登录(网页认证使用)」分组;
  2. 「回调地址」填 https://auth.example.com,下方会提示要登记的完整回调地址;
  3. 点「添加登录方式」,类型选「GitHub」,标识填 github(它同时是身份前缀),显示名填 GitHub,再填 Client ID 和 Client Secret;
  4. 用 Google 时再点一次「添加登录方式」,类型选「Google」,标识填 google,填入 Google 的客户端 ID 与密钥;
  5. 服务器直连不了 Google、GitHub 时,在「代理」里填 http:// 或 socks5:// 代理地址,只作用于这个登录方式。Docker 部署时 127.0.0.1 指容器自己,要填宿主机地址;
  6. 点「保存」。

Web 服务全局设置:回调地址与 GitHub 登录方式

在站点里列出允许的身份。 回到相册站点的「安全」页,「第三方登录」每行一条 提供方标识:账号,行尾可用 # 加备注:

text
github:octocat          # 管理员自己
google:mom@example.com

GitHub 可以写登录名或数字 ID(数字 ID 不受改名影响),Google 写已验证的邮箱或 sub。github:* 表示任意 GitHub 账号都能登录,任何人注册一个 GitHub 账号就能进来,家庭站点不要这样写。QQ 的 openid 每个应用不同,第一次登录被拒绝时页面会显示账号标识,把它加进列表即可。

保存后登录页出现「使用 GitHub 登录」按钮。登录页只显示允许列表里用到的提供方。

从哪个地址发起登录

第三方登录完成后,浏览器带一次性票据回到发起登录的站点地址,所以只能从指向本实例的地址发起:域名要匹配站点填写的域名;经路由器端口映射、端口转发或协议分流以其他端口访问时,要在监听的「访问地址」里填写对外端口。不满足时拒绝发起,原因写在监听的运行日志里。

4. 让家人用 Passkey 登录(可选) ​

第 1 步已经打开了「Passkey 登录」。Passkey 由每个用户在自己的设备上注册,管理员无法代为添加:

  1. 家人在手机或电脑浏览器打开 https://photos.example.com/__gately_auth/passkey(登录页的「管理 Passkey」链接指向这里);
  2. 输入用户名、密码,开了 TOTP 的还要填动态验证码;
  3. 点添加,按系统提示确认指纹、面容或设备 PIN;
  4. 以后在登录页点「使用 Passkey 登录」,选中这个 Passkey 确认即可,不再需要密码和验证码。

几个限制:

  • 配置了单点登录域时,Passkey 在该域下的所有站点通用,单点登录域改了之后旧 Passkey 要重新注册;没配置时只在注册时的域名有效;
  • 只在站点填写的精确域名上提供,*.example.com 这样的通配站点与默认站点没有 Passkey 入口;
  • 必须 HTTPS 加域名访问,用 IP 打开时登录页不显示 Passkey 按钮;
  • 每个用户最多 10 个 Passkey。设备丢失时,管理员在「认证用户」页编辑该用户,在「Passkey」一行删除对应条目,立即生效。

5. 按路径开例外:API 免登录,管理页只对内网 ​

整站开了网页认证后,相册的手机 App 会被登录页挡住(App 不会渲染网页登录页),管理页又希望只在家里能开。这两件事都用「路径规则」解决。

  1. 回到相册站点的「安全」页,找到「路径规则」,点两次「添加规则」;
  2. 第一条:前缀填 /api,认证选「无需认证」,IP 保持「IP:沿用站点」。/api 及其下所有路径不再要求 Gately 登录,由相册自己的令牌校验;
  3. 第二条:前缀填 /admin,认证保持「认证:沿用站点」(仍需登录),IP 选「IP 白名单」,在出现的输入框里填 192.168.1.0/24(多个用逗号分隔),也可以在「订阅列表」里引用订阅的 IP 列表;
  4. 点「保存」。

路径规则与国家过滤

路径规则的匹配方式:

  • 按路径段匹配,/admin 匹配 /admin 与 /admin/users,不匹配 /administrator;
  • 多条规则同时匹配时,最长前缀优先;同一前缀只能有一条;
  • 匹配前先规范化路径,/api/../admin 按 /admin 处理,无法借 .. 绕过;
  • 规则里设了 IP 模式时,这条路径只用规则自己的名单,站点的 IP 访问控制在这条路径上不再生效;优先拒绝名单与国家过滤对所有路径照常生效。

反过来:大部分公开,只保护几个路径。 例如博客整站公开、只给 /wp-admin 加登录:在「认证」勾选网页认证,勾选「认证范围」下的「仅对下方标记为「必须认证」的路径启用认证,其余路径公开」,再加一条 /wp-admin →「必须认证」。Vaultwarden 的 /admin 就是这种用法,见这一节。

临时分享给没有账号的朋友

开了网页认证或基本认证后,「安全」页还有「分享链接」:点「添加分享链接」,填名称、过期时间、可用次数(0 为不限)和可选的路径限制(如 /share/2026-春游),保存后点复制按钮拿到完整链接。对方打开链接即获得最长 24 小时的免登录会话;删除链接后已发出的会话立即失效。复制站点时分享链接不会被复制。

6. IP 白名单、黑名单与订阅 IP 列表 ​

当整个站点只给固定的几个地方用(家里、办公室、某台 VPS),IP 白名单比登录更彻底:名单外的来源连登录页都看不到。

  1. 站点「安全」页的「IP 访问控制」选「白名单」(或「黑名单」);
  2. 「IP / 网段」每行一个,IPv4、IPv6、单个地址或网段都可以,例如:
    text
    192.168.1.0/24
    2001:db8:1234::/48
    203.0.113.8
  3. 「订阅列表」可以多选已订阅的 IP 列表,与上面手填的地址一起判断,命中任意一项即视为在名单中;
  4. 「优先拒绝名单」与「拒绝订阅列表」独立于上面的模式:命中的来源一律拒绝,先于白名单、黑名单判断,路径规则也覆盖不了。要「先黑后白」时,把恶意 IP 情报列表放进拒绝订阅列表,再用白名单放行自家网段;
  5. 点「保存」。

IP 访问控制:白名单、订阅列表与优先拒绝名单

订阅 IP 列表。 省市、运营商、云厂商或威胁情报的 IP 段经常变化,适合订阅:

  1. 「Web 服务 → 全局设置」,下拉到「订阅 IP 列表」,点「添加 IP 列表」;
  2. 「名称」填 广东省,「下载地址」填 https://metowolf.github.io/iplist/data/cncity/440000.txt(metowolf/iplist 的省市数据,末尾是行政区划代码);
  3. GitHub 直连不通时,在「下载代理」里选全局更新代理或填写代理;
  4. 「刷新间隔」默认 24 小时,点「保存」,列表里显示「已载入 N 条」后即可在站点里引用。

添加订阅 IP 列表

列表内容每行一个 IP、CIDR 或 起始-结束 范围,#、;、// 之后为注释,可以指向你自己维护的文本文件。

白名单引用订阅列表时

  • 列表下载成功前按空列表处理,白名单因此拒绝所有人。先确认列表显示「已载入」,再把站点切到白名单;
  • 下载到无法识别的内容(例如错误页面)时保留上次的列表,并在列表上显示原因,一小时后重试;
  • 停用仍被引用的列表后,引用它的白名单拒绝全部来源;删除仍被引用的列表会被拒绝。

订阅列表同样能在端口转发、协议分流、STUN 规则和 frps 实例的 IP 访问控制里引用。

7. 按国家或地区限制 ​

  1. 先导入 GeoIP 数据库:「Web 服务 → 全局设置 → GeoIP 数据库(国家过滤)」,点「上传 .mmdb」上传 MaxMind GeoLite2、DB-IP 等国家库或城市库,或在输入框填 .mmdb 的下载地址后点「下载」。状态一行显示「已加载:…」即可;
  2. 回到站点「安全」页,「国家过滤」选「仅允许」,「国家代码」填两位 ISO 代码,逗号分隔,例如 CN, HK;
  3. 下方提示「GeoIP 数据库已加载。」表示过滤会生效;
  4. 点「保存」。

规则:

  • 内网地址始终放行,在家里访问不受影响;
  • 「拒绝」模式下,库里查不到国家的地址放行;「仅允许」模式下只放行列出的国家;
  • 数据库没有加载时过滤不生效(放行所有访客),站点页面会提示「尚未导入 GeoIP 数据库」。

国家过滤对整个站点生效,路径规则无法单独覆盖。出门在外经境外漫游或代理访问时会被拦下,需要时用 IP 白名单之外的手段(登录、端口敲门)补上。

8. 拒绝时断开连接 ​

默认被拦下的请求得到 403 Forbidden。「安全」页的「拒绝方式」改成「断开连接」后,被封禁、IP 访问控制(含路径规则)、敲门准入或国家过滤拒绝的请求不返回任何内容,访问日志记为 444。扫描器看不到 403 页面,也就少了「这里有个受保护的站点」这条信息。

  1. 「拒绝方式」点「断开连接」;
  2. 点「保存」。

拒绝方式、后台登录免认证与信任已登录用户

断开连接的能力边界:

  • 认证失败(登录页、401)、限流(429)与 WAF 拦截不受这个选项影响;
  • TCP 握手与 TLS 握手已经完成,对方仍能确认端口在监听,证书里的域名也已经暴露;
  • HTTP/1.x 下关闭连接,HTTP/2、HTTP/3 下只重置这个请求。

要让反复扫描的地址之后只看到超时,交给入侵防护封禁,开启防火墙同步后在内核层丢弃。

9. 信任已登录用户,以及管理员免登录 ​

站点挂了 WAF 后,家人上传照片、编辑相册时偶尔会被规则误拦;入侵防护的 404 探测、诱饵路径规则也可能把自己人封掉。勾选「信任已登录用户」的「已登录访客跳过 WAF 与路径探测封禁」后,带有本站点 Gately 认证有效凭据的请求不再经过 WAF,也不计入 Web 路径探测。

信任的范围:

  • 只认 Gately 自己签发的凭据:网页认证会话、第三方登录会话、共享用户单点登录、基本认证(首次验证通过后生效);分享链接与转发认证不算;
  • 第三方登录只信任允许列表中逐个写出的身份,靠 github:* 这类通配登录的访客照常经过 WAF;
  • 封禁、IP 访问控制、国家过滤、限流照常生效,登录失败照常计数;
  • 开启后这些用户的请求不再受 WAF 保护,只在用户可信时开启。

后台登录免认证。 同一页的「后台登录免认证」勾选后,已登录 Gately 管理后台的管理员访问本站点无需再输入账号。前提是第 1 步设置了单点登录域,并且管理员经该域下的站点、用 HTTPS 访问后台。站点与后台不在同一个父域时,在全局设置里填「后台入口地址」,细节见 Web 服务 · 路径规则下的说明。

10. 组合示例:完整设置一览 ​

把前面的步骤合在一起,家庭相册站点 photos.example.com 的「安全」页最终是这样:

设置值效果
认证网页认证浏览器打开先登录
共享用户使用共享用户家人用「认证用户」页的账号登录,可用 TOTP、Passkey,example.com 下单点登录
第三方登录github:octocat管理员自己可以用 GitHub 登录
IP 访问控制关闭家人在外面用手机网络也能打开
优先拒绝名单订阅的恶意 IP 列表(可选)已知恶意来源直接拦下
路径规则/api 无需认证;/admin IP 白名单 192.168.1.0/24相册 App 正常同步;管理页只在家里内网能开,且仍需登录
国家过滤仅允许 CN, HK境外扫描流量拦在登录页之前
拒绝方式断开连接被来源检查拦下的请求不返回任何内容
WAF 实例选一个实例未登录的请求经过 WAF
信任已登录用户勾选登录后的家人不被 WAF 误拦

Gately 的管理入口、路由器、NAS 管理页这类只该在家里打开的服务,建议单独放在一个内网监听(例如 8443 端口,不在路由器上映射)上,站点「IP 访问控制」选白名单 192.168.1.0/24,「拒绝方式」选「断开连接」,再加一层基本认证或网页认证。需要从外面临时打开时,用端口敲门的「敲门准入」与「登录后放行」,或经组网回家。

验证 ​

把下面的域名换成你的站点。

bash
# 1. 浏览器访问会跳到登录页:返回 302,Location 指向 /__gately_auth/login?next=...
curl -sI -A 'Mozilla/5.0' -H 'Accept: text/html' https://photos.example.com/ | grep -iE '^(HTTP|location)'

# 2. 非浏览器客户端得到 401,并带 WWW-Authenticate: Basic
curl -sI https://photos.example.com/ | head -n 1

# 3. 用没开 TOTP 的共享用户走 Basic 凭据,返回相册的页面(200)
curl -s -o /dev/null -w '%{http_code}\n' -u alice:你的密码 https://photos.example.com/

# 4. /api 免登录:返回相册自己的响应,以 Immich 为例返回 200
curl -s -o /dev/null -w '%{http_code}\n' https://photos.example.com/api/server/ping

# 5. 从外网(例如手机热点)访问 /admin:拒绝方式为断开连接时,HTTP/1.1 下 curl 报 Empty reply from server
curl -sv --http1.1 https://photos.example.com/admin 2>&1 | tail -n 2

在界面上看:

  • 站点行点「日志」,被 IP 名单拒绝的请求在运行日志里是「拒绝 x.x.x.x 访问 photos.example.com(访问控制)」,被国家过滤拒绝的是「(国家过滤:US)」这样的写法;访问日志里断开连接记为 444;
  • 「Web 服务」页的「访客审计」标签与站点行的「连接」能看到已登录访客的用户名;
  • 用家人的账号在浏览器登录一次,打开同一父域下的另一个开了「使用共享用户」的站点,应当无需再次登录。

常见问题 ​

改成白名单后自己也打不开了

先确认 Gately 看到的来源地址:在站点「连接」或运行日志里看你的请求显示的 IP。Gately 前面有 CDN 或反向代理时,日志里全是代理的地址,要先配「可信代理」;Docker bridge 网络下外部访客可能显示为 172.x 网桥地址,改用 host 网络。白名单只引用了订阅列表而列表还没下载成功时,也会拒绝所有人。实在进不去时,在内网用 Gately 管理界面把站点「IP 访问控制」改回「关闭」。

手机 App 连不上,网页正常

App 不会处理 Gately 的登录页。用第 5 步的路径规则把 App 使用的 API 路径设为「无需认证」,或改用 IP 白名单、国家过滤这类对 App 透明的手段。各应用的情况见给 Jellyfin、Immich 等加 HTTPS 和登录最后一节。

登录页一直提示过于频繁,或者 IP 被封了

同一来源 15 分钟内认证失败累计 10 次后暂时拒绝继续尝试。「Web 服务 → 全局设置 → 自动封禁 → 认证失败封禁」填了分钟数时,达到 10 次会封禁来源 IP(IPv6 按 /64 计)。在同一处的「封禁列表」点「解除」;开启了入侵防护时到「入侵防护」页管理封禁。

登录页没有「使用 GitHub 登录」按钮

检查三处:全局设置里填了「回调地址」并添加了这个登录方式;站点「第三方登录」里写了以该标识开头的身份(如 github:...);保存了全局设置和站点。点按钮后被拒绝时,看监听的运行日志里的原因,常见的是回调地址登记错误、从未在站点中填写的域名或端口发起登录。

登录页没有 Passkey 按钮

需要同时满足:「认证用户」页打开了「Passkey 登录」并保存;站点勾选了「使用共享用户」;站点填写了精确域名(通配域名站点与默认站点没有 Passkey 入口);通过 HTTPS 和域名访问;浏览器支持 Passkey。

开了 TOTP 的家人用 WebDAV 或命令行登录失败

基本认证没有地方填动态验证码,只接受未启用 TOTP 的共享用户。给这类客户端单独建一个不开 TOTP 的共享用户,或在站点「用户」里加一个站点自有账号。

国家过滤没有效果

看站点「安全」页国家代码下方的提示。显示「尚未导入 GeoIP 数据库」时过滤不生效,按第 7 步导入。内网地址始终放行,从家里测试看不到效果,用手机网络或境外 VPS 测试。

下一步 ​

演示:网页认证、共享用户、IP 白名单与国家过滤(约 1 分钟)

以 Apache-2.0 许可证开源发布。