企业官网建设流程全解析

GBrain 远程 MCP 服务器部署方案全解：ngrok、Tailscale 与云主机对比与实战

【免费下载链接】gbrainGarry's Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain

GBrain 的 MCP 服务器默认以 stdio 传输运行（gbrain serve），仅供本机 Agent 使用。本文基于 docs/mcp/ALTERNATIVES.md 与 docs/mcp/DEPLOY.md 等配套文档，系统讲解如何借助内置 HTTP 传输（gbrain serve --http）与公网隧道，把大脑安全地暴露给其他设备与 AI 客户端，并逐项对比 ngrok、Tailscale Serve/Funnel、Fly.io/Railway 三种主流方案的适用场景、成本与安全性。读完本文，你将能够按自己的隐私要求与预算，选型并完成一套可远程访问、带 OAuth 2.1 认证的 GBrain MCP 服务。

前置：gbrain serve --http内置 HTTP 传输

一切远程部署都建立在同一个前提之上：GBrain 自带一个内置 HTTP 传输，无需任何额外服务即可让远程客户端通过 MCP 协议访问大脑。

gbrain serve --http --port 8787

从源码结构看，--http在 src/commands/serve.ts 中分发到独立的runServeHttp（实现在 src/commands/serve-http.ts），该模块组合了 MCP SDK 的mcpAuthRouter（OAuth 端点：/authorize、/token、/register、/revoke）、工具调用端点/mcp、位于/admin的内置 React 管理面板、/admin/events的 SSE 实时活动流以及/health健康检查。它同时支持 PGLite 与 Postgres 两种引擎的 brain，是远程部署唯一的正式推荐路径。

gbrain serve --http开箱即带以下安全与审计能力（详见 docs/mcp/DEPLOY.md 与 SECURITY.md）：

• OAuth 2.1 全套协议：客户端凭证（client credentials）、授权码 + PKCE、刷新令牌轮换，可选动态客户端注册（DCR）。
• Legacy bearer 兼容：verifyAccessToken会回退到access_tokens表；未带scopes的令牌默认携带read+write+admin，用gbrain auth create --scopes …铸造的令牌则严格按其授予的 scope 生效。
• 默认拒绝的 CORS、双桶限流、请求体大小上限、按请求审计日志（mcp_request_log）。

关键启动参数（默认值取自 src/commands/serve.ts）：

方案一：ngrok 公网隧道（推荐）

ngrok 提供即时的公网隧道。Hobby 档（约 $8/月）提供永不变化的固定域名，这是推荐它的核心理由：免费档的 URL 每次重启都会变化，会连带打断 Twilio webhook、Claude Desktop 等所有依赖固定地址的集成。

# 1. 安装 ngrok brew install ngrok # 2. 启动内置 HTTP 传输 gbrain serve --http --port 8787 # 令牌配置见 docs/mcp/DEPLOY.md # 3. 通过 ngrok 暴露 ngrok http 8787 --url your-brain.ngrok.app

完整安装流程（含 auth token 配置、固定域名申请、守护进程）见 recipes/ngrok-tunnel.md。该配方记录了生产环境中最容易踩的三个坑：

1. Claude Desktop 必须走 GUI：远程 MCP 服务器只能通过 Settings > Integrations 添加，claude_desktop_config.json配置会静默失败。
2. 免费档 URL 是临时的：每次重启都会变，需要看门狗脚本自动拉起 ngrok，并在无固定域名时回写 Twilio webhook。
3. 一个域名对应一个本地端口：ngrok http <port>会把所有路径转发到单一端口；若要同一域名同时路由/mcp与/voice到不同端口，需要 ngrok 流量策略或本地反向代理。

配方的看门狗模式（watchdog）是生产部署的要点：通过 cron 每 2 分钟检查pgrep -f "ngrok.*http"，未运行则自动重启，并可用curl -sf http://localhost:4040/api/tunnels校验隧道健康状态。验证隧道后，Claude Code 可用claude mcp add gbrain -t http https://your-brain.ngrok.app/mcp -H "Authorization: Bearer YOUR_GBRAIN_TOKEN"直接接入。

方案二：Tailscale Serve / Funnel（tailnet 私有或公网）

Tailscale 提供永久的 MagicDNS 名称与自动 TLS，免费档可用。两种模式仅一字之差，但暴露范围完全不同：

# 1. 安装 Tailscale brew install tailscale # 2. 以 Tailscale 呈现的 HTTPS issuer 启动 gbrain（默认 127.0.0.1 绑定即可） gbrain serve --http --port 8787 --public-url https://your-machine.your-tailnet.ts.net # 3a. 仅 tailnet 内访问 tailscale serve --bg 8787 # 3b. 公网访问 tailscale funnel 8787 # 你的 brain 现在位于 https://your-machine.your-tailnet.ts.net/mcp

注意：tailscale serve模式下，--public-url已设置但未传--bind时启动会打印 WARN，这是预期行为——Tailscale Serve 会把流量转发到 loopback，因此保持默认回环绑定是正确的。这一点在 docs/mcp/DEPLOY.md 的「Tailnet / LAN-only」一节有专门说明。

如果你需要纯 HTTP、仅 bearer、无任何 TLS 的局域网端点，可以不传--public-url，直接绑定 tailnet/LAN 网卡：

gbrain serve --http --port 3131 --bind 100.x.y.z # 或 --bind 0.0.0.0

该形态下 OAuth issuer 默认回落到http://localhost:3131（MCP SDK 接受），bearer 校验完全不读取 issuer；代价是不提供 OAuth 发现能力，因此依赖 OAuth 的客户端（如 ChatGPT）需要上面的 HTTPS 形态。

方案三：Fly.io / Railway 云主机（7×24 常驻）

前两种方案都依赖你的笔记本在线。需要 24/7 无停机生产部署时，选择云主机：

• Fly.io：约 $5-10/月，全球边缘节点，fly deploy一键部署。
• Railway：约 $5/月，git push 触发部署。

两者都以 Bun 原生运行 GBrain，无需打包、无需 Deno、无冷启动、无超时限制。部署时注意两点生产化配置：用GBRAIN_ADMIN_BOOTSTRAP_TOKEN预设管理员令牌（非 TTY 启动时生成的令牌会被隐藏，避免进入日志存储），并显式--bind 0.0.0.0 --public-url https://<你的域名>。

方案对比

关于「完整远程操作面」需要说明一个重要的安全边界：所有 HTTP 请求都受每个令牌 scope 的约束，且标记为localOnly: true的操作（如sync_brain与file_*系列）无论 scope 如何，在 HTTP 下都会被直接拒绝。远程 Agent 无法触达本地文件系统面。这一约束可以在 src/core/operations.ts 的操作目录中看到（sync 与 files 区域均标注 localOnly）。

选型决策要点

• 个人跨设备使用、在意零暴露：选 Tailscale Serve——只有你的 tailnet 可达，公网零暴露面，免费。
• 需要接入 ChatGPT / Claude.ai 等云端连接器：必须公网可达，选 ngrok（Hobby 固定域名）或 Tailscale Funnel。
• 笔记本经常关机，但要常驻服务：选 Fly.io / Railway。
• 最简方案：如果你已在用 Tailscale，tailscale funnel与 ngrok 功能等价且免费；若未用 Tailscale，ngrok 上手最快。

绑定与 OAuth issuer 的一致性（高频故障点）

远程部署最常见的故障是「隧道起来了但 Agent 报 ECONNREFUSED」，根因是--bind与--public-url不匹配：

• --public-url设置了但没传--bind，启动时会在 stderr 打印 WARN（默认仍只绑定 loopback，远程全部被拒）。
• --bind 0.0.0.0但未设置GBRAIN_HTTP_CORS_ORIGIN也会告警：浏览器类客户端拿不到 CORS 头，直到你配置允许列表。

正确姿势（以 ngrok 为例）：

gbrain serve --http --port 3131 --bind 0.0.0.0 --public-url https://your-brain.ngrok.app

--public-url同时决定 OAuth issuer：发现端点位于/.well-known/oauth-authorization-server，受保护资源元数据（RFC 9728）位于/.well-known/oauth-protected-resource/mcp，每个 401 都会携带WWW-Authenticate: Bearer resource_metadata="<该 URL>"，因此 MCP 客户端只需指向https://your-brain.ngrok.app/mcp即可从全新连接中发现令牌端点，无需粘贴任何 URL。

生产环境加固建议

1. scope 最小化：gbrain auth create <name> --scopes read铸造窄权限令牌，取代无 scope 的全权令牌。
2. DCR 默认关闭：动态客户端注册默认关闭（--enable-dcr才开启）。开启后自注册客户端最多只能申请read write，admin等特权 scope 会被 400 拒绝；每个授权码连接仍需管理员在/admin面板审批。
3. 令牌生命周期：DCR 请求可携带token_ttl_seconds，但会被钳制在管理员配置窗口内（默认 min 300 秒、max 由你的--token-ttl决定，可gbrain config set oauth.dcr_ttl_min_seconds 600放宽）。
4. 容器内 Postgres 网络隔离：OAuth scope 只保护gbrain serve --http路径，不保护裸 Postgres——同 Docker 主机上的其他容器若共享默认 bridge 网络，可直接开 DB 会话绕过认证。生产环境务必把 Postgres 放到独立用户自定义网络，发布宿主机端口时仅绑定 loopback。
5. PID 1 问题：若gbrain serve是容器 entrypoint，用 tini /--init包装，避免孤儿进程堆积（ENTRYPOINT ["/usr/bin/tini", "--", "gbrain", "serve", "--http"]）。
6. 反向代理信任：仅在可信代理后设置GBRAIN_HTTP_TRUST_PROXY，防止客户端伪造X-Forwarded-For绕过预认证 IP 限流。

常见排障速查

各主流客户端的接入指引分别见 docs/mcp/CHATGPT.md（OAuth 2.1 + PKCE，必须--http）、docs/mcp/CLAUDE_CODE.md、docs/mcp/CLAUDE_DESKTOP.md（必须 GUI 添加）、docs/mcp/CLAUDE_COWORK.md、docs/mcp/PERPLEXITY.md。

总结

GBrain 的远程部署有一条清晰的决策路径：本地 stdio 零配置起步，需要跨设备时用gbrain serve --http+ 隧道。隐私优先选 Tailscale Serve（零公网暴露），需要接入云连接器选 ngrok Hobby 或 Tailscale Funnel，需要常驻服务选 Fly.io/Railway。无论走哪条路，内置的 OAuth 2.1、scope 最小化、localOnly硬边界与默认拒绝的 CORS 共同构成了可审计、可隔离的远程访问基线。更多环境变量与可调参数请继续阅读 docs/mcp/DEPLOY.md 与 SECURITY.md。

【免费下载链接】gbrainGarry's Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain