企业官网建设流程全解析

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

本篇基于 agent-memory（openJiuwen 智能体长期记忆模块）官方文档梳理其部署体系：先厘清「容器化部署」与「SDK 部署」两类运行形态及各自的可选项，再给出按需求选型的对照表，最后深入默认内存栈、HTTP 与MemoryAPI的对齐规则、HTTP 服务安全边界等能力边界，并结合仓库内 Docker Compose 配置与源码实现，给出可直接复制的启动、验证与排障操作。读完本篇，你可以为开发联调、内嵌集成或常驻服务场景选对部署形态，并安全地拉起、验证一套 agent-memory 记忆服务。

1. 部署形态总览

agent-memory 的部署方式可以归为两大类：容器化部署与SDK 部署。整体拓扑如下：

agent-memory ├── 容器化部署 │ ├── 远程嵌入/精排模型 + Redis / Milvus / Elasticsearch │ ├── 本地嵌入/精排模型 + Redis / Milvus / Elasticsearch │ └── 远程嵌入/精排模型 + PostgreSQL / pgvector / Elasticsearch └── SDK 部署（Python 进程运行内核） ├── 存储：进程内内存 / Docker 后端存储 └── 调用：直接调用 MemoryAPI / 启动本地 HTTP 服务

1.1 容器化部署

容器化部署使用 Docker Compose 同时运行 agent-memory HTTP 服务与所需存储后端。应用、连接配置和后端依赖被组织在同一个 Compose profile 中，适合希望快速得到一套完整服务、并尽量减少宿主机 Python 环境差异的场景。

当前仓库在 deploy/docker 下提供三套相互独立的完整 Compose profile：

两个容易误解的点需要注意：

• 文档中的“本地模型”仅指嵌入与精排模型本地运行，当前localprofile 没有内置本地 LLM；
• PostgreSQL 是存储选型，与模型形态是两个正交维度，仓库当前没有提供“本地嵌入/精排 + PostgreSQL”的现成组合 profile。

从 deploy/docker/README.md 的选型表还能看到各角色实现：

召回采用「向量 + 关键词」双通道，图召回关闭。HTTP 以POST /v1/<MemoryAPI method>一一暴露全部公开方法，单个内核实例随进程生命周期常驻、跨请求保持状态。

1.2 SDK 部署

SDK 部署是指由使用方的 Python 进程安装并装配jiuwen_memory内核，可以直接调用MemoryAPI，也可以在该进程内启动仓库提供的本地 HTTP 服务。

当前jiuwen_memory_entry/sdk还没有独立封装的 SDK 客户端或启动器。因此“SDK 部署”是对Python 包直接集成方式的统称，稳定入口是 jiuwen_memory/api/memory_api_impl/assembly.py 中jiuwen_memory.api.assemble()返回的MemoryAPI。

从源码看，assemble()的签名接受policies、kv与config三个可选参数：不传任何参数即落入内置离线配置（见第 4.1 节）；传入配置字典或Config对象后，可在同一 Python 进程内把存储路由到 PostgreSQL/pgvector/Elasticsearch 等真实后端。

SDK 部署有两个独立的选择维度：

2. 选型指南：按需求对号入座

官方给出的选型对照表完整如下：

3. 能力与边界

3.1 默认内存栈

不传配置直接调用assemble()时，系统使用内置离线配置（OFFLINE 栈）：

• CompositeStorage统一承载 Storage 接口；
• KV、Vector、Fulltext、Graph Store 均为进程内实现；
• 嵌入使用 hashing 实现，不依赖外部模型；
• LLM 使用 echo，精排使用 overlap；
• 进程退出后内存数据全部丢失。

这与 jiuwen_memory/config/defaults.py 中的默认配置一致：

"embedder": {_D: {"target": "hashing", "params": {"tokenizer": _D}}}, "llm": {_D: "echo"}, "reranker": {_D: {"target": "overlap", "params": {"tokenizer": _D}}},

该模式适合功能开发和测试，不应当被当作持久化部署。

3.2 HTTP 与 MemoryAPI 一一对齐

本地 HTTP 服务是MemoryAPI上的一层 JSON 适配，公开其全部 36 个方法（命令集直接来自MemoryAPI.__abstractmethods__，见 CLI 设计说明）。规则如下：

• 每个方法使用POST /v1/<method_name>；
• 请求字段名称、嵌套结构、必填项和默认值与同名MemoryAPI方法保持一致；
• 成功响应直接序列化原方法返回值，不增加另一层业务响应或任务语义。

HTTP 边界只做两类必要转换：

1. Scope、Context、MemoryPatch等 Python 对象使用同结构 JSON 对象表达，枚举用字符串值、时间用 ISO 8601 字符串表达；
2. security不接受请求体传入，而是由认证边界根据认证 runtime 的认证结果构造后注入；dev 模式也通过配置装配完整SecurityRuntime，并使用统一BindingPolicy。

同步方法在请求线程内直接调用；异步方法（如add_async、batch_add_async）由 HTTP 入口等待同名异步方法完成后返回原结果，不改造成后台 job。选择 Python 直接调用通常是为了进程内低延迟、静态类型和 Python 对象，而不是为了弥补 HTTP 的常规接口缺口。

四个记忆新增入口（add、add_async、batch_add、batch_add_async）支持请求级system_metadata.coords对象，按字符串键值单独校验；批量逐项不能携带该键。归属判定仍需内核 router、空间及权限配置，且装配期存在一致性校验：assembly.py 中的_reject_routing_without_space_authorization会拒绝“判定表已配置而空间治理未开启”的组合，直接抛出带修复建议的ValidationError。

3.3 当前 HTTP 服务的安全边界

仓库提供的是基于 Python 标准库ThreadingHTTPServer的参考服务，不内置 TLS 或多进程管理。关键边界如下：

• 业务请求必须先建立可信RequestSecurityContext，请求体中的security、actor_*、identity等身份声明会被拒绝；
• 默认required模式下，生产 runtime 未装配时业务接口返回 503，不会降级信任请求体身份；
• 本地功能测试可显式启用dev模式：未配置身份映射时忽略认证头并使用固定local/developerROOT 身份；配置http.dev_identities后，可按 Bearer 或 X-API-Key 测试标识选择服务端预设身份，缺失或未知标识返回 401。两种模式都执行 MemoryAPI 授权，不允许通过请求体伪造身份；
• 仅固定 DEV 且未配 security/permission 时临时注入 allow_all；映射 DEV 保留真实权限判定。具名管理员/ROOT 角色权限及受控委托待 PR2 Authorizer 接管。

绑定地址校验在标准启动入口中强制执行。从 jiuwen_memory_entry/http_server/__main__.py 看，HttpServer.serve()在创建 socket 之前先调用_check_binding(host)：读取认证器的requires_loopback_binding要求，再用 runtime 的binding_policy校验。因此 dev 模式默认只允许回环地址（127.0.0.1、::1、localhost）。注意：仅复用handler_cls()在外部自行构造服务器不会执行该校验，嵌入方必须自行保证绑定策略。DEV 没有环境变量旁路，不能监听0.0.0.0；容器、共享网络或生产部署必须使用required并配置 api_key / trusted 认证器（显式声明可远程暴露），再由前置网关补充 TLS、访问控制和流量保护。

4. 不单独视为部署方案的接入方式

以下形态是接入面而非独立部署选项：

• CLI：提供全部 36 个 API 同名命令，参数名和 JSON 结构与 MemoryAPI 一致。本地模式直接调用 API；使用--server时原样发送 HTTP 请求，不保留旧参数和返回值转换。本地测试须显式--auth-mode dev，远程认证由服务端决定。详见 CLI 设计说明。
• MCP：可通过 stdio 或 streamable HTTP 暴露工具，本质上是协议接入面，其底层部署仍需选择内存或真实存储。
• jiuwen_memory_entry/sdk：当前只有包目录骨架，没有形成独立于jiuwen_memory.api的 SDK 产品层。
• Kubernetes / Helm / systemd：当前仓库没有提供对应的现成部署清单。

5. 容器化部署实操

5.1 前置条件

• Docker + docker compose v2；
• 分配给 Docker 的内存≥ 20 GB（若默认配额偏低请在 Docker Desktop 设置中上调），全栈常驻约占用 13–18 GB；
• 网络可达：拉取镜像、访问云端 LLM 端点；在线模型模式还需能访问EMBEDDER_BASE_URL/RERANKER_BASE_URL；
• postgres模式会拉取 PostgreSQL 16 + pgvector 0.8.3 镜像，首次创建数据卷时自动执行 scripts/pg_schema.sql；
• 本地模型模式需通过 ModelScope 下载 bge 模型（约 4 GB）；
• 无 GPU 时本地模型模式走 CPU 推理，功能可用，但批量写入与高并发场景吞吐受限。

5.2 预下载模型（仅本地模型模式必需）

嵌入/精排使用本地 bge 模型，不在容器启动时联网下载。直连 HuggingFace 在部分网络环境下并不稳定，且下载失败时索引构建会静默降级（捕获嵌入异常后记录日志并继续），导致写入看似成功、召回却为空。建议在宿主机预先下载至deploy/docker/models，再由 compose 挂载到容器/models-local离线加载：

cd deploy/docker/local ./download-models.sh # 等价手动步骤： # pip install modelscope # modelscope download --model BAAI/bge-m3 --local_dir ../models/bge-m3 # modelscope download --model BAAI/bge-reranker-v2-m3 --local_dir ../models/bge-reranker-v2-m3

下载完成后，deploy/docker/models/下应包含bge-m3/与bge-reranker-v2-m3/两个目录；local/.env中的EMBED_MODEL/RERANK_MODEL默认即指向容器内的/models-local/...，无需修改。

5.3 启动三套 profile

在线模型模式（不安装torch/FlagEmbedding/transformers，不挂载本地模型目录）：

cd deploy/docker/online cp .env.example .env # 编辑 .env，至少填入 LLM_API_KEY、MODEL_API_TOKEN、EMBEDDER_BASE_URL、RERANKER_BASE_URL docker compose up -d --build

注意 URL 约定：EMBEDDER_BASE_URL必须包含/v1（如https://models.example.com/v1）；RERANKER_BASE_URL不要包含/rerank。LLM 默认target: dashscope，LLM_ENABLE_THINKING=false会通过 DashScope Adapter 发送extra_body.enable_thinking=false，设为null则完全不发送该厂商字段。

PostgreSQL 模式（保留在线模型 API 与 Elasticsearch，仅把 Redis KV、默认 Vector、L0 Vector、L1 Vector 替换为同一个 PostgreSQL 实例中的四张独立表）：

cd deploy/docker/postgres cp .env.example .env # 编辑 .env，至少填写模型凭据和模型端点；生产环境还应修改数据库密码 docker compose config docker compose up -d --build

该模式启动pgvector/pgvector:0.8.3-pg16，不再启动 Redis、Milvus、etcd 或 MinIO。扩展和四张表由/docker-entrypoint-initdb.d/10-agent-memory.sql在空数据卷首次启动时创建，因此配置固定auto_create_schema: false/create_extension: false；默认 DDL 为publicschema、1024 维、COSINE/HNSW。初始化脚本不会在已有数据卷上重复执行，调整 schema、表名或向量维度时应在首次启动前同步修改.env、config.yml和初始化脚本。

本地模型模式：

cd deploy/docker/local cp .env.example .env # 编辑 .env，至少填入 LLM_API_KEY docker compose up -d --build

首次启动顺序：etcd / MinIO 就绪 → Milvus、Elasticsearch、Redis 健康后应用才启动（depends_on: service_healthy）。bge 模型从挂载的/models-local直接加载、全程不联网；模型在应用首次收到请求时载入内存，该次请求耗时较长，此后常驻复用。

查看状态与日志：

docker compose ps docker compose logs -f agent-memory

5.4 验证服务

默认JIUWEN_MEMORY_HTTP_AUTH_MODE=required，在生产认证 runtime 尚未装配时业务接口返回 503。仅本机功能测试时，把当前 profile 的.env改为：

JIUWEN_MEMORY_HTTP_AUTH_MODE=dev HTTP_BIND_ADDRESS=127.0.0.1

然后执行docker compose up -d --force-recreate agent-memory。未配置身份映射时 dev 固定生成local/developerROOT 身份、忽略认证头但仍执行 MemoryAPI 授权；多用户测试可在挂载配置中加入与memory_api同级的http.dev_identities，用 Bearer 或 X-API-Key 选择预设身份（详见 Config 指南）。两种模式都不得暴露到共享网络或生产环境。

# 健康检查 curl http://localhost:8137/healthz # 写入一条记忆（首次请求会触发模型载入内存，需等待数秒） curl -X POST http://localhost:8137/v1/add \ -H 'Content-Type: application/json' \ -d '{"content":"用户偏好用 Python 写代码","scope":{"org":"local","space":"","user":"developer","agent":"","session":""}}' # 召回 curl -X POST http://localhost:8137/v1/search \ -H 'Content-Type: application/json' \ -d '{"query":"用什么语言","context":{"scope":{"org":"local","space":"","user":"developer","agent":"","session":""},"extensions":{}},"top_k":5}'

其他接口参见 S02 MemoryAPI 规约。

5.5 端口规划

5.6 常见调整

• 换 LLM 厂商：同时修改config.yml的llm.default.target和.env中的LLM_BASE_URL/LLM_MODEL。阿里云用dashscope，通用 OpenAI-compatible 端点用openai；不要只换 URL 而保留其他厂商的专属参数。
• 换在线模型服务：改online/.env的EMBEDDER_BASE_URL/RERANKER_BASE_URL/MODEL_API_TOKEN。
• 降低内存占用：将vector_store改用 Milvus Lite（pymilvus 内嵌、文件存储），在对应模式目录的config.yml中把uri改为本地文件（如./milvus.db），并从 compose 中移除 etcd / minio / milvus 三个服务。Milvus Lite 不适用于生产环境。
• 提升中文关键词检索精度：为 Elasticsearch 安装 IK 分词插件（需自建 ES 镜像）；默认 standard 分析器对中文按单字切分。

5.7 配置文件挂载与分层机制

服务读哪个配置由两处决定：模式目录下的docker-compose.yml把宿主机文件挂到容器/config/config.yml，同目录Dockerfile的CMD把该路径作为参数传给__main__.py——真正决定“用哪个文件”的开关是 compose 里的挂载源：

# online/docker-compose.yml → 服务 agent-memory volumes: - ./config.yml:/config/config.yml:ro # 左 = 宿主机文件，右 = 容器内固定路径

配置是两级命名空间且会合并覆盖内置默认（纯内存离线栈），故配置文件只需写“与默认不同”的部分。新增并启用一个配置文件分三步：

1. 在对应模式目录下新建文件（如online/config.lite.yml），只写要改动的命名空间/参数；
2. 把 compose 的挂载源整体替换过去（无需改 CMD）；
3. 重新创建容器使挂载生效（改 compose 须 recreate，restart不够）：docker compose up -d agent-memory。

进阶的多文件分层：__main__.py接收多个配置路径，依次叠在内置 OFFLINE 之上、靠后覆盖靠前。但注意文件之间是顶层键浅合并——后一个文件的memory_api会整体替换前一个的，不做深合并；「只覆盖内核里某几项」应写在单个文件的memory_api内，分层更适合覆盖profile/policies这类顶层键。

不走 docker 直接本地功能测试可用：scripts/run-server.sh --auth-mode dev <配置路径> [更多路径…]。

5.8 关停与清数据

docker compose down # 停止服务，保留数据卷 docker compose down -v # 停止服务并删除当前 profile 声明的本地数据卷

在postgresprofile 中执行down -v会同时删除 Elasticsearch 与 PostgreSQL 数据卷，包括所有 KV 和向量数据；仅停止服务请使用不带-v的命令。

6. 相关文档

• 容器化部署（英文）
• SDK 部署（英文）
• Storage API 文档
• Retrieval API 文档
• Docker Compose 原始说明
• CLI 与 MemoryAPI 对齐说明

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