客户端架构安全性
orbitproxy 客户端运行在你的内网、服务器或个人电脑上，持有机器身份，并有权访问本地服务。本页说明客户端在设计上如何保护这些资产：它向外暴露什么、凭据如何保管、流量如何处理，以及云网关能够对客户端做什么。
orbitproxy 客户端和 SDK 均为开源项目，本页描述的行为都可以在源代码中核对：orbitproxy-machine（命令行客户端）和 orbitproxy-go（SDK）。
设计原则
- 不开放入站端口：客户端只向外发起连接，不在本机监听任何端口。
- 全程加密并校验对端：客户端与云网关之间的连接经过加密，并且客户端会校验云网关的身份。
- 私钥不离开本机：机器身份的私钥在本机生成，仅用于本机签名，不会被上传。
- 只转发，不解析：客户端对转发的流量只做字节搬运，不解析、不存储、不记录内容。
- 权限最小化：本地文件仅当前用户可读写，转发范围仅限于你配置的服务。
网络暴露面
客户端启动后主动向云网关发起一条出站连接，公网流量通过这条连接送达本机。客户端本身不在本机监听任何端口，因此：
- 不需要在防火墙或路由器上开放入站端口，也不需要公网 IP 或 VPN。
- 本机不会因为运行客户端而新增可被扫描、被探测的端口。
客户端访问本地服务时，同样只在本机主动拨出连接，对象仅限于你为端点配置的本地地址。
传输安全
客户端与云网关之间的连接使用 TLS，最低版本为 TLS 1.2。
客户端在建立连接时校验云网关的证书。用于校验的 CA 证书在机器注册时由 orbitproxy 下发，保存在 orbitproxy.yml 的 machine_ca_cert 字段中，客户端使用它校验云网关，而不是依赖系统信任的根证书。证书校验失败时，连接不会建立，也不会发送任何业务数据。
机器身份与认证
每台机器都有独立的身份，由以下几部分构成：
- machine key：机器的标识，注册时由 orbitproxy 分配。
- 密钥对：注册时在本机生成的 Ed25519 密钥对。私钥只保存在本机，公钥在注册时提交给 orbitproxy。
客户端不使用共享密码或固定令牌认证，而是使用私钥对认证信息签名：
- 客户端连接云网关时，发送经私钥签名的握手信息，签名内容包含时间戳和一次性随机数。云网关使用已登记的公钥校验签名，并检查时间戳与随机数，使截获的握手信息无法被重复使用。
- 客户端调用控制面接口时，每个请求同样携带签名、时间戳和随机数。
签名校验未通过的连接和请求会被拒绝。由于私钥不离开本机，即使通信内容被第三方获取，也无法据此冒充这台机器。
凭据与本地文件
注册凭据
- authtoken：仅在执行
orbitproxy authtoken时使用一次，用于向控制面完成注册，不会写入本地文件。 - 浏览器登录：
orbitproxy login使用设备授权流程，在浏览器中完成确认，不需要在终端输入账号或密码。
文件权限
客户端写入的文件和目录仅限当前用户访问。在 macOS 和 Linux 上，目录权限为 0700，文件权限为 0600，包括：
orbitproxy.yml（包含私钥）。default、last-machine、pending-login.json等状态文件。- 日志文件。
- Stdio MCP 的环境变量文件。
私钥只存在于 orbitproxy.yml。客户端在日志中不会输出私钥，握手日志中的签名字段也会被清除。
使用 sudo 安装系统服务时，数据目录仍归属发起安装的用户，不会变为 root 所有。各文件的用途请见了解 .orbitproxy 目录。
流量处理
客户端收到公网流量后，直接在云网关连接与本地服务之间双向转发字节：
- 客户端不解析、不修改转发的请求和响应内容。
- 客户端不存储转发的内容，也不把内容写入日志。日志中与流量相关的信息仅限于端点 ID、本地地址和传输的字节数。
- 转发只针对云网关登记过的端点。客户端不会处理指向未登记端点的连接。
转发范围
客户端能够访问的本地服务，由端点的配置决定：
- 转发到本地地址：客户端只连接端点配置中的本地地址，端点由你在控制台或通过
orbitproxy proxy add创建。 - 通过 SDK 接入：Go 应用通过 SDK 的
Listen直接接收连接，不经过本地网络端口。 - Stdio MCP 服务：客户端启动你在端点中配置的命令，并通过标准输入输出与其通信。
对于 Stdio MCP 子进程，客户端采取以下措施：
- 命令以参数列表直接执行，不经过 shell，避免命令注入。
- 子进程运行在独立的进程组中，不会因客户端的信号而被连带终止。
- 子进程所需的密钥放在
env/<endpointID>.env中（权限0600），不出现在命令行参数里。 - 单个端点最多 8 个并发会话，全机最多 32 个子进程，空闲 300 秒后自动回收。
云网关可以做什么
客户端与云网关之间是一条已认证的会话，云网关只能通过这条会话向客户端下发指令。可下发的指令包括：
| 指令 | 说明 |
|---|---|
| 创建和关闭端点 | 对应你在控制台或命令行中创建、关闭分享的操作。 |
| 停止客户端 | 终止客户端，并让客户端不再重连。 |
| 重启客户端 | 客户端重新启动。 |
| 升级客户端 | 客户端下载新版本程序、替换自身并重启。 |
| 预检与工具发现 | 检查 Stdio MCP 端点的命令是否可用，并读取其提供的工具列表。 |
除上述指令外，客户端不接受会话之外的任何控制。如果希望完全由本机控制客户端的运行，可以随时使用 orbitproxy stop 或 orbitproxy service stop 停止它。
吊销与清理
- 登出：
orbitproxy logout会使本机的密钥在控制面失效，停止后台运行的客户端，并删除本地的机器目录。此后这把私钥无法再用于认证。 - 清除本地数据：
orbitproxy reset删除除程序以外的全部本地数据，orbitproxy delete连同程序一并删除。命令详情请见 orbitproxy cli。
怀疑私钥已经泄露时，应在该机器上执行 orbitproxy logout 使密钥失效，再重新注册。
后续步骤
- 客户端工作原理：了解会话、重连和流量转发机制。
- 了解 .orbitproxy 目录：了解客户端在本机保存的文件。
- orbitproxy cli：查看全部命令和参数。