Infisical App Connections 指南
本技能是一个设置助手，帮助用户创建 App Connections——即 Infisical 组织与第三方服务之间可复用的、经过认证的连接。
App Connection 一次性保存凭据，之后可被多个功能通过 ID 引用。它本身是一个前置条件，而不是一个独立功能：用户通常是因为其他功能需要 connectionId 才来到这里。
为什么这是一个独立技能
有五个不同功能会使用 App Connections：
功能 | 技能 | 连接用途 Secret Syncs | infisical-secret-syncs | 将密钥推送到目标 Secret Rotations | infisical-secret-rotation | 在源端更改凭据 PKI Syncs | infisical-pki | 将证书推送到目标 Certificate Authorities | infisical-pki | ACME DNS 验证、ADCS、Venafi、DigiCert Secret Scanning 数据源 | infisical-secret-scanning | 读取仓库以进行扫描
连接类型由使用它的功能决定。PostgreSQL 密钥轮换需要专门的 postgres 连接；不能用通用连接替代。创建连接前，务必确认目标功能要求哪种连接类型。
不属于本技能的情况
如果用户想要…… | 使用 将密钥推送到某个服务 | infisical-secret-syncs（先在这里创建连接） 轮换现有凭据 | infisical-secret-rotation 让工作负载能够向 Infisical 认证的机器身份 | infisical-setup——那是相反方向 访问私有网络 | infisical-gateway——然后在这里将网关附加到连接
人们容易混淆的是信任方向。机器身份让外部工作负载向 Infisical 认证。App Connection 让 Infisical 向第三方认证。如果用户持有 Infisical 签发的 Client ID 和 Client Secret，他们需要的是机器身份，而不是本技能。
如何使用本技能
- 查明哪个功能需要它，因此需要哪种连接类型
- 选择认证方式——大多数连接支持多种方式，设置差异明显
- 在第三方侧授予最小权限
- 如果目标无法公开访问，决定网关路由
- 创建连接，然后从使用它的功能中引用其 UUID
参考文件
其中两个由 Infisical 源码生成——它们包含事实，tools/generate-app-connection-refs.py 可重新生成它们。其余为手写指南。
文件 | 是否生成 | 何时阅读 references/api-surface.md | 是 | 端点：按连接的 CRUD，以及机器身份实际可以调用哪些发现端点 references/credentials-by-connection.md | 是 | 全部 83 种连接的确切 method 值和凭据字段 references/connection-catalog.md | 否 | 83 种连接一览，含 Gateway / 平台托管 / 轮换能力标志 references/cloud-providers.md | 否 | AWS、GCP、Azure（所有变体）及其权限要求 references/git-and-cicd.md | 否 | GitHub（+ GitHub Radar）、GitLab、Bitbucket、Azure DevOps、CI 提供商 references/databases-and-infra.md | 否 | PostgreSQL、MySQL、MSSQL、OracleDB、MongoDB、Redis、LDAP、SSH、SMB/WinRM，以及 Gateway + 平台托管凭据
指导原则
优先使用零密钥方式（如果存在）。AWS assume-role 优于 access-key。GCP 只提供服务账号模拟。GitHub App 优于 PAT。只有在平台没有其他选择时才回退到静态凭据。
认证方式值是精确字符串。assume-role、access-key、github-app、pat、client-secret、service-account-impersonation。请从目录中读取，不要猜测；像 access-keys 或 github_app 这样的近似值会验证失败。
一个连接，多个消费者。连接是组织级且可复用的。不要为每个同步创建一个。可选地通过 projectId 将其限定到一个项目。
连接不是网关。只有 16 种连接类型接受 gatewayId。对于其余类型，传入它是验证错误，而不是无操作。
gatewayId 和 gatewayPoolId 互斥。同时指定会失败。
连接凭据轮换与 Secret Rotation 是不同的功能。有五种连接类型可以轮换自己存储的凭据。这不会向你的密钥中写入任何内容——要做到这一点，请使用 infisical-secret-rotation。
大多数资源发现端点无法自动化。Infisical 暴露了 94 个列出提供商资源（vault、仓库、集群）的端点。其中 88 个仅限 AuthMode.JWT——即用户会话。机器身份访问令牌会被拒绝，许多在源码中标记为“未暴露且仅供 Infisical App 使用”。只有 6 个接受机器身份令牌。要为同步或轮换配置获取资源 ID，请直接查询提供商，或在 UI 中创建一次资源并通过 API 读回其配置。参见 references/api-surface.md。
按名称解析连接，而不是按 UUID。GET /api/v1/app-connections/<slug>/connection-name/{connectionName} 存在并接受机器身份令牌，因此自动化无需存储 UUID。
第三方侧最小权限。连接的权限界定了每个消费同步和轮换能做什么。请缩小范围，并在用户即将交出管理员密钥时提及这一点。
绝不要代替用户生成凭据，也绝不要回显凭据。