1. Docker Compose 单机资源起点
以下规格为整机容量(含应用、本地数据组件、索引峰值与升级余量)。业务数据盘必须使用企业级 SSD/NVMe,切勿将数据库与向量/全文索引落在机械硬盘上:
| 部署档位 | CPU | 内存 | 系统盘 | 业务数据盘 | 独立备份空间 | 索引工作器 |
|---|---|---|---|---|---|---|
| 功能验证 | 16 vCPU | 32 GiB | 200 GiB SSD | 500 GiB SSD | 500 GiB 起 | 1 个 |
| 正式单机部署(推荐起点) | 48 vCPU | 96 GiB | 200 GiB SSD | 1 TiB 起(云对象);本机 RustFS/MinIO 共盘则 2 TiB 起 | 1 TiB 起 | 初始 2 个 |
| 单机高负载评估 | 64 vCPU | 128 GiB | 200 GiB SSD | 2 TiB 企业级 NVMe | 2 TiB 起 | 初始 4 个 |
正式单机 48 vCPU / 96 GiB 的典型主机内预算分配:API(2–4C / 4 GiB)、2 × 索引工作器(各 1–2C / 4–8 GiB)、前端(1–2C / 2 GiB)、Parser(2–4C / 4–8 GiB)、元数据与图谱 PostgreSQL(合计 4–8C / 8–12 GiB)、Elasticsearch(2–4C / 4–6 GiB)、Qdrant(2–4C / 8 GiB)、Redis(1–2C / 2 GiB)、RustFS(1–2C / 4 GiB),并保留至少 16–24 GiB 给操作系统页缓存、检索峰值与滚动升级余量。
2. Kubernetes + KubeBlocks Enterprise 生产规划
生产集群建议从 3 台跨故障域节点起步(每节点 16 vCPU / 32 GiB 内存 / 200 GiB SSD 系统盘),业务数据卷通过企业级 SSD/NVMe StorageClass 独立供给,不与系统盘混用。
应用层起始副本与单副本配额
| 组件 | 起始副本 | 单副本 CPU(Requests / Limits) | 单副本内存(Requests / Limits) |
|---|---|---|---|
| ApeMind 前端 | 2 | 0.1 / 0.5 核 | 256 MiB / 512 MiB |
| ApeMind API | 2 | 0.5 / 2 核 | 1 GiB / 4 GiB |
| 索引工作器 | 2 | 2 / 4 核 | 4 GiB / 8 GiB |
| 独立 Parser 服务 | 1–2 | 2 / 4 核(OCR 属 CPU 密集型,每解析槽位建议 ≥2 核) | 4 GiB / 8 GiB |
数据组件单成员采购起点
下表为单成员(单副本)长期运行起点,集群总磁盘 ≈ 单成员容量 × 成员数,并在此之上按首年文档增长预留 6–12 个月空间(磁盘水位达 60%–70% 即应启动扩容评审):
| 组件 | 推荐生产拓扑 | 单成员 CPU / 内存 | 单成员 PVC | 关键说明 |
|---|---|---|---|---|
| PostgreSQL 元数据 | 主从 2 副本 | 1 核 / 2 GiB | 100 GiB | 持续承载会话、任务、审计与账本 |
| PostgreSQL 图存储 | 独立库主从 2 副本 | 1 核 / 4 GiB | 100 GiB | 随文档实体与关系密度增长 |
| Redis | 1 主 1 从 + 3 Sentinel | 1 核 / 2 GiB | 50 GiB | 索引队列、限流、分布式锁与缓存 |
| Elasticsearch | 3 Master + 3 Data | Master 0.5C/1G;Data 1C/2G | Master 50 GiB;Data 100 GiB | 开启安全认证时需授予 manage_index_templates |
| Qdrant 向量库 | 3 副本 | 2 核 / 4 GiB | 200 GiB | 高维向量与大量分块是主要磁盘消耗源 |
| 对象存储 | 云 S3,或自托管 RustFS 单副本 | 1 核 / 2 GiB | 1 TiB 起 | 生产多副本 Worker 必须使用 OBJECT_STORE_TYPE=s3;备份应存往独立故障域 |
可选:MinerU 本地 PDF 解析节点(独立核算)
如果需要使用本地 MinerU 解析复杂版式 PDF,其资源须独立于核心平台核算:单副本建议 1 张 24 GB 显存 GPU(如 NVIDIA A10 同档)、2–6 vCPU、16–32 GiB 主机内存与独立镜像/模型缓存盘。
3. 统一入口网关与多副本会话亲和
在多副本部署中,ApeMind 通过前置 Nginx 统一网关分流请求,使同一对话(chat_id)的执行与代码模式工作区文件读写尽量落在同一个 API 实例上,同时避免流式响应被缓冲:
- 路由分流:页面路由交由 Next.js 前端;
/api、/v1、/mcp、/health、/docs、/openapi.json与 OAuth Discovery 交由 API。Nginx 保留原始路径、Host、Cookie 与鉴权头,关闭 SSE 响应缓冲,且不对非幂等写请求自动重放。 - 亲和键提取规则:优先从路径
/api/v2/agent/chats/<chat_id>/...与/api/v2/chats/<chat_id>/...提取chat_id,其次读取查询参数chat_id(包含/v1/chat/completions);不含chat_id的请求和匿名访客请求按普通负载均衡分流。 - 本地沙箱文件边界:沙箱本地工作目录隶属于所在 API 实例,Pod 重建、扩缩容或故障切换时原本地文件可能不可见;需要长期保存的成果物请转存知识库或通过工作区导出保存。
Kubernetes 与 Compose 网关要点
- Kubernetes(Helm Chart 默认内置):Chart 默认部署 Nginx 网关并通过 headless
api-discoveryService 的 DNS SRV 记录直接发现各 API Pod(无需赋予网关 Kubernetes API 权限)。若自定义覆盖了ingress.rules,升级时须把应用根路径/指向网关组件(service.component: gateway、port: 3000),不要继续直接指向旧的独立前端/API Service。 - Docker Compose:使用支持原生 DNS
resolve的 Nginx(默认nginx:1.27.5)。单 API 实例无需额外配置;若在单机配置多 API 实例,须在 upstream 中列出各自独立的服务名,不要把多副本挂在同一普通 DNS 名下假定一致性哈希生效。 - 公共访问地址:当站点前面有企业 HTTPS 反向代理时,通过
X-Forwarded-Proto和X-Forwarded-Host透传外部协议与域名,并显式配置APEMIND_PUBLIC_URL,确保 A2A Agent Card、OAuth Discovery 与连接交接链接生成正确的外部地址。
4. 反向代理与客户端 IP 信任(FORWARDED_ALLOW_IPS)
公开链接与网站嵌入的匿名访客限流(单 IP 每分钟 60 次)依赖 API 进程解析真实客户端 IP。配置不当会导致限流失效或所有用户误共用同一个 IP 额度:
- 默认可信网段:API 默认信任回环与标准私有网段(
127.0.0.1、::1、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、100.64.0.0/10、fc00::/7)。请求来自可信网段时,取X-Forwarded-For中最右侧的非可信地址;直接来自公网的请求忽略X-Forwarded-For。 - 纯内网部署必须显式收窄:如果访客本身也在公司内网(私有网段)访问,默认规则会把访客 IP 也视作“可信代理”从而继续向左读取客户端伪造的头。请将环境变量
FORWARDED_ALLOW_IPS(Helm 中为api.forwardedAllowIps)设为实际反代/Ingress/网关的精确 IP 或 CIDR 列表:- 切勿设为
*(会让客户端任意伪造X-Forwarded-For绕过 IP 限流); - 切勿只填
127.0.0.1(会导致所有外部访客被识别成同一个 Ingress IP 而互相挤占额度)。
- 切勿设为
- 前端代理启动参数:Docker Compose 场景下前端服务转发
/api请求时,镜像默认通过node --import ./forwarded-for.mjs server.js将真实 TCP 对端地址追加到X-Forwarded-For末尾;若脱离官方镜像自行运行前端构建产物,务必保留该启动参数。
5. 监控指标与扩容触发信号
| 信号 | 建议动作 |
|---|---|
| 数据盘 / PVC 使用率持续达到 60%–70% | 立即扩容对应存储卷或调整日志/账本保留期,避免磁盘写满触发 ES 只读或 PG 不可写 |
索引队列持续积压、Parser 频繁返回 429 |
增加 parser.replicaCount 与 indexingWorker.replicaCount(K8s 用安全扩容脚本检查 PG 连接池) |
| API Pod CPU 持续高于 70% 或对话延迟抖动 | 开启 API HPA 或增加副本数,并同步校验 postgres.maxConnections 预算 |
| PostgreSQL 连接数逼近上限 | 核对总连接预算公式并调整数据库 max_connections,或评估启用 PgBouncer(Tier 3) |