# NebulaKB 故障处理文档

本文用于一线交付和运维排查企业版常见问题。

## 快速定位顺序

1. 确认用户、工作空间和资源 ID。
2. 查询审计日志，确认失败事件的 `event_name`、`actor`、`resource`、`result`。
3. 查询工作空间运营指标，判断是否为整体性故障。
4. 检查 Web、worker、scheduler、PostgreSQL、Redis 和模型供应商日志。
5. 修复后复测并再次确认审计事件写入。

## 登录失败

现象：

- 返回用户名或密码错误。
- 提示账号被锁定。
- SSO 登录后没有权限。

排查：

- 查询 `event_name` 包含 `log_in` 的审计日志。
- 确认用户 `is_active=true`。
- 确认登录失败锁定配置是否触发。
- SSO 用户确认 `source`、邮箱和用户名映射唯一。

处理：

- 重置密码或解除锁定。
- 修正 SSO 属性映射。
- 将用户加入正确工作空间并分配角色。

## 无权限访问

现象：

- 管理端返回 403 或 “No permission to access”。
- 用户能看到工作空间，但打不开具体资源。

排查：

- 确认用户角色是否包含 `ADMIN`、`WORKSPACE_MANAGE:/WORKSPACE/{workspace_id}` 或 `USER:/WORKSPACE/{workspace_id}`。
- 对资源级访问，确认 `workspace_user_resource_permission` 中存在目标资源授权。
- 确认请求路径中的 `workspace_id` 与资源所属工作空间一致。

处理：

- 工作空间管理员补充资源授权。
- 只读用户仅授予 `VIEW`。
- 需要编辑、删除、导入、导出时授予 `MANAGE` 或对应操作权限。

## 审计日志缺失

现象：

- 操作成功但审计查询接口查不到记录。

排查：

- 确认操作视图已接入 `@log`。
- 检查 `log` 表是否已执行审计契约迁移。
- 查询是否使用了正确 `workspace_id`。
- 检查数据库写入错误。

处理：

- 对缺失的管理、数据访问或配置变更入口补充 `@log`。
- 执行 `python main.py upgrade_db`。
- 补充回归用例，覆盖关键操作的审计写入。

## 工作空间数据串读

现象：

- A 工作空间用户看到 B 工作空间资源。
- 运营指标或审计日志包含其他工作空间数据。

排查：

- 检查业务查询是否过滤 `workspace_id`。
- 检查资源表中的 `workspace_id` 是否正确。
- 检查 API Key 绑定的应用是否属于当前工作空间。

处理：

- 立即暂停相关账号或 API Key。
- 修复查询条件并补充隔离测试。
- 导出审计日志评估影响范围。

## API Key 调用失败

现象：

- 返回 Secret key invalid 或 expired。
- 跨域调用失败。
- 调用量异常增长。

排查：

- 确认 Key 是否启用。
- 确认 Key 是否过期。
- 确认跨域白名单是否包含实际 Origin。
- 查询运营指标中的 `call_count` 和审计日志中的失败事件。

处理：

- 启用或重新生成 Key。
- 调整过期时间和跨域白名单。
- 如果怀疑泄漏，停用旧 Key 并轮换。

## 运营指标异常

现象：

- 调用量、成本、活跃度或失败率不符合预期。

排查：

- 确认查询时间范围和时区。
- 调用量与 `application_chat_record` 数量比对。
- 成本与 `ChatRecord.const` 汇总比对。
- 失败率与 `log.status >= 400` 数量比对。

处理：

- 修正统计时间范围。
- 排查模型供应商错误、超时、限流和认证失败。
- 失败率持续超过阈值时，暂停高风险工作流或切换备用模型。

## 数据库迁移失败

现象：

- 启动时报迁移错误。
- `log` 表缺少审计契约字段。

排查：

- 查看 `python main.py upgrade_db` 输出。
- 确认数据库连接和权限。
- 确认已执行到 `system_manage.0006_audit_event_contract`。

处理：

- 备份数据库。
- 修复连接或权限后重新执行迁移。
- 如迁移中断，先确认表结构再决定是否手工补字段。

## Redis 异常

现象：

- 登录频繁失效。
- 权限缓存不刷新。
- 验证码或访问次数异常。

排查：

- 检查 Redis 地址、密码和网络。
- 检查 Redis 内存和淘汰策略。
- 重启后确认 token、权限、验证码缓存是否恢复。

处理：

- 恢复 Redis 服务。
- 清理异常缓存。
- 重新登录并复测权限。
