租户管理（组织与成员）

单个 AgentEye 部署可服务于多个完全隔离的组织（租户），因此一个实例可以承载不同的团队、业务单元或客户，而不会将任何一个租户的数据暴露给其他租户。每一行数据（事件、评估、会话、仪表板、已保存查询、告警、API 密钥和成员）都归属于唯一一个组织。主要隔离由应用程序代码强制执行：每个请求都通过显式 org_id 谓词限定到其所属组织。在 ClickHouse 中——高容量事件和评估数据存储于此——这由强力的引擎级强制措施支撑：每个组织获得一个专用的只读 ClickHouse 用户，并配有按组织划分的行级策略，因此即使是不受信任的分析 SQL 也无法读取其他租户的数据行。在 PostgreSQL 上，行级安全为只读查询路径（/queries/run）增加了深度防御，即使应用层过滤器某时缺失，该路径所能访问的内容也会被收窄；服务器自身的写入连接以表所有者身份运行，因此通过相同的应用层 org_id 作用域进行操作。租户生命周期由运维人员控制，而成员的日常操作则在仪表板中完全自助完成。组织及其成员关系通过 agenteye-orgctl CLI 创建和管理，该工具内置于服务器镜像中，并在现有服务器 Pod 内运行，因此会读取服务器使用的相同 DATABASE_URL、CLICKHOUSE_URL 和 ORG_CH_SECRET。租户的创建和删除被刻意排除在仪表板和 HTTP API 之外：没有 HTTP API，也没有仪表板按钮用于租户生命周期管理，因此它受集群/Pod Shell 访问权限而非应用程序界面的保护。在组织内部，成员完全在仪表板和 API 中工作：他们登录、在所属组织之间切换、管理自己的 API 密钥、构建仪表板和已保存查询，以及为其组织配置告警。职责划分清晰：运维人员通过 CLI 配置和注销租户及其成员；成员则通过 UI 在租户内执行所有操作。

单租户部署无需进行任何此类操作。 单租户安装无需任何运维人员操作即可运行。所有数据、用户和密钥都存在于自动配置的内置 default 组织中。只有当您决定添加第二个组织时，才需要参阅本指南。

前提条件

在创建第二个组织之前（内置 default 组织无需任何操作）：

PostgreSQL 15+。 组织成员关系 schema 使用了列列表 ON DELETE SET NULL 外键，需要 PostgreSQL 15+。请在配置第二个组织之前升级 PostgreSQL。
强固且稳定的 ORG_CH_SECRET。 每个组织的 ClickHouse 密码派生自 HMAC(ORG_CH_SECRET, org_id)，因此使用公开已知的内置开发默认值会导致每个组织的凭据可被公开推导。agenteye-orgctl org create 在 ORG_CH_SECRET 未设置或保留内置开发默认值时拒绝运行。请先设置您自己的值（参见部署 → 环境变量，以及在 Kubernetes 上，参见 Kubernetes 指南的 §2.6）。请在所有服务器副本间保持该值一致，且不要随意轮换；轮换后会使每个组织的 ClickHouse 用户变为孤立状态，直至下次启动重新配置。

运行 CLI

agenteye-orgctl 与服务器打包在同一镜像中（与 agenteye-server 并列）。您不需要为其部署独立的 Pod、Job 或 Deployment；只需在已运行的服务器 Pod 内执行它，这样它就能读取服务器使用的相同 DATABASE_URL、CLICKHOUSE_URL 和 ORG_CH_SECRET。 Kubernetes：

kubectl -n agenteye exec deploy/server -- agenteye-orgctl <args>

Docker Compose：

docker compose exec server agenteye-orgctl <args>

以下示例为简洁起见仅显示裸命令 agenteye-orgctl <args>；请根据您的部署方式在每条命令前加上上述两行中的对应前缀。

命令参考

组织

命令	说明
`org create --slug <slug> --name <name>`	创建新组织。在 `ORG_CH_SECRET` 未设置或保留内置开发默认值时拒绝运行（请先设置您自己的值，参见前提条件）。配置该组织的只读 ClickHouse 用户和行级策略。
`org list`	列出所有组织（slug、名称和生命周期状态）。
`org rename --slug <slug> --name <new name>`	更改组织的显示名称。slug（用于 URL 和密钥）保持不变。
`org delete --slug <slug>`	软删除组织并删除其 ClickHouse 用户。数据保留。此操作撤销访问权限并释放按组织划分的 ClickHouse 凭据，但不会删除事件数据。可由运维人员恢复；是清除前安全的第一步。
`org purge --slug <slug>`	不可逆的数据清除。组织必须已处于 `delete` 状态。不允许对内置 `default` 组织执行此操作。仅在您确定应销毁租户数据时使用。

成员

命令	说明
`member add --org <slug> --email <email> [--set <permission-set>] [--add perm1,perm2] [--remove perm3] [--protected]`	将成员添加到组织。可选择从内置权限集开始，然后添加/移除单个权限。`--protected` 将该成员标记为受保护，使其无法通过仪表板被移除或降权（见下文）。新成员在首次登录仪表板时会收到一次性密码。
`member list --org <slug>`	列出组织的成员。输出列为 `EMAIL`、`SET`（成员起始的内置权限集，或 `-`）、`PROT`（成员是否受保护）和 `PERMISSIONS`（其有效权限）。带尾随 `*` 的邮箱表示实例管理员，他们可访问每个组织。
`member update --org <slug> --email <email> [--set ...] [--add ...] [--remove ...] [--protected \| --unprotect]`	更改成员的权限和/或受保护标志。`--set` 从内置权限集替换；`--add` / `--remove` 调整单个权限；`--protected` / `--unprotect` 切换保护状态。仅传递 `--protected`/`--unprotect`（不带授权标志）时，仅更改保护状态，现有权限保持不变。
`member remove --org <slug> --email <email>`	从组织中移除成员。若成员受保护则拒绝操作；请先执行 `--unprotect`。（一个用户可以是多个组织的成员；此操作仅影响指定组织。）

一个用户可以在多个组织中拥有不同的权限，例如在一个组织中是管理员，在另一个组织中是只读成员。每个成员关系按组织独立管理：在一个组织中授予或更改某人的权限不会影响其在其他组织中的成员关系。

受保护成员（不可移除的组织管理员）

保护机制确保组织永远不会意外地将自己锁定在自我管理之外。默认情况下，组织自己的管理员可以通过仪表板的自助用户页面互相添加和移除，因此他们可能会移除最后一位管理员，导致组织无人能够管理。

用户页面：每位仪表板用户显示为一张卡片，包含其邮箱、已授予权限以及编辑/禁用控件

为防止这种情况，将某位成员标记为受保护：

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl member add --org acme --email owner@acme.example --set admin --protected

受保护成员无法通过仪表板被移除或降权；这些操作会返回错误。只有运维人员才能对其进行更改，且只能通过此 CLI 操作：先运行 member update --org acme --email owner@acme.example --unprotect，然后再移除或降权。这确保每个组织至少保留一位其成员无法锁定的管理员，同时将租户控制权仅限于运维人员。保护是按组织划分的；保护某人在一个组织中的身份不会影响其在其他组织中的成员关系。

内置权限集

--set 接受三个内置权限集之一，按组织应用：

权限集	适用对象
`admin`	组织内的完整访问权限，包括管理组织的 API 密钥和用户。
`standard`	日常使用：读取和运行查询、构建仪表板、确认事件。
`read-only`	对组织数据和仪表板的只读访问权限。

使用 --set 从权限集开始，然后使用 API 密钥中列出的单个权限令牌通过 --add / --remove 进行微调。权限令牌本身与 API 密钥使用的完全相同。

操作示例

配置新的 acme 租户，添加其首位管理员，让其创建密钥，然后注销组织。 1. 创建组织（ORG_CH_SECRET 必须已设置为强固且稳定的值，不能未设置或使用内置开发默认值）：

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl org create --slug acme --name "Acme Corp"

2. 将首位成员添加为组织管理员：

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl member add --org acme --email alice@acme.example --set admin

Alice 首次登录仪表板时会收到一次性密码。此后她将完全在 UI 中、在其组织的 URL 前缀下工作（例如 /acme/sessions）。 3. 创建按组织划分的 API 密钥（在仪表板中）： 运维人员不需要通过 CLI 创建按组织划分的数据密钥。Alice（或任何拥有 keys:create 权限的组织成员）可以从仪表板的密钥页面为 acme 组织创建采集器/仪表板密钥。她创建的每个密钥都会自动标记其所属组织，且只能读写 acme 的数据。参见 API 密钥。 4. 后续调整成员权限：

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl member update --org acme --email alice@acme.example --add alerts:write

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl member list --org acme

5. 软删除组织（撤销访问权限并删除其 ClickHouse 用户；数据保留）：

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl org delete --slug acme

6. 清除组织（不可逆；仅在软删除后执行；不可对 default 组织执行）：

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl org purge --slug acme

使用 Docker Compose 时，将每条命令的 kubectl -n agenteye exec deploy/server -- 前缀替换为 docker compose exec server。

职责划分

组织成员日常所需的一切操作均可在仪表板和 API 中自助完成，并自动限定在其当前组织范围内：

按组织划分的 API 密钥由组织成员在仪表板中创建和管理（或通过携带 keys:create 权限的密钥调用密钥 API）。CLI 不创建数据密钥。参见 API 密钥。
组织切换内置于仪表板中；成员可通过组织切换器在所属组织之间切换，组织级页面位于 /<org-slug>/… 下。
仪表板、已保存查询、告警及所有数据使用完全在 UI 和 API 中进行，限定在成员当前所属组织范围内。

运维人员通过 agenteye-orgctl 仅负责组织和成员的生命周期管理：创建/重命名/删除/清除组织，以及添加/列出/更新/移除成员。

另请参阅

部署：ORG_CH_SECRET 及其他服务器环境变量。
Kubernetes 部署：§2.6 在您的首个多租户组织创建之前创建 agenteye-org-ch-secret Secret。
API 密钥：按组织划分的密钥模型，以及 --add / --remove 使用的权限令牌。
故障排除：多租户配置和 ClickHouse 隔离问题。

​前提条件

​运行 CLI

​命令参考

​组织

​成员

​受保护成员（不可移除的组织管理员）

​内置权限集

​操作示例

​职责划分

​另请参阅