Agent Office 隧道详解:tunnel 如何把 worker 的服务器拉到你的电脑

原创2026-10-26 18:21:461,969 阅读

Agent Office 隧道详解:tunnel 如何把 worker 的服务器拉到你的电脑

Agent Office(一个卡通 3D 虚拟办公室,团队在其中雇佣 Claude Code 等 AI worker 干活)自带一条命令行隧道:agent-office tunnel 把远程服务器上 worker 启动的 web 服务(如 npm run dev)自动映射到你本地电脑的相同端口,实现"服务器在云上,预览在本机"的无缝体验。本文带你一次看懂它的工作原理、用法与安全设计。

为什么需要这条隧道?

当 Agent Office 部署在远程服务器(AWS、Railway、Fly.io 等)上时,worker 启动的开发服务器监听在那台机器上,而不是你的电脑。你本机的 http://localhost:5173 打不到 worker 的 Vite 服务,设计师和队友也很难直接"看到"worker 的产出。

tunnel 命令正是为此而生(详见官方文档 docs/tunnel.md):

  • 同一端口:worker 在 5173 起服务,你本地就打开 5173;worker 停掉服务,几秒后端口自动关闭。
  • 零维护:不需要每个服务单独执行命令,新服务出现时自动开通。
  • 一行搞定:
agent-office tunnel office@203.0.113.7

这个 SSH 地址就是办公室内 👥 Invite teammates 面板显示的地址(在 Railway、Fly.io、Dokploy 上形如 ssh://office@host:2222)。运行后它会自动:① 打通到办公室的 SSH 隧道;② 在浏览器打开办公室;③ 持续跟踪所有 worker 的服务端口。

快速上手:安装与登录

tunnel 是 agent-office 的一部分,要求 Node.js 20+,安装后无需在本地跑办公室:

# 仅安装、不启动办公室(Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/AgentSystemLabs/agent-office/main/install.sh | AGENT_OFFICE_INSTALL_ONLY=1 bash

首次运行会以和浏览器相同的方式登录:在终端输入办公室密码(有账号则输入名字和密码)。登录态保存在 ~/.config/agent-office/tunnel.json(仅当前用户可读),两周内不用重复输入;删除该文件即登出。脚本场景可改用环境变量 AGENT_OFFICE_PASSWORD(配合 --name)。

💡 如果办公室版本过旧(无法列出 worker 的服务),命令会明确提示:通过 ☰ 菜单 → ⬆️ Upgrade the office 或部署脚本的 update 升级后再试。

工作原理:三个角色协同

隧道功能的核心代码集中在 src/server/tunnel/ 目录,它是整个项目里唯一运行在你自己电脑上的组件:

1️⃣ 服务器端:每 4 秒扫描端口

办公室每 4 秒扫描一次本机 TCP 监听端口(Linux 用 ss,macOS 用 lsof),把每个端口归属到启动它的 worker(按进程树、AGENT_OFFICE_WORKER_ID 环境变量、worktree 工作目录逐级判断),只发布应答 HTTP 的端口,并抓取页面 <title> 作为服务名。逻辑在 services.ts 中。

2️⃣ 本地端:轮询 + 同步端口

tunnel 客户端每 2 秒请求一次 GET /api/services(见 index.ts 中的 POLL_MS),对比"办公室列表"与"本地已打开的端口",差量同步:

  • 新端口 → 在本地 127.0.0.1 和 ::1 上监听;
  • 服务消失 → 端口保留约 10 秒再关闭(forwarder.ts 中的 LINGER_MS),避免开发服务器热重启时"闪断";
  • 端口被占用 → 跳过并提示,等端口空闲后自动开启;
  • WebSockets 也被转发,所以 Vite 热更新(HMR)正常工作。

3️⃣ 转发链路:一切流量只走办公室这一个端口

这是设计最巧妙的地方:本地收到的请求并不直连 worker,而是发给办公室自己的端口(默认 4600),由办公室中继(relay)到 worker 的服务器。办公室通过请求头 x-agent-office-service: <port> 或 Host 名(localhost:5173)判断该请求属于哪个 worker,转发逻辑在 relay.ts 与 wire.ts 中定义。

这带来两个好处:

  • 被邀请的 SSH 密钥只需允许转发那一个端口即可,不需要为每个服务开新端口;
  • worker 的服务器永远看不到办公室的会话 Cookie,中继时会剥离(withoutOfficeCookies)。

🔄 断线自动重连

SSH 隧道断开(笔记本休眠、Wi-Fi 切换)时,客户端在约一分钟内感知到(ServerAliveInterval=15 心跳探测,见 ssh.ts),随后以指数退避(2s → 4s → … 最长 30s)自动重连,重连期间本地端口保持打开。

常用命令选项一览

agent-office tunnel [地址] [选项] [-- <ssh 选项>]

  -p, --port <n>       SSH 方式下,办公室在本机占用的端口
      --office-port <n>  办公室在其机器上的端口(默认 4600)
      --name <name>      以指定账号登录(或 AGENT_OFFICE_NAME)
      --password <pw>    直接提供密码(或 AGENT_OFFICE_PASSWORD)
      --no-open          不自动打开浏览器
      --insecure         接受自签名证书(--self-signed 启动的办公室)

-- 之后的参数原样传给 ssh,例如使用非默认密钥:

agent-office tunnel office@203.0.113.7 -- -i ~/.ssh/office

如果办公室已经能通过浏览器访问(本地部署、自有域名或 tailnet),直接把该地址传给 tunnel 即可,它不会改动你现有的访问方式:

agent-office tunnel https://office.example.com

办公室里 🌐 Services 面板(挂在休息区墙上,也可从 ☰ 菜单 打开,代码在 services.ts)会按你当前的进入方式显示可复制的 tunnel 命令;单击某一行还能生成只转发单个服务的裸 ssh -L 命令——无需安装任何东西就能临时预览某个 worker 的产出。

安全设计:隧道"能做什么"与"不能做什么"

  • 只监听本机回环地址(127.0.0.1 / ::1),且只接受 Host 为 localhost 的请求——外网网页无法把自己的域名指向这些端口(wire.ts 中的 LOOPBACK_NAME 校验,不匹配返回 421);
  • 登录态即通行证:tunnel 自身完成了办公室登录,所以浏览器、curl、测试脚本都能直接使用这些端口,无需再输入密码——相当于在本机跑了一个开发服务器;
  • 只中继、不越权:中继请求永远只去 worker 的 web 服务;端口上没服务时返回 "Not running" 页面,绝不会把办公室自身的页面暴露出去;
  • Ctrl-C 一键全关:所有本地端口随命令退出而释放;
  • 登录会话(而非密码)存于权限 0600 的 tunnel.json,见 session.ts。

延伸阅读:相关文件

内容 路径
隧道功能官方文档 docs/tunnel.md
客户端入口(命令解析、轮询循环) src/server/tunnel/index.ts
本地端口监听与同步 src/server/tunnel/forwarder.ts
SSH 隧道与自动重连 src/server/tunnel/ssh.ts
登录与会话持久化 src/server/tunnel/session.ts
客户端↔办公室的通信协议 src/server/tunnel/wire.ts
服务器端请求中继 src/server/relay.ts
端口扫描与归属判断 src/server/services.ts
整体架构说明(含 Services 一节) docs/how-it-works.md
各云平台部署指南 docs/aws.md、docs/fly.md、docs/railway.md

小结

agent-office tunnel 用"每 2 秒轮询 + 端口差量同步 + 单一入口中继"三板斧,把远程 worker 的 web 服务像本地开发一样自然地搬到你的电脑上:同端口、热更新可用、断线自愈、权限最小化。只要在你的电脑终端里让它安静地跑着,团队里的任何人都可以实时查看 AI worker 构建的每一版页面。

登录后查看全文
agent-office