企业官网建设流程全解析

Mem0 自托管 REST 服务器（server/）工程指南：Docker-only 的 FastAPI、pgvector 与热重载开发栈

【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain

本文以 server/AGENTS.md 为核心骨架，系统讲解 Mem0 自托管服务器的定位、命令体系、端口规划与工程约定，并结合 server/Makefile、server/docker-compose.yaml、server/dev.Dockerfile 与 server/main.py 的源码证据，还原"生产镜像构建 + Compose 开发栈热重载"两条路径的完整实现细节。读完后，你可以直接在 Docker 中构建、运行和调试这套 REST 服务，并理解其热重载、密钥管理、默认配置与请求日志的底层机制。

一、定位：Docker-only 的 Python SDK REST 封装

server/目录提供的是一个自托管 FastAPI REST 服务器，其本质是对仓库中 Python SDK（mem0/包）的 HTTP 封装。server/AGENTS.md 开篇即给出两条强约束：

1. Docker only——"Docker only; there is no local non-Docker path"，即不存在绕过 Docker 的本地运行路径，任何"直接用 uvicorn 跑"的方案都不应引入；
2. SDK 约定继承——服务器从仓库导入 Python SDK 代码，因此凡是触及 SDK 代码，都须遵守mem0/AGENTS.md中的约定。

从源码结构看，这种"封装"关系体现在 server/main.py 与 server/server_state.py：所有/memories、/search等端点最终都通过get_memory_instance()调用 SDK 的Memory实例，REST 层只负责鉴权、参数校验、请求日志与错误映射，记忆提取与向量存储逻辑完全复用 SDK。

二、命令体系：两条路径的构建与运行

server/AGENTS.md 给出了四组核心命令，它们在 server/Makefile 中都有对应 target，可直接复制执行：

# 生产镜像 make build # docker build -t mem0-api-server . make run_local # docker run -p 8000:8000 with .env # 开发栈（FastAPI + PostgreSQL/pgvector + Neo4j） docker-compose up

2.1 生产镜像：make build与make run_local

对照 server/Makefile#L58-L62：

build: docker build -t mem0-api-server . run_local: docker run -p 8000:8000 -v $(shell pwd):/app mem0-api-server --env-file .env

生产镜像由 server/Dockerfile 构建，基于python:3.12-slim，以pip install --no-cache-dir -r requirements.txt安装依赖，EXPOSE 8000，入口为uvicorn main:app --host 0.0.0.0 --port 8000。注意run_local通过--env-file .env传入环境变量并挂载当前目录，因此运行前需准备 server/.env.example 描述的.env文件（见第五节）。

2.2 开发栈：docker compose up

开发栈由 server/docker-compose.yaml 定义，定义了三服务：mem0（API）、postgres（pgvector）、mem0-dashboard（Next.js 面板）。make uptarget（server/Makefile#L7-L21）在启动前还会做三件事：

• 用lsof检查 3000/8888 端口是否已被占用，占用则报错退出并提示排查命令；
• docker compose up -d --build构建并启动；
• 轮询等待就绪：wait-api轮询$(API_URL)/auth/setup-status，wait-dashboard轮询$(DASHBOARD_URL)/api/health。

此外 Makefile 还提供日常运维 target：down（停止栈）、clean（docker compose down -v连卷删除）、logs（docker compose logs -f）、health（分别探测 API/docs、Dashboard/api/health与pg_isready）、bootstrap（up + 双等待 + seed 一步到位）、seed（调用 server/scripts/seed.sh 创建首个 admin 与 API key，支持EMAIL/PASSWORD/NAME/OUTPUT=json变量覆盖）。

2.3 端口规划

server/AGENTS.md 给出的开发栈端口约定如下：

其中 API 与 Postgres 端口可直接在 server/docker-compose.yaml 中验证：mem0服务映射8888:8000，postgres服务映射8432:5432。关于 Neo4j：文档将其列为开发栈存储组件（5.x + APOC 插件）之一，而从当前 server/docker-compose.yaml 结构看，compose 文件仅定义了mem0、postgres、mem0-dashboard三个服务，未内置 Neo4j；结合 server/dev.Dockerfile 中pip install -e .[graph]安装了 SDK 的 graph 扩展这一事实，可以推断 Neo4j 属于图记忆场景下的可选配套组件，端口表是其接入时的约定值。

三、开发栈内部实现：热重载是如何生效的

"Hot reload: the dev Dockerfile mounts bothserver/andmem0/" 是 server/AGENTS.md 的关键约定，其实现链条由三个文件共同完成：

1. server/dev.Dockerfile：基于python:3.12，安装 Poetry 与server/requirements.txt依赖，随后把仓库根目录的pyproject.toml、poetry.lock、mem0/拷贝进容器并执行pip install -e .[graph]，即以可编辑模式安装 SDK；最后拷贝server/代码，CMD为uvicorn main:app --host 0.0.0.0 --port 8000 --reload。
2. server/docker-compose.yaml#L14-L21：mem0服务以.（即server/目录）为构建上下文、server/dev.Dockerfile为 Dockerfile，并把.:/app卷挂载进容器。由于 SDK 是可编辑安装且源码目录被挂载，修改server/或mem0/下任何 Python 文件后，uvicorn --reload会自动重载进程——SDK 改动无需重新构建镜像。
3. 启动命令（server/docker-compose.yaml#L20-L21）：

rm -rf /app/packages && pip install -q --force-reinstall --no-deps mem0ai \ && alembic upgrade head \ && uvicorn main:app --host 0.0.0.0 --port 8000 --reload

即：每次容器启动先强制重装可编辑安装的mem0ai包（保证包元数据与挂载源码一致），再执行 Alembic 数据库迁移（迁移脚本见 server/alembic/versions），最后以 reload 模式启动 uvicorn。配套的PYTHONDONTWRITEBYTECODE=1与PYTHONUNBUFFERED=1避免字节码缓存干扰热重载、保证日志实时输出；./history目录挂载到/app/history用于持久化记忆变更历史。

Postgres 侧（server/docker-compose.yaml#L32-L50）使用官方pgvector/pgvector:pg17镜像（PostgreSQL 17 + pgvector 0.8.0），shm_size128MB，数据落在postgres_db卷；server/init-db.sh 挂载到/docker-entrypoint-initdb.d/，在容器初始化时创建mem0_app数据库（存放用户/认证/API key 等应用数据），而默认的postgres库由 pgvector 承载记忆向量。Dashboard 服务从 server/dashboard 目录构建，监听 3000 端口，通过API_INTERNAL_URL=http://mem0:8000在容器网络内直连 API。

四、工程约定（Conventions）

server/AGENTS.md 的 Conventions 一节逐条列出了必须遵守的工程边界，结合仓库实现可以进一步理解其理由：

• 框架：FastAPI 跑在 uvicorn 上，开发环境开启 auto-reload。入口即 server/main.py 中的FastAPI(title="Mem0 REST APIs", ...)实例，OpenAPI 文档暴露在/docs。
• 存储：PostgreSQL + pgvector 扩展，Neo4j 5.x + APOC 插件。
• 热重载：如上节所述，dev Dockerfile 同时挂载server/与mem0/，SDK 编辑即时生效。
• 只用 Docker Compose 做本地开发，明确"不要添加直接用 uvicorn 运行的路径"。这与 AGENTS.md 首句"Docker only"呼应，保证所有开发者与 CI 使用同一运行路径。
• SDK 约定继承：服务器导入仓库内的 Python SDK，触及 SDK 代码时须遵循mem0/AGENTS.md。

五、密钥与配置边界：.env 纪律

server/AGENTS.md 结尾给出硬性规则：永不提交.env；compose 服务的凭据只能以占位符形式存在于.env.example。仓库中的 server/.env.example 正是这一规则的直接产物，其完整变量如下：

两条关键约束在代码中可验证：

• POSTGRES_PASSWORD强制必填：server/docker-compose.yaml#L40 使用${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}语法——变量为空时 Compose 直接报错退出，不存在回退默认密码；
• JWT_SECRET启动期校验：server/main.py#L90-L94 中，若AUTH_DISABLED未开启而JWT_SECRET缺失，进程直接抛出RuntimeError；若设置了ADMIN_API_KEY但长度小于 16 字符，会打印警告（server/main.py#L48 定义MIN_KEY_LENGTH = 16）。

六、服务器运行时行为：默认配置、内置提供商与请求日志

理解服务器"默认长什么样"，可以深入 server/main.py：

• 默认配置：server/main.py#L120-L139 的DEFAULT_CONFIG声明向量存储为pgvector（连接参数全部来自POSTGRES_*环境变量），LLM 与 embedder 默认openai提供商，模型分别为MEM0_DEFAULT_LLM_MODEL（默认gpt-5-mini）与MEM0_DEFAULT_EMBEDDER_MODEL（默认text-embedding-3-small）。
• 内置提供商白名单：server/main.py#L62-L63 定义BUNDLED_LLM_PROVIDERS = ("openai", "anthropic", "gemini")与BUNDLED_EMBEDDER_PROVIDERS = ("openai", "gemini")。POST /configure会经_validate_bundled_providers校验（server/main.py#L232-L259）：非内置提供商返回 400，提示需自行安装包、重建容器并扩展白名单——这解释了为何 Dockerfile 要预装依赖，也解释了.env.example中为何只列出三个提供商的密钥。
• 配置脱敏：GET /configure返回前会经_redact_config递归处理，命中SENSITIVE_CONFIG_KEYS（如api_key、jwt_secret、password、token等，server/main.py#L49-L58）的值一律替换为[redacted]。
• 请求日志：中间件log_requests（server/main.py#L292-L319）为每个请求生成 request id、计时，并异步把 method、path、状态码、延迟、认证方式写入request_logs表；/api/health、/docs、/redoc、/openapi.json与/requests前缀路径被跳过（server/main.py#L59-L60）。由于该表只增不减，server/README.md 建议生产环境把make prune-logs接入 cron/systemd 定期清理，REQUEST_LOG_RETENTION_DAYS控制保留窗口。
• CORS 收紧：CORSMiddleware 的allow_origins只允许DASHBOARD_URL（server/main.py#L160-L167），即只有本机 Dashboard 可跨域调用 API。

七、小结

围绕 server/AGENTS.md 的三条主线——命令（make build/make run_local/docker compose up）、端口（8888/8432/8474/8687）、约定（Docker only、热重载、SDK 约定继承、.env纪律）——在当前仓库中全部有可验证的落地实现：Makefile target 与 Compose 服务一一对应，dev Dockerfile 的可编辑安装加卷挂载实现了"SDK 改动免重建"，POSTGRES_PASSWORD强制校验与启动期JWT_SECRET检查保证了安全默认值。对需要自托管 Mem0 或在此基础上二次开发的读者，按第五节准备好.env，用make up拉起开发栈、通过/docs验证接口，是进入该服务器内部世界最短的路径；更多运维细节（首次引导make bootstrap、密码重置、请求日志清理、pgvector 镜像迁移）可参阅 server/README.md。

【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain