mem9 自托管部署完全教程:mnemo-server + TiDB 从零到生产环境的 6 个步骤(附 Docker 与全量环境变量说明)

原创2026-10-13 22:58:541,663 阅读
文章标签:人工智能Agent 记忆AI 插件dsh-plugin后端前端CLI文档

mem9 自托管部署完全教程:mnemo-server + TiDB 从零到生产环境的 6 个步骤(附 Docker 与全量环境变量说明)

mem9 是一个为 AI Agent 提供持久化记忆的开源项目,本教程带你从零开始自托管部署 mem9 的记忆服务端 mnemo-server:连接 TiDB 作为存储后端,完成 schema 初始化、构建、Docker 打包、环境变量配置与生产上线验证,全程附完整命令。

mem9 自托管部署:mnemo-server 服务端架构示意图

一、先搞懂:mem9 自托管架构长什么样?

在动手之前,花 1 分钟理解架构,能帮你少走 90% 的弯路。

mem9 的核心思想是:Agent 插件保持轻量无状态,所有存储、检索、写入、策略逻辑都收敛到 mnemo-server 这一层。OpenClaw、Claude Code、OpenCode、Codex 等运行时统一通过 REST API 访问同一个记忆服务(架构设计详见 docs/DESIGN.md)。

自托管时涉及 两层数据库,这是新手最容易混淆的点:

层 作用 对应配置
控制面(Control Plane) 存放租户(tenant)注册信息、Space Chain、webhook 等 MNEMO_DSN 指向的数据库
租户库(Tenant DB) 每个 Space 独立的记忆数据 + 向量列 + 全文索引 由租户库连接串记录在控制面里

也就是说:MNEMO_DSN 不是"记忆库"本身,而是"管租户的库"。服务端的完整请求链路为 handler → service → repository,源码组织见 server/AGENTS.md。

TiDB:mem9 自托管的默认存储后端

mnemo-server 支持三种存储后端,通过 MNEMO_DB_BACKEND 切换,其中 tidb 是默认值且功能最全(支持服务端自动 embedding、原生向量检索、全文检索):

  • tidb:默认,推荐生产使用
  • postgres:走高级手动 bootstrap 路径
  • db9:类 TiDB 的兼容后端

二、环境准备:3 样东西缺一不可

开始部署前,确认你手上有:

  1. Go 1.24+(构建用,依赖清单见 server/go.mod)与 make
  2. 一个 TiDB 兼容数据库:可以是 TiDB Serverless 实例、TiDB Cloud Starter,或自建 TiDB。DSN 格式为 MySQL 风格连接串
  3. Docker(可选,用于容器化部署)

💡 如果你只想先体验而不折腾基础设施,可以先用托管 API,自托管时只需把 MEM9_API_URL 换成自己的服务地址,插件代码不用改一行。

三、一键构建与首次启动

步骤 1:获取代码并构建

git clone https://gitcode.com/gh_mirrors/me/mem9
cd mem9
make build   # 产出 server/bin/mnemo-server(静态二进制,CGO_ENABLED=0)

make build 的目标定义在 Makefile,它会以 GOOS/GOARCH 无关的方式产出可执行文件。

步骤 2:初始化控制面 schema

首次启动前必须在 MNEMO_DSN 指向的数据库中执行控制面建表脚本(不同后端对应不同文件):

mysql -h <host> -P 4000 -u <user> -p < server/schema.sql

该脚本会创建 tenants、tenant_activity、space_chains 等表,是整个自托管的地基。

步骤 3:启动 mnemo-server

最小运行配置只需要一个变量 MNEMO_DSN:

cd server
MNEMO_DSN="user:pass@tcp(host:4000)/mnemos?parseTime=true" ./bin/mnemo-server

服务默认监听 8080 端口。启动后日志为 JSON 格式,会依次打印 database connected、embedding 配置状态、starting mnemo server 等信息,配置解析逻辑见 server/internal/config/config.go,入口逻辑见 server/cmd/mnemo-server/main.go。

本地开发可以用热重载模式:

MNEMO_DSN="user:pass@tcp(host:4000)/mnemos?parseTime=true" make dev

步骤 4:验证服务

服务内置健康检查端点:

curl http://localhost:8080/healthz

更完整的端到端验证可以直接跑仓库自带的冒烟测试脚本(覆盖租户创建、写入、检索、更新、删除全流程):

MNEMO_BASE=http://localhost:8080 bash e2e/api-smoke-test.sh

脚本说明见 e2e/api-smoke-test.sh。全部 PASS 即代表 mnemo-server + TiDB 链路完全打通。

四、Docker 部署:两条命令完成容器化

mem9 的 Docker 流程是"先编译、后打包":make docker 会先执行 build-linux 交叉编译出 Linux amd64 二进制,再把它 COPY 进一个极简的 alpine:3.19 镜像(只加 ca-certificates),最终镜像体积非常小。镜像定义见 server/Dockerfile。

# 构建并打上 local/mnemo-server:dev 标签
make docker REGISTRY=local COMMIT=dev

# 运行
docker run -d \
  -e MNEMO_DSN="user:pass@tcp(host:4000)/mnemos?parseTime=true" \
  -e MNEMO_DB_BACKEND="tidb" \
  -p 8080:8080 \
  local/mnemo-server:dev

生产建议:用 ${REGISTRY}/mnemo-server:${COMMIT} 的命名方式按 commit 打标签,方便灰度和回滚。

五、全量环境变量说明(分类速查表)

所有配置均通过环境变量注入,唯一必填项是 MNEMO_DSN,其余按需开启。以下按用途分类整理(完整默认值以 server/internal/config/config.go 为准)。

5.1 核心服务

变量 必填 默认值 说明
MNEMO_DSN ✅ — 控制面数据库连接串
MNEMO_PORT ❌ 8080 HTTP 监听端口
MNEMO_DB_BACKEND ❌ tidb 存储后端:tidb / postgres / db9
MNEMO_ENV ❌ development 环境标识,影响默认 CORS 白名单;生产设为 production
MNEMO_CORS_ALLOWED_ORIGINS ❌ 按环境 逗号分隔的 CORS 来源,覆盖 MNEMO_ENV 默认值
MNEMO_RATE_LIMIT ❌ 100 每 IP 每秒请求数
MNEMO_RATE_BURST ❌ 200 限流突发容量
MNEMO_UPLOAD_DIR ❌ ./uploads 上传文件存储目录
MNEMO_WORKER_CONCURRENCY ❌ 5 异步上传导入的并行 worker 数
MNEMO_UTM_ENABLED ❌ false 启用 UTM 归因记录(需 tenant_utm 表存在)

5.2 Embedding 与智能导入(Ingest)

这一组决定"混合检索"是否可用。什么都不配也不会报错——服务会降级为纯关键词检索。

变量 必填 默认值 说明
MNEMO_EMBED_AUTO_MODEL ❌ — TiDB/db9 服务端 EMBED_TEXT() 模型(如 tidbcloud_free/cohere/embed-multilingual-v3),设置后优先于客户端 embedding
MNEMO_EMBED_AUTO_DIMS ❌ 1024 服务端向量维度;Cohere Embed v3 模型强制要求 1024
MNEMO_EMBED_API_KEY ❌ — 客户端 embedding 提供方 API Key
MNEMO_EMBED_BASE_URL ❌ OpenAI 地址 自定义 OpenAI 兼容 embedding 端点(可指向本地模型)
MNEMO_EMBED_MODEL ❌ text-embedding-3-small 客户端 embedding 模型名
MNEMO_EMBED_DIMS ❌ 1536 客户端向量维度
MNEMO_LLM_API_KEY ❌ — LLM Key;不设置则 smart ingest 退化为 raw 导入
MNEMO_LLM_BASE_URL ❌ OpenAI 地址 自定义 OpenAI 兼容 chat 端点
MNEMO_LLM_MODEL ❌ gpt-4o-mini 智能导入使用的 LLM
MNEMO_LLM_TEMPERATURE ❌ 0.1 LLM 温度
MNEMO_INGEST_MODE ❌ smart 导入模式:smart(LLM 抽取事实)或 raw
MNEMO_FTS_ENABLED ❌ false TiDB 全文检索开关,仅在集群支持 FTS 时开启

5.3 租户供给与连接池(Provisioning)

mnemo-server 对 TiDB 后端支持三种租户供给方式,这是自托管时最核心的运营决策:

方式 触发条件 特点
TiDB Zero 自动供给 默认开启(MNEMO_TIDB_ZERO_ENABLED=true + tidb 后端) 新 Space 自动创建独立租户库,零运维
TiDB Cloud Pool MNEMO_TIDB_ZERO_ENABLED=false 且配置了 MNEMO_TIDBCLOUD_API_KEY / MNEMO_TIDBCLOUD_API_SECRET 从 Serverless 资源池接管集群,适合团队级部署
手动 Bootstrap 不配置任何供给器 使用控制面中已存在的租户记录,postgres/db9 后端必须走这条路
变量 必填 默认值 说明
MNEMO_TIDB_ZERO_ENABLED ❌ true 开启 TiDB Zero 自动供给(优先级最高)
MNEMO_TIDB_ZERO_API_URL ❌ TiDB Zero 地址 自定义 Zero API 入口
MNEMO_TIDBCLOUD_API_URL ❌ Serverless 地址 自定义 Cloud Pool API 入口
MNEMO_TIDBCLOUD_POOL_ID ❌ 2 Cloud Pool 资源池 ID
MNEMO_TIDBCLOUD_API_KEY / MNEMO_TIDBCLOUD_API_SECRET ❌ — Cloud Pool 凭据(digest 认证)
MNEMO_TENANT_POOL_MAX_IDLE ❌ 5 进程内租户库空闲连接上限
MNEMO_TENANT_POOL_MAX_OPEN ❌ 10 单租户库最大打开连接数
MNEMO_TENANT_POOL_CONNECT_TIMEOUT ❌ 3s 冷连接 ping/打开超时
MNEMO_TENANT_POOL_IDLE_TIMEOUT ❌ 10m 租户库句柄空闲回收时间
MNEMO_TENANT_POOL_TOTAL_LIMIT ❌ 200 全进程租户库句柄总量上限

5.4 安全加密(⚠️ 一次性决策)

变量 必填 默认值 说明
MNEMO_ENCRYPT_TYPE ❌ plain 租户库密码加密方式:plain / md5 / kms
MNEMO_ENCRYPT_KEY ❌ — md5 模式的密钥,或 kms 模式的 KMS Key ID

⚠️ 重要警告:MNEMO_ENCRYPT_TYPE 是一次性部署决策。租户创建后再切换加密方式,会导致所有存量租户请求返回 HTTP 500(旧密码无法用新方案解密)。生产环境建议第一天就选好,KMS 模式需要额外配置 AWS 凭据(AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGION)。

5.5 计费与用量(按需)

  • Metering(API 用量上报):MNEMO_METERING_ENABLED=true + MNEMO_METERING_URL(支持 s3://、http(s)://),刷新间隔 MNEMO_METERING_FLUSH_INTERVAL(默认 10s)
  • Runtime Usage(配额管控):MNEMO_RUNTIME_USAGE_ENABLED=true 时,必须同时提供 MNEMO_RUNTIME_USAGE_BASE_URL 与 MNEMO_RUNTIME_USAGE_INTERNAL_SECRET,否则服务拒绝启动

以上默认全部关闭,纯自托管场景可以先不配置。

六、生产环境部署清单 ✅

检查项 操作
环境标识 设置 MNEMO_ENV=production,CORS 默认收紧为 https://mem9.ai,需自定义时用 MNEMO_CORS_ALLOWED_ORIGINS
加密方式 上线前确定 MNEMO_ENCRYPT_TYPE,之后不再变更
供给方式 明确选择 Zero / Cloud Pool / 手动 Bootstrap 三者之一
限流 按业务调整 MNEMO_RATE_LIMIT / MNEMO_RATE_BURST
向量能力 确认 embedding 方案(服务端 MNEMO_EMBED_AUTO_MODEL 或客户端 MNEMO_EMBED_*)已生效,否则只有关键词检索
优雅停机 内置 SIGTERM 处理(先停 worker、webhook,再关 HTTP),可直接对接容器编排
健康检查 将 GET /healthz 接入你的监控与负载均衡
端到端验证 上线后跑 MNEMO_BASE=<你的域名> bash e2e/api-smoke-test.sh 全量回归

服务启动后,客户端插件只需两个环境变量即可接入你的私有记忆服务:

export MEM9_API_URL="http://你的服务器:8080"
export MEM9_API_KEY="<provisioning 流程返回的 mem9 API key>"

七、常见问题 FAQ

Q1:忘了配置 embedding,服务会挂吗? 不会。日志会打印 no embedding configured, keyword-only search active,检索自动降级为关键词模式,后续补配置即可。

Q2:MNEMO_DSN 和租户库是什么关系? MNEMO_DSN 只连控制面(存租户注册表)。每个 Space 的实际记忆数据存在各自独立的租户库中,由供给器自动创建或手动写入。

Q3:postgres 后端能用 TiDB Zero 自动供给吗? 不能。TiDB Zero 供给仅支持 tidb 后端,postgres/db9 必须使用手动 Bootstrap 路径(控制面中需已存在 active 租户记录)。

Q4:如何验证部署是"对的"? 以 e2e/api-smoke-test.sh 全绿为准——它覆盖了健康检查、租户创建、消息导入、内容导入、按 query/tag 检索、按 ID 读写删等 12 项检查。

写在最后

mem9 的自托管比想象中简单:schema 初始化 → make build → 一个 MNEMO_DSN 环境变量 → 启动,核心路径不到 5 分钟。真正的复杂度在运营层——供给方式、embedding 方案、加密策略的一次性选择。按上面的清单逐项确认,你就能把 mnemo-server 稳定地跑在生产环境,给整个 Agent 团队提供"永不失忆"的共享记忆。

📚 延伸阅读:

登录后查看全文
mem9