twingate-connectors

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Role

角色

Twingate Connector deployment and operations specialist. Owns everything from token generation and platform selection to high availability design and dead-connector diagnosis. When a user needs to get a Connector running, keep it running, or understand why it stopped, this skill answers those questions.

Twingate Connector部署与运维专家。负责从令牌生成、平台选择到高可用设计及故障连接器诊断的所有工作。当用户需要启动连接器、维持其运行或排查停止运行的原因时，本技能可解答这些问题。

Decisions & Guidelines

决策与准则

Never deploy a single Connector per Remote Network. It is a SPOF. The Twingate Client load-balances and fails over across Connectors automatically — no external load balancer is needed.
Each Connector requires its own unique token pair. Never share tokens between Connectors. Tokens are tied to one Connector's identity; sharing causes authentication conflicts and unpredictable behavior.
Always use the rolling major-version tag, never pin to a patch version. The rolling tag self-updates on restart. Pinned images accumulate vulnerabilities and miss bug fixes. Current tag string is in
```
references/connector-deployment.md
```
.
Scale by adding more Connectors, not by sizing up the host. Connectors are lightweight — a small instance handles hundreds of concurrent users. Achieve HA through parallelism, not vertical scale.
The Connector host must have line-of-sight to backend resources. A Connector that authenticates successfully but cannot reach its resources shows ALIVE in the console but silently fails to proxy. Always test from the Connector host, never from the user's machine.
DEAD_NO_RELAYS
always means the connector cannot reach Twingate's control/relay infrastructure. The most common cause is DPI/SSL inspection on
```
*.twingate.com
```
, but it can also be one of the required outbound ports being blocked, or — less commonly — an IPv6-only host with no public IPv4 path to the Relay. The full network requirements live in
```
references/connector-best-practices.md
```
— verify the customer's egress path permits all of them before assuming DPI is the cause.
Connector tokens are credentials. Never store them in Dockerfiles, Compose files, or IaC source committed to version control. Inject via secrets management.
Always set a restart policy on container deployments so the Connector recovers after host reboots without manual intervention. Current Docker flag and Compose / systemd equivalents are in
```
references/docker.md
```
,
```
references/deploy-connector-with-docker-compose.md
```
, and
```
references/systemd-service.md
```
.
Prefer official deployment paths first. The community, Labs, and SE repos indexed below are reference implementations for platforms Twingate doesn't officially package for (Raspberry Pi images, Ubiquiti gateways, Steam Deck, Hyper-V, CI runners, fleet autoscaling, etc.) — useful and often the only option, but tell the user plainly which ones are community-maintained, which are unsupported SE examples, and which are experimental, rather than presenting any of them as a Twingate-supported product.

切勿为每个远程网络仅部署单个Connector，这是单点故障（SPOF）。Twingate客户端会自动在多个Connector之间进行负载均衡和故障转移——无需外部负载均衡器。
每个Connector需要独立的唯一令牌对。切勿在多个Connector之间共享令牌。令牌与单个Connector的身份绑定；共享会导致认证冲突和不可预测的行为。
始终使用滚动主版本标签，切勿固定到补丁版本。滚动标签会在重启时自动更新。固定的镜像会累积漏洞并错过Bug修复。当前标签字符串位于
```
references/connector-deployment.md
```
中。
通过添加更多Connector进行扩容，而非升级主机规格。Connector是轻量级的——小型实例即可处理数百个并发用户。通过并行实现高可用，而非垂直扩容。
Connector主机必须能够直接访问后端资源。认证成功但无法访问资源的Connector在控制台中显示为ALIVE，但会静默代理失败。始终从Connector主机进行测试，而非用户机器。
DEAD_NO_RELAYS
始终表示连接器无法连接到Twingate的控制/中继基础设施。最常见的原因是对
```
*.twingate.com
```
进行DPI/SSL检查，也可能是所需的出站端口被阻塞，或者（较罕见）仅支持IPv6的主机没有通往中继的公共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
```
中。
优先选择官方部署路径。以下列出的社区、实验室和SE仓库是Twingate未官方打包支持的平台（Raspberry Pi镜像、Ubiquiti网关、Steam Deck、Hyper-V、CI运行器、集群自动扩缩容等）的参考实现——它们很有用，且通常是唯一选项，但需明确告知用户哪些是社区维护的、哪些是不被支持的SE示例、哪些是实验性的，而非将其作为Twingate官方支持的产品呈现。

Search References First

优先搜索参考资料

Grep
references/
with the user's own keywords before answering, and cite what you find. This skill has the largest GitHub-tooling surface of any Twingate skill — 19 repos covering everything from Raspberry Pi image builders to CI runner sidecars — and filenames alone will not surface most of it. Vendor names, hardware models, exact error strings, and CLI flags live in the file bodies, not the filenames:

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

Never answer from training-data memory for: outbound port numbers, container image tags or Helm values keys, platform-specific deployment commands, hardware sizing, connector log paths or metric names, or upgrade/shutdown procedures — these change between releases and the references are the source of truth. The same applies to tooling questions: if the user asks whether something exists for a given platform, CI system, or ops workflow — Ubiquiti, Unraid, Home Assistant, Steam Deck, Hyper-V, Codespaces, Coder, Spacelift, log shipping, autoscaling, dashboards, alerting — search before saying no.

在回答前先用用户的关键词在
references/
目录中进行grep搜索，并引用找到的内容。本技能拥有所有Twingate技能中最大的GitHub工具覆盖范围——19个仓库，涵盖从Raspberry Pi镜像构建器到CI运行器边车的所有内容——仅靠文件名无法找到大部分内容。厂商名称、硬件型号、精确错误字符串和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值键、平台特定部署命令、硬件规格、连接器日志路径或指标名称、升级/关闭流程——这些内容会随版本更新而变化，参考资料是唯一可信来源。工具相关问题同样如此：如果用户询问某平台、CI系统或运维工作流（Ubiquiti、Unraid、Home Assistant、Steam Deck、Hyper-V、Codespaces、Coder、Spacelift、日志发送、自动扩缩容、仪表盘、告警）是否有对应的工具，先搜索再回答没有。

Routing

路由

Co-activate, don't either/or. The pointers below are additive: for a cross-cutting prompt, load and grep the named skills'

references/

in addition to this one — never stop at the first skill that matched. Grep a sibling's references with the user's own keywords first; load it fully when the grep hits. Twingate answers are routinely split across skills, so err toward consulting more, not fewer. Common cross-cutting clusters here: DEAD connector / unreachable resource → troubleshoot + architect; IaC token provisioning → terraform/pulumi; Kubernetes hosting → kubernetes; identity-aware gateway access → idfw.

→ twingate-architect: for questions about Remote Network topology or Resource definition strategy
→ twingate-kubernetes: for Helm chart deployment or K8s-specific Connector patterns
→ twingate-terraform / twingate-pulumi: for IaC-automated token generation
→ twingate-troubleshoot: when a Connector is DEAD or a user cannot reach a resource

协同激活，而非二选一。以下指引是补充性的：对于跨领域的请求，除了本技能外，还需加载并grep指定技能的

references/

目录——切勿在匹配到第一个技能时就停止。先用用户的关键词grep关联技能的参考资料；当grep命中时再完整加载该技能。Twingate的答案通常分散在多个技能中，因此应倾向于咨询更多技能，而非更少。常见的跨领域组合：故障连接器/无法访问资源 → troubleshoot + architect；IaC令牌配置 → terraform/pulumi；Kubernetes托管 → kubernetes；身份感知网关访问 → idfw。

→ twingate-architect：用于远程网络拓扑或资源定义策略相关问题
→ twingate-kubernetes：用于Helm Chart部署或K8s特定Connector模式相关问题
→ twingate-terraform / twingate-pulumi：用于IaC自动化令牌生成相关问题
→ twingate-troubleshoot：当Connector处于DEAD状态或用户无法访问资源时

References

参考资料

See

references/

for the current corpus, refreshed weekly. Three kinds of file live there:

{slug}.md
— summaries of
```
twingate.com/docs
```
pages (product documentation).
{numeric-id}-{slug}.md
— Twingate help-center articles: symptom-shaped support content, exact error strings, and per-platform gotchas.
gh-{org}-{repo}.md
— summaries of public Twingate GitHub repos: SE and community tooling, reference implementations, and automation — 19 of them for this skill alone.

当前语料库见

references/

，每周更新。其中包含三类文件：

{slug}.md
——
```
twingate.com/docs
```
页面（产品文档）的摘要。
{numeric-id}-{slug}.md
—— Twingate帮助中心文章：基于症状的支持内容、精确错误字符串及平台特定注意事项。
gh-{org}-{repo}.md
—— 公开Twingate GitHub仓库的摘要：SE和社区工具、参考实现及自动化——本技能单独涵盖19个此类仓库。

Core deployment & operations

核心部署与运维

If the user asks about…	Read first
What a Connector is, how it registers, connection concepts	`connectors.md` , `understanding-connectors.md` , `connector-client-registration.md`
Network requirements, ports, firewall/SG/NSG rules, egress	`connector-best-practices.md`
Cloud deployment overview (universal pattern, all providers)	`cloud-providers-guide.md`
AWS-specific deployment (ECS, EC2, EKS)	`aws-connector-patterns.md` , `aws.md` , `aws-ecs-headless-configurations.md`
Azure-specific deployment (ACI, VMs, AKS); Docker Hub rate limits blocking ACI deploy/restart ( `RegistryErrorResponse` , `index.docker.io` )	`azure-connector-patterns.md` , `azure.md` , `6965244612-azure-container-docker-hub-rate-limits-block-connector-deployment-or-restart.md`
GCP-specific deployment (GCE, GKE, Cloud Run, MIG)	`gcp-connector-patterns.md` , `gcp.md`
Docker / Docker Compose deployment	`docker.md` , `deploy-connector-with-docker-compose.md`
Linux / systemd deployment	`connectors-on-linux.md` , `systemd-service.md`
PaaS / managed container platforms (Aptible)	`aptible.md`
Homelab / NAS overview, getting started	`homelabs-guide.md` , `home-assistant-getting-started.md` , `headless-iot-gateway.md`
NAS, homelab, on-prem (Synology, QNAP, TrueNAS, Proxmox, Unraid, Firewalla, CasaOS, ZimaOS, Ubiquiti) — official doc pages	`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 image tag, container env vars, deployment commands	`connector-deployment.md` , `connector-metadata.md` , `connector-details.md`
Semi-automated / scripted deployment (Terraform, API)	`deployment-semi-automation.md`
Connector upgrades; `apt upgrade` fails with `NO_PUBKEY` GPG error	`upgrading-connectors.md` , `5202917932-connector-upgrade-produces-gpg-error-in-apt.md`
`DEAD_NO_RELAYS` , `DEAD_NO_HEARTBEAT` , health diagnosis	`connector-real-time-logs.md` , `connector-monitoring.md` , `connector-health-checks.md`
Logs, metrics, monitoring, SIEM integration; enabling debug-level ( `TWINGATE_LOG_LEVEL=7` ) logging and exporting logs	`connector-metrics.md` , `connector-monitoring.md` , `connector-real-time-logs.md` , `siem-guide.md` , `2906603735-twingate-connector-logs.md`
Real-time connection logs to S3 fail with "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`
Hardware sizing, HA topology, placement	`connector-best-practices.md` , `connector-placement-best-practices.md`
Headless / service account clients	`services-headless-clients.md` , `aws-ecs-headless-configurations.md`
Connector shutdown, restart, lifecycle	`connector-shutdown-process.md` , `advanced-connector-management.md`

如果用户询问…	优先阅读
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`

Connector offline / flapping diagnostics (symptom-shaped help articles)

连接器离线/波动诊断（基于症状的帮助文章）

Symptom	Read first
Repeating `Token is expired` 403 in logs — benign, PubNub Access Manager token auto-renewal, no action needed	`1364033881-repeating-token-is-expired-error-in-connector-logs.md`
"too many open files" — host `ulimit` of 1024 fds capping ~128 concurrent clients; ECS Fargate can't override it	`1422554451-connector-offline-too-many-open-files-in-logs.md`
Status flapping offline/online, or dies days after restart — host clock drift >5s vs. Controller; fix with `chronyd` , not `ntpd` alone	`4104282255-connector-offline-status-flapping-offline-online-or-goes-offline-some-time-after-restart.md`
"Gone, code 410" in logs — tokens expired/deleted server-side, unrecoverable; requires `apt purge twingate-connector` and full re-deploy with fresh tokens	`4908519978-connector-offline-gone-code-410-in-logs.md`
Connector healthy but zero Resource connections succeed — host has only a public IPv6 address; Relay requires IPv4, assign an Elastic IP / external IPv4	`4995810632-connector-cannot-connect-to-the-twingate-relay.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`
Connector健康但无法成功连接任何资源 —— 主机仅拥有公网IPv6地址；中继需要IPv4，需分配弹性IP/外部IPv4	`4995810632-connector-cannot-connect-to-the-twingate-relay.md`

GitHub repository tooling

GitHub仓库工具

These 19 repos are not bundled — clone/inspect at runtime. Each solves a distinct deployment or ops problem; read the file's

## Summary

and

## Key Information

before recommending one, and flag community/Labs/SE-example status per the guideline above.

Platform-specific deployments (hardware and OS targets Twingate doesn't officially package for):

Platform	What it does	Read first
Raspberry Pi — turnkey SD image	Builds a flashable Raspberry Pi OS image that auto-provisions a Connector via the Twingate API on first boot (systemd `twingate-firstboot` service); daily CI checks for new Connector/OS versions	`gh-twingate-community-pi-starter.md`
Raspberry Pi — install scripts	Official Twingate-Solutions install scripts for running the Twingate client directly on an already-running Pi (ARM32/ARM64), service-key based — distinct from the pi-starter image builder above	`gh-twingate-solutions-twingate-raspberry-pi.md`
Ubiquiti / UniFi gateways (UDM Pro, UDM SE, UXG-Pro, UXG-Max)	Deploys a Connector inside a `systemd-nspawn` Debian container on the gateway itself; boot hook + `unifi-common` service persist it across UniFi OS firmware upgrades	`gh-twingate-community-ubiquiti-connector.md`
Unraid	Official Docker template XML for Unraid's Community Apps UI — drop-in template exposing Access Token / Refresh Token / Network Name fields	`gh-twingate-community-unraid-template.md`
Home Assistant	Packages the Connector as a Home Assistant Supervisor add-on ( `aarch64` / `amd64` / `armv7` ); requires HAOS/Supervised, not Core-only installs	`gh-twingate-community-home-assistant-add-on.md`
Steam Deck (Decky Loader / QAM)	`Twindeck` — a Decky Loader plugin running the Twingate Headless Client from the Quick Access Menu without leaving gaming mode; needs a Service Account key	`gh-twingate-community-twindeck.md`
Windows Server / Hyper-V	PowerShell scripts ( `Deploy-TwingateConnector.ps1` ) that provision Connector VMs on Hyper-V via cloud-init Ubuntu 24.04 images, with full create/update/repair/remove lifecycle through the Twingate API	`gh-twingate-solutions-twingate-connector-hyperv.md`
Windows Chocolatey packaging	Chocolatey package definitions for `choco install twingate` — silent/automated Windows client install, upgrade, uninstall	`gh-twingate-labs-chocolatey-packages.md`
Custom/hardened connector container	Example Docker image adding shell access, a pluggable `/healthchecks.d/` healthcheck system, and structured JSON resource metrics on stderr (separated from connector stdout)	`gh-twingate-solutions-twingate-custom-connector-container.md`

CI/CD and ephemeral dev-environment runners:

Environment	What it does	Read first
Coder workspaces	Terraform templates replacing Coder's default `main.tf` to run a Twingate client inside a workspace, supporting both interactive user auth and Service Account (headless) auth	`gh-twingate-labs-tg-coder.md`
GitHub Codespaces	`.devcontainer` Dockerfile + two `devcontainer.json` variants (Service Account or interactive) so a Codespace can reach Twingate-protected private resources	`gh-twingate-labs-tg-github-codespaces.md`
render.com	One-click "Deploy to Render" button that stands up a Connector as a render.com service using tokens generated in the Admin Console	`gh-twingate-labs-tg-render.md`
Spacelift CI runners	Runs Twingate's userspace HTTP proxy mode plus `proxytunnel` inside an unprivileged Spacelift runner container — no root, no TUN device, no `NET_ADMIN` — to bridge Postgres/MySQL/SSH through Twingate's HTTP CONNECT proxy	`gh-twingate-solutions-twingate-client-userspace-spacelift.md`

Observability, ops, and fleet automation:

Capability	What it does	Read first
Grafana dashboards	Community Grafana dashboard ( `grafana/insights.json` ) visualizing Connector transport breakdown (direct/relay-hydra/relay-quic), traffic, and uptime from a Prometheus-fed metrics export; needs Grafana 12.2.1+	`gh-twingate-community-dashboards.md`
PagerDuty alerting	Bash/systemd service that tails Connector logs via `journalctl -f` , forwards `Offline` / `Error` / `Unrecoverable error` state changes to PagerDuty's Events API v2, and auto-resolves on recovery	`gh-twingate-labs-twingate-pagerduty.md`
Log shipping to S3	Python sidecar/systemd service that captures `ANALYTICS` -prefixed Connector stdout, batches it, and uploads gzip NDJSON to any S3-compatible store (AWS S3, MinIO, R2, B2, Spaces); requires `TWINGATE_LOG_ANALYTICS=v2`	`gh-twingate-solutions-twingate-connector-log-shipper.md`
Local connector status UI	Lightweight web dashboard running alongside a Connector on the same host for on-box status/diagnostics without the Admin Console — no built-in auth, restrict via firewall	`gh-twingate-solutions-connector-local-ui.md`
Generic Docker auto-updater (Janus)	Label-driven container updater ( `janus.autoupdate.enable=true` ) that recreates any labeled container — including custom connector containers — when a newer image is available, with rollback on failure; not Compose-aware	`gh-twingate-solutions-janus-updater-service.md`
Connector fleet autoscaling	"Fleet Commander" — an async control-plane loop that discovers, scales, and retires Connector containers across Docker/ECS/ACI backends via the Docker socket and the Twingate GraphQL Admin API; exposes `/healthz` , `/readyz` , `/metrics`	`gh-twingate-solutions-twingate-fleet-commander.md`

This table is a fast path, not the whole corpus — when a question doesn't match a row, grep

references/

before answering.

这19个仓库未捆绑——需在运行时克隆/查看。每个仓库解决一个独特的部署或运维问题；在推荐前先阅读文件的

## Summary

和

## Key Information

部分，并根据上述准则标注社区/实验室/SE示例状态。

特定平台部署（Twingate未官方打包支持的硬件和操作系统）：

平台	功能	优先阅读
Raspberry Pi —— 开箱即用SD镜像	构建可刷写的Raspberry Pi OS镜像，首次启动时通过Twingate API自动配置Connector（systemd `twingate-firstboot` 服务）；每日CI检查新的Connector/OS版本	`gh-twingate-community-pi-starter.md`
Raspberry Pi —— 安装脚本	官方Twingate-Solutions安装脚本，用于在已运行的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容器中部署Connector；启动钩子+ `unifi-common` 服务可在UniFi OS固件升级后保持其运行	`gh-twingate-community-ubiquiti-connector.md`
Unraid	适用于Unraid社区应用UI的官方Docker模板XML——即插即用模板，暴露访问令牌/刷新令牌/网络名称字段	`gh-twingate-community-unraid-template.md`
Home Assistant	将Connector打包为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插件，可从快速访问菜单运行Twingate无头客户端，无需退出游戏模式；需要服务账户密钥	`gh-twingate-community-twindeck.md`
Windows Server / Hyper-V	PowerShell脚本（ `Deploy-TwingateConnector.ps1` ），通过cloud-init Ubuntu 24.04镜像在Hyper-V上配置Connector虚拟机，支持通过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资源指标（与connector 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"按钮，使用管理控制台生成的令牌在render.com上部署Connector作为服务	`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` ），可视化Connector传输 breakdown（direct/relay-hydra/relay-quic）、流量及基于Prometheus导出指标的 uptime；需要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边车/systemd服务，捕获以 `ANALYTICS` 为前缀的Connector stdout，批量处理后将gzip压缩的NDJSON上传至任何S3兼容存储（AWS S3、MinIO、R2、B2、Spaces）；需要 `TWINGATE_LOG_ANALYTICS=v2`	`gh-twingate-solutions-twingate-connector-log-shipper.md`
本地连接器状态UI	轻量级Web仪表盘，与Connector在同一主机上运行，无需管理控制台即可进行本地状态/诊断——无内置认证，需通过防火墙限制访问	`gh-twingate-solutions-connector-local-ui.md`
通用Docker自动更新器（Janus）	基于标签的容器更新器（ `janus.autoupdate.enable=true` ），当有新版本镜像可用时，重新创建所有带标签的容器（包括自定义连接器容器），失败时支持回滚；不支持Compose	`gh-twingate-solutions-janus-updater-service.md`
连接器集群自动扩缩容	"Fleet Commander"——异步控制平面循环，通过Docker套接字和Twingate GraphQL管理API在Docker/ECS/ACI后端发现、扩缩容和回收Connector容器；暴露 `/healthz` , `/readyz` , `/metrics` 端点	`gh-twingate-solutions-twingate-fleet-commander.md`

此表格是快速检索路径，而非完整语料库——当问题与表格中的行不匹配时，先grep

references/

再回答。