# NebulaKB 管理员手册

本文面向平台管理员和工作空间管理员，说明企业交付版的日常管理边界。

## 管理职责

平台管理员负责全局安全与交付：

- 创建和停用工作空间。
- 管理平台用户、全局角色、系统配置和登录策略。
- 查看全量审计日志与跨工作空间运营指标。
- 配置模型供应商、共享资源和全局安全策略。

工作空间管理员负责本工作空间：

- 邀请、移除和停用成员。
- 为成员分配成员、只读或自定义资源权限。
- 管理应用、知识库、模型、工具、API Key 和访问控制。
- 查看本工作空间审计日志和运营指标。

## 工作空间管理

1. 创建工作空间后确认 `workspace_id` 唯一且稳定。
2. 将应用、知识库、模型、工具和 API Key 绑定到该 `workspace_id`。
3. 禁止通过数据库手工复制资源到其他工作空间；如需迁移，应走导入导出或后台迁移脚本，并保留审计记录。
4. 删除工作空间前先导出审计日志、对话记录和资源清单。

## 用户与角色

角色分配建议：

| 场景 | 建议角色 |
| --- | --- |
| 运维和交付负责人 | 平台管理员 |
| 客户侧业务负责人 | 工作空间管理员 |
| 业务编辑、知识维护人员 | 成员 |
| 审计、法务、客户验收人员 | 只读 |
| 系统集成、自动化调用 | 服务账号 |

只读用户只授予 `VIEW` 资源权限。服务账号使用应用 API Key，不创建可登录用户。

## 审计日志

审计日志用于回答“谁在什么时间对哪个资源做了什么，结果如何”。

查询入口：

```http
GET /admin/api/workspace/{workspace_id}/audit_log/{current_page}/{page_size}
```

常用过滤：

- `event_name`: 按事件名称模糊查询。
- `actor_id`: 按操作者查询。
- `result`: `success` 或 `failure`。
- `start_time` / `end_time`: 支持 `YYYY-MM-DD` 或 ISO 时间。

每条日志包含 `event_name`、`actor`、`resource`、`timestamp`、`result` 五个契约字段，同时保留旧字段 `menu`、`operate`、`user`、`details` 以兼容现有页面。

## API Key 管理

1. 每个应用按集成方创建独立 API Key。
2. 生产环境必须设置过期时间，不建议使用永久 Key。
3. 开启跨域时只填写明确域名，禁止使用泛域名。
4. 服务账号必须登记负责人、用途、到期时间和轮换周期。
5. Key 泄漏时立即停用并生成新 Key，随后查询审计日志确认异常调用范围。

## 运营指标

查询入口：

```http
GET /admin/api/workspace/{workspace_id}/operation_metrics?start_time=2026-04-01&end_time=2026-04-21
```

管理员每周至少检查：

- `call_count`: 调用量是否异常增长。
- `total_cost`: 成本是否超过预算。
- `active_user_count`: 活跃度是否符合客户使用预期。
- `failure_rate`: 失败率是否超过交付阈值。

建议验收阈值：生产首月失败率低于 3%，核心客户工作空间低于 1%。

## 变更流程

所有高风险变更按以下顺序执行：

1. 记录变更目标、影响工作空间和回滚方案。
2. 在低峰期执行。
3. 变更后查询审计日志，确认事件成功写入。
4. 查询运营指标，确认失败率和调用量没有异常。
5. 将变更记录同步给客户或内部交付负责人。
