客户端
客户端是任何与 orbitproxy 云网关保持着活跃会话的程序，包括你自己在终端里运行的 orbitproxy 命令行客户端，以及用 SDK 嵌入到你自己应用程序里的 SDK 客户端。
它们的区别在于你怎样运行它，而不在于它做什么：每一种客户端都会主动连接 orbitproxy 云网关，接收转发过来的公网流量，再把流量送到你的上游服务。
orbitproxy高度重视用户数据安全以及用户隐私，相比于闭源的承诺，我们更愿意提供绝对的开源， 你可以在我们的 github 主仓中找到 orbitproxy-sdk 以及 orbitproxy 客户端的完整源代码， 并对其行任意 debug 或者解析，以确保部署在你内网的 orbitproxy 客户端满足你的安全合规需求，同时确保 orbitproxy 不会泄露以及读取你的敏感数据
- orbitproxy 客户端 github 仓库: https://github.com/orbitproxy/orbitproxy-machine
- orbitproxy sdk github 仓库: https://github.com/orbitproxy/orbitproxy-go
为什么需要 orbitproxy 客户端
你想要发布到公网的服务，往往并不能被公网访问。它们可能在公司防火墙或者 NAT 后面，在一台每天要切换两次网络的笔记本上，在没有公网 IP 的云主机里，或者在你已经交付给客户的设备上。这些地方都不能接受入站连接，而要让它们接受入站连接，通常意味着 VPN、端口映射，或者一个你并不想对外开放的公网 IP。
orbitproxy 客户端把连接的方向反过来。它运行在你的服务旁边，主动出站连接到 orbitproxy 云网关，发往你的公网流量沿着同一条连接回传。你的服务不用动，网络配置也不用改。
客户端能做什么
- 转发 HTTP(S) 和 TCP 流量。 网站、API、数据库、SSH 等服务，都可以用同样的方式发布出去。
- 承载 MCP 服务。 既可以转发已经以 HTTP 形态运行的 MCP 服务，也可以按命令唤起 Stdio 形态的 MCP 服务，并通过标准输入输出与 MCP 网关交互。
- 只使用一条出站连接。 所有流量都通过这一条加密连接往返，你不需要开放任何入站端口。
- 持续检查上游状态。 客户端会检查本机上游服务是否可用，并把结果上报给云网关。
- 提供可观测性。 无论是哪种客户端，连接状态和流量都会出现在控制中心里。
两种客户端
命令行客户端
一个独立的可执行程序，安装在你的服务旁边运行，没有运行时依赖，支持 macOS、Linux 和 Windows，也可以把自己注册成操作系统服务。你可以在终端里完成登录、运行、查看状态、创建和关闭分享等所有操作。
命令行客户端的手动安装请见安装指引，交给 AI Agent 发布请见快速入门，命令请见客户端命令行界面。
SDK 客户端
SDK 客户端是把 orbitproxy 直接嵌入到你的应用程序里的库。目前提供 Golang SDK，不需要再打包、分发或守护一个单独的进程。
它还提供了命令行客户端没有的能力：创建 net.Listener 之后，云网关转发来的连接可以直接在你的进程内被接收，不必经过本地端口。
每个 SDK 客户端对应一个 Machine Key，一个程序使用一个 SDK 客户端，Machine Key 不能在多个程序之间复用。创建方式请见安装指引的「使用 SDK 接入」。
如何选择
先从命令行客户端开始。它是让一个服务上线最快的方式，也是和控制中心配合最完整的方式。关于云端点、MCP 连接器和流量策略的所有知识，换成 SDK 以后依然适用。
遇到下面的情况，再考虑 SDK：
- 你在交付一个应用程序。SDK 把 orbitproxy 放进应用进程里，用户不需要另外安装和维护客户端。
- 你的程序是 Go 语言写的，并且希望直接在进程内接收连接，而不是转发到本地端口。
客户端如何工作
每一种客户端都做同样的三件事：和云网关建立会话，在会话上承载端点，把流量送回你的上游服务。这三件事基本解释了客户端的全部行为。
会话
客户端启动后，会主动连接 orbitproxy 云网关，建立一条长期保持的 TLS 加密连接，这条连接就是会话。控制中心里客户端的在线状态，就是这条会话是否存在。
会话只有出站方向，你的机器上没有任何监听入站连接的端口，所以它可以在 NAT、公司防火墙和你无法控制的网络里工作。
会话建立在身份之上：
- 客户端注册时，会在本机生成一对密钥，私钥只保存在本机，公钥交给 orbitproxy。
- 每次建立会话，客户端都用私钥对握手消息签名，云网关用公钥验证，验证通过才会接受这条会话。
- 客户端同样会校验云网关的证书，使用的是注册时下发的 CA 证书。
保活与重连
客户端会定期发送保活消息，检查连接是否仍然可用。网络中断、Wi-Fi 切换到移动网络、笔记本休眠唤醒之后，客户端会自动重连，重试间隔逐渐拉长但不会放弃，直到云网关明确要求它停止。重连的过程中，命令行客户端的状态面板会显示 reconnecting 和当前的重试次数。
因为云网关持有会话的另一端，所以你可以在控制中心里对客户端执行停止、重启和升级，即使你当时没有办法登录那台机器。
会话上的端点
会话建立之后，云网关会把端点下发给客户端。端点就是流量到达的入口，同时告诉客户端要把流量转发到哪个上游服务。
端点的配置保存在云端，而不是客户端本地：
- 你可以在控制中心创建端点，也可以用命令行客户端的
proxy add创建，客户端上线后立即生效。 - 客户端停止，不会让端点配置消失，但在客户端重新上线之前，流量无法被转发到你的服务。
- 同一个客户端上可以有任意多个端点，它们共用同一条会话。
客户端停止时
客户端停止时，它上面的端点就无法转发流量，这是最重要的一个结果，大部分运行方式上的选择都是为了应对它：
- 把客户端注册为操作系统服务，让它开机自启动，并在异常退出后被拉起。
- 同一台机器上同一时间只会有一个客户端进程。前台运行、后台运行和系统服务共用同一把锁，同时启动第二个会失败，并告诉你是谁占用着。
命令行客户端支持三种运行方式：
| 运行方式 | 命令 | 适合场景 |
|---|---|---|
| 前台运行 | orbitproxy run | 临时分享或测试，关闭终端后停止，终端里会显示状态面板 |
| 后台运行 | orbitproxy run --background | 关闭终端后继续运行，用 orbitproxy stop 停止 |
| 系统服务 | sudo orbitproxy service install | 生产环境，开机自启动，由操作系统守护 |
客户端不做什么
客户端只负责连接和转发，它不是一个需要你配置规则的代理。认证、访问控制、限速、改写这些事情由流量策略描述，并且在流量到达你的客户端之前，就已经在 orbitproxy 云网关里执行完毕。
所以无论端点是哪种客户端创建的，同一份流量策略的效果都完全一致。
本地文件
命令行客户端的所有数据都放在数据根目录里，默认是 ~/.orbitproxy，所有操作系统通用，可以用 --workdir 修改。
| 路径 | 内容 |
|---|---|
bin/ | 客户端程序本身。 |
<machineKey>/orbitproxy.yml | 这台机器的身份和云网关地址，包含私钥，请妥善保管，不要提交到代码仓库。 |
<machineKey>/logs/ | 运行日志，排查问题时首先查看这里。 |
<machineKey>/orbitproxy.lock | 运行锁，保证同一台机器同一时间只有一个客户端进程。 |
一台电脑上可以有多个 machineKey。有多个时，运行和管理命令需要用 --machine-key 指定要操作哪一个。
网络要求
客户端只需要能够出站连接到 orbitproxy 云网关，不需要开放任何入站端口，也不需要公网 IP。云网关的地址保存在注册时生成的配置里，运行 orbitproxy status 时可以看到，对应 edge 一行。
排查问题
客户端连不上云网关时，先用下面的方法确认状态：
- 运行
orbitproxy status，查看是否已登录、客户端进程的运行方式，以及它没有运行的原因。 - 查看
<machineKey>/logs/里的日志文件，里面记录了每一次连接和重连。 - 运行
orbitproxy run --log=legacy，让日志直接输出到终端，替换状态面板，方便复制和搜索。
如果你需要给脚本或者 AI Agent 使用，status、list、close 和 proxy add 都支持 --json，输出结构化结果。
常见用例
- 本地开发联调。 让第三方的 Webhook 回调直接打到你笔记本上的服务，见localhost/内网服务接收微信支付等第三方 webhook回调。
- 发布本地和内网服务。 不需要域名和服务器，就能让 localhost 上的服务拥有公网地址，见使用orbitproxy作为你任何服务的流量入口。
- 让 AI Agent 访问内网 MCP 服务。 把数据库、日志等 Stdio MCP 服务注册到 MCP 网关，见连接你的内部 Stdio MCP 服务。
- 接入没有固定地址的设备。 设备不需要公网 IP 和入站端口，只要能出站联网就能被访问。
后续步骤
- 快速入门：交给 AI Agent 把第一个服务发布到公网。
- 安装指引：手动安装并启动客户端，把第一个服务发布到公网。
- orbitproxy cli：查看
orbitproxy的所有命令和参数。 - 客户端工作原理：深入了解会话、端点、重连以及流量在客户端里的完整流转过程。
- 了解 .orbitproxy 目录：了解客户端在本机保存了哪些文件，它们各自的作用，以及哪些可以删除。
- 客户端架构安全性：了解客户端的身份认证、加密连接，以及它为什么不会读取和泄露你的数据。
- 升级客户端版本：了解如何查看当前版本，以及在控制台在线更新、手动重新安装和升级 SDK 的方法。