访问控制

“访问控制”仅管理员可见，包含“面板黑白名单”“可信代理”和“游戏黑名单”三个部分。面板黑白名单只限制 Web 管理面板访问；游戏黑名单通过原生 RCON 管理 L4D2 服务端封禁，两者互不影响。

面板黑白名单和可信代理统一在管理面板中配置，不使用旧的名单环境变量。配置保存后立即生效，无需重启管理器。面板访问判断在登录页、静态资源和全部 API 之前执行。

快速配置

1. 使用管理员身份登录，打开“访问控制”。
2. 在“面板黑白名单”Tab 中添加规则，并开启需要生效的规则。
3. 打开页面顶部的“启用面板黑白名单”总开关。
4. 可在“规则预览”中输入 IPv4 或 IPv6，确认草稿的判断结果。
5. 点击“保存”。

规则未生效时先检查总开关

单条规则右侧的启用开关只决定该规则是否参与判断。顶部总开关关闭时，所有面板黑白名单规则都只是已保存的停用草稿，不会拦截访问。修改后还需要点击“保存”。

“面板黑白名单”和“可信代理”两个 Tab 独立保存。多名管理员同时修改配置时，后保存的一方可能收到配置冲突提示；刷新配置后再重新编辑即可。“游戏黑名单”读取游戏服务器当前状态，添加和删除会立即执行，不使用草稿或保存按钮。

面板黑白名单

规则支持以下三种类型：

类型	示例	匹配方式
地区关键字	中国、广东、电信	对 ip2region 原始查询结果进行区分大小写的子串匹配。
单 IP	203.0.113.10、2001:db8::10	只匹配指定的 IPv4 或 IPv6 地址。
CIDR 网段	192.168.1.0/24、2001:db8::/32	匹配网段内的全部地址。

每条规则可以单独启用或停用，并可填写备注。相同名单内不能保存类型和值完全相同的重复规则。如果一个单 IP 已包含在同名单的 CIDR 中，额外添加该单 IP 没有作用。

判断顺序

管理器按以下顺序判断最终客户端 IP：

1. 127.0.0.0/8 和 ::1 回环地址始终允许。
2. 顶部总开关关闭时允许访问。
3. 命中任意已启用的面板黑名单规则时立即拒绝。
4. 没有已启用的面板白名单规则时允许访问。
5. 存在已启用的面板白名单规则时，至少命中一条才允许访问。

因此，面板黑名单优先于面板白名单。普通局域网地址不会因为属于 10.0.0.0/8、172.16.0.0/12 或 192.168.0.0/16 而自动放行；需要限制访问时，应显式添加实际使用的局域网 CIDR 白名单。

地区规则依赖管理器随包提供的 ip2region_*.xdb 数据文件。仅当当前判断需要地区规则时才会查询 GeoIP；此时 GeoIP 不可用会返回 503，避免在无法确认地区时错误放行。

防止锁定当前管理员

保存已启用的面板黑白名单时，服务端会先用草稿检查当前管理员：

• 当前管理员命中面板黑名单，拒绝保存。
• 存在已启用的面板白名单，但当前管理员未命中，拒绝保存。

被拒绝的配置不会写入文件，原配置继续生效。顶部总开关关闭时，可以先保存尚未放行当前管理员的草稿；以后打开总开关并保存时仍会重新检查。

回环地址始终允许，因此在服务器本机通过 127.0.0.1 或 ::1 访问时，不会被普通黑白名单规则拦截。

可信代理

可信代理用于决定管理器能否接受 X-Forwarded-For 和 X-Real-IP 中的客户端地址。它不是允许访问面板的白名单，只应填写实际由你控制、并且会直接连接管理器的反向代理 IP 或 CIDR。

配置文件首次创建时默认信任：

127.0.0.0/8
::1/128

这两个默认值适合 Nginx、Caddy 等代理与管理器运行在同一台主机的情况。可信代理列表支持单 IP 和 CIDR，禁止使用会信任全部来源的 0.0.0.0/0 与 ::/0。显式清空列表并保存后，重启仍会保持为空。

客户端 IP 识别

• TCP 对端不可信：忽略所有转发头，使用 TCP 对端地址。
• TCP 对端可信且存在 X-Forwarded-For：从右向左检查地址链，跳过已配置的可信代理，取第一个不可信地址作为客户端 IP。
• TCP 对端可信但没有 X-Forwarded-For：使用 X-Real-IP；两者都没有时仍使用 TCP 对端地址。
• 可信代理发送格式错误的转发头：请求返回 400。

多层代理时，需要把所有由你控制并可能出现在地址链右侧的代理网段加入列表。不要填写访客、办公网终端或整个互联网网段，否则客户端可以伪造转发头。

例如，Nginx 直接连接管理器时可传递：

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;

随后在“可信代理”Tab 中添加 Nginx 连接管理器时实际使用的源地址。Docker 部署通常是反向代理容器所在的桥接网段，例如 172.18.0.0/16；应以本机实际网络为准，不要直接照抄示例。

本机反向代理

如果本机代理没有被识别为可信代理，管理器只会看到代理的回环地址，而回环地址始终允许。使用本机反向代理时，应保留对应的回环可信代理，并确保代理正确传递客户端地址。

保存可信代理时，如果面板黑白名单已启用，服务端会使用代理草稿重新识别当前管理员并执行同样的防锁定检查。新配置会让当前连接被拒绝时，保存不会生效。

游戏黑名单

“游戏黑名单”Tab 通过原生 RCON 实时读取和修改游戏服务器内存中的封禁列表，不依赖 SourceMod 封禁插件。进入该 Tab 时才会连接游戏服务器，因此 RCON 不可用不会影响面板黑白名单或可信代理的配置。

SteamID 封禁

添加 SteamID 时支持以下格式：

• Steam2，例如 STEAM_1:1:123456；
• Steam3，例如 [U:1:246913]；
• Steam64，例如 76561197960512641。

管理器会将输入统一转换为 Steam2 后执行 banid。添加封禁时始终带有 kick 参数；玩家当前在线时会被立即踢出。原生列表不保存备注或封禁原因，因此页面只展示 ID 和剩余时长。

IP 封禁

IP 封禁仅接受单个 IPv4，例如 203.0.113.10，不支持 CIDR、端口或 IPv6。页面始终将 listip 返回的内容作为游戏 IP 黑名单管理。

永久和计时封禁

• 永久 SteamID/IP 封禁会分别执行 writeid 或 writeip，写入 banned_user.cfg 或 banned_ip.cfg。
• 计时封禁按分钟执行，只存在于当前游戏服务器进程中，游戏服务端重启后失效。
• 页面“刷新”会重新执行 listid 和 listip，因此通过 RCON 控制台、游戏控制台或其他工具产生的变化也会显示出来。

管理器会自动在 server.cfg 和现有 tick 配置中维护加载封禁文件的隐藏区块。该区块位于管理器自定义配置标记之前，不会出现在“服务器配置”的自定义项中：

// [L4D2-MANAGER-GAME-BANS]
exec banned_user.cfg
exec banned_ip.cfg

游戏黑名单的可视化接口仅管理员可用。现有 RCON 控制台的角色权限保持不变；通过 RCON 控制台直接修改列表后，返回游戏黑名单并刷新即可看到最新结果。

统一客户端 IP

解析后的最终客户端 IP 会统一用于：

• 面板黑白名单判断；
• 登录失败限流；
• 自助授权限制与记录；
• 操作审计中的 IP。

被访问控制直接拒绝的请求发生在登录和业务接口之前，因此不会作为一条普通业务操作出现在“操作审计”中；后端日志会记录被拒绝的最终客户端 IP。

配置文件与恢复

配置保存在 data/access_control.json。管理器会原子写入并热更新运行中的完整配置，不建议在服务运行时手工编辑该文件。

文件不存在时，面板黑白名单默认关闭，可信代理使用上述回环默认值。文件损坏或版本无法识别时，管理器进入恢复模式：只有 TCP 直连回环地址可以访问，其他请求返回 503。管理员可在服务器本机打开面板并保存有效配置；保存成功后即可退出恢复模式。

常见响应

状态码	含义
400	可信代理提供了非法转发头，或保存的规则格式无效。
403	当前 IP 被面板访问规则拒绝，或非管理员尝试读取、修改访问控制配置。
409	草稿会锁定当前管理员、配置已被同时修改，或游戏封禁状态冲突。
502	游戏服务器返回了无法完整解析或无法验证的封禁结果。
503	地区规则需要 GeoIP 但服务不可用、配置文件损坏后处于恢复模式，或游戏服务器 RCON 不可用。