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 托管的高可用数据层:
应用镜像包含四个核心工作负载: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)为准,步骤如下:
-
准备部署目录与核心环境变量(
.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 -
拉取镜像并启动基础设施与应用服务
# 1. 拉取固定版本镜像 docker compose pull # 2. 启动全部服务(初始化容器会自动生成 installation-identity 并完成数据库迁移) docker compose up -d # 3. 检查全部容器处于 healthy / running 状态 docker compose ps -
验证健康检查与首次管理员初始化
# 检查统一入口与 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完成首个平台管理员账号注册与登录,然后前往「平台管理 › 模型管理」配置默认对话与向量模型(详见模型管理与容灾)。 -
标准升级步骤(保留安装身份与数据卷)
# 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/)」的顺序安装:
-
前置检查: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明文保存密码。
- Elasticsearch 索引模板权限:如果 ES 开启了
-
准备生产覆盖配置(
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 -
安装并校验 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 -
升级与安全扩缩容纪律
- 避免
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、决定审计保留期与数据脱敏策略 |
首次部署完成后,建议按以下最小链路逐项验证后再开放给业务团队:
- 浏览器访问统一入口登录管理员账号,检查
/health与「平台管理 › 可观测性」中所有依赖组件显示正常; - 在「平台管理 › 模型管理」完成对话模型与向量模型配置并校验连通性;
- 新建测试知识库上传 1 份 PDF 文档,确认解析、向量、全文与图谱索引全部进入
ACTIVE; - 新建测试 Agent 绑定该知识库并提问,确认返回流式回答且可点击句级引用核对原文;
- 进入「平台管理 › 运维任务」确认每日数据库备份策略与存储余量,并配置至少一条告警通知渠道。