> 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.

# 系统说明

> 查看艾维斯应用、模型、Agent 和数据服务之间的部署层级与安全边界。

艾维斯由一组协同服务组成，并为用户访问、应用控制、知识索引、模型负载、Agent 执行和持久数据分别设置边界。

## 应用层

| 组件                 | 作用                                                |
| ------------------ | ------------------------------------------------- |
| AIvis Web          | 面向管理员和用户的 Next.js 界面，应通过公开请求路由器访问。                |
| AIvis API          | 处理认证上下文、业务逻辑、管理操作、对话、连接器和 runtime 协调的 FastAPI 服务。 |
| Background Workers | 处理文档同步、索引、计划任务和其它异步工作的 worker 服务。                 |

API 服务是用户上下文的控制边界。其它服务不应从提示词文本、runtime 输出、连接器元数据或客户端传入字段推断用户权限。

## 模型与检索层

| 组件                     | 作用                                   |
| ---------------------- | ------------------------------------ |
| Inference Model Server | 服务查询时使用的模型，例如 embedding 和 reranking。 |
| Indexing Model Server  | 将文档 embedding 与索引负载从实时查询流量中隔离。       |
| OpenSearch             | 为艾维斯知识搜索提供关键词和向量检索。                  |

将索引和查询时模型负载分离，可以避免大型连接器回填影响实时对话和搜索请求。生产部署应分别监控这两类队列。

## Agent 执行层

| 组件              | 作用                              |
| --------------- | ------------------------------- |
| Agent Runtime   | 在部署边界内运行获准的 Agent 工作。           |
| Tool Bridge     | 只向 runtime 暴露已授权的艾维斯工具。         |
| Runtime Gateway | 可选部署组件，用于通过专用内部边界路由 runtime 流量。 |

浏览器不应直接调用 Agent runtime。艾维斯API 会在工作发送到 runtime 服务前重建用户、工作区、对话和权限上下文。

## 主要数据流

| 流程           | 路径                                                         | 安全边界                               |
| ------------ | ---------------------------------------------------------- | ---------------------------------- |
| 用户请求         | 浏览器 → 路由器 → AIvis Web/API → 模型与检索服务。                       | 浏览器流量终止在公开路由器；内部服务只信任服务端上下文。       |
| 连接器摄取        | Background Workers → 源系统 → 对象存储、Postgres、OpenSearch 和模型服务。 | 连接器凭据应仅覆盖获准源内容，并避免出现在用户可见输出中。      |
| 搜索与对话        | AIvis API → OpenSearch → 模型服务 → AIvis API 响应。              | 检索上下文必须来自当前用户或 Agent 路径获授权的文档范围。   |
| Agent Action | AIvis API → Agent Runtime → Tool Bridge → AIvis 服务或获准集成。   | Runtime 输出不是授权依据；工具调用和数据访问仍由艾维斯授权。 |
| 管理操作         | 管理员浏览器 → 路由器 → AIvis API → 配置存储。                           | 管理路由需要角色检查，并应带 request ID 记录日志。    |

## 信任边界

| 边界                | 不应信任                      | 只在以下条件后信任                            |
| ----------------- | ------------------------- | ------------------------------------ |
| 浏览器到 API          | 客户端提供的角色、工作区、模型、工具或文档声明。  | 会话验证和服务端授权。                          |
| 连接器到索引            | 源标签、文件名或 metadata 作为访问控制。 | 明确的艾维斯文档访问配置，以及经过测试的群组行为。            |
| Agent runtime 到工具 | 提示词指令或生成的工具参数作为权限。        | 工具 allowlist、用户上下文、Agent 配置和服务端策略检查。 |
| 模型提供商到响应          | 模型输出作为安全决策。               | 应用校验、策略检查和安全输出处理。                    |

## 数据层

| 组件         | 作用                   |
| ---------- | -------------------- |
| Postgres   | 存储应用数据、用户会话、配置和系统状态。 |
| Redis      | 提供缓存、协调和性能支持。        |
| MinIO 或 S3 | 存储上传文件和连接器对象。        |
| OpenSearch | 存储用于检索的可搜索内容和向量数据。   |

## 基础设施层

Nginx 或等效请求路由器应作为公开入口。它负责终止或转发 TLS，将流量路由到 AIvis Web 和 API 服务，并保持内部服务端口私有。

Postgres、Redis、OpenSearch、对象存储、模型服务、worker 和 Agent runtime 服务的内部端口不应暴露到公网。如果托管服务必须使用公开端点，请通过私有网络、防火墙规则、身份控制和 TLS 限制访问。

## 组件替换

对象存储可替换为 S3 兼容服务。Redis 和 Postgres 可在满足延迟、网络策略和备份要求时替换为托管服务。OpenSearch 可作为本地容器、集群或托管服务运行，但替换为其它搜索引擎需要开发工作，因为检索行为与艾维斯紧密集成。

## 架构审查清单

* 确认公开请求路由器是唯一面向互联网的组件。
* 确认 Web、API、worker、模型服务和 runtime 服务使用私有网络路径。
* 确认连接器 worker 只能访问获准 SaaS API 和内部服务。
* 确认 OpenSearch 和对象存储已备份并具备访问控制。
* 确认 request ID 可贯穿路由器、API、worker、runtime 和模型服务日志。