12.1 · 服务端设置与部署（Server Setup and Deployment）

长期记忆与上下文管理 · 聚焦本章的模块关系、源码依据与实现要点。

项目Mem0 章节12.1 状态全文译文模块安装与启动、模型调用与提供方适配、配置治理、接口与服务契约

项目要点页2.5 参考项目项目章节目录Mem0 DeepWiki 原始章节Server Setup and Deployment 上一章12 下一章12.2

源码线索

docs/open-source/features/rest-api.mdx
examples/graph-db-demo/alice-memories.png
examples/graph-db-demo/memgraph-example.ipynb
server/.env.example
server/Dockerfile
server/Makefile
server/README.md
server/dev.Dockerfile
server/docker-compose.yaml
server/main.py

模块标签

安装与启动
模型调用与提供方适配
配置治理
接口与服务契约
测试、发布与运维

章节正文

服务端设置与部署

原始 DeepWiki 页面https://deepwiki.com/mem0ai/mem0/12.1-server-setup-and-deployment

服务器设置与部署

1. 系统架构

Mem0 服务器基于 FastAPI 后端构建，与持久化存储层（支持 pgvector 的 PostgreSQL）以及各类 AI 提供商进行交互。

数据流与代码实体映射

下图展示了服务器如何处理传入的 REST 请求，并将其转换为记忆操作。

图表：请求流到记忆操作

Mem0 · 数据流与代码实体映射 · 图 1

来源： server/main.py:173-181, server/server_state.py:34-34, server/auth.py:16-16

2. 部署模型

该服务器主要通过 Docker 进行部署，支持开发环境和生产环境配置。

2.1 Docker Compose 设置

标准部署使用 docker-compose.yaml 来编排三个主要服务：

mem0：FastAPI 应用容器。它运行 uvicorn，并通过 alembic upgrade head 处理数据库迁移 server/docker-compose.yaml:4-31。
postgres：一个 PostgreSQL 实例，使用 ankane/pgvector:v0.5.1 镜像进行向量相似性搜索 server/docker-compose.yaml:32-51。
mem0-dashboard：基于 Next.js 的前端，用于可视化记忆管理，通过 NEXT_PUBLIC_API_URL 连接到 API server/docker-compose.yaml:52-70。

2.2 Makefile 命令

提供了一个 Makefile 来简化常见的管理任务：

命令	操作
`make bootstrap`	启动服务栈，等待健康检查通过，并初始化管理员用户和 API 密钥 `server/Makefile:43-43`。
`make up`	检查端口冲突（3000, 8888），然后以分离模式启动容器 `server/Makefile:7-22`。
`make down`	停止并移除容器 `server/Makefile:23-24`。
`make clean`	停止容器并删除所有卷，包括 Postgres 数据 `server/Makefile:26-27`。
`make reset-admin-password`	使用 `reset_admin_password.py` 脚本重置指定用户的密码 `server/Makefile:50-53`。
`make prune-logs`	根据 `REQUEST_LOG_RETENTION_DAYS` 删除旧的请求日志 `server/Makefile:55-56`。

来源： server/Makefile:1-63, server/README.md:5-44, server/docker-compose.yaml:21-21

3. 环境配置

服务器通过环境变量进行配置，这些变量通常存储在 .env 文件中。

3.1 核心配置变量

服务器使用一个 DEFAULT_CONFIG 对象进行初始化，该对象将这些环境变量映射到底层 Memory 类的设置。

变量	描述	默认值
`OPENAI_API_KEY`	用于大语言模型和嵌入向量生成器的主要 API 密钥 `server/main.py:108-108`。	必填
`POSTGRES_HOST`	pgvector 数据库的主机名 `server/main.py:101-101`。	`postgres`
`JWT_SECRET`	用于签署仪表盘会话令牌的密钥。如果启用认证，则为必填项 `server/main.py:83-87`。	必填
`ADMIN_API_KEY`	用于程序化访问的旧版主密钥 `server/main.py:91-98`。	可选
`AUTH_DISABLED`	如果为 `true`，则绕过所有认证（仅限本地开发）`server/main.py:89-90`。	`false`
`MEM0_DEFAULT_LLM_MODEL`	用于事实提取的默认模型 `server/main.py:110-110`。	`gpt-4.1-nano-2025-04-14`
`MEM0_DEFAULT_EMBEDDER_MODEL`	用于生成嵌入向量的默认模型 `server/main.py:111-111`。	`text-embedding-3-small`

来源： server/main.py:101-132, server/.env.example:1-34

4. 服务器启动与状态

服务器生命周期涉及初始化全局状态和配置 FastAPI 应用。

4.1 初始化序列

加载环境：通过 load_dotenv() 加载变量 server/main.py:36-36。
遥测：除非 MEM0_TELEMETRY 设置为 false，否则将当前状态记录到遥测服务 server/main.py:99-99。
初始化状态：调用 server_state.py 中的 initialize_state(DEFAULT_CONFIG) 函数来实例化 Memory 对象 server/main.py:136-136。
数据库连接：set_session_factory(SessionLocal) 连接应用级数据库，用于用户和日志管理 server/main.py:135-135。
中间件：配置 CORS 以允许 DASHBOARD_URL server/main.py:154-160。
路由包含：包含 auth、api_keys、entities 和 requests 的路由器 server/main.py:162-165。

4.2 代码实体交互

此图将初始化函数映射到各自的文件和角色。

图表：服务器初始化实体

Mem0 · 4.2 代码实体交互 · 图 2

来源： server/main.py:135-165, server/server_state.py:34-34

5. 部署验证

5.1 健康检查

服务器通过 make health 命令提供健康检查机制，该命令会验证 API（通过 /docs）、仪表盘（通过 /api/health）和 Postgres 连接（通过 pg_isready）的状态 server/Makefile:45-49。

5.2 生产就绪

对于生产环境部署，需要满足以下要求：

进程管理：使用 uvicorn 配合进程管理器（如 systemd、Supervisor 或 PM2）来保证弹性 docs/open-source/features/rest-api.mdx:117-119。
安全性：确保 AUTH_DISABLED 为 false，并使用 openssl rand -base64 48 生成强 JWT_SECRET server/main.py:83-87。
日志保留：设置一个 cron 任务来执行 make prune-logs，防止 request_logs 表无限增长。created_at 列使用 BRIN 索引以实现高效的范围删除 server/README.md:77-85。
API 路径：请注意，自托管的开源服务器不使用托管平台上的 /v1/ 前缀 docs/open-source/features/rest-api.mdx:20-22。

来源： docs/open-source/features/rest-api.mdx:20-119, server/main.py:83-98, server/README.md:77-85