agent-memory 容器化部署实战:online、local、postgres 三套 Docker Compose Profile 详解与配置原理
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、Elasticsearch9200;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 会:
- 若本机未安装 modelscope CLI,先创建临时 venv
.venv-modelscope安装(避免污染系统 Python); - 从 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:6379milvus:19530elasticsearch:9200postgres: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. 相关文档
- docs/en/Installation Guide/Deployment Overview.md:部署方式概览
- docs/en/Installation Guide/SDK Deployment.md:SDK 部署(宿主机运行应用 + Docker 存储的混合模式)
- deploy/docker/README.md:三套 Compose 的原始参数、常见调整(换 LLM 厂商、Milvus Lite 降内存、IK 分词等)
- docs/en/API Docs/storage.md:Storage API 文档
- docs/en/API Docs/retrieval.md:Retrieval API 文档
- docs/specs/S02-memory-api.md:MemoryAPI 规约(HTTP 参数名、嵌套结构与默认值和同名
MemoryAPI方法一致)