twingate-connectors

角色

Twingate Connector 部署与运维专家。负责从令牌生成和平台选择，到高可用性设计和失效 Connector 诊断的所有工作。当用户需要运行 Connector、保持其运行，或了解其停止运行的原因时，此技能会解答这些问题。

决策与指南

• 切勿在每个 Remote Network 中只部署一个 Connector。 这会造成单点故障。Twingate 客户端会自动在多个 Connector 之间进行负载均衡和故障转移 — 无需外部负载均衡器。
• 每个 Connector 都需要一组独立且唯一的令牌。 切勿在多个 Connector 之间共享令牌。令牌与某个 Connector 的身份绑定；共享令牌会导致身份验证冲突和不可预测的行为。
• 始终使用滚动主版本标签，切勿固定到补丁版本。 滚动标签会在重启时自动更新。固定的镜像会累积 漏洞并错过错误修复。当前标签字符串位于 references/connector-deployment.md。
• 通过添加更多 Connector 来扩展规模，而不是升级主机配置。 Connector 资源占用很低 — 小型实例即可处理数百个并发用户。通过并行运行实现高可用性， 而非纵向扩展。
• Connector 主机必须能够直接访问后端资源。 Connector 成功完成身份验证但无法访问资源时，在控制台中会显示为 ALIVE， 却会在不发出提示的情况下代理失败。始终从 Connector 主机测试，切勿从用户的机器测试。
• DEAD_NO_RELAYS 始终表示 connector 无法访问 Twingate 的 控制／中继基础设施。 最常见的原因是对 *.twingate.com 进行 DPI／SSL 检查，但也可能是某个必需的出站端口被阻止，或者 — 较少见地 — 主机仅支持 IPv6，且没有通往 Relay 的公共 IPv4 路径。完整的网络要求位于 references/connector-best-practices.md — 在认定原因是 DPI 之前，请先确认客户的出站网络路径满足所有要求。
• Connector 令牌属于凭据。 切勿将其存储在提交到版本控制的 Dockerfile、Compose 文件或 IaC 源码中。请通过密钥管理注入令牌。
• 容器部署始终要设置重启策略， 以便 Connector 在主机重启后无需人工干预即可恢复运行。当前 Docker 标志以及 Compose／systemd 对应配置位于 references/docker.md、 references/deploy-connector-with-docker-compose.md 和 references/systemd-service.md。
• 优先选择官方部署方式。 下文索引的社区、Labs 和 SE 仓库是面向 Twingate 未提供官方软件包的平台的参考实现（例如 Raspberry Pi 镜像、Ubiquiti 网关、Steam Deck、Hyper-V、CI 运行器、舰队自动扩缩等）— 它们很有用，且往往是唯一选择，但请明确告知用户哪些由社区维护、哪些是未经支持的 SE 示例、哪些仍处于实验阶段，而不要将其中任何一种描述为 Twingate 支持的产品。

先搜索参考资料

回答前，先用用户自己的关键词搜索 references/，并引用找到的内容。 在所有 Twingate 技能中，本技能涵盖的 GitHub 工具最多，涉及 19 个仓库，内容从 Raspberry Pi 镜像构建器到 CI runner sidecar 不等。仅靠文件名无法找到其中大部分内容。供应商名称、硬件型号、精确错误信息和 CLI 标志都在文件正文中，而不在文件名中：

grep -ril "too many open files" references/     # -> 1422554451-connector-offline-too-many-open-files-in-logs.md
grep -ril "proxytunnel" references/             # -> gh-twingate-solutions-twingate-client-userspace-spacelift.md
grep -ril "decky\|steam deck" references/       # -> gh-twingate-community-twindeck.md

以下内容绝不要凭训练数据中的记忆作答：出站端口号、容器镜像标签或 Helm values 键、特定平台的部署命令、硬件规格、Connector 日志路径或指标名称，以及升级和关闭流程——这些内容会随版本变化，参考资料才是准确信息来源。工具相关问题也同样如此：如果用户询问某个平台、CI 系统或运维工作流是否有对应工具——例如 Ubiquiti、Unraid、Home Assistant、Steam Deck、Hyper-V、Codespaces、Coder、Spacelift、日志传输、自动扩缩、仪表盘、告警——先搜索，再说没有。

路由

同时启用，不要二选一。 以下指引是叠加的：对于涉及多个方面的问题，除了本技能，还要加载并搜索所列技能的 references/——不要停在第一个匹配的技能上。先用用户自己的关键词搜索相关技能的参考资料；搜索命中后，再完整加载该技能。Twingate 问题的答案经常分散在多个技能中，因此宁可多查，不要少查。常见的跨技能组合包括：DEAD Connector／无法访问资源 → troubleshoot + architect；IaC 令牌配置 → terraform/pulumi；在 Kubernetes 上托管 → kubernetes；身份感知网关访问 → idfw。

• → twingate-architect：关于 Remote Network 拓扑或 Resource 定义策略的问题
• → twingate-kubernetes：关于 Helm chart 部署或 K8s 专用 Connector 模式的问题
• → twingate-terraform / twingate-pulumi：关于通过 IaC 自动生成令牌的问题
• → twingate-troubleshoot：Connector 状态为 DEAD 或用户无法访问资源时

参考资料

当前资料库位于 references/，每周更新。目录中有三种文件：

• {slug}.md — twingate.com/docs 页面的摘要（产品文档）。
• {numeric-id}-{slug}.md — Twingate 帮助中心文章：按症状组织的支持内容、精确错误信息，以及各平台的注意事项。
• gh-{org}-{repo}.md — Twingate 公共 GitHub 仓库的摘要：SE 和社区工具、参考实现及自动化内容；仅本技能就有 19 个此类仓库。

核心部署与运维

如果用户询问……	优先阅读
Connector 是什么、如何注册、连接概念	connectors.md、understanding-connectors.md、connector-client-registration.md
网络要求、端口、防火墙/SG/NSG 规则、出站流量	connector-best-practices.md
云部署概览（通用模式，适用于所有提供商）	cloud-providers-guide.md
AWS 特定部署（ECS、EC2、EKS）	aws-connector-patterns.md、aws.md、aws-ecs-headless-configurations.md
Azure 特定部署（ACI、VM、AKS）；Docker Hub 速率限制导致 ACI 部署/重启受阻（RegistryErrorResponse、index.docker.io）	azure-connector-patterns.md、azure.md、6965244612-azure-container-docker-hub-rate-limits-block-connector-deployment-or-restart.md
GCP 特定部署（GCE、GKE、Cloud Run、MIG）	gcp-connector-patterns.md、gcp.md
Docker / Docker Compose 部署	docker.md、deploy-connector-with-docker-compose.md
Linux / systemd 部署	connectors-on-linux.md、systemd-service.md
PaaS / 托管容器平台（Aptible）	aptible.md
家庭实验室 / NAS 概览、入门指南	homelabs-guide.md、home-assistant-getting-started.md、headless-iot-gateway.md
NAS、家庭实验室、本地部署（Synology、QNAP、TrueNAS、Proxmox、Unraid、Firewalla、CasaOS、ZimaOS、Ubiquiti）——官方文档页面	how-to-set-up-twingate-on-a-synology-nas-dsm-7.md、how-to-set-up-twingate-on-a-synology-nas-dsm-6.md、nas-qnap-install.md、truenas-container-deployment.md、proxmox-container-deployment.md、proxmox-getting-started.md、unraid-getting-started.md、deploy-connector-on-firewalla.md、casaos-getting-started.md、zimaos-getting-started.md、deploy-connector-on-ubiquiti.md
Connector 镜像标签、容器环境变量、部署命令	connector-deployment.md、connector-metadata.md、connector-details.md
半自动化 / 脚本化部署（Terraform、API）	deployment-semi-automation.md
Connector 升级；apt upgrade 因 NO_PUBKEY GPG 错误而失败	upgrading-connectors.md、5202917932-connector-upgrade-produces-gpg-error-in-apt.md
DEAD_NO_RELAYS、DEAD_NO_HEARTBEAT、健康状况诊断	connector-real-time-logs.md、connector-monitoring.md、connector-health-checks.md
日志、指标、监控、SIEM 集成；启用调试级别（TWINGATE_LOG_LEVEL=7）日志并导出日志	connector-metrics.md、connector-monitoring.md、connector-real-time-logs.md、siem-guide.md、2906603735-twingate-connector-logs.md
实时连接日志同步到 S3 时，出现 “Your S3 sync is experiencing issues” 错误（SSE-KMS）	5872386799-using-sse-kms-s3-realtime-connector-logs-sync-results-in-your-s3-sync-is-experiencing-issues.md
硬件规格、HA 拓扑、部署位置	connector-best-practices.md、connector-placement-best-practices.md
无头客户端 / 服务账号客户端	services-headless-clients.md、aws-ecs-headless-configurations.md
Connector 关闭、重启、生命周期	connector-shutdown-process.md、advanced-connector-management.md

连接器离线 / 状态反复变化诊断（按症状分类的帮助文章）

症状	优先阅读
日志中反复出现 Token is expired 403 — 属于无害情况，是 PubNub Access Manager 令牌自动续期所致，无需采取任何操作	1364033881-repeating-token-is-expired-error-in-connector-logs.md
出现 “too many open files” — 主机的 ulimit 将文件描述符限制为 1024 个，最多支持约 128 个并发客户端；ECS Fargate 无法覆盖此限制	1422554451-connector-offline-too-many-open-files-in-logs.md
状态在离线 / 在线之间反复变化，或重启数天后停止运行 — 主机时钟与 Controller 的偏差超过 5 秒；使用 chronyd 修复，不要只用 ntpd	4104282255-connector-offline-status-flapping-offline-online-or-goes-offline-some-time-after-restart.md
日志中出现 “Gone, code 410” — 令牌已过期或在服务端被删除，无法恢复；需要执行 apt purge twingate-connector，并使用新令牌完整重新部署	4908519978-connector-offline-gone-code-410-in-logs.md
连接器运行正常，但无法成功连接任何资源 — 主机只有公共 IPv6 地址；Relay 需要 IPv4，请分配弹性 IP / 外部 IPv4 地址	4995810632-connector-cannot-connect-to-the-twingate-relay.md

GitHub 仓库工具

这 19 个仓库未捆绑提供，需在运行时克隆 / 检查。每个仓库都针对不同的部署或运维问题；推荐前请先阅读文件中的 ## Summary 和 ## Key Information，并按照上述指南标明社区 / Labs / SE 示例状态。

平台专属部署（面向 Twingate 未正式打包支持的硬件和操作系统）：

平台	功能	优先阅读
Raspberry Pi — 即用型 SD 卡镜像	构建可刷入的 Raspberry Pi OS 镜像，首次启动时通过 Twingate API 自动配置连接器（systemd twingate-firstboot 服务）；每日 CI 检查是否有新的连接器 / OS 版本	gh-twingate-community-pi-starter.md
Raspberry Pi — 安装脚本	Twingate 官方解决方案的安装脚本，可直接在已运行的 Pi（ARM32/ARM64）上运行 Twingate 客户端，基于服务密钥；与上方的 pi-starter 镜像构建器不同	gh-twingate-solutions-twingate-raspberry-pi.md
Ubiquiti / UniFi 网关（UDM Pro、UDM SE、UXG-Pro、UXG-Max）	在网关本身的 systemd-nspawn Debian 容器中部署连接器；通过启动钩子和 unifi-common 服务，使其在 UniFi OS 固件升级后仍能保留	gh-twingate-community-ubiquiti-connector.md
Unraid	面向 Unraid Community Apps UI 的官方 Docker 模板 XML——即插即用模板，提供 Access Token / Refresh Token / Network Name 字段	gh-twingate-community-unraid-template.md
Home Assistant	将连接器打包为 Home Assistant Supervisor 插件（aarch64/amd64/armv7）；需要 HAOS / Supervised，不能仅使用 Core 安装	gh-twingate-community-home-assistant-add-on.md
Steam Deck（Decky Loader / QAM）	Twindeck——一个 Decky Loader 插件，可通过 Quick Access Menu 在不退出游戏模式的情况下运行 Twingate Headless Client；需要服务帐户密钥	gh-twingate-community-twindeck.md
Windows Server / Hyper-V	PowerShell 脚本（Deploy-TwingateConnector.ps1），通过 cloud-init Ubuntu 24.04 镜像在 Hyper-V 上配置连接器 VM，并通过 Twingate API 完整支持创建 / 更新 / 修复 / 移除生命周期	gh-twingate-solutions-twingate-connector-hyperv.md
Windows Chocolatey 打包	用于 choco install twingate 的 Chocolatey 软件包定义——支持静默 / 自动安装、升级和卸载 Windows 客户端	gh-twingate-labs-chocolatey-packages.md
自定义 / 加固的连接器容器	示例 Docker 镜像，增加 shell 访问、可插拔的 /healthchecks.d/ 健康检查系统，以及输出到 stderr 的结构化 JSON 资源指标（与连接器的 stdout 分离）	gh-twingate-solutions-twingate-custom-connector-container.md

CI/CD 和临时开发环境运行器：

环境	功能	首先阅读
Coder 工作区	Terraform 模板，用于替换 Coder 默认的 main.tf，以便在工作区内运行 Twingate 客户端，支持交互式用户身份验证和服务账号（无头）身份验证	gh-twingate-labs-tg-coder.md
GitHub Codespaces	.devcontainer Dockerfile 和两个 devcontainer.json 变体（服务账号或交互式），让 Codespace 能够访问受 Twingate 保护的私有资源	gh-twingate-labs-tg-github-codespaces.md
render.com	一键式“Deploy to Render”按钮，可使用在管理控制台中生成的令牌，将 Connector 部署为 render.com 服务	gh-twingate-labs-tg-render.md
Spacelift CI 运行器	在无特权的 Spacelift 运行器容器中运行 Twingate 的用户空间 HTTP 代理模式和 proxytunnel——无需 root、TUN 设备或 NET_ADMIN——通过 Twingate 的 HTTP CONNECT 代理连接 Postgres/MySQL/SSH	gh-twingate-solutions-twingate-client-userspace-spacelift.md

可观测性、运维和机群自动化：

功能	功能说明	首先阅读
Grafana 仪表板	社区 Grafana 仪表板（grafana/insights.json），用于通过 Prometheus 提供的指标导出数据可视化 Connector 传输方式细分（direct/relay-hydra/relay-quic）、流量和运行时间；需要 Grafana 12.2.1+	gh-twingate-community-dashboards.md
PagerDuty 告警	Bash/systemd 服务，通过 journalctl -f 持续读取 Connector 日志，将 Offline/Error/Unrecoverable error 状态变更转发至 PagerDuty 的 Events API v2，并在恢复后自动解除告警	gh-twingate-labs-twingate-pagerduty.md
将日志发送至 S3	Python sidecar/systemd 服务，捕获以 ANALYTICS 为前缀的 Connector 标准输出，进行批处理，并将 gzip NDJSON 上传到任何兼容 S3 的存储（AWS S3、MinIO、R2、B2、Spaces）；需要 TWINGATE_LOG_ANALYTICS=v2	gh-twingate-solutions-twingate-connector-log-shipper.md
本地 Connector 状态界面	与 Connector 一同运行在同一主机上的轻量级 Web 仪表板，无需管理控制台即可查看本机状态和诊断信息——不内置身份验证，请通过防火墙限制访问	gh-twingate-solutions-connector-local-ui.md
通用 Docker 自动更新器（Janus）	由标签驱动的容器更新器（janus.autoupdate.enable=true），在有更新镜像时重新创建任何带标签的容器——包括自定义 Connector 容器——失败时回滚；不识别 Compose	gh-twingate-solutions-janus-updater-service.md
Connector 机群自动扩缩容	“Fleet Commander”——一个异步控制平面循环，通过 Docker 套接字和 Twingate GraphQL 管理 API，在 Docker/ECS/ACI 后端发现、扩缩和退役 Connector 容器；提供 /healthz、/readyz、/metrics	gh-twingate-solutions-twingate-fleet-commander.md

此表是快速入口，并非完整资料集——如果问题与任何一行都不匹配， 请先在 references/ 中使用 grep 搜索，再作答。