访问控制

访问控制功能支持配置 IP 黑白名单，可以只允许特定 IP 访问 NetPanel 管理界面，或者屏蔽某些恶意 IP，是保护管理界面安全的重要手段。

技术原理

IP 访问控制机制

访问控制在请求到达 NetPanel 处理逻辑之前进行 IP 检查，根据配置的模式和 IP 列表决定是否允许访问：

客户端请求
    │
    ▼
┌─────────────────────────────────┐
│         IP 访问控制层            │
│                                 │
│  获取客户端 IP                   │
│         │                       │
│         ▼                       │
│  ┌─────────────┐                │
│  │  黑名单模式  │                │
│  │  IP 在黑名单? → 是 → 拒绝 403 │
│  │      │                       │
│  │      否 → 放行               │
│  └─────────────┘                │
│                                 │
│  ┌─────────────┐                │
│  │  白名单模式  │                │
│  │  IP 在白名单? → 是 → 放行    │
│  │      │                       │
│  │      否 → 拒绝 403           │
│  └─────────────┘                │
└─────────────────────────────────┘
    │
    ▼
 NetPanel 处理逻辑

黑名单 vs 白名单

模式	工作方式	适用场景
黑名单模式	拒绝列表中的 IP，允许其他所有 IP	屏蔽已知恶意 IP，对大多数用户开放
白名单模式	只允许列表中的 IP，拒绝其他所有 IP	仅允许特定 IP 访问，安全性最高

CIDR 网段匹配原理

访问控制支持 CIDR（无类别域间路由）表示法，可以一次性匹配整个 IP 网段：

格式	示例	匹配范围
单个 IPv4	`192.168.1.100`	仅匹配该 IP
/24 网段	`192.168.1.0/24`	192.168.1.0 ~ 192.168.1.255
/16 网段	`192.168.0.0/16`	192.168.0.0 ~ 192.168.255.255
/8 网段	`10.0.0.0/8`	10.0.0.0 ~ 10.255.255.255
单个 IPv6	`2001:db8::1`	精确匹配单个 IPv6
IPv6 网段	`2001:db8::/32`	匹配 IPv6 网段

功能概述

黑名单模式：拒绝黑名单中的 IP 访问，其他 IP 正常访问
白名单模式：只允许白名单中的 IP 访问，其他 IP 全部拒绝
支持单个 IP 和 CIDR 网段
支持 IPv4 和 IPv6
实时生效，无需重启服务

配置说明

进入 访问控制 页面：

字段	类型	必填	默认值	说明
启用访问控制	布尔	✅	`false`	是否启用 IP 访问控制
控制模式	枚举	✅	`黑名单`	`黑名单` 或 `白名单`
IP 列表	文本	✅	—	每行一个 IP 或 CIDR 网段

配置步骤

配置黑名单（屏蔽恶意 IP）

进入 访问控制 页面
将控制模式设置为 黑名单
在 IP 列表中填入要屏蔽的 IP 或网段，每行一条
启用访问控制
点击保存，立即生效

配置白名单（仅允许特定 IP）

操作前必读

启用白名单模式前，务必先确认你当前的 IP 已在白名单中，否则保存后你将立即无法访问 NetPanel 管理界面！

查询你当前的公网 IP（可访问 ip.sb 查询）
进入 访问控制 页面
将控制模式设置为 白名单
在 IP 列表中填入允许访问的 IP 或网段（包含你当前的 IP）
启用访问控制
点击保存

配置示例

示例 1：只允许局域网访问

白名单模式，只允许局域网 IP 和本机访问 NetPanel：

字段	值
控制模式	白名单
IP 列表	`192.168.0.0/16`（家庭局域网） `10.0.0.0/8`（企业内网） `172.16.0.0/12`（Docker 内网） `127.0.0.1`（本机）

示例 2：屏蔽特定恶意 IP

黑名单模式，屏蔽已知的恶意 IP 或扫描来源：

字段	值
控制模式	黑名单
IP 列表	`1.2.3.4` `5.6.7.0/24` `8.8.8.8`

示例 3：配合 EasyTier 异地访问

如果通过 EasyTier 虚拟组网远程访问 NetPanel，需要将 EasyTier 虚拟 IP 网段加入白名单：

字段	值
控制模式	白名单
IP 列表	`192.168.0.0/16`（本地局域网） `10.144.144.0/24`（EasyTier 虚拟网段） `127.0.0.1`（本机）

示例 4：办公室 + 家庭双白名单

允许办公室和家庭两个固定 IP 访问：

字段	值
控制模式	白名单
IP 列表	`203.0.113.10`（办公室公网 IP） `198.51.100.20`（家庭公网 IP） `127.0.0.1`（本机）

安全最佳实践

推荐使用白名单模式

对于 NetPanel 管理界面，强烈建议使用白名单模式，只允许已知的 IP 访问。这是最安全的配置方式。

结合 VPN/组网使用

将 NetPanel 管理界面设置为只允许 VPN/EasyTier 虚拟 IP 访问，通过 VPN 连接后才能管理，安全性极高。

定期检查 IP 列表

如果使用动态公网 IP，需要在 IP 变化时及时更新白名单。可以配合 DDNS 使用固定域名，或使用 EasyTier 组网避免 IP 变化问题。

与防火墙配合

访问控制针对 NetPanel 管理界面，防火墙针对所有网络流量。两者配合使用，形成多层防护。

常见问题

Q：启用白名单后无法访问 NetPanel 怎么办？

如果被锁定在外，可以通过以下方式恢复：

在服务器本机通过 127.0.0.1 访问（本机访问不受访问控制限制）
通过 SSH 登录服务器，直接修改 NetPanel 数据库中的访问控制配置
重启 NetPanel 并在启动参数中临时禁用访问控制

Q：如何获取当前公网 IP？

访问以下任一网站查询：

https://ip.sb
https://ifconfig.me
命令行：curl ip.sb

Q：访问控制对 API 接口也生效吗？

是的，访问控制对 NetPanel 的所有接口（包括 Web 界面和 API）均生效。

Q：IP 列表支持多少条记录？

IP 列表没有硬性限制，但建议保持在合理范围内（100 条以内），过多的规则可能影响匹配性能。

访问控制 ​

技术原理 ​

IP 访问控制机制 ​

黑名单 vs 白名单 ​

CIDR 网段匹配原理 ​

功能概述 ​

配置说明 ​

配置步骤 ​

配置黑名单（屏蔽恶意 IP） ​

配置白名单（仅允许特定 IP） ​

配置示例 ​

示例 1：只允许局域网访问 ​

示例 2：屏蔽特定恶意 IP ​

示例 3：配合 EasyTier 异地访问 ​

示例 4：办公室 + 家庭双白名单 ​

安全最佳实践 ​

常见问题 ​