05-Mem0 的自托管 Server 架构

Mem0 的自托管 Server 架构

学习目标

本章分析 Mem0 自托管 Server 如何组织 FastAPI 应用、管理 Docker Compose 三服务栈、处理认证与数据库迁移。你将了解：

• FastAPI 路由组织与中间件
• Docker Compose 三服务依赖（API + PostgreSQL + Neo4j）
• Alembic 数据库迁移
• 认证初始化与 Makefile 一键启动

项目实践

三服务架构

服务	端口	用途
FastAPI API	8888	记忆 CRUD API
PostgreSQL	8432	关系数据 + 向量存储（pgvector）
Neo4j	8474 HTTP / 8687 Bolt	图谱存储（实体关系）

FastAPI 应用结构

server/
├── main.py              # FastAPI 应用入口
├── models.py            # SQLAlchemy 数据模型
├── schemas.py           # Pydantic 请求/响应模型
├── db.py                # 数据库连接
├── auth.py              # 认证中间件
├── rate_limit.py        # 速率限制
├── routers/             # 路由模块
│   ├── memories.py      # 记忆 CRUD
│   └── ...
├── alembic/             # 数据库迁移
├── docker-compose.yaml  # 三服务定义
├── Dockerfile           # 生产镜像
└── Makefile             # 开发命令

一键启动

# 开发环境
cd server && docker compose up -d

# 生产环境（含管理员初始化）
cd server && make bootstrap

make bootstrap 执行：

1. 启动 Docker Compose 三服务
2. 打开浏览器完成初始设置向导
3. 创建管理员账号并发放第一个 API Key

认证机制

自托管 Server 默认启用认证：

• 初始设置向导创建管理员
• 管理员通过 API 发放用户 API Key
• 请求通过 Authorization: Bearer <api_key> 认证
• 开发环境可设置 AUTH_DISABLED=true 跳过认证

Alembic 数据库迁移

server/alembic/
├── env.py           # Alembic 配置
├── script.py.mako   # 迁移模板
└── versions/        # 迁移脚本
    └── <revision>_<description>.py

迁移脚本定义升级/降级操作：

def upgrade():
    op.create_table("memories", ...)

def downgrade():
    op.drop_table("memories")

速率限制

rate_limit.py 实现简单的速率限制中间件，防止 API 被滥用。具体策略可在 server/ 配置中调整。

问题与规避

问题	对策
Docker 端口冲突	docker-compose.yaml 中可自定义端口映射
认证初始化失败	make bootstrap 自动完成；手动可 AUTH_DISABLED=true
Neo4j 连接失败	Docker Compose 确保 Neo4j 先于 API 启动
Alembic 迁移冲突	按版本号顺序执行迁移，不跳过

设计取舍

为什么用 PostgreSQL + pgvector 而非独立向量数据库？

优势：

• 单数据库管理关系数据和向量数据
• 不需要额外的 Qdrant/Pinecone 部署
• 事务一致性：关系操作和向量操作在同一事务中

代价：

• pgvector 的向量检索性能不如专用向量数据库
• 大规模数据时索引构建慢

为什么 Neo4j 是可选的？

Neo4j 用于实体关系存储，不是核心功能。Mem0 的默认向量存储（Qdrant）已经可以管理实体链接。Neo4j 只在需要复杂图谱查询时才需要。

参考来源

• Mem0 源码：server/ 目录
• FastAPI 文档：https://fastapi.tiangolo.com/
• pgvector 文档：https://github.com/pgvector/pgvector