mistgate 文档
中文

在管理后台：设置

安全

了解管理后台的权限、登录、重新验证和会话机制，面板如何通过伪装站点隐藏管理后台，数据目录包含哪些内容，以及如何从面板服务器恢复访问权限。

本页内容

本页介绍管理后台的防护机制：角色、登录、重新验证、会话、人机验证、审计日志、前置伪装站点、已保存的 SSH 凭据、数据目录，以及如何从面板服务器恢复访问权限。报告漏洞的方法见本页末尾。

管理员角色#

管理后台支持三种角色。每个请求都会按操作权限检查；没有单独规则的操作需要所有者权限。

角色 权限
所有者 全部权限：节点（添加、通过 SSH 安装、退役、查看日志、管理已保存的 SSH 凭据）、协议配置及其部署位置、DNS 预设以及节点向用户提供的预设、诊断修复、节点和面板更新、WARP、备份、API 令牌和审批、审计日志、安全和品牌设置。
协作者 日常操作：用户（创建、更改、启用和停用、续期、重置流量、删除、管理设备和订阅链接）、分组、订阅设置、重置用户在页面上选择的 DNS、节点设置（所有者专属的客户端 IPv6除外）以及重启节点上的协议配置、静默告警、立即检测、运行诊断、接受诊断警告。
只读 查看：概览、节点、协议配置（密钥已隐藏）、分组、DNS 预设、订阅设置、用户、事件、告警、检测结果、诊断报告和更新页面。还可以管理自己的账户：通行密钥、密码和会话。
注意

目前面板只有一位管理员，即设置时创建的所有者；暂时无法添加协作者或只读管理员。角色目前已用于 API 令牌，令牌权限级别对应这些角色。

登录#

所有者通过 mistgate setup 输出的一次性链接创建（有效期为 30 分钟；如果没有管理员时再次运行 setup，会生成新链接并使旧链接失效）。所有者可以选择以下两种登录方式之一，之后也可以在 设置 → 安全 中添加另一种。

通行密钥。使用指纹、人脸或安全密钥登录。无需填写用户名；浏览器会提供此面板对应的通行密钥。每次都需要用户验证（PIN 或生物识别）。通行密钥绑定到管理员地址（设置时指定的 WebAuthn 依赖方），因此只能在该地址使用。

密码和身份验证器验证码。需要用户名（3 到 64 个字符，只能包含 a-z 0-9 . _ @ -）、密码（至少 12 个字符，最多 256 字节）以及身份验证器应用生成的 6 位验证码（基于时间，每 30 秒更新一次）。密码以 argon2id 哈希形式存储（19 MiB，2 轮），并使用主密钥派生的 pepper，因此仅有数据库副本不足以离线尝试密码；旧哈希会在下次登录时升级；身份验证器密钥使用主密钥加密，没有主密钥的面板无法提供此登录方式。每个验证码只能使用一次。

密码登录限制：

  • 一小时内同一用户名登录失败 5 次，会锁定该用户名 15 分钟，即使随后输入了正确凭据也一样。
  • 一小时内同一地址（IPv4 地址或 IPv6 /64）登录失败 10 次，会锁定该地址 15 分钟，适用于任何用户名。
  • 登录名不存在时返回的结果也相同，因此失败响应不会泄露哪些登录名真实存在。
  • 登录、初始设置和重新验证请求也按地址速率限制（突发最多 10 次，之后每 3 秒允许一次请求）。
  • 锁定事件会连同地址和时间写入审计日志。如果已关联 Telegram，所有者会立即收到通知：参见 Telegram 告警，其中还介绍了如何通知新地址登录和登录方式变更。

管理员可以在 设置 → 安全 中管理自己的登录方式：

  • 通行密钥：可以添加（需要重新验证）或移除（需要重新验证；不能移除最后一种登录方式）。
  • 密码与验证码：可以在通行密钥之外添加密码登录作为备用方式；更改密码（需要重新验证和当前密码，并会结束其他会话）；为新手机重新绑定应用（需要重新验证，并会结束其他会话）。

重新验证#

被盗的会话 Cookie 不应足以添加通行密钥、移除所有者的通行密钥或更改节点上运行的内容。以下操作需要最近 5 分钟内的登录凭据证明：

  • 添加或移除通行密钥；
  • 结束另一个会话或所有其他会话；
  • 更改密码或绑定身份验证器应用；
  • 更改人机验证设置；
  • 启动、暂停、继续或取消滚动更新，回滚节点，再次读取发布目录，安装面板更新，定时更新节点或取消定时任务，更改更新时区；
  • 验证 SSH 登录，以及通过 SSH 启动或重试安装；
  • 更改、查看或清除节点已保存的 SSH 密码；
  • 注册、导入或删除 WARP 账户；
  • 保存备份设置、测试备份存储、立即创建备份；
  • 创建或吊销 API 令牌，审批 AI 智能体的变更。

登录本身就算作凭据证明，因此「登录后添加通行密钥」无需再次确认。否则，管理后台会显示确认是你本人：使用通行密钥或输入身份验证器验证码。重新验证所用的验证码必须晚于登录时使用的验证码（等待下一个 30 秒周期）。连续输错 5 次会锁定重新验证 15 分钟。API 令牌不能通过重新验证；参见 API。

会话#

  • 会话 Cookie 为 __Host-sid：仅限 HTTPS，脚本无法读取，只会发送给面板本身（SameSite=Strict）。
  • 会话在 12 小时无操作后结束，最长不超过 30 天。
  • 设置 → 会话会列出管理员自己的会话、地址和浏览器。结束会结束一个会话（结束当前会话以外的会话需要重新验证）；结束其他会话会结束其余会话（需要重新验证）。
  • 更改密码、重新绑定应用以及运行 mistgate auth reset-login 也会结束其他会话。

Cloudflare Turnstile#

所有者可以在登录和初始设置页面前启用 Cloudflare Turnstile 检查：设置 → 安全 → 登录时的 Cloudflare 人机验证。

  1. 在 Cloudflare 控制面板中为面板域名创建 Turnstile 小组件。
  2. 输入站点密钥和密钥。密钥为只写字段：面板会使用主密钥加密存储，不会再次显示。
  3. 点击验证并开启，然后通过显示的人机验证。面板会向 Cloudflare 确认密钥与小组件生成的令牌匹配；验证通过前不会保存任何内容。

启用后，每次开始登录（通行密钥或密码）和初始设置时，都需要从小组件获取新的令牌；通行密钥登录的第二步不需要令牌。如果无法连接 Cloudflare，登录会被拒绝。只有启用检查时，管理页面才会加载 Cloudflare 脚本。

如果此检查导致所有人都无法登录（Cloudflare 无法连接或密钥错误），请在面板服务器上将其关闭；密钥仍会保留：

Shell
mistgate auth turnstile off

审计日志#

设置 → 审计（仅限所有者）会按时间倒序列出操作人、操作内容和来源地址。

  • 审计来源：全部来源、面板、机器人、MCP、API。
  • 显示内容：全部；登录（初始设置、登录和退出、锁定、重新验证、人机验证、通行密钥、密码、会话）；变更（用户、分组、协议配置、设备、DNS 预设、节点及其 SSH 安装和已保存的 SSH 凭据、WARP、更新、诊断修复、令牌、审批、设置）；失败（任何类型的失败、拒绝或锁定操作）。备份操作列在「全部」中，失败时也列在「失败」中。
  • 每行包含操作者、操作、参数、结果和客户端地址。参数中绝不包含密钥。
  • 令牌显示为「API 令牌 <name>」或「MCP 令牌 <name>」。令牌成功读取操作按每个操作每分钟最多记录一次；变更和拒绝操作每次都会记录。
  • 命令行操作（mistgate auth ...）显示为「命令行」；面板自身的操作（例如登录锁定、自动重新注册 WARP）显示为「面板自身」；用户在自己的页面上执行的操作显示为「用户本人（在其页面上）」。DNS 相关行包括：node_dns_options（所有者更改节点提供的预设）、link_dns_options（为订阅类应用提供的预设发生变化）、page_dns_choice（用户在自己的页面上为服务器选择 DNS：记录用户名、节点名称和预设，不记录链接或地址）、page_link_dns_choice（用户为自己的订阅类应用选择 DNS：记录用户名和预设）以及 user_dns_choices_reset（管理员重置用户的选项）。参见 DNS。

面板不会清理审计日志。

伪装站点和隐藏的管理后台#

公共监听器上，凡是不属于管理后台、订阅或 Agent 接入端点的请求，都会返回伪装站点。

  • 伪装站点。默认情况下，/ 显示内置的「即将推出」页面，robots.txt 会阻止已知 AI 爬虫；其他所有路径和除 GET、HEAD 以外的请求方式都会显示同一个 404 页面。每个安装都使用相同的内置页面，因此很容易识别；可以使用 serve --decoy-dir <dir> 提供自己的站点。文件响应不包含 Last-Modified 或 ETag；以点开头的文件名不会提供；目录中的 404.html 和 429.html 可替换内置错误页面。

  • 管理后台有三种访问方式，由 mistgate setup 选择：

    • 私密路径前缀（默认）：https://panel.example.com/<24 random characters>/；
    • 私密主机名：setup --admin-host <name>；
    • 单独的监听器：setup --admin-listen 127.0.0.1:8081。它提供普通 HTTP，因此应绑定到回环地址，并通过 SSH 隧道访问。

    错误的前缀或其他主机名会返回伪装站点；不常见的路径形式会返回 404。管理后台不会使用可能泄露路径前缀的重定向。

  • 订阅位于另一个私密路径前缀下。未知订阅令牌会返回与未知路径相同的 404；每个 404 至少耗时 8 ms，因此无法通过内容、响应头或响应时间判断猜测的令牌与错误路径的区别。

  • Agent 接入端点使用私密 TLS 服务器名称选择：它是面板域名下的随机标签，无需 DNS 记录。面板使用自己的 CA 签发证书响应；该证书不会出现在公开证书日志中，也不会显示产品名称。没有正确名称的客户端会看到伪装站点。

  • 速率限制按客户端网段（IPv4 地址或 IPv6 /64）执行：公共站点和订阅每秒 10 个请求（突发 60 个），管理后台每秒 30 个请求（突发 200 个），Agent 接入端点每秒 5 个请求（突发 30 个）。超过限制后会返回采用伪装站点样式的 429 页面，并附带 Retry-After。

  • 管理页面使用严格的 Content-Security-Policy，禁止嵌入框架，不发送 referrer，设置 noindex 和 no-store；HTTPS 上还会启用 HSTS。

设置 → 域名会向所有者显示管理后台地址和订阅链接基础地址。两者都包含私密部分；不要公开。使用反向代理时，请通过 serve --trusted-proxy 配置代理列表，以便面板看到真实客户端地址（速率限制、会话和审计日志都依赖这些地址）。所有标志见配置。

已保存的 SSH 凭据#

通过 SSH 安装的节点会将 SSH 登录信息保存在面板中：地址、端口、用户名、密码和固定的主机密钥。密码使用主密钥加密。只有所有者能在节点的设置中的SSH 凭据下查看这些信息。使用方法见通过 SSH 安装节点中的「已保存的 SSH 凭据」。

  • 只有服务器提供所有者确认过的主机密钥后，面板才会发送密码。主机密钥发生变化时，面板不会发送密码。
  • 显示密码需要重新验证，并会写入审计日志。API 读取、MCP 工具和日志都不会返回密码。
  • AI 智能体永远看不到密码。通过 MCP 安装时，由所有者在审批界面输入密码。AI 智能体可以请求更改密码，并由所有者审批计划；随后由面板生成新密码，在所有者查看之前只有面板知道该密码。
  • 所有者在安装管理器中更改密码或使用自动生成的新密码时，面板都会先使用新的 SSH 登录验证，然后再保存新密码。
  • 退役节点时会保留已保存的凭据，因为密码可能只有面板知道。之后选择清除已保存的凭据会永久删除凭据；此操作需要重新验证。

数据目录#

面板掌握的所有信息都位于数据目录中，默认路径为 /var/lib/mistgate（权限模式 0700）：

路径 内容
master.key 32 个随机字节，权限模式 0600。此密钥使用 XChaCha20-Poly1305 加密所有已存储的密钥。面板也可以从 systemd 凭据（$CREDENTIALS_DIRECTORY/master.key）读取它。
mistgate.db（以及 -wal 和 -shm） SQLite 数据库，权限模式 0600：用户、节点、协议配置、会话、审计日志，以及使用主密钥加密私钥的面板 CA。
acme/ 使用 serve --acme-domain 时保存的 Let’s Encrypt 证书。
dist/ 节点 Agent 发布包（参见更新）。
release.pub 此安装的发布公钥：第一个带有发布密钥的构建会保存该密钥，使用它校验节点发布包。若面板二进制编译时使用了另一个密钥，在运行 mistgate release trust-key 前不会信任任何发布包。

节点 Agent 不会在会话报告中发送 VPN 客户端 IP 地址，面板也不会在实时会话视图中存储这些地址。

存储的密钥包括协议配置密钥和设备密钥、身份验证器密钥、Turnstile 密钥、WARP 密钥、已保存的 SSH 密码以及备份使用的 R2 机密访问密钥。用户页面密码不会存储；它们由主密钥派生。因此，更换主密钥会更改所有页面密码，并导致所有已存储的密钥无法读取。丢失数据目录后，必须重新注册所有节点（节点信任面板的 CA），并为用户提供新链接。

危险

丢失的 master.key 无法通过新密钥替代；请从备份中恢复它。如果已有数据库，mistgate serve 和 mistgate setup 都会拒绝生成新密钥。

备份#

可以在 设置 → 备份中配置仅限所有者操作的 Cloudflare R2 加密备份。完成配置前，备份保持关闭。每个备份在上传前都会由面板加密到 age 公钥（recipient），因此 R2 存储桶中不会有可读取的副本；私有恢复私钥会由你离线保管。启用前请阅读面板加密备份，其中介绍了令牌权限、定时任务、保留期限以及如何恢复到新的数据目录。

手动复制无需使用 R2。停止面板后创建副本：

Shell
systemctl stop mistgate     # 你的服务单元名称
tar czf mistgate-backup-$(date +%F).tgz -C /var/lib mistgate
systemctl start mistgate
警告

副本中包含 master.key；持有该密钥的人可以读取面板的所有密钥。请对副本加密，并将其保存在面板服务器之外。如果 systemd 通过凭据向面板提供密钥，该密钥就不在数据目录中；请将凭据与副本一同保存，否则无法读取副本。

恢复时，停止面板，将目录放回原处（所有者应为运行面板的用户，权限模式为 0700），然后启动面板。

恢复访问权限#

以下命令都在面板服务器上运行，并使用有权读取数据目录的账户（通常为 root）。面板运行或停止时都可以执行。如果数据不在 /var/lib/mistgate，请添加 --data-dir <dir>。reset-login 需要主密钥：如果密钥不在数据目录中，而是由 systemd 凭据提供给面板，请将 CREDENTIALS_DIRECTORY 设为包含 master.key 的目录。

手机丢失（密码登录）。

Shell
mistgate auth reset-login <login>

命令会输出新密码和新的身份验证器密钥：以适用于深色背景的终端二维码显示（浅色背景请添加 --qr-invert），以四位一组的文本显示，并提供 otpauth:// 链接。它会解除该登录名和重新验证的锁定，并结束该管理员的所有会话。通行密钥会保留。使用登录名、密码和验证码登录，然后在 设置 → 安全 中设置自己的密码。密码只显示一次，不会以明文存储在任何位置。

没有可用的通行密钥（管理员只使用通行密钥）。不带参数时，命令会列出管理员；通过 ID 为管理员添加密码登录：

Shell
mistgate auth reset-login
mistgate auth reset-login <new login> --admin <admin id>

然后使用密码登录，并在 设置 → 安全 中移除丢失的通行密钥。

人机验证导致无法登录：mistgate auth turnstile off。

管理后台地址丢失：再次运行 mistgate setup。它会保留现有设置并输出管理后台 URL。

API 令牌和 MCP 永远无法读取的内容#

API 令牌和 MCP 服务器通过与管理后台相同的操作访问面板，但令牌只能调用固定操作列表，而且这些操作都不会返回凭据：

  • 订阅链接、用户页面密码、设备密钥和设备配置；
  • WARP 账户和密钥、协议配置密钥（返回时会隐藏）；
  • 已保存的 SSH 密码（令牌只能查看已保存凭据的连接详情：地址、端口、用户名和主机密钥）；
  • 备份及其设置；
  • 令牌、审批、会话、通行密钥和安全设置。

令牌无法通过重新验证，因此除非所有者通过 MCP 计划审批，否则令牌无法执行需要重新验证的操作。每次令牌调用都会写入审计日志。请为每个脚本或智能体选择满足需求的最小权限级别。详情见 API 和 MCP。

报告安全漏洞#

请通过 GitHub 私下报告：打开仓库的 「安全」 标签页，并选择 「报告安全漏洞」。不要创建公开问题。仓库中的 SECURITY.md 说明哪些问题属于报告范围，哪些不属于。

在 GitHub 上编辑此页