# 权限、租户与 API

多人维护时，先确定对方需要管理哪些功能、能访问哪一批资源，再分配权限。角色、租户和 API 密钥分别解决功能权限、资源范围和自动化接入，不能相互替代。

| 对象 | 作用 |
| --- | --- |
| 普通订阅用户 | 在自己的套餐／线路和额度内使用业务 |
| 子管理员角色 | 按功能域授予查看或管理权限 |
| 租户 | 隔离用户、节点、网络与路由资源，并设置配额 |
| API Key | 在属主权限和 scope 范围内调用接口，不自动成为超级管理员 |

部分平台能力仍仅向超级管理员开放，角色中勾选某个管理域不会自动获得平台密钥、证书、租户或其他专有能力。授权套餐也可能限制可用功能。

## 创建与分配角色

使用超级管理员进入 **系统设置 → 角色管理**，选择 **从模板创建**或 **创建角色**。

![角色的功能域与查看／管理权限矩阵](https://img.coderluny.com:444/uploads/zfc-tutorial-20261018-role-permissions-c046dd382c17.png)

1. 填写名称与用途，例如只查看节点与告警的值班角色。
2. 对所需功能域勾选 **查看**；需要变更时再给 **管理**。
3. 保存后到 **订阅管理**找到对应账号，通过操作菜单 **分配角色**。
4. 使用该账号重新核对菜单、列表与实际操作权限。

“管理”包含同域“查看”。角色模板是创建起点，仍要检查完整权限；不要以菜单隐藏代替服务端权限验证。

变更或撤销角色后，检查现有登录会话和该账号创建的自动化密钥。多人使用独立账号，便于审计定位实际操作者。

## 划分租户与配额

在 **系统设置 → 租户管理 → 创建租户**填写租户名称、管理员账号与配额。管理员初始密码由你在自己的面板中设置并妥善交付，公开教程不展示真实凭据。

![租户资源、网络域和路由域配额配置](https://img.coderluny.com:444/uploads/zfc-tutorial-20261018-tenant-quota-52e0328d55d5.png)

配额覆盖服务器、用户、端口、WireGuard 网络、NAT、转发链、解锁服务和路由／防火墙对象等。按字段提示区分空值与数字 `0`，不要批量把所有空项填成零。

**允许分发**关闭后，租户管理员不能新建订阅账户、套餐、兑换码等分发资源，但仍可管理自己已有订阅和资源。

兑换码等商城运营功能还要求商用 tier，个人 tier 不支持；开启“允许分发”不会解除 tier 限制，详见[商城与运营](/docs/operations/)。

平台超级管理员查看列表时留意“平台／全部／指定租户”过滤。能在“全部”看到资源，不代表新对象可引用其他租户的节点；跨租户引用会被服务端拒绝。创建入口置灰时先切回允许创建的范围。

暂停租户会影响其访问和管理，应先核对业务与界面提示。**应急取用 Token**涉及租户凭据，只在明确需要时按页面要求填写原因，并在审计中追踪；它不是日常查看用户数据的入口。

## 创建 API 密钥

进入 **系统设置 → API Key 管理 → 创建 API Key**，填写名称、描述、过期时间和功能权限。

![API Key 的期限与功能权限](https://img.coderluny.com:444/uploads/zfc-tutorial-20261018-api-key-scopes-88558d36eefe.png)

| Scope | 常见用途 |
| --- | --- |
| `ports_traffic` | 端口／订阅自助、流量与连接统计 |
| `forward_endpoint` | 端点管理与相关延迟数据 |
| `subscription_link` | 客户端订阅链接和模板维护 |
| `shared_server` / `shared_endpoint` | 对应跨面板共享管理 |
| `admin_system` | 属主有权执行的管理与系统操作 |
| `agent_diag` | 只读进程内诊断导出；含日志、内部地址等敏感信息 |
| `agent_exec` | 远程执行能力，仍受服务端开关及只读白名单约束 |
| `full` | 普通接口的广泛 scope；**不会自动授予上述两个 Agent 专用权限** |

密钥同时受属主身份、角色、租户范围、授权和接口专有条件限制。不要因为持有 `full`就推断所有接口都可调用。

创建成功后完整密钥仅显示一次，及时保存到受控凭据存储。列表里的掩码不能还原原密钥。请求使用 `X-API-Key`头，不把密钥放进 URL、截图、仓库或共享日志。

从同页的 **API 文档**查看当前面板生成的接口说明，也可在管理界面访问 `/dashboard/admin/api-docs`。以当前版本请求模型和权限要求为准，先选必要的读取接口验证，再进行已授权的写入。

泄露或不用时停用／删除密钥，替换调用端并验证旧密钥失效；仅修改密钥名称不会轮换秘密值。AI 诊断的独立开关和适用范围见[用 AI 助手定位问题](/docs/agent-diagnose/)。

## 审计与会话核对

**审计日志**可按时间、操作、资源和结果追踪管理变更。记录请求尝试不等于变更成功；结合成功／失败结果及目标资源状态判断。

账号设置中的会话管理用于检查已登录设备和撤销不需要的会话。API Key、用户登录凭据和客户端订阅 Token 分别维护，撤销其中一种不应被当作其他凭据也全部作废。

导出诊断或分享审计片段前，遮住 Token、邮箱、来源地址、机器名和业务目标，仅保留定位问题所需的字段。