agent-memory 容器化部署实战:online、local、postgres 三套 Docker Compose Profile 详解与配置原理

原创2026-10-13 11:35:051,969 阅读
文章标签:Agent 记忆人工智能MCP 服务RAGAI Agent

agent-memory 容器化部署实战:online、local、postgres 三套 Docker Compose Profile 详解与配置原理

本文基于 openJiuwen/agent-memory 仓库的官方文档 docs/en/Installation Guide/Containerized Deployment.md 编写,系统讲解如何用 Docker Compose 一键拉起 agent-memory 的 HTTP 记忆服务及其全部存储后端:三套现成 profile(online、local、postgres)的选型与启动步骤、模型端点配置规则、容器网络与配置加载原理、启动后验证闭环,以及生产上线前必须补齐的安全能力清单。读完本文,你可以独立完成从环境准备、三选一部署到 add/search 闭环验证的完整流程,并能读懂 Compose 文件、config.yml 与 .env 三者之间的协作关系。

1. 部署架构总览

容器化部署使用 Docker Compose 同时运行 agent-memory HTTP 服务与后端存储。调用方通过 8137 端口访问应用容器,应用内部完成 MemoryAPI 调用、记忆构建与检索,并通过 Storage 接口读写三类后端:

Caller
  │ HTTP :8137
  ▼
agent-memory application container
  ├── MemoryAPI / construction / retrieval
  ├── Models: remote calls or BGE loaded inside the container
  └── Storage interface
       ├── Redis or PostgreSQL KV
       ├── Milvus or pgvector
       └── Elasticsearch

仓库在 deploy/docker 目录下维护三套相互独立的部署文件,每套都包含 docker-compose.yml、Dockerfile、config.yml 和 .env.example 四个要素,可以复制模板环境变量文件后直接配置启动:

模式 Compose 镜像 配置 环境变量示例
在线模型 online/docker-compose.yml online/Dockerfile online/config.yml online/.env.example
本地模型 local/docker-compose.yml local/Dockerfile local/config.yml local/.env.example
PostgreSQL postgres/docker-compose.yml postgres/Dockerfile postgres/config.yml postgres/.env.example

从 Compose 文件可以看到三套栈的共同设计:应用容器通过 depends_on: condition: service_healthy 等待所有后端健康后才启动,自身也定义了基于 GET /healthz 的健康检查(start_period: 120s、retries: 5),并以 restart: unless-stopped 保持常驻。以 deploy/docker/online/docker-compose.yml 为例,栈内包含 redis、elasticsearch、etcd、minio、milvus、agent-memory 六个服务,其中 Milvus 依赖 etcd 与 MinIO 健康后启动(depends_on.etcd.condition: service_healthy)。

2. 前置条件

  • 宿主机上不需要安装 Python 应用,但必须安装 Docker 与 Docker Compose v2;
  • Redis/Milvus/Elasticsearch 相关的 profile 建议为 Docker 分配至少 20 GB 内存,完整栈运行时约占用 13–18 GB;
  • 宿主机网络需能拉取所需镜像;使用远程模型时,容器还需能访问对应的模型端点;
  • 默认端口约定:HTTP 8137、Elasticsearch 9200;Milvus profile 额外暴露 19530/9091;PostgreSQL profile 默认暴露 5432。

各 profile 实际拉取的关键镜像版本(可在 Compose 文件中确认):

组件 镜像
Redis redis:7-alpine(开启 AOF 持久化)
Elasticsearch docker.elastic.co/elasticsearch/elasticsearch:8.13.4(单节点、默认关闭 xpack 安全)
Milvus milvusdb/milvus:v2.4.13(standalone,依赖 etcd v3.5.5 + MinIO)
PostgreSQL pgvector/pgvector:0.8.3-pg16

完整的原始 Compose 参数说明可对照 deploy/docker/README.md。

3. Profile 选型

Profile 应用内模型 外部模型 存储后端 适用场景
online 无 LLM、嵌入、精排 Redis + Milvus + ES 已有远程模型服务,希望应用镜像更轻
local BGE 嵌入、BGE 精排 LLM Redis + Milvus + ES 记忆内容不希望发送给远程嵌入/精排服务
postgres 无 LLM、嵌入、精排 PostgreSQL KV + pgvector + ES 希望减少 Milvus、etcd、MinIO 组件

三套 profile 的差异可以从源码层面印证:

  • online 的 deploy/docker/online/Dockerfile 明确注释"不安装 torch / FlagEmbedding / transformers 或项目 [embed] extra",只安装 [deploy] extra(Milvus / Elasticsearch / Redis / YAML 客户端),嵌入走 OpenAI 兼容 /v1/embeddings,精排走 Cohere 风格 /rerank;
  • local 的 deploy/docker/local/Dockerfile 额外安装 CPU 版 torch==2.12.1+cpu 与 [embed,deploy] extra(镜像约 5–6 GB,纯 CPU 推理、不装 CUDA 库),模型文件从挂载的 /models-local 离线加载;
  • postgres 的 deploy/docker/postgres/docker-compose.yml 只包含 postgres、elasticsearch、agent-memory 三个服务,不再启动 Redis、Milvus、etcd、MinIO。

接口与安全模式(三套 profile 通用):

  • 所有 profile 都通过 POST /v1/<method_name> 暴露与 MemoryAPI 同名的 HTTP 接口,并提供 GET /healthz 健康检查;
  • 当前 Compose 启动器尚未装配生产级 SecurityRuntime,因此默认 required 认证模式下只有健康检查可直接访问,业务接口返回 503(源码 jiuwen_memory_entry/http_server/main.py 中,runtime is None 时业务请求直接返回 SecurityUnavailable 错误);
  • 本地功能测试可以在 .env 中显式设置 JIUWEN_MEMORY_HTTP_AUTH_MODE=dev。

4. 在线模型模式(online)

该模式下 LLM、嵌入、精排全部由远程服务提供:Redis 保存真源记录,Milvus 保存向量索引,Elasticsearch 保存全文索引。启动步骤:

cd deploy/docker/online
cp .env.example .env
# 编辑 .env,至少配置 LLM_API_KEY、MODEL_API_TOKEN、
# EMBEDDER_BASE_URL、RERANKER_BASE_URL
docker compose config
docker compose up -d --build

deploy/docker/online/.env.example 中的关键变量如下:

变量 默认/说明
JIUWEN_MEMORY_HTTP_AUTH_MODE required(生产保持)/ dev(仅本地功能测试)
HTTP_BIND_ADDRESS 127.0.0.1,控制宿主机侧发布地址
LLM_API_KEY DashScope API Key(必填)
LLM_BASE_URL / LLM_MODEL 默认 DashScope 兼容端点 + qwen-plus
LLM_ENABLE_THINKING false(默认关闭思考)、true 开启、null 不发送该厂商字段
MODEL_API_TOKEN 远程嵌入/精排服务的 API Token
EMBEDDER_BASE_URL / EMBEDDER_MODEL 嵌入服务地址(必须包含 /v1)与模型名,默认 bge-m3
RERANKER_BASE_URL / RERANKER_MODEL 精排服务地址(不要包含 /rerank)与模型名,默认 bge-reranker-v2-m3
RERANKER_DIALECT 默认 cohere
REDIS_URL / ES_HOSTS / MILVUS_URI 默认值即 Compose 内部服务名,无需修改
*_SSL_VERIFY / *_SSL_CA 对接云端托管后端与模型端点的 TLS 开关(见下文)

两条必须特别注意的模型 URL 规则:

  • EMBEDDER_BASE_URL 必须包含 /v1,例如 https://models.example.com/v1——OpenAI 客户端会在其后追加 /embeddings;
  • RERANKER_BASE_URL 不要包含 /rerank,例如 https://models.example.com——适配器会自行追加该路径。

deploy/docker/online/config.yml 中对应配置为 embedder_base_url: "${EMBEDDER_BASE_URL}"、reranker_base_url: "${RERANKER_BASE_URL}",且 embedder_api_key 与 reranker_api_key 都复用 MODEL_API_TOKEN。配置注释明确说明:不提供公共默认嵌入端点,因为记忆内容只应发往你在 .env 中显式配置的端点。

切换 LLM 厂商的注意事项: 默认 LLM target 为 DashScope(llm.default.target: dashscope,参数 enable_thinking 由 LLM_ENABLE_THINKING 注入)。若改用通用 OpenAI-compatible 服务,需要同时调整 config.yml 中的 target、模型名(llm_model)、URL(llm_base_url)和厂商专属参数,只替换 URL 是不够的。

SSL 配置要点(*.env.example 注释归纳):

  • 各后端的 ssl_verify 只控制"是否校验服务端证书",加密开关在连接串的 scheme 上:Redis 要换成 rediss://,ES 要换成 https://,Milvus 是参数形态开关(内部置 secure=True,uri 用 http/https 皆可);
  • 启用任一 *_SSL_VERIFY=true 时对应的 *_SSL_CA 必填(自签场景),否则装配阶段直接报错;证书需挂载进容器并使用容器内路径,且 TLS 默认校验主机名,连接串建议用域名而非 IP。

5. 本地模型模式(local)

该模式在应用容器内加载 bge-m3(嵌入)与 bge-reranker-v2-m3(精排),LLM 仍默认调用 DashScope。启动步骤:

cd deploy/docker/local
./download-models.sh
cp .env.example .env
# 编辑 .env,至少配置 LLM_API_KEY
docker compose up -d --build

模型文件不会在容器启动时自动下载,必须先通过宿主机准备。仓库提供的 deploy/docker/local/download-models.sh 会:

  1. 若本机未安装 modelscope CLI,先创建临时 venv .venv-modelscope 安装(避免污染系统 Python);
  2. 从 ModelScope 下载 BAAI/bge-m3 与 BAAI/bge-reranker-v2-m3 到 deploy/docker/models/ 下的对应目录(目录已存在则跳过);

脚本头部注释解释了为什么不在容器内联网下载:直连 HuggingFace 在部分网络环境下不稳定,且下载失败时索引构建会静默降级(向量索引构建器捕获嵌入异常后记录日志并继续),导致写入看似成功、召回却为空。下载完成后,deploy/docker/local/docker-compose.yml 会把 ../models 以只读方式挂载到容器 /models-local,local/.env 中 EMBED_MODEL=/models-local/bge-m3、RERANK_MODEL=/models-local/bge-reranker-v2-m3 默认即指向该处,无需修改。

运行特性:

  • 模型在应用第一次收到相关请求时才载入内存,因此首次 add/search 会明显更慢,之后常驻复用;
  • 没有 GPU 时嵌入/精排走 CPU 推理,功能仍可用,但批量写入与并发吞吐受限;
  • 该模式 .env 只需配置 LLM_API_KEY(嵌入/精排本地化,无需 MODEL_API_TOKEN),后端连接串默认即 Compose 服务名。

6. PostgreSQL 模式(postgres)

该模式用同一个 PostgreSQL 实例保存 KV 真源与三张 pgvector 向量表,Elasticsearch 继续保存全文索引,不再启动 Redis、Milvus、etcd、MinIO。启动步骤:

cd deploy/docker/postgres
cp .env.example .env
# 编辑 .env:配置模型凭据与端点,并替换默认数据库密码
docker compose config
docker compose up -d --build

Compose 会将 scripts/pg_schema.sql 挂载为 /docker-entrypoint-initdb.d/10-agent-memory.sql,在 PostgreSQL 数据卷**首次创建(空卷)**时自动执行:

  • CREATE EXTENSION IF NOT EXISTS vector(安装 pgvector);
  • 创建 KV 真源表 agent_memory_kv(六段 scope 字段 + key 联合主键,value bytea,附带 expires_at 部分索引);
  • 创建三张向量表 agent_memory_vectors、agent_memory_vectors_l0、agent_memory_vectors_l1(embedding vector(1024),scope 联合主键,metadata jsonb);
  • 为每张向量表创建 scope 联合索引、metadata GIN 索引与 HNSW 向量索引(vector_cosine_ops,m = 16, ef_construction = 64)。

对应的应用配置见 deploy/docker/postgres/config.yml:kv_store 与三层 vector_store 全部指向同一个 DSN postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB},并固定 auto_create_schema: false / create_extension: false——即建表完全交给初始化脚本,应用自身不再建表。

维度与命名一致性约束: 初始化脚本只在空数据卷首次启动时执行一次,默认 DDL 使用 public schema、1024 维向量、COSINE/HNSW。如果你要修改 schema、表名或嵌入维度(.env 中的 PG_SCHEMA / PG_KV_TABLE / PG_VECTOR_TABLE*),必须在创建数据卷之前同步修改 .env、config.yml 和初始化 SQL;已有数据卷不会自动迁移。embedder_dim(globals 中默认 1024)必须与向量表 vector(N) 维度一致,否则检索会报错。

端口说明: PostgreSQL 端口通过 ${POSTGRES_PORT:-5432}:5432 发布到宿主机,仅用于数据库连接与排障。

7. 启动后验证

以下命令适用于三套 profile:

docker compose ps
docker compose logs -f agent-memory

另开终端执行健康检查:

curl http://localhost:8137/healthz

健康检查返回 {"status": "ok", "profile": "<profile名>"}(见 jiuwen_memory_entry/http_server/main.py 中 handle_get 的实现)。

测试业务接口需要显式启用开发认证。 在当前 profile 的 .env 中设置:

JIUWEN_MEMORY_HTTP_AUTH_MODE=dev
HTTP_BIND_ADDRESS=127.0.0.1

然后重新创建应用容器(.env 变化只影响容器环境,必须 recreate 才生效):

docker compose up -d --force-recreate agent-memory

行为细节(源码印证):

  • 启动脚本 jiuwen_memory_entry/http_server/main.py 的 --auth-mode 参数默认读取 JIUWEN_MEMORY_HTTP_AUTH_MODE 环境变量(缺省 required);dev 模式下调用 with_local_dev_security() 装配本地开发认证;
  • 未配置 http.dev_identities 时,dev 模式忽略认证头并固定使用 local/developer 的 ROOT 身份,但仍执行 MemoryAPI 层的授权;
  • 容器内进程始终监听 0.0.0.0:8137,HTTP_BIND_ADDRESS=127.0.0.1 通过 Compose 端口映射 ${HTTP_BIND_ADDRESS:-127.0.0.1}:8137:8137 把宿主机端口只发布到回环地址;
  • dev 模式仅用于隔离功能测试;共享网络或生产部署必须恢复 required 并注入可信生产 runtime。

随后用下列请求验证一次 add/search 闭环:

curl -X POST http://localhost:8137/v1/add \
  -H 'Content-Type: application/json' \
  -d '{"content":"The user prefers to write code in Python","scope":{"org":"local","space":"","user":"developer","agent":"","session":""}}'

curl -X POST http://localhost:8137/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"Which language does the user prefer","context":{"scope":{"org":"local","space":"","user":"developer","agent":"","session":""},"extensions":{}},"top_k":5}'

多身份测试: 需要测试多用户/多身份时,在 profile 实际挂载的 config.yml 中加入与 memory_api 同级的 http.dev_identities 映射(格式与用法详见 docs/en/API Docs/config.md),或修改你的自定义挂载文件,然后保持 dev 开关并重建应用容器。配置映射后,每个业务请求必须携带有效的 Bearer 或 X-API-Key 测试标识,缺失或未知标识返回 401;映射不创建空间、不添加成员,也不绕过授权——无认证头的请求示例仅适用于未配置映射的情况。

健康检查的局限: status: ok 只确认 HTTP 进程能响应。完整可用性必须用一次真实 add/search 闭环来验证,因为模型连通性、向量维度、索引配置类错误往往只在业务请求时才暴露。

8. 配置加载规则

每个 profile 的 Compose 文件把本目录 config.yml 挂载到容器内 /config/config.yml,应用镜像的 CMD 再把这个路径作为参数传给 HTTP 启动脚本,例如 deploy/docker/online/Dockerfile:

# docker-compose.yml 中的挂载
volumes:
  - ./config.yml:/config/config.yml:ro
# Dockerfile 中的启动命令
CMD ["python", "jiuwen_memory_entry/http_server/__main__.py", \
     "--host", "0.0.0.0", "--port", "8137", "/config/config.yml"]

因此真正决定使用哪份配置的,是 Compose 中的挂载源(左侧宿主机文件),容器内路径固定。

配置文件是两层结构(以 deploy/docker/online/config.yml 为例):

profile: docker-profile-name

memory_api:
  globals: {}
  kv_store: {}
  vector_store: {}
  fulltext_store: {}
  • profile 属于服务接入层(服务面),标识当前 profile;
  • memory_api 内部才是交给内核装配 assemble() 的两级组件命名空间(顶层 = 组件命名空间,其下 = 具名实例的 target/params);
  • 用户配置合并覆盖内置默认装配(纯内存离线栈),因此只需声明需要替换的实现;
  • ${VAR} 与 ${VAR:-default} 由 HTTP 启动配置加载器递归展开;
  • Docker Compose 通过 env_file: [.env] 读取同目录 .env 并注入容器环境变量,所以密钥不落在配置文件里。

多配置文件是浅合并: 启动脚本允许传入多个配置路径(依次叠在内置 OFFLINE 之上,靠后覆盖靠前),但文件之间按顶层键浅合并——后一个文件一旦声明 memory_api,就整体替换前一个文件的 memory_api 段,不会对其内部深合并。所以同一 profile 的内核差异应尽量写在一份 memory_api 中;分层更适合覆盖 profile、http 这类顶层键。

9. 容器网络与宿主机地址

Compose 网络内部,应用容器通过服务名访问后端:

  • redis:6379
  • milvus:19530
  • elasticsearch:9200
  • postgres:5432

这些名称只在 Compose 网络内可解析。如果改成"应用在宿主机直接运行、只用 Docker 启动存储"的混合部署,配置必须改用 127.0.0.1 加映射到宿主机的端口,不能复用上述容器 DNS 名称。SDK 方式接入的完整说明见 docs/en/Installation Guide/SDK Deployment.md。

10. 数据与生命周期

docker compose down

停止全部服务并保留具名数据卷(redis-data、es-data、etcd-data、minio-data、milvus-data;postgres profile 为 postgres-data、es-data)。再次启动后后端数据仍然存在。

docker compose down -v

停止服务并删除当前 profile 声明的数据卷——这会删除真源与索引数据,通常不可恢复(postgres profile 下会同时删除 PostgreSQL 与 Elasticsearch 数据卷,包含所有 KV 和向量数据)。执行前务必确认已有备份。

11. 生产使用前需要补齐的能力

当前 HTTP 服务是参考实现:不内置 TLS 与多进程管理(从源码看,服务为单进程 ThreadingHTTPServer,并发线程上限 256、请求体上限 4 MiB,见 jiuwen_memory_entry/http_server/main.py)。业务身份必须由可信 SecurityRuntime 从认证头构造,runtime 也可以接入限流(rate_limiter)与工作负载保护(workload_guard)策略;当前 Compose 启动器尚未提供其生产装配器。Compose 中的 Elasticsearch 默认关闭 xpack 安全认证,默认数据库凭据(如 MinIO 的 minioadmin、postgres profile 的默认密码)仅适合开发环境。

在共享网络或生产环境部署前,至少应补齐:

  • 在反向代理或 API 网关终止 TLS;
  • 装配可信 SecurityRuntime,从认证信息构造 RequestSecurityContext;
  • 替换所有默认密码,按最小权限配置后端账户;
  • 限制 PostgreSQL、Elasticsearch、Milvus 等后端端口的对外暴露;
  • 为 PostgreSQL、Redis、Elasticsearch、Milvus 与模型端点配置 TLS(各后端的 SSL 开关见 deploy/docker/online/.env.example 注释);
  • 增加限流、超时、重试、日志采集、监控、备份与恢复策略;
  • 按可用性目标补充进程编排与多副本方案(注意配置中 async_timer 调度器与恢复实例锁体现的是单实例部署模型,多实例共用同一 KV 会被拒绝)。

12. 常见问题

健康检查通过,但检索没有结果

按顺序检查:应用日志中的嵌入异常、模型端点连通性、向量维度是否一致(embedder_dim、Milvus collection dim / pgvector vector(N) 三者必须一致)、Elasticsearch/Milvus 或 pgvector 中是否真正生成了索引数据。本地模型模式下,模型下载不完整也会让写入成功而索引构建静默降级(嵌入异常被捕获、记日志后继续)。

中文关键词召回效果差

Elasticsearch 默认 analyzer 未必适合中文。可用内置 cjk 分析器,或使用安装了 IK 插件的 Elasticsearch 镜像并配置 ik_max_word。config.yml 中通过 text_analyzer: "${ES_TEXT_ANALYZER:-english}" 指定(见 deploy/docker/postgres/config.yml 的 fulltext_store 段)。注意 analyzer 只在索引创建时生效,修改后必须删除旧索引重建才能应用。

修改配置后没有生效

如果修改了 Compose 的挂载源或服务定义,必须执行 docker compose up -d 重新创建受影响容器——单纯的 restart 不会应用 Compose 文件变化。之后用 docker compose config 查看渲染后的完整配置,并配合容器日志确认实际生效内容。

13. 相关文档

登录后查看全文
agent-memory