# NebulaKB 安全说明

本文定义 NebulaKB 企业交付的安全边界、控制点和验收要求。

## 安全目标

| 目标 | 要求 |
| --- | --- |
| 权限可控 | 所有管理入口必须经过 Token 鉴权和 RBAC 校验 |
| 行为可追溯 | 登录、管理操作、数据访问、配置变更必须写入审计事件 |
| 数据可隔离 | 工作空间内资源必须通过 `workspace_id` 隔离 |
| 客户可交付 | 管理、部署、安全和故障处理文档齐全 |

## 身份认证

NebulaKB 当前支持本地用户登录和应用 API Key 调用。

安全要求：

- 生产环境启用强密码策略和登录失败锁定。
- 平台管理员账号必须最少化。
- SSO 用户必须标记非 `LOCAL` 来源，并复用统一审计契约。
- 服务账号使用 API Key，不允许共享个人账号。

## RBAC

RBAC 采用三层控制：

1. 平台角色：平台管理员拥有全局管理能力。
2. 工作空间角色：工作空间管理员和成员限定在 `workspace_id` 范围内。
3. 资源权限：对应用、知识库、模型、工具进一步区分 `VIEW` 和 `MANAGE`。

只读角色不得授予 `MANAGE` 权限。服务账号只通过绑定应用的 API Key 获得最小调用能力。

## 租户隔离

隔离规则：

- 路径中的 `workspace_id` 是租户边界。
- 数据表中的资源 `workspace_id` 必须与请求 `workspace_id` 一致。
- 审计日志按工作空间写入和查询。
- API Key 通过应用继承工作空间归属。
- 跨工作空间共享必须显式配置，不得通过跳过权限校验实现。

开发验收时至少执行：

1. 用户 A 属于工作空间 A。
2. 用户 B 属于工作空间 B。
3. A 尝试读取 B 的应用、知识库、API Key、审计日志和运营指标，均应被拒绝。

## 审计日志

统一事件契约：

- `event_name`: 事件名称，使用小写下划线格式。
- `actor`: 操作者，包含类型、ID、用户名、邮箱、角色。
- `resource`: 资源，包含 `workspace_id`、请求路径、方法、对象。
- `timestamp`: 事件时间。
- `result`: 结果，包含状态码和成功标记。

禁止在审计日志中明文保存密码、令牌和 API Key。登录日志中的密码必须脱敏或加密摘要化。

## API Key

API Key 管理要求：

- 每个集成方独立 Key。
- 生产环境设置过期时间。
- 定期轮换，建议 90 天。
- 泄漏时先停用旧 Key，再查询审计日志确认影响范围。
- API Key 只允许调用绑定应用，不授予管理端权限。

## 配额限流

一期配额控制要求：

- 对话访问次数必须可按应用或访问令牌限制。
- API Key 调用应纳入工作空间调用量统计。
- 超限错误必须返回明确错误码，并写入审计事件。
- 高价值客户建议在反向代理层叠加 IP 或 Key 级限流。

## 可观测性

工作空间指标必须覆盖：

- 调用量：`call_count`
- 成本：`total_cost`
- 活跃度：`active_user_count`
- 失败率：`failure_rate`

失败率连续升高时，应按故障处理文档检查模型供应商、数据库、Redis、权限配置和外部网络。

## 密钥与数据保护

- 数据库、Redis、模型供应商 Key 必须通过环境变量或密钥管理系统注入。
- 禁止提交真实密钥到仓库。
- 上传文件和知识库内容应按客户数据分类设置备份、保留和删除策略。
- 导出文件应按客户安全要求加密传输和留存。
