主题
全局管理员拥有覆盖整个平台的访问权，可以在你的自托管 LlamaCloud 部署里管理所有组织、用户与系统级配置。本指南说明如何配置并管理全局管理员的访问权。
概述
全局管理员这一能力提供的是：
- 跨组织可见性：可查看平台上所有的 user-organization 成员关系
- 管理员用户管理：增删全局管理员权限
- 系统级访问：为排障与支持而绕过组织级的限制
- 协助用户的能力：帮用户处理组织访问与成员关系问题
引导出最初的全局管理员
按你的部署需要在下面几种做法里选一种：
做法一：把全局管理员授予第一个用户（最省事）
当你希望自动把管理员权限交给部署里最早的那位用户、且不想配置任何邮箱列表时，用这种做法。
何时使用
- 全新部署、尚无任何管理员
- 希望由创建时间最早的用户出任第一位管理员
- 最简配置 —— 不需要任何环境变量
配置步骤
- 部署 LlamaCloud，不做任何特别的全局管理员配置
- 确保至少有一位用户登录过（这会创建 user_organization 记录）
- 调用同步端点来引导出第一位管理员：
终端窗口
curl -X POST "https://your-llamacloud-domain/api/internal/permissions/sync-global-admins?earliest_email=true"提示
earliest_email=true 参数会在 user_organization 表里找到 created_at 时间戳最早的那位用户，并授予其管理员权限。这在没有管理员时能帮你把管理员体系先立起来。
做法二：用环境变量指定管理员用户
当你想明确控制哪些用户会成为全局管理员（例如第一个用户并不是你想选的那位）时，用这种做法。
何时使用
- 想按邮箱地址把管理员权限授予特定用户
- 需要更受控的管理员指派
- 在初始配置之后追加更多管理员
配置步骤
- 在你的
values.yaml里配置管理员邮箱：
backend:
extraEnvVariables:
- name: GLOBAL_ADMIN_EMAILS
value: "admin1@yourcompany.com,admin2@yourcompany.com,admin3@yourcompany.com"把更新后的配置部署到你的集群
调用 API 端点同步权限：
终端窗口
curl -X POST "https://your-llamacloud-domain/api/internal/permissions/sync-global-admins"- 邮箱要求：用逗号分隔的邮箱地址，中间不带空格
- 用户前提：被列出的用户必须至少登录过平台一次
- 幂等：可以安全地重复执行 —— 不会创建重复的权限
做法三：把一个邮箱模式当作全局管理员（临时覆盖）
当你要让所有邮箱匹配某个模式的人（例如你公司域名下的所有人）都具备全局管理员身份、而又不想逐个人授权时，把这种做法作为临时覆盖使用。
- 在你的
values.yaml里配置该模式：
backend:
extraEnvVariables:
- name: ALLOWED_GLOBAL_ADMIN_REGEX
value: '[^@]+@yourcompany\.com'- 把更新后的配置部署到你的集群
匹配上的用户在后端重启后的请求里就具备全局管理员访问权。不需要调用同步，也不会存储任何东西：要结束这次覆盖，删掉该变量并重新部署即可。
- 整串邮箱匹配：模式必须匹配整个邮箱地址，忽略大小写。
[^@]+@yourcompany\.com不会匹配someone@yourcompany.com.example.net。 - 要把域名锚住：像
.*yourcompany.*这样宽松的模式，会让任何包含这段文字的地址都成为管理员。只有在身份提供方会校验邮箱地址时才可这样用。 - 不会出现在管理员列表里：因为没有存储任何权限，这些用户不会显示在 Admin Management 标签页中。要把某人变成持久的大管理员，请用做法二或直接走界面。
通过界面管理更多全局管理员
一旦有了至少一位全局管理员，就可以通过 Web 界面来管理更多管理员。
进入全局管理员界面
- 用一个全局管理员账号登录你的 LlamaCloud 实例
- 在浏览器里访问
/global-admin - 你会看到 Users 与 Admin Management 两个标签页
添加新的全局管理员
- 走到 Admin Management 标签页
- 点击 Add Admin
- 填入你要提升的那位用户的 User ID（不是邮箱）
- 点击 Add Admin
手工方式要求的是 User ID（UUID），不是邮箱地址。你可以先在 Users 标签页里搜索来找到 User ID。
全局管理员的权限层级
- 全局管理员界面访问权：可查看并管理所有 user-organization 关系
- 管理员用户管理：可增删其他全局管理员用户
- RBAC 权限：可通过 API 创建与删除 RBAC 权限
- 跨组织 API 访问：使用用户级 API key 时，可跨所有组织调用现存的 API
- 绕过组织限制：经 API 获得覆盖整个平台的访问权
要拿到跨组织的 API 访问权，你必须使用用户级 API key，而不是 project 级的 key。
API 参考
同步全局管理员
POST /api/internal/permissions/sync-global-admins
POST /api/internal/permissions/sync-global-admins?earliest_email=true从 GLOBAL_ADMIN_EMAILS 环境变量同步全局管理员权限。可选地把最早的用户（按创建时间）一并纳入，用于引导场景。
参数：
earliest_email（boolean，可选）：为true时，自动把管理员权限授予 user_organization 表里 created_at 时间戳最早的那位用户。适合初次部署时使用。
响应：
{
"added": ["admin1@company.com", "earliest-user@company.com"],
"skipped": ["admin2@company.com"],
"errors": ["nonexistent@company.com"]
}说明：
- 限速为每 30 秒 2 次请求
- 幂等 —— 可安全重复执行
- 为所有处理到的用户创建
admin权限 - 邮箱列表与最早用户得到的权限级别相同
管理 RBAC 权限
GET /api/permissions?target_type=global&relationship=admin
POST /api/permissions
DELETE /api/permissions/{permission_id}创建、读取与删除全局管理员权限。