部署架构与实操指南

按业务规模在两套正式私有化方案间选型,并按照可复现的步骤完成 Docker Compose 单机部署或 Kubernetes (Helm) + KubeBlocks Enterprise 生产部署、初始化、升级与验收。

1. 两套正式部署方案怎么选

对比维度 Docker Compose 单机方案 Kubernetes (Helm) + KubeBlocks Enterprise
定位 POC 验证、部门级团队或中小规模正式单机部署 企业级高可用、多副本容错与持续横向扩展生产环境
推荐日增文档 / 副本 日增 1–100 篇(Tier 1),单 API + 1–2 索引工作器 日增 1,000–10,000+ 篇(Tier 2 / Tier 3),前端/API/工作器 2/2/2 起步
高可用与维护 单机故障域,主机宕机即服务中断 多节点跨故障域,支持滚动升级、节点故障迁移与数据库自动主从切换
数据组件管理 同机容器运行 PostgreSQL / Redis / ES / Qdrant / RustFS(或外接云服务) KubeBlocks Enterprise 统一托管数据库部署、扩缩容、备份恢复与版本升级
硬件起点 验证 16C/32G;正式单机 48C/96G(详见容量规划) 3 节点 × 16C/32G 起步 + 企业级 SSD 存储类

2. 生产架构拓扑

两套方案运行完全相同的应用逻辑组件;Kubernetes 方案在此基础上增加了独立网关、多副本调度以及由 KubeBlocks Enterprise 托管的高可用数据层:

用户与 API / MCP 客户端 Ingress / LB → Nginx 统一网关(会话亲和) ApeMind 应用层(Kubernetes 多副本 · Helm Chart 管理) ApeMind 前端 Next.js · 2 副本 ApeMind API FastAPI / MCP · 2 副本 索引与后台 Worker 入库 / 图谱 / 备份 · 2 副本 独立 Parser 服务 apemind-parser · 1+ 副本 读写业务数据与索引 调用模型与外置解析 标准数据与存储层 PostgreSQL 元数据 主从 2 副本 Redis 1 主 1 从 · Sentinel ×3 Elasticsearch 3 Master + 3 Data Qdrant 向量库 3 副本 PostgreSQL 图存储 独立库 · 2 副本 RustFS / 云 S3 默认 RustFS · 兼容 S3 模型与可选解析 LLM / Embedding / Jev 云端 API 或私有化模型服务 MinerU / OCR / ASR 复杂 PDF 与音视频按需扩展 运维与可观测层 KubeBlocks Enterprise · 数据库扩容 / 备份恢复 / 升级 Prometheus / Grafana / 告警通知 / 应用内每日备份 数据库全生命周期托管 指标、链路与审计采集
ApeMind 生产部署架构:应用层采用独立 Parser 与统一 Nginx 网关,数据层支持标准 6 件套与云对象存储。
自研组件职责说明

应用镜像包含四个核心工作负载:apemind-enterprise-frontend(Web 界面)、apemind-enterprise(同时承载 api 与 indexing-worker,v2.12.17 起应用内定时维护与每日备份也由其调度)、apemind-parser(独立本地文档解析服务,默认端口 8090)以及 nginx 统一入口网关。

3. Docker Compose 单机快速部署实操

适用于具备 Docker Engine 24+ 与 Docker Compose v2 的 Linux 服务器。正式单机交付以官方交付包(apecloud/apemind-compose-deploy)为准,步骤如下:

  1. 准备部署目录与核心环境变量(.env)

    将固定版本号、国内/私有镜像源、公开访问地址与持久化密钥写入 .env(切勿使用 latest 浮动标签):

    cat > .env <<'EOF'
    # 镜像与版本(离线或国内环境替换为可达镜像仓库)
    REGISTRY=apecloud-registry.cn-zhangjiakou.cr.aliyuncs.com
    VERSION=v2.12.18
    IMAGE_NGINX=nginx:1.27.5
    
    # 对外公开地址(用于 OAuth / MCP / A2A Agent Card 与分享链接)
    PUBLIC_PORT=3000
    APEMIND_PUBLIC_URL=https://apemind.example.com
    
    # 安全密钥(留空时由 jwt-secret-init 自动生成并持久化到 app-secrets 卷)
    JWT_SECRET=<至少32字节高熵随机串>
    
    # 标准数据面后端
    VECTOR_DB_TYPE=qdrant
    GRAPH_DB_TYPE=postgresql
    OBJECT_STORE_TYPE=s3
    INDEXING_QUEUE_BACKEND=redis
    INDEXING_QUOTA_BACKEND=redis
    EOF
  2. 拉取镜像并启动基础设施与应用服务
    # 1. 拉取固定版本镜像
    docker compose pull
    
    # 2. 启动全部服务(初始化容器会自动生成 installation-identity 并完成数据库迁移)
    docker compose up -d
    
    # 3. 检查全部容器处于 healthy / running 状态
    docker compose ps
  3. 验证健康检查与首次管理员初始化
    # 检查统一入口与 API 健康状态
    curl -fsS "http://127.0.0.1:${PUBLIC_PORT:-3000}/health"
    
    # 检查 Parser 服务就绪状态(容器网络内)
    docker compose exec api curl -fsS http://parser:8090/readyz

    浏览器打开 APEMIND_PUBLIC_URL 完成首个平台管理员账号注册与登录,然后前往「平台管理 › 模型管理」配置默认对话与向量模型(详见模型管理与容灾)。

  4. 标准升级步骤(保留安装身份与数据卷)
    # 1. 升级前确认每日备份正常,或手动执行一次数据库备份
    # 2. 更新 .env 中的 VERSION 为目标版本
    docker compose pull
    docker compose up -d --remove-orphans
    
    # 绝对不要在常规升级时执行 docker compose down -v!
    # 该命令会删除 installation-identity 与业务数据卷,导致 License 绑定失效与数据丢失。

4. Kubernetes (Helm) 生产部署实操

生产集群建议遵循「先数据底座(deploy/databases/),再应用 Chart(deploy/apemind/)」的顺序安装:

  1. 前置检查:Elasticsearch 权限与 Secret
    • Elasticsearch 索引模板权限:如果 ES 开启了 xpack.security.enabled=true,必须在安装前为 ApeMind 使用的 ES 账号授予 manage_index_templates 集群权限(应用镜像不会自动授权,缺少该权限在索引重建时会导致非规范 mapping)。
    • 敏感凭据统一走 Kubernetes Secret:通过 api.jwtSecret.existingSecret、数据库密码 Secret、对象存储 Secret 与 license.existingSecret 注入,不要在 Git 中的 values.yaml 明文保存密码。
  2. 准备生产覆盖配置(my-prod-values.yaml)
    global:
      # 国内或内网私有仓库统一覆盖全部应用镜像前缀
      imageRegistry: "apecloud-registry.cn-zhangjiakou.cr.aliyuncs.com"
    
    api:
      env:
        APEMIND_PUBLIC_URL: "https://apemind.example.com"
        OBJECT_STORE_TYPE: "s3"
        VECTOR_DB_TYPE: "qdrant"
        GRAPH_DB_TYPE: "postgresql"
        INDEXING_QUEUE_BACKEND: "redis"
        INDEXING_QUOTA_BACKEND: "redis"
      jwtSecret:
        existingSecret: "apemind-jwt-secret"
        key: "JWT_SECRET"
    
    parser:
      enabled: true
      replicaCount: 2
    
    ingress:
      enabled: true
      hosts:
        - host: apemind.example.com
          paths:
            - path: /
              pathType: Prefix
              service:
                component: gateway
                name: ""
                port: 3000
  3. 安装并校验 PostgreSQL 连接池预算

    Helm Chart 在渲染期内置了元数据 PG 与独立图 PG 的 max_connections 静态保护:若副本数 × 连接池超出 postgres.maxConnections 或 graphPostgres.maxConnections,渲染会直接报错阻止上线。先 helm template 检查,再执行安装:

    # 渲染检查(Tier 2 生产叠加 values-production.yaml)
    helm template apemind ./deploy/apemind \
      -n apemind \
      -f deploy/apemind/values.yaml \
      -f deploy/apemind/values-production.yaml \
      -f my-prod-values.yaml > /dev/null
    
    # 正式安装(固定 Chart/镜像版本)
    helm upgrade --install apemind ./deploy/apemind \
      -n apemind --create-namespace \
      -f deploy/apemind/values.yaml \
      -f deploy/apemind/values-production.yaml \
      -f my-prod-values.yaml \
      --wait --timeout 10m
  4. 升级与安全扩缩容纪律
    • 避免 helm --reuse-values:每次升级合并版本化 values 文件并先执行 helm lint / helm template。
    • 勿直接 kubectl scale 索引工作器:直接扩容会绕过 Helm 的 PostgreSQL 连接池预算校验,可能打满数据库连接;扩缩 indexingWorker.replicaCount 应使用 scripts/k8s/safe-scale-indexing-worker.sh 或常规 helm upgrade。
    • v2.12.17+ 维护任务与每日备份:原独立 CronJob 已改为应用内调度,升级后自动清理旧 CronJob;v2.12.18 起每日数据库备份默认开启,建议立即在「平台管理 › 运维任务」确认备份存储目标(详见运维、告警、备份与审计)。

5. 交付责任边界与最低验收清单

领域 ApeMind 产品侧负责 部署与运维侧(客户 / 基础设施)负责
应用镜像与升级 发布版本化前后端/Parser 镜像、Helm Chart、数据库迁移脚本与升级说明 内网镜像同步、变更窗口审批、执行升级与回滚演练
基础设施与网络 提供标准端口、健康探针与代理头要求 主机/K8s 集群、企业级 SSD 存储类、DNS、TLS 证书、防火墙与外网代理
数据层与备份 提供数据模型、标准组件推荐拓扑与应用内每日数据库备份能力 监控磁盘水位、配置异地/外部 S3 备份目标、定期恢复演练与灾难恢复
模型与合规 提供模型接入适配、配额限流与审计日志能力 采购模型 API/GPU 算力、配置 SSO/OIDC、决定审计保留期与数据脱敏策略

首次部署完成后,建议按以下最小链路逐项验证后再开放给业务团队:

  1. 浏览器访问统一入口登录管理员账号,检查 /health 与「平台管理 › 可观测性」中所有依赖组件显示正常;
  2. 在「平台管理 › 模型管理」完成对话模型与向量模型配置并校验连通性;
  3. 新建测试知识库上传 1 份 PDF 文档,确认解析、向量、全文与图谱索引全部进入 ACTIVE;
  4. 新建测试 Agent 绑定该知识库并提问,确认返回流式回答且可点击句级引用核对原文;
  5. 进入「平台管理 › 运维任务」确认每日数据库备份策略与存储余量,并配置至少一条告警通知渠道。

下一步