连接器部署
WingGate 把你接入的服务与你网络内运行的 wing-connector 分开。本文说明连接器做什么、部署在哪里、需要什么网络连通性，以及如何运维与排障。
架构
WingGate 部署有两侧：服务，以及你这一侧运行的 wing-connector。
| 组件 | 部署位置 | 职责 |
|---|---|---|
| WingGate | 服务，托管或自托管部署 | 身份、组织与项目、授权、会话与审计记录，以及所有访问的协调点。资产凭据以加密形式（AES-256-GCM）存储，绝不通过 API 返回；连接器只能通过作用域化的按引用兑换获取它们。 |
| wing-connector | 你的网络，能触达资产的主机上 | 通过双向 TLS 主动连接 WingGate，并把 Web 终端、SSH、文件与 MCP 流量代理到目标主机。资产只需对该组件可达。 |
wing-connector 通过相互认证的 TLS 通道向 WingGate 建立出站连接：你侧无需任何入站防火墙规则，目标资产也不需要公网 IP。完整的职责划分见连接模型。
部署形态
- 单机 —— 个人基础设施只需在一台能触达资产的机器上运行一个 wing-connector。最简单的起步方式。
- 每个网络一个 —— 面向团队，在每个持有资产的网络（VPC、家庭实验室、办公室）各运行一个 wing-connector。每个网络只需具备到 WingGate 的出站能力。
网络要求
| 连接 | 要求 |
|---|---|
| wing-connector 到 WingGate | 出站连接，通过反向传输上的 mTLS 认证。你侧无需任何入站防火墙规则。 |
| wing-connector 到目标主机 | 连接器必须能按你启用的连接配置访问每台目标主机的对应端口，通常是 SSH。首次使用前会探测并确认 SSH 主机密钥。 |
| 客户端到 WingGate | SSH 客户端使用 SSH 协议连接 WingGate 的 SSH 端点；Web 终端与控制台内文件访问直接与服务通信。 |
| MCP 客户端 | MCP 客户端连接连接器的 MCP ingress，而不是服务。 |
访问路径
每种访问方式一条路径，各自终结在其协议要求的端点。
| 客户端 | 连接目标 | 认证方式 |
|---|---|---|
| SSH 客户端 | WingGate 的 SSH 端点 | SSH 公钥，由服务校验 |
| SSH Direct | wing-connector 的本地 SSH listener | 公钥、密码 + OTP 或 Web 授权，经服务校验 |
| Web 终端（浏览器） | WingGate（会话流） | 带 MFA 的登录会话 |
| MCP 客户端 | wing-connector 的 MCP ingress | 项目 MCP 凭据 |
| 文件访问（控制台内） | WingGate，经你的会话提供服务 | 活跃会话作用域 |
端点
规划三类端点：服务（Web 控制台与 API，HTTPS）、SSH 端点（SSH 协议，供你的客户端连接）、连接器的出站 mTLS 通道（无需任何入站防火墙规则）。具体地址与端口由你的部署提供。
前置条件
- 一台能触达目标资产 SSH 端口的 Linux 主机。
- 该主机到 WingGate 的出站 HTTPS 连通性；无需开放任何入站端口。
- WingGate mTLS 端点的 DNS 名称与有效证书，需与防火墙规则一并规划。
- 你要绑定连接器的组织中的 Owner 或 Admin 角色。
安装与绑定
- 使用你的部署提供的安装脚本在主机上安装 wing-connector（控制台「执行端」页的「添加执行端」对话框给出的一行命令，自动识别 x86_64/aarch64，需要 root 或 sudo）；systemd 主机上它以 systemd 服务运行，非 systemd 主机按脚本提示手动运行。
- 为连接器配置 WingGate 的 mTLS 端点地址。
- 启动服务并确认其运行状态：
systemctl status winggate-connector-entry
- 在 Web 控制台（导航中的「执行端」）绑定该组织内的连接器。绑定会为连接器签发独立凭据，用于向 WingGate 认证。
预期结果
连接器在组织的连接器清单中显示为在线。此后你可以在它后面注册资产并挂载连接配置，再通过项目授予访问。
可选：SSH Direct listener
连接器可以暴露一个本地 SSH listener（SSH Direct），让你的 SSH 客户端直接连到连接器主机即可访问资产，而不是连 WingGate 的 SSH 端点。归属分两类：
- wing-connector 自身的 listener：默认关闭，按连接器配置。
- WingGate 的 SSH 入口：不是按连接器配置项。首次安装时由 WingGate 侧给出默认端点（canonical 默认
0.0.0.0:9022；本部署用22），它也不出现在控制台的连接器列表里，当前没有受支持的控制台更新路径。
按连接器配置：
- 在 Web 控制台打开该连接器的 SSH Direct 设置。
- 启用 listener 并选择监听地址（仅本机用
127.0.0.1:9022，接受所有接口用0.0.0.0:9022）。将监听暴露到 loopback 之外还需连接器的ssh_direct.allowNonLoopback设置。listener 的暴露面遵循连接器主机的防火墙。 - 至少选择一种认证方式：公钥、密码 + OTP 或 Web 授权。
- 连接器通过 WingGate 认证你，只列出你已被授权的项目内、且支持 SSH 客户端入口的资产。
SSH Direct 会话与其它入口走相同的会话、授权与审计边界——见身份与访问。
分层排障
访问失败时按顺序排查——每一层都有不同的失败特征：
- WingGate 服务 —— 能否登录 Web 控制台并看到组织？如果不能，问题在账号或服务侧，与你网络内的一切无关。
- wing-connector —— 控制台是否显示它在线且绑定到正确的组织？连接器离线会让其下所有资产的所有访问方式同时失效。
- 目标主机 —— wing-connector 能否触达主机，SSH 主机密钥是否与已确认的一致？主机密钥不匹配与连接拒绝都发生在这一层。
审计与排障文章逐层覆盖了详细排查方法，包括连接器日志与升级流程。
升级与回滚边界
- 升级顺序如下：先 WingGate 服务，后连接器组件；手动操作时保持同样顺序。
- WingGate 服务重启期间，活跃 session 与连接器 shell 会被保留，前端自动重连；据此规划升级窗口。
- 回滚意味着连同配置一起恢复之前的 WingGate 服务与连接器二进制；服务的存储及其备份留在你的信任边界内，由你决定恢复内容。
连接器离线时
连接器离线意味着 WingGate 无法触达其后的资产；到这些资产的现有会话会失败。按以下顺序排查：
- 连接器主机到 WingGate 的出站连通性（DNS、防火墙、代理）。
- 主机上的连接器服务状态与日志（
journalctl -u winggate-connector-entry）。 - 连接器凭据是否仍然有效；如有疑问，像对待其它机器凭据一样轮换它。