企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 记忆
• RAG
• MCP 服务

本文基于 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 文件可以看到三套栈的共同设计：应用容器通过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；
• 宿主机网络需能拉取所需镜像；使用远程模型时，容器还需能访问对应的模型端点；
• 默认端口约定：HTTP8137、Elasticsearch9200；Milvus profile 额外暴露19530/9091；PostgreSQL profile 默认暴露5432。

各 profile 实际拉取的关键镜像版本（可在 Compose 文件中确认）：

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

3. Profile 选型

三套 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 中的关键变量如下：

两条必须特别注意的模型 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全部指向同一个 DSNpostgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}，并固定auto_create_schema: false/create_extension: false——即建表完全交给初始化脚本，应用自身不再建表。

维度与命名一致性约束：初始化脚本只在空数据卷首次启动时执行一次，默认 DDL 使用publicschema、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 collectiondim/ pgvectorvector(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方法一致）

• 人工智能
• AI Agent
• Agent 记忆
• RAG
• MCP 服务