# 管理后台使用说明：访问名单功能

URL: https://docs.ones.cn/deploy/configure/ones-admin/ones-admin-access-users-usage

本文面向实施维护人员，说明如何在 ONES 管理后台维护访问名单。

管理后台打开方式请参考： [打开管理后台](https://docs.ones.cn/deploy/configure/ones-admin/open-ones-admin/) 。

## 1. 功能说明

访问名单用于控制哪些 ONES 用户可以进入管理后台。

只有在访问名单中，并且状态为 `启用` 的账号，才能登录管理后台。未加入名单、被停用或被删除的账号，登录时会被拒绝。

注意：

- 访问名单只控制管理后台入口，不影响用户正常使用 ONES。
- 操作访问名单前，请确认至少保留一个可用管理员账号。
- 禁用或删除管理员前，请先确认还有其他管理员可以登录管理后台。

## 2. 使用前准备

使用访问名单前，请先确认：

- 管理后台已经打开，IDS 登录可以正常跳转。
- 当前操作人已经在访问名单中，并且状态为 `启用` 。
- 环境中至少保留一个 `启用` 状态的管理员。
初装环境一般会由初始化流程写入一个管理员。如果没有任何可用管理员，普通 IDS 登录会被拒绝，需要先按 [紧急登录说明](https://docs.ones.cn/deploy/configure/ones-admin/ones-admin-emergency-login/) 处理。

紧急登录账号绑定的用户，也必须已经在访问名单中，并且状态为 `启用` 。

## 3. 登录和入口

浏览器访问：

```text
http://<管理后台访问地址>/ones-admin/
```

登录成功后，在左侧菜单点击 `访问名单` 。

如果登录时报"当前账号未被加入管理后台访问名单"，说明当前账号还没有权限进入管理后台，需要由已有管理员先加入名单。

## 4. 查看访问名单

进入 `访问名单` 页面后，列表会展示当前可维护的管理员账号。

重点查看以下信息：

- `管理员` ：管理员名称。
- `邮箱` ：管理员邮箱。
- `来源` ：这条记录的来源。
- `状态` ：当前是否允许登录管理后台。
- `更新时间` ：最近一次维护时间。
- `操作` ：启用、停用或删除。
来源说明：

- `初装写入` ：环境初始化时写入的管理员。
- `升级迁移` ：升级过程中迁移生成的记录。
- `手工维护` ：通过管理后台手动添加的管理员。

## 5. 操作原则

现场维护时建议按下面原则操作：

- 新增管理员时，先添加新管理员，并确认新管理员可以登录，再停用或删除旧管理员。
- 临时收回权限时，优先使用 `停用` 。
- 确认账号不再需要维护管理后台时，再使用 `删除` 。
- 搜索候选用户时，只会搜索当前 ONES 组织内的用户。
- 每次添加、停用、启用或删除后，点击 `刷新列表` 确认状态。
- 访问名单不改变 ONES 业务权限，也不影响用户正常登录 ONES。

## 6. 按状态筛选

页面支持按状态筛选：

- `全部` ：查看所有访问名单记录。
- `启用` ：只查看当前可以登录管理后台的账号。
- `停用` ：只查看已停用的账号。
排查登录问题时，建议先按 `停用` 筛选，确认目标账号是否曾经被加入但后来停用了。

## 7. 添加管理员

在 `访问名单` 页面点击 `添加管理员` 。

操作步骤：

1. 在弹窗中输入姓名或邮箱关键字。
2. 系统会自动搜索当前组织内的候选用户。
3. 找到目标用户后，点击 `加入名单` 。
4. 页面提示添加成功后，该用户即可使用 IDS 登录管理后台。
注意：

- 搜索不到用户时，请确认关键字是否正确，并确认该用户已经存在于当前 ONES 组织中。
- 如果候选用户显示 `已在名单中` ，说明该用户已经是启用状态，不需要重复添加。
- 如果候选用户显示 `名单中但已停用` ，请关闭弹窗，在列表中筛选 `停用` 后点击 `启用` 。

## 8. 停用管理员

如需临时禁止某个账号进入管理后台，可以在列表中点击该账号右侧的 `停用` 。

停用后：

- 该账号不能再登录管理后台。
- 记录仍保留在访问名单中。
- 后续需要恢复时，可以点击 `启用` 。
注意：

- 不要停用最后一个可用管理员。
- 如果系统提示"至少保留一个启用中的普通管理员"，说明当前操作会导致没有可用管理员，应先添加或启用其他管理员。

## 9. 启用管理员

如果账号已停用，需要恢复登录权限：

1. 在状态筛选中选择 `停用` 。
2. 找到目标账号。
3. 点击右侧 `启用` 。
4. 提示启用成功后，该账号可以重新登录管理后台。

## 10. 删除管理员

如需彻底移除某个账号的管理后台访问权限，可以点击该账号右侧的 `删除` 。

删除后：

- 该账号不能再登录管理后台。
- 该记录不再出现在正常访问名单列表中。
- 如果后续需要恢复，需要重新通过 `添加管理员` 加入名单。
建议：

- 临时收回权限时优先使用 `停用` 。
- 确认不再需要该账号维护管理后台时，再执行 `删除` 。

## 11. 容器内检查

如果页面无法进入，或者怀疑访问名单数据异常，可以在操作容器内检查数据库记录。

生产环境在部署机执行：

```sh
./ones-ai-k8s.sh
```

进入容器后切到部署目录：

```sh
cd /data/ones/ones-ai-k8s
```

查询当前访问名单：

```sh
MYSQL_PWD="$(sed -n 's/^mysqlPassword:[[:space:]]*//p' config/private.yaml | head -1)"

kubectl -n ones exec mysql-cluster-mysql-0 -c mysql -- \
  env MYSQL_PWD="$MYSQL_PWD" \
  mysql -uones -N ones_admin -e \
  "SELECT org_uuid, region_uuid, org_user_uuid, auth_user_uuid, display_name_snapshot, email_snapshot, status FROM admin_access_grant WHERE deleted_at_ms=0;"
```

重点确认：

- `status` 为 `active` ：表示该用户可以登录管理后台。
- `status` 为 `disabled` ：表示该用户已停用，不能登录管理后台。
- `deleted_at_ms=0` ：表示记录未删除。
- `org_user_uuid` 和 `auth_user_uuid` 应与当前登录用户匹配。
不建议直接修改数据库。能进入管理后台时，请优先在页面上维护访问名单。

## 12. 常见问题

### 登录后提示不在访问名单中

请让已有管理员登录管理后台，在 `访问名单` 中添加当前账号，并确认状态为 `启用` 。

### 登录后提示账号已被移出访问名单

说明当前账号曾经加入过访问名单，但现在不是可用状态。请让已有管理员在 `访问名单` 中按 `停用` 筛选，找到该账号后点击 `启用` 。

如果列表中找不到该账号，请重新通过 `添加管理员` 加入名单。

### 没有任何可用管理员怎么办

请先按 [紧急登录说明](https://docs.ones.cn/deploy/configure/ones-admin/ones-admin-emergency-login/) 进入管理后台，再添加或启用至少一个普通管理员。

处理完成后，建议让新的普通管理员重新登录验证。

### 添加管理员时搜不到用户

常见原因：

- 姓名或邮箱关键字不准确。
- 用户不在当前组织中。
- 用户数据暂时未同步完成。
可以换邮箱关键字重试，或先在 ONES 中确认用户是否存在。

### 用户已加入名单但仍不能登录

请检查：

- 账号状态是否为 `启用` 。
- 用户是否使用正确的 IDS 账号登录。
- 浏览器是否停留在旧的登录错误页，可以重新打开管理后台入口再登录。
如果仍然不能登录，可以在容器内查询 `admin_access_grant` ，确认当前登录用户对应的 `org_user_uuid` 、 `auth_user_uuid` 和访问名单记录一致。

### 停用或删除失败

常见原因：

- 当前账号没有维护访问名单的权限。
- 正在操作最后一个启用中的管理员。
- 后端服务暂时异常。
如果提示"至少保留一个启用中的普通管理员"，请先添加或启用另一个管理员后再操作。

### 访问名单操作是否会影响 ONES 正常使用

不会。访问名单只影响管理后台登录，不影响用户登录和使用 ONES 业务系统。