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

# 部署加固

> 使用网络、密钥、存储、日志和备份控制加固艾维斯生产部署。

艾维斯可运行在不同部署形态中。无论服务运行在单主机、多主机还是托管基础设施上，下面的加固清单都适用于生产环境。

## 网络暴露

| 服务                                        | 建议暴露方式                          |
| ----------------------------------------- | ------------------------------- |
| Nginx 或请求路由器                              | 公开，受 TLS 和部署防火墙规则保护。            |
| AIvis Web 和 API                           | 除非部署有明确的内部访问设计，否则应位于路由器后方的私有网络。 |
| Agent Runtime 和 Tool Bridge               | 仅限私有内部网络。                       |
| Postgres、Redis、OpenSearch、MinIO 或 S3 兼容存储 | 仅限私有网络。                         |
| Model servers 和 background workers        | 仅限私有网络。                         |

## 基线加固矩阵

| 区域   | 生产最低控制                                                  |
| ---- | ------------------------------------------------------- |
| TLS  | 在公开路由器终止或转发 TLS。明文流量应重定向或完全阻断。                          |
| 防火墙  | 只允许公开入站流量进入路由器。数据库、缓存、搜索、模型、worker 和 runtime 端口限制在私有网络。 |
| 身份   | 使用经过审查的管理员清单，并在上线前移除未使用账号。                              |
| 密钥   | 将密钥保存在源码之外，并在事故响应、人员变化或环境复制后轮换。                         |
| 数据存储 | 启用持久卷、备份、受支持的静态加密和恢复测试。                                 |
| 日志   | 集中日志，并支持按服务、request ID、用户、连接器、Agent 和 job ID 检索。        |
| 出站访问 | 将出站流量限制到获准模型 Provider、SaaS API、对象存储端点和内部服务。             |

## 密钥

* 使用部署密钥存储或环境专用密钥管理，避免把密钥提交到源码。
* 按文档化周期轮换模型、连接器、服务和对象存储凭据。
* 在 runbook 和示例中使用占位符；不要把真实 authorization token、API key、private key 或用户邮箱放入公开文档。
* 按环境分离凭据，避免 staging 访问 production 数据。

## 凭据轮换事件

出现以下情况时，应轮换受影响凭据：

* 连接器负责人变更。
* 模型 Provider key 被复制到测试环境。
* Runtime 或 bridge 服务在访问策略变更后重新部署。
* 管理员离开运维团队。
* 日志、截图、工单或聊天消息意外包含密钥。

## 存储与备份

Postgres、OpenSearch 和对象存储包含最重要的持久状态。生产部署应在大规模用户上线前定义备份频率、保留周期、恢复测试、静态加密和灾备责任人。

| 存储         | 备份重点                             |
| ---------- | -------------------------------- |
| Postgres   | 用户、会话、配置、凭据 metadata、连接器状态和任务状态。 |
| OpenSearch | 可搜索文档内容、向量数据和检索索引。               |
| 对象存储       | 上传文件、连接器对象和重建索引所需文档。             |
| 配置         | 环境变量、服务定义、路由规则和密钥引用。             |

## 日志与监控

记录 request ID、服务健康、索引任务、连接器同步失败、runtime 错误和授权拒绝。除非部署策略明确要求，否则避免记录原始密钥、完整凭据 payload 或无限制用户内容。

至少监控：

* API 错误率、延迟和授权拒绝。
* 连接器同步状态、跳过文档和凭据失败。
* 索引队列深度和模型服务延迟。
* Agent runtime 失败、工具拒绝和长时间运行任务。
* OpenSearch 磁盘使用、Redis 可用性、对象存储错误和 Postgres 连接数。

## 出站控制

连接器 worker 和 runtime 服务可能需要出站访问获准的 SaaS API、模型提供商或内部服务。请将出站访问限制到已启用连接器、集成和模型提供商所需的域名和网络。

## 事故响应准备

生产上线前请准备运维 runbook：

| 事件           | 首批动作                                                 |
| ------------ | ---------------------------------------------------- |
| 凭据暴露         | 吊销凭据，轮换依赖服务，搜索日志中的使用记录，并更新受影响连接器或模型配置。               |
| 连接器索引范围过大    | 禁用连接器，删除或收紧文档集，必要时重建受影响索引，并审查群组访问。                   |
| Runtime 工具误用 | 禁用工具或 Agent，按 request ID 检查运行日志，轮换相关凭据，并为拒绝路径增加回归测试。 |
| 搜索数据不一致      | 暂停受影响摄取，检查 worker 和 OpenSearch 健康，并重建受影响索引范围。        |

## 生产清单

* 公开流量只通过受 TLS 保护的路由进入。
* 内部服务端口不暴露到公网。
* 管理员账号和身份提供方设置已审查。
* 已在测试环境中恢复过备份。
* 密钥轮换和事故响应责任人已确定。
* 日志可搜索且不暴露敏感值。
* 连接器范围和 Agent 工具范围已由数据负责人审查。
* 模型、连接器、Agent 和 runtime 配置变更都有回滚路径。