> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# AI 安全

> 了解 Gateway 执行、策略评估、敏感数据处理、Agent 工具控制和部署加固

Alephant 通过鉴权、策略评估、Provider 路由、Agent 工具执行和可观测性保护 AI 流量。这些控制并不全部运行在同一个组件中：Dashboard 保存配置，Gateway 执行数据平面决策，policy-service 评估支持的策略，日志则提供结果证据。

本页描述当前 Gateway 和 Dashboard 中能够确认的安全行为。Dashboard 中显示某项控制，并不自动证明每个已部署 Gateway 都会执行它。

## 安全模型

一条通过鉴权的模型请求会经过以下安全链路：

```text
客户端
  → Gateway 鉴权与 Virtual Key 上下文
  → Gateway 模型和 Provider 检查
  → 启用时由 policy-service 评估
  → 选定的上游 Provider
  → 请求、响应、用量和策略日志
```

主要信任边界如下：

| 边界                      | 职责                                       |
| ----------------------- | ---------------------------------------- |
| Dashboard 与控制平面         | 保存工作区、策略、密钥和可用状态配置                       |
| AI Gateway              | 鉴权请求、附加可信工作区上下文、执行支持的运行态检查并路由已允许流量       |
| policy-service          | 使用 Gateway 提供的上下文评估支持的内容、成本、访问和 Agent 策略 |
| 上游 Provider             | 使用配置的 Provider Key 处理模型请求                |
| Request Logs 与 Agent 日志 | 记录请求结果和当前部署暴露的运行上下文                      |

应把配置、执行和可观测性作为三项独立检查。保存策略只能确认控制平面状态；请求结果及其日志才能确认运行态行为。

## 鉴权与凭证

启用 Alephant 鉴权后，Gateway 会：

* 要求普通 Gateway 流量携带 Virtual Key。
* 通过哈希解析密钥，并拒绝未知或已过期密钥。
* 在可用时，把请求关联到工作区、Virtual Key、Master Key、部门、成员或 Agent 上下文。
* 仅在已选定的上游请求中使用解析出的 Provider Key。

以 Master Key 保存的 Provider 凭证使用 AES-256-GCM 加密。Secret 值通过 Gateway 的 secret wrapper 序列化或记录时会被掩码。

> Private deployment 不应在不可信网络上使用关闭鉴权的 Gateway 配置。关闭 Alephant 鉴权后，能够访问 Gateway 的调用方可以使用已配置的上游 Provider Key。

鉴权只保护 Gateway 入口，不能替代网络控制、TLS、secret 管理以及 Dashboard 和日志的角色权限。

## 请求策略评估

启用策略评估后，携带 Virtual Key 的请求可以在到达上游模型前接受检查。Gateway 会向 policy-service 提供可信请求上下文，例如：

* 工作区、Virtual Key 和部门标识
* 请求标识、模型和已选 Provider
* 客户端 IP 与请求头
* 可用时的预估输入 Token 和成本

请求头可能包含敏感信息，因此必须把 policy-service 视为可信内部依赖，并进行相应的网络隔离。

### 正文检查与策略动作

只有为工作区启用正文检查时，请求正文才会附加到策略评估中。当前 Gateway 最多附加 1 MiB 正文。

policy-service 可以返回以下请求决策：

| 决策   | Gateway 行为                    |
| ---- | ----------------------------- |
| 允许   | 转发原始请求                        |
| 拒绝   | 使用 `content_filter` 客户端错误拒绝请求 |
| 重写   | 转发策略生成的新请求正文                  |
| 切换模型 | 把请求模型替换为策略选定的模型               |

当正文检查要求使用重写正文时，如果允许结果没有返回替换正文，Gateway 会拒绝请求，而不是转发语义不明确的请求。

策略选定的模型会成为该请求后续链路的权威结果。应确保 policy-service 的替换模型集合与工作区模型和 Provider 规则一致。

### 策略服务可用性

policy-service 不可用时，Gateway 支持两种行为：

| 模式      | 行为                |
| ------- | ----------------- |
| `deny`  | Fail closed，不转发请求 |
| `allow` | Fail open，转发原始请求  |

Managed Cloud 和 private deployment 可以使用不同设置。应根据工作负载显式选择失败模式：敏感或受监管流量通常需要 `deny`，风险较低且更重视可用性的工作负载可以选择 `allow`。

## 模型与 Provider 访问

Gateway 会在不同作用域执行模型和 Provider 规则：

* Virtual Key 请求命中 `blocked_models` 时会被拒绝。
* 模型命中 `allowed_models` 时会被允许。
* 在当前 Gateway 合同中，模型未命中以上两个列表时也会被允许。
* Managed Cloud 会在向上游 Provider 分发前执行工作区 Provider allowlist。

由于未命中的模型当前仍然允许，因此不能只依赖 Virtual Key 的 `allowed_models` 字段作为严格白名单。如果 Dashboard 显示 **Model Allowlist**，在把它作为安全边界前，必须先验证目标部署中的实际行为。

Fallback、成本路由和策略驱动的模型切换必须继续使用工作区有效的 Provider 和模型。应结合[Provider 路由](/ai-gateway/provider-routing)一起审阅访问策略。

## 敏感数据与请求日志

Dashboard 可以保存电子邮箱、电话号码、SSN、信用卡号、IP 地址和自定义正则表达式的 PII 策略配置。支持的动作包括 block、redact 和 alert。

这些字段描述的是期望策略状态。检测覆盖范围、输入或输出扫描、语言支持、超时行为和通知投递取决于已部署的 policy-service。在生产环境依赖 PII 策略前，应使用代表性请求进行测试。

### 请求与响应正文

启用可观测性后，Request Logs 可能包含完整请求和响应正文：

* 两侧正文都小于 1 MiB 时，当前 Cloud 日志链路会内联保存两侧正文。
* 任意一侧达到 1 MiB 时，当前 Cloud 日志链路会把两侧正文存入对象存储，并记录临时读取 URL。
* 对象存储上传失败时，当前 Gateway 可以回退为内联日志存储。
* 能够打开 Request Logs 的用户可以查看并复制可用的请求和响应 JSON。

对转发给模型的正文执行 PII 脱敏，并不自动保证所有运行日志都已脱敏。应避免发送不必要的 secret、限制日志访问，并设置与数据敏感程度相匹配的保留期。

## Agent 与工具安全

Agent 工具执行与模型请求属于不同的安全边界。启用 Agent 工具后，Gateway 可以：

* 按工作区、Virtual Key 和已鉴权 Agent 身份限制可见和可调用工具。
* 存在已鉴权 Agent 身份时，忽略仅由请求正文上报的不可信 Agent 标识。
* 在分发前根据配置的 JSON Schema 校验工具参数。
* 限制每个工作区的并发工具调用，并阻止超过单次调用成本上限的请求。
* 对 OpenAPI、MCP Streamable HTTP 和 MCP SSE 目标执行 policy preflight。
* 无法记录必要审计事件时，阻止 high 或 critical 风险工具调用。
* 限制请求大小、响应大小和执行时间。

默认出站策略要求 HTTPS，并阻止显式 loopback、link-local、metadata service 和 private network IP 目标。域名当前不会在 DNS 解析后重新校验，因此 DNS rebinding 和解析到私网地址的风险仍需要额外网络层保护。

除非部署确实需要，否则应保持 Agent 工具关闭。启用后，应把 Gateway 规则与 DNS 控制、出站代理或防火墙、最小权限服务凭证和上游授权结合使用。

## 失败行为

应用应处理机器可读的状态和错误字段，而不是依赖固定的人类可读错误消息。

| 条件                   | 当前行为                            |
| -------------------- | ------------------------------- |
| Virtual Key 缺失、无效或过期 | 请求在 Provider 分发前被拒绝             |
| 内容策略拒绝               | 使用错误码 `content_filter` 拒绝请求     |
| policy-service 不可用   | 按配置的 `deny` 或 `allow` 模式处理      |
| 缺少必需的重写正文            | 作为无效请求拒绝                        |
| Agent 工具并发耗尽         | 在分发前阻止工具调用并返回 HTTP `429`        |
| 高风险工具的审计接收端不可用       | 工具调用 fail closed 并返回 HTTP `503` |

应对鉴权失败、策略服务不可用、策略拒绝、异常模型切换、工具阻止和请求正文的异常访问建立记录与告警。

## Private deployment 检查表

在向生产流量开放 private Gateway 前：

1. 启用 Alephant 鉴权，并验证未鉴权请求会被拒绝。
2. 在 Gateway 或可信 Ingress 终止 TLS，并限制对内部监听地址的直接访问。
3. 对浏览器可访问的部署，在可信边缘收紧 CORS。
4. 配置可信代理 CIDR，避免客户端 IP 策略和速率限制信任任意 forwarded header。
5. 把 PostgreSQL、Redis、policy-service、日志存储和对象存储放在受保护网络中。
6. 通过部署的 secret manager 注入 Provider Key、Master Key 加密密钥、存储凭证和服务 token。
7. 在生产环境关闭请求和响应正文 debug logging。
8. 显式选择 policy-service 不可用时的处理模式，并在上线期间测试。
9. 根据 Prompt 和响应的敏感程度设置日志保留期和 Request Logs 访问权限。
10. 只有在配置明确工具作用域、出站控制、审计投递和上游授权后才启用 Agent 工具。

Gateway 应用层当前接受宽松 CORS 设置，因此在运行态配置被显式收紧前，private deployment 应在可信 Ingress 或反向代理上应用限制性 CORS 策略。

## 能力状态

| 能力                        | 当前状态                | 安全解释                       |
| ------------------------- | ------------------- | -------------------------- |
| Virtual Key 鉴权与过期检查       | 启用鉴权时由 Gateway 执行   | 运行态安全边界                    |
| Virtual Key 模型阻止规则        | 由 Gateway 执行        | 命中的 blocked model 会被拒绝     |
| 工作区 Provider allowlist    | 在 Managed Cloud 中执行 | 需要确认 private deployment 行为 |
| Dashboard Model Allowlist | 仅部分对齐               | 不能假设未命中模型会被拒绝              |
| PII block、redact 和 alert  | 依赖策略服务              | 配置需要兼容的 policy-service     |
| 时间窗口、IP allowlist 和部门密钥矩阵 | 依赖部署                | 保存配置不足以证明已执行               |
| Data Residency            | 当前生效策略 UI 未暴露       | 不能作为运行态保证                  |
| 请求与响应日志                   | 启用可观测性时可用           | 正文可能包含敏感业务数据               |
| Agent 工具控制                | 启用 Agent 工具时可用      | 关闭工具的部署不暴露工具执行面            |

## 验证执行结果

对工作负载依赖的每项安全策略：

1. 在 **Control → LLM Policy** 或 **Control → Agent Policy** 保存策略。
2. 通过目标 Gateway Base URL 分别发送一条应允许和一条应拒绝的请求。
3. 确认返回状态、模型、Provider 和策略结果。
4. 打开 Request Logs，确认工作区、Virtual Key、模型、Provider、状态和可用策略元数据。
5. 对 Agent 工具检查 Agent Runs，确认 requested、blocked、approval 和 completion 事件。
6. 重启 Gateway 后重复测试，并在受控环境中让 policy-service 不可用后再次测试。

这些验证能证明已部署版本的实际行为，其证据强于 Dashboard 中保存的表单或功能标签。

## 相关页面

* [护栏](/ai-gateway/guardrails)
* [Provider 路由](/ai-gateway/provider-routing)
* [Session](/ai-gateway/session)
* [策略与规则](/docs/overview/security-compliance/policies-rules)
* [审计与日志](/docs/overview/security-compliance/audit-logs)