文档
网关（Gateway）
Index

Gateway 安全

Moltbot 的 Gateway 安全模型旨在将服务暴露给 LAN 和 tailnet，同时默认将凭证和认证流量限制在本地环回网络。

  • 默认绑定：loopback（127.0.0.1）— Gateway 仅接受来自 localhost 的连接。
  • 远程访问：通过 Tailscale Serve/Funnel 或 SSH 隧道暴露。
  • 认证：对于非环回绑定始终需要（令牌或密码）。
  • Tailscale 集成：可选的身份标头认证（gateway.auth.allowTailscale）。

参见 /zh-cn/docs/gateway/tailscale 了解 Tailscale 特定指南。

认证模式

令牌认证（默认）

向导默认生成 Gateway 令牌。

配置：

{
  gateway: {
    auth: { mode: "token", token: "your-secret-token" }
  }
}

或设置 MOLTBOT_GATEWAY_TOKEN。

密码认证 

{
  gateway: {
    auth: { mode: "password", password: "your-password" }
  }
}

或设置 MOLTBOT_GATEWAY_PASSWORD。

对于 tailscale.mode: "funnel" 需要密码认证（Funnel 不支持 WS 标头，因此令牌认证不可行）。

Tailscale 身份认证（无凭证）

使用 Tailscale Serve 时，您可以跳过显式凭证并依赖 Tailscale 身份标头：

{
  gateway: {
    auth: {
      mode: "password",
      allowTailscale: true  // 允许 Tailscale 身份满足认证
    }
  }
}
  • 设置 allowTailscale: true 后，您的 tailnet 上的客户端通过 Tailscale-User-Name 标头自动认证。
  • 设置 allowTailscale: false 以要求即使在 Tailscale 上也有显式令牌/密码。
  • 不使用 Tailscale Serve 时，allowTailscale 无效。

绑定模式

模式绑定地址需要认证？用例
loopback127.0.0.1否（但推荐）仅本地，通过隧道/Serve 代理
lan0.0.0.0是本地网络访问
tailnet0.0.0.0是直接 tailnet 绑定（非 Serve）
auto操作系统依赖是自动检测

非环回绑定需要共享令牌/密码（gateway.auth 或 env）。

Tailscale 集成

Serve（推荐）

将 Gateway 保持在环回上，让 Tailscale Serve 代理它：

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" }
  }
}

然后启动 gateway：

moltbot gateway

打开：https://<magicdns>/（或您配置的 gateway.controlUi.basePath）。

使用 Serve，您可以使用 gateway.auth.allowTailscale: true 跳过显式凭证。

Funnel（公共互联网） 

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password" } // 或 MOLTBOT_GATEWAY_PASSWORD
  }
}

Funnel 通过 Tailscale 将 Gateway 暴露给公共互联网。密码认证是必需的（Funnel 不支持用于令牌认证的 WS 标头）。

Tailnet 绑定 

{
  gateway: {
    bind: "tailnet",
    controlUi: { enabled: true },
    auth: { mode: "token", token: "your-token" }
  }
}

然后启动 gateway（非环回绑定需要令牌）：

moltbot gateway

打开：http://<tailscale-ip>:18789/（或您配置的 gateway.controlUi.basePath）。

安全清单

  • Gateway 默认绑定到 loopback（检查 gateway.bind）。
  • 非环回绑定设置了共享令牌/密码。
  • 如果您想在 Tailscale 上要求显式凭证，gateway.auth.allowTailscale 设置为 false。
  • 对于 Funnel，配置了密码认证（gateway.auth.mode: "password"）。
  • 机密存储在 ~/.moltbot/ 中，具有限制性权限（chmod 700）。
  • 如果使用 SSH 隧道，隧道使用密钥保护，而不是密码。

Webhooks 安全

当 hooks.enabled=true 时，Gateway 在同一 HTTP 服务器上暴露 webhook 端点。

参见 Gateway 配置 → hooks 了解 webhook 认证 + 负载。

安全模型（形式化验证）

Moltbot 的形式化安全模型（今天的 TLA+/TLC；根据需要更多）位于 /zh-cn/docs/security/formal-verification。

这些模型证明：

  • 机密性：机密永远不会离开本地环回网络。
  • 完整性：只有经过身份验证的客户端才能改变 Gateway 状态。
  • 可用性：Gateway 在 DoS 条件下保持响应。

常见安全陷阱

  • 在没有认证的情况下将 Gateway 暴露给公共互联网：仅在使用密码认证时使用 tailscale.mode: "funnel"。
  • 使用弱密码：通过向导或 openssl rand -hex 32 生成强令牌/密码。
  • 以明文存储机密：CLI 将机密存储在 ~/.moltbot/ 中，具有限制性权限；避免将它们复制到可读位置。
  • 通过不安全渠道共享凭证：使用 Tailscale Serve 或 SSH 隧道，而不是通过纯 HTTP 发送令牌/密码。
  • 以 root 身份运行：Gateway 以您的用户身份运行；除非必要，避免 sudo（例如，系统服务安装）。

审计

运行 moltbot security audit 以检查常见安全陷阱：

moltbot security audit
moltbot security audit --deep  # 包括实时 Gateway 探测
moltbot security audit --fix   # 应用安全修复

参见 /zh-cn/docs/cli/security 了解详情。

Bonjour / mDNS 发现