主题
连接器把文件从 Google Drive、SharePoint、S3 与 Confluence 同步进 project 目录。它们如何工作见连接器。在自托管部署上，你要提供三样东西：
- 加密密钥。 LlamaCloud 会加密它保存的每一份凭据。没有密钥时它拒绝存储凭据，创建 connection 就会失败。
- 要提供哪些连接类型。 例如只有 S3，或者 S3 加上 Google Drive 与 SharePoint 的登录式连接。
- OAuth 客户端应用，仅当你提供登录式（“Sign in with Google” 或 “Sign in with Microsoft”）连接时才需要。这些应用由你自己向 Google 或 Microsoft 注册，再通过 API 把它们的 client ID 与 secret 交给 LlamaCloud。
使用密钥的连接（S3 access key、Google 服务账号密钥、SharePoint 应用注册、Confluence API token）只需要第 1、2 两步。
values.yaml 里的连接器设置
chart 0.9.3 及之后把连接器配置在 config.connectors 下。chart 会把这些设置传给所有会存取凭据的工作负载：API 与 Temporal worker。
config:
connectors:
# Which connection types to offer (see below). This is the default.
enabledAuthTypes: "google_drive:oauth,google_drive:service_account,sharepoint:oauth,sharepoint:service_account,s3:service_account"
# Where Google or Microsoft sends users back after sign-in.
# Defaults to https://<ingress.host>/credential-brokers/return.
oauthReturnUrl: ""
# Encrypt with AWS KMS...
credentialsKmsKeyArn: ""
tokenVaultKmsKeyArn: ""
# ...or with master keys, and the sign-in seal key, from a Secret you create.
secret: llamacloud-connector-secrets请在安装或升级之前先把这个 Secret 建好。chart 绝不会代你生成这些密钥：
终端窗口
kubectl create secret generic llamacloud-connector-secrets \
--from-literal=CONNECTOR_AUTH_SEAL_KEY="$(openssl rand -base64 32)" \
--from-literal=CONNECTOR_MASTER_KEY="$(openssl rand -base64 32)" \
--from-literal=TOKEN_VAULT_MASTER_KEY="$(openssl rand -base64 32)"当你为对应项改设了 KMS key ARN 时，就可以不设 CONNECTOR_MASTER_KEY 或 TOKEN_VAULT_MASTER_KEY。下面逐项说明。
连接器的加密密钥
LlamaCloud 保存两类连接器机密，每一类都用自己独立的密钥加密：
| 机密 | 举例 | KMS 密钥 | 或放在 Secret 里的主密钥 |
|---|---|---|---|
| connection 自己持有的凭据 | S3 access key、Google 服务账号密钥、SharePoint client secret、Confluence API token | credentialsKmsKeyArn | CONNECTOR_MASTER_KEY |
| OAuth 客户端应用，以及登录式连接拿到的 token | 你的 Google 与 Entra client secret、用户的 refresh token | tokenVaultKmsKeyArn | TOKEN_VAULT_MASTER_KEY |
每一类都二选一：
- 一把 KMS 密钥：填密钥 ARN 或别名 ARN，且要带地域，例如
arn:aws:kms:us-east-1:123456789012:alias/llamacloud-connector-credentials。API 与 Temporal worker pod 的 IAM 角色需要对它有kms:GenerateDataKey、kms:Decrypt与kms:DescribeKey权限。若 KMS 密钥与主密钥都设了，以 KMS 密钥为准。 - 一把主密钥：放在 Secret 里的一把随机密钥，用于没有 AWS KMS 的部署。用
openssl rand -base64 32生成。
密钥的规则：
- 每一类用不同的密钥。 不要把
CONNECTOR_MASTER_KEY复用成TOKEN_VAULT_MASTER_KEY，也不要一把 KMS 密钥两用。 - 一旦已有 connection，就绝不更改或丢失密钥。 已存的凭据只能用加密它的那把密钥解开；密钥变了，用过它的每一个 connection 都必须删掉重建。
没有密钥时，创建基于密钥的 connection 会返回 503 Credentials could not be stored securely，注册 OAuth 客户端应用则返回 500 Token vault encryption is not available。
CONNECTOR_AUTH_SEAL_KEY 是第三把独立的密钥，用于保护登录过程中来回传递的短期 state。它必须是 32 随机字节并做 base64 编码（openssl rand -base64 32）。没有它就创建不了登录式连接；基于密钥的连接不需要它。
选择要提供哪些连接类型
config.connectors.enabledAuthTypes 是一个逗号分隔的 integration:auth_type 列表。API 会拒绝任何未列出的组合并返回 422。设成 "" 即整体关闭连接器。
| 组合 | 连接 | 默认是否包含 |
|---|---|---|
s3:service_account | 用 access key 密钥对的 S3 | 是 |
google_drive:service_account | 用服务账号密钥文件的 Google Drive | 是 |
google_drive:oauth | Google Drive，用 Google 登录 | 是 |
sharepoint:service_account | 用 Entra 应用注册与 client secret 的 SharePoint | 是 |
sharepoint:oauth | SharePoint，用 Microsoft 登录 | 是 |
confluence:api_key | 用 API token 或个人访问令牌的 Confluence | 否 |
confluence:oauth | Confluence Cloud，用 Atlassian 登录 | 否 |
Add connection 对话框里的那些卡片是在前端镜像构建时就固定的，并与默认列表一致。如果你收窄了列表（例如只留 s3:service_account），其他卡片仍会显示，但被使用时会因 422 失败。而不在默认列表里的连接类型，根本无法从对话框添加 —— 只要你把它列进配置，API 就接受。
对于只用 S3 的部署，s3:service_account 加上 CONNECTOR_MASTER_KEY（或 credentialsKmsKeyArn）就够了。本页其余部分可以跳过。
启用登录式连接
登录式连接走你自己部署内的 token vault，使用你在下面注册的 OAuth 客户端应用。除 token vault 密钥与 CONNECTOR_AUTH_SEAL_KEY 之外，它们还需要一个回调 URI：
https://<your-llamacloud-host>/credential-brokers/return<your-llamacloud-host> 就是你的 ingress.host，即你打开界面用的那个域名。chart 会据 ingress.host 替你拼出这个 URL。只有当用户访问 LlamaCloud 的地址与之不同（例如走你自己的 ingress）时，才需要设 config.connectors.oauthReturnUrl。
这个 URI 必须与你向 Google 和 Microsoft 注册的逐字符一致：同样的协议、同样的主机、结尾不带斜杠。LlamaCloud 会在发起登录时以及换取 code 时各发送一次它，任何不一致都会被提供方拒绝。
为 Google Drive 创建 Google OAuth 客户端
请在你组织掌控的一个 Google Cloud project 里完成这些操作。
在 Google Cloud 控制台打开 APIs & Services → Library，启用 Google Drive API 与 Google Picker API。
打开 Google Auth Platform → Branding（即 OAuth 同意屏幕）并填写。在 Audience 下选择：
- 只有你 Google Workspace 内的账号需要连接时选 Internal。这是最省事的选择，Google 不会审查 Internal 应用。
- 还需要其他域的账号连接时选 External。
drive.readonly属于受限 scope，因此 External 应用必须通过 Google 的验证，你测试用户之外的人才能使用它。
在 Data Access 下加入这些 scope：
openid.../auth/userinfo.email.../auth/userinfo.profilehttps://www.googleapis.com/auth/drive.readonly
在 Clients 下点击 Create client，选择 Web application，并添加一个 Authorized redirect URI：
https://<your-llamacloud-host>/credential-brokers/return。复制 Client ID 与 Client secret。
LlamaCloud 始终会申请 offline access，因此每个 connection 都会拿到一个 refresh token，无需用户再次登录就能持续同步。
为 SharePoint 登录创建 Microsoft Entra 应用
这个应用是给 SharePoint（用 Microsoft 登录）连接用的。它与 SharePoint Keys 连接所用的应用注册不是一回事 —— 后者需要的是 application 权限，见 SharePoint 连接器。
在 Microsoft Entra 管理中心 里，进入 App registrations → New registration。
在 Supported account types 下选择 Accounts in any organizational directory (multitenant)。LlamaCloud 通过 Microsoft 的
organizations端点让用户登录，而单租户应用在该端点上会被拒绝。在 Redirect URI 下选择 Web 平台，填入
https://<your-llamacloud-host>/credential-brokers/return。在 API permissions → Add a permission → Microsoft Graph → Delegated permissions 下，把下面表里的每一个 scope 都加上。这正是 LlamaCloud 每次用户登录时申请的完整列表，也就是你要为登记进 token vault 的那个应用所批准的 scope 集合。少加一个，登录就会失败。
Scope LlamaCloud 为何要它 offline_access拿到 refresh token，使 connection 无需用户重新登录就能持续同步 openid,profile,email识别用户及其租户 User.Read读取已登录用户的个人资料 Sites.Read.All读取该用户能打开的 SharePoint 站点、文档库与文件 Sites.FullControl.All读取每个文件的访问者，SharePoint 权限同步需要它，并能在不做完整重同步的情况下察觉文件夹被共享或取消共享 为了让用户能用 Microsoft 的文件选择器浏览文件夹，还要加上 SharePoint → Delegated permissions →
AllSites.Read。没有它选择器打不开。用户仍可以创建文件夹，但只能靠填写 ID。为你的租户点击 Grant admin consent。
Sites.Read.All与Sites.FullControl.All在多数租户里都需要管理员同意，提前做掉可省去每个用户各自去申请。在 Certificates & secrets 下创建一个 client secret。复制的是它的 Value，不是 Secret ID，并记下它的过期日期。
从 Overview 复制 Application (client) ID。
以上全部是 delegated 权限。这个 connection 只能读到已登录用户本人能打开的内容。
通过 API 登记 OAuth 客户端应用
用 POST /api/v2/internal/token-vault/apps 把每个应用的 client ID 与 secret 交给 LlamaCloud。secret 会用 token vault 密钥加密，且永不回传。每个应用只作用于一个层级：
tenant_type | tenant_id | 谁能登记 | 作用于 |
|---|---|---|---|
global | 省略 | 全局管理员 | 整个部署里的所有 project |
organization | 组织 ID | 组织管理员 | 该组织下的 project |
project | project ID | project 管理员 | 仅该 project |
在多数部署里，每个提供方登记一个 global 应用就足够了。调用该 API 时，请使用在你所要登记的层级上拥有管理员角色的账号的 API key：
终端窗口
LLAMACLOUD="https://llamacloud.example.com"
# Google Drive
curl -sS -X POST "$LLAMACLOUD/api/v2/internal/token-vault/apps" \
-H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"integration": "google_drive",
"tenant_type": "global",
"client_id": "'"$GOOGLE_CLIENT_ID"'",
"client_secret": "'"$GOOGLE_CLIENT_SECRET"'"
}'
# SharePoint (set expires_at to the client secret's expiry)
curl -sS -X POST "$LLAMACLOUD/api/v2/internal/token-vault/apps" \
-H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"integration": "sharepoint",
"tenant_type": "global",
"client_id": "'"$ENTRA_CLIENT_ID"'",
"client_secret": "'"$ENTRA_CLIENT_SECRET"'",
"expires_at": "2027-09-30T00:00:00Z"
}'响应会回显 client_id 与应用自身的 id，但绝不会回显 secret。每个 integration 的 OAuth scope 是固定的，因此你不必提交它们。
integration 接受 google_drive、sharepoint 与 confluence。对于 Confluence，用同样的方式注册一个 Atlassian OAuth 2.0 (3LO) 应用，并把它的回调 URL 设为同一个 redirect URI。
管理已登记的 OAuth 应用
| 请求 | 作用 |
|---|---|
GET /api/v2/internal/token-vault/apps?tenant_type=global | 列出某一层级下的应用（organization 或 project 要再加 &tenant_id=…）。可用 integration、is_enabled、is_expired 过滤。 |
PATCH /api/v2/internal/token-vault/apps/{app_id} with {"enabled": false} | 不再把该应用提供给新的 connection。已有的 connection 继续可用。 |
DELETE /api/v2/internal/token-vault/apps/{app_id} | 删除该应用。若仍有 connection 在用它则返回 409。 |
应用不能被编辑。要轮换 client secret，就把新 secret 登记为第二个应用、停用旧的那个，并在没有任何 connection 使用它之后再删除。越过其 expires_at 之后，该应用不再被提供给新的 connection。
同步 SharePoint 的文件权限
SharePoint 同步还可以读取每个文件与文件夹的访问者，并把它以 allowed_* 元数据写到文件上，供你在检索时按此过滤。它默认关闭，因为读取访问权限意味着要为每个文件额外调一次 Graph。
按 SharePoint 的每种连接类型分别开启，使用形如 <INTEGRATION>__<AUTH_TYPE>__SYNC_PERMISSIONS 的环境变量：
| 变量 | 连接 |
|---|---|
SHAREPOINT__OAUTH__SYNC_PERMISSIONS | SharePoint，用 Microsoft 登录 |
SHAREPOINT__SERVICE_ACCOUNT__SYNC_PERMISSIONS | SharePoint Keys（Entra 应用注册） |
后端与 Temporal worker 都要设置它。worker 执行同步并决定是否读取访问权限；后端在创建时校验文件夹用的是同一个设置。只配了其中一个，两边就会不一致。
backend:
extraEnvVariables:
- name: SHAREPOINT__OAUTH__SYNC_PERMISSIONS
value: "true"
temporalWorkloads:
workers:
temporal-jobs-worker:
extraEnvVariables:
- name: SHAREPOINT__OAUTH__SYNC_PERMISSIONS
value: "true"该设置在 pod 启动时读取，因此从 helm upgrade 的那次滚动更新起生效。
这个 connection 还需要 Sites.FullControl.All：
- 登录式连接：已包含在上面那个 Entra 应用的 scope 列表里。请确认它已被添加并在应用上完成管理员同意。
- SharePoint Keys 连接：需要带管理员同意的 application 权限，见 SharePoint 连接器。如果应用注册里没有它，文件仍会同步但不带访问元数据，且 worker 会记一条
SharePoint permission sync is on, but the app registration lacks the role it needs。
此后每个同步过来的文件都会带上这些元数据键，按有权访问的主体种类各一个列表：
| 键 | 内容 |
|---|---|
allowed_user_ids, allowed_user_display_names | Entra 用户 |
allowed_group_ids, allowed_group_display_names | Entra 组 |
allowed_siteUser_ids, allowed_siteUser_display_names | SharePoint 站点用户 |
allowed_siteGroup_ids, allowed_siteGroup_display_names | SharePoint 站点组 |
allowed_audiences | 拿到链接即可访问时为 public，组织内所有人可见时为 domain |
某类主体为空时就没有对应的键。完全没有任何 allowed_* 键，意味着该文件的访问权限从未被读取过。ID 列表与显示名列表是分别排序的，因此同一位置上的名字并不属于同一位置上的 ID。这些键名与 legacy SharePoint 数据源所写入的一致，所以为它写好的过滤器仍然可用。
自托管连接器的排障
| 症状 | 该检查什么 |
|---|---|
503 Credentials could not be stored securely when adding a key-based connection | config.connectors.secret 里 credentialsKmsKeyArn 与 CONNECTOR_MASTER_KEY 都没设。 |
500 Token vault encryption is not available when registering an app | config.connectors.secret 里 tokenVaultKmsKeyArn 与 TOKEN_VAULT_MASTER_KEY 都没设。 |
| ”No enabled google_drive app is configured for this tenant” at sign-in | 在能覆盖该 project 的层级上没有为该 integration 登记应用，或它被停用、或已越过 expires_at。 |
Google: redirect_uri_mismatch; Microsoft: AADSTS50011 | 应用上登记的 redirect URI 与 https://<ingress.host>/credential-brokers/return（或 config.connectors.oauthReturnUrl）不完全一致。 |
Microsoft: AADSTS50194 | 该 Entra 应用是单租户的。把 Supported account types 改为多租户。 |
422 naming an integration and auth type | 该组合不在 config.connectors.enabledAuthTypes 里。 |
SharePoint files sync without allowed_* metadata | 后端与 temporal-jobs-worker 没有都设 SHAREPOINT__<AUTH_TYPE>__SYNC_PERMISSIONS，或该 connection 缺 Sites.FullControl.All。见同步 SharePoint 的文件权限。 |
Syncs fail with an error naming a SHAREPOINT__… variable | auth type 之后那一段并不是连接器的设置项，通常是拼写错误。LlamaCloud 会显式报错而不是忽略它。 |
| Syncs fail with decryption errors after a redeploy | Secret 里的密钥或 KMS 密钥 ARN 被改过。请恢复原值。 |