部署Mem0项目流程详细记录1. 规划服务器2. 更新 Ubuntu 基础环境3. 安装 Docker Engine 与 Docker Compose4. 下载 Mem0 源码5. 创建并保护配置文件6. 第一次启动先在服务器本机验证7. 最小功能测试8. 访问方式选择其一方案 A只在服务器本机或内网使用方案 B正式公网部署推荐9. 日常运维命令10. 备份与日志清理11、相关自定义配置Docker 网络注意事项项目地址https://github.com/mem0ai/mem0可以。下面是一套适合 Ubuntu 22.04/24.04 小白的部署路线先在服务器上跑通再按是否公网访问做安全收口。先说明一个关键点仓库当前的server/docker-compose.yaml是开发型配置含热重载、源码挂载并把 PostgreSQL 映射到宿主机8432。它适合先跑通和内网测试若要公开给互联网使用应在第二阶段改为仅反向代理暴露 HTTPS绝不公开 PostgreSQL。官方自托管组件包括Dashboard3000API8888PostgreSQL pgvector容器内5432当前开发配置映射到宿主机8432Neo4j 不在当前 Compose 配置中Mem0 的 API 默认需要认证不要在公网环境设置AUTH_DISABLEDtrue。1. 规划服务器建议起步配置Ubuntu 22.04 或 24.04 LTS2 核 CPU、4 GB 内存、40 GB 磁盘起步一个普通 Linux 用户并具备sudo权限若要公网访问域名例如mem0.example.com和api.mem0.example.com一个 LLM/Embedding 服务的 API Key。默认配置使用 OpenAI 的gpt-5-mini与text-embedding-3-small部署目录建议使用/opt/mem0/mem0不要把密钥写进 Git、截图、聊天记录或提交.env文件。2. 更新 Ubuntu 基础环境通过 SSH 登录服务器后执行sudoaptupdatesudoaptupgrade-ysudoaptinstall-yca-certificatescurlgitmakeopenssl若系统提示内核已更新执行sudoreboot重连服务器后继续。3. 安装 Docker Engine 与 Docker Compose使用 Docker 官方 APT 仓库sudoinstall-m0755-d/etc/apt/keyringssudocurl-fsSLhttps://download.docker.com/linux/ubuntu/gpg-o/etc/apt/keyrings/docker.ascsudochmodar /etc/apt/keyrings/docker.ascsudotee/etc/apt/sources.list.d/docker.sources/dev/nullEOF Types: deb URIs: https://download.docker.com/linux/ubuntu Suites:$(./etc/os-releaseecho${UBUNTU_CODENAME:-$VERSION_CODENAME})Components: stable Architectures:$(dpkg --print-architecture)Signed-By: /etc/apt/keyrings/docker.asc EOFsudoaptupdatesudoaptinstall-ydocker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin验证 Dockersudodockerrun hello-worlddockercompose version可选让当前用户不用每次输入sudosudousermod-aGdocker$USERnewgrpdockerdockerrun hello-world注意加入docker组等同于获得较高系统权限只应给可信账号。Docker 官方安装与权限说明见 Docker Ubuntu 安装文档 和 Linux post-install 文档。4. 下载 Mem0 源码sudomkdir-p/opt/mem0sudochown-R$USER:$USER/opt/mem0gitclone https://github.com/mem0ai/mem0.git /opt/mem0/mem0cd/opt/mem0/mem0/server确认当前位置pwdgitrev-parse--shortHEAD应位于/opt/mem0/mem0/server5. 创建并保护配置文件创建.envumask077cp.env.example .envchmod600.envnano.env该项目默认支持的文本生成模型与嵌入模型是OpneAI官方的模型如下所示至少填写以下项目OPENAI_API_KEY你的模型服务密钥 POSTGRES_HOSTpostgres POSTGRES_PORT5432 POSTGRES_DBpostgres POSTGRES_USERpostgres POSTGRES_PASSWORD请填一个强随机密码 POSTGRES_COLLECTION_NAMEmemories JWT_SECRET请填一个强随机密钥 ADMIN_API_KEY AUTH_DISABLEDfalse MEM0_DEFAULT_LLM_MODELgpt-5-mini MEM0_DEFAULT_EMBEDDER_MODELtext-embedding-3-small MEM0_TELEMETRYfalse REQUEST_LOG_RETENTION_DAYS30在另一个终端生成两个随机值复制到.envopenssl rand-hex32openssl rand-hex48分别用作POSTGRES_PASSWORDJWT_SECRETADMIN_API_KEY可以先留空首次通过 Dashboard 向导创建管理员后为实际应用生成独立 API Key。不要把 API Key 硬编码到业务代码使用环境变量或密钥管理服务。6. 第一次启动先在服务器本机验证仍在/opt/mem0/mem0/server目录dockercompose up-d--build首次构建要下载 Python、Node、PostgreSQL 镜像可能需要数分钟。查看状态dockercomposeps查看日志dockercompose logs-fmem0另开一个终端验证 APIcurlhttp://127.0.0.1:8888/auth/setup-status健康检查curl-Ihttp://127.0.0.1:8888/docscurl-Ihttp://127.0.0.1:3000/api/health在服务器有图形界面时可打开http://服务器IP:3000首次访问会进入初始化向导创建管理员账号检查当前模型与嵌入模型配置创建第一把m0sk_...API Key立刻保存 API Key——完整值只显示一次完成向导。API 文档地址http://服务器IP:8888/docs自托管 API 没有/v1前缀例如实际写入接口是POST /memories。7. 最小功能测试在 Dashboard 创建 API Key 后在服务器执行curl-XPOST http://127.0.0.1:8888/memories\-HContent-Type: application/json\-HX-API-Key: m0sk_替换为你的密钥\-d{ messages: [{role: user, content: 我喜欢喝咖啡。}], user_id: test-user }再查询curlhttp://127.0.0.1:8888/memories?user_idtest-user\-HX-API-Key: m0sk_替换为你的密钥如果写入失败且日志出现502 Upstream provider error优先检查.env中的OPENAI_API_KEY、模型名称及服务器是否能访问对应模型服务。8. 访问方式选择其一方案 A只在服务器本机或内网使用适合测试、家庭/公司内网。需要把 Compose 文件中的地址改为服务器实际 IP避免浏览器错误地访问自己电脑的localhost。在server/docker-compose.yaml中将-DASHBOARD_URLhttp://localhost:3000改为-DASHBOARD_URL${DASHBOARD_URL}将-NEXT_PUBLIC_API_URLhttp://localhost:8888改为-NEXT_PUBLIC_API_URL${NEXT_PUBLIC_API_URL}然后在.env增加例如服务器内网 IP 是192.168.1.50DASHBOARD_URLhttp://192.168.1.50:3000 NEXT_PUBLIC_API_URLhttp://192.168.1.50:8888重新创建容器dockercompose up-d--build--force-recreate此时从内网电脑访问http://192.168.1.50:3000方案 B正式公网部署推荐建议使用两个子域名https://mem0.example.com Dashboard https://api.mem0.example.com API架构如下浏览器 / 业务系统 │ HTTPS :443 ▼ Nginx ├── mem0.example.com → 127.0.0.1:3000 └── api.mem0.example.com → 127.0.0.1:8888 │ ▼ Docker 内部 PostgreSQL正式部署必须做到只开放22、80、443API 与 Dashboard 仅绑定到127.0.0.1PostgreSQL 不映射宿主机端口AUTH_DISABLEDfalse使用 HTTPS.env权限保持600通过 Nginx 统一暴露公网服务。这一步需要将当前开发 Compose 改成生产 Compose去除源码挂载和--reload限制端口绑定并配置域名环境变量。因为仓库当前提供的是开发 Compose我建议不要直接把它的默认端口暴露到公网。公网环境的.env应是DASHBOARD_URLhttps://mem0.example.com NEXT_PUBLIC_API_URLhttps://api.mem0.example.com AUTH_DISABLEDfalseNginx 反向代理配置示例server { listen 80; server_name mem0.example.com; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }server { listen 80; server_name api.mem0.example.com; location / { proxy_pass http://127.0.0.1:8888; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }配置域名 DNS 解析到服务器公网 IP 后可用 Certbot 申请证书。注意 Docker 映射端口可能绕开 UFW 普通规则因此更安全的措施是从 Compose 层面把 API 和 Dashboard绑定到127.0.0.1数据库不发布到宿主机Docker 官方对此有明确提醒。Docker 防火墙限制说明9. 日常运维命令进入目录cd/opt/mem0/mem0/server查看容器dockercomposeps查看全部日志dockercompose logs-f只看 API 日志dockercompose logs-fmem0停止服务但保留数据dockercompose down启动服务dockercompose up-d更新代码并重建gitpulldockercompose up-d--build不要随便执行下面这个命令dockercompose down-v它会删除 PostgreSQL 数据卷即用户、API Key、配置和 memories。10. 备份与日志清理备份 PostgreSQLcd/opt/mem0/mem0/serverdockercomposeexec-Tpostgres pg_dumpall-Upostgresmem0-backup-$(date%F).sql确认备份不是空文件ls-lhmem0-backup-*.sql恢复时必须先停 API只启动 PostgreSQL再导入备份否则迁移表可能冲突。请求审计日志会不断增长。项目内置清理命令makeprune-logsREQUEST_LOG_RETENTION_DAYS30可用 cron 每天凌晨执行crontab-e加入0 3 * * * cd /opt/mem0/mem0/server /usr/bin/make prune-logs REQUEST_LOG_RETENTION_DAYS30 /var/log/mem0-prune.log 21建议同时把数据库备份复制到另一台机器或对象存储只放在同一台服务器不算真正的容灾。如果你告诉我部署目标是“仅本机/内网”还是“公网域名访问”以及是否已有域名我可以下一步直接给你一套可复制的生产版 Compose、Nginx 和 HTTPS 配置。11、相关自定义配置该项目默认支持的文本生成模型与嵌入模型是OpneAI官方的模型如果想配置成本地启动的自定义文本生成模型与嵌入模型需要进行如下修改结论先说文本模型Qwen3.5-27B-FP8服务地址应为http://可访问主机:9026/v1嵌入模型bge-m3-local服务地址应为http://可访问主机:9027/v1BGE-M3 稠密向量维度1024pgvector collection 的维度也必须是1024目前代码不能完整满足“文本模型、嵌入模型、向量维度各自独立配置”的需求需要改造但改动集中在server/main.py与.env.example。BGE-M3 的官方配置确实是 1024 维和你贴出的hidden_size: 1024一致。BGE-M3 模型卡现有代码的问题当前 main.py 的默认配置有三个限制LLM 和 Embedder 共用同一个OPENAI_API_KEY。两者没有分别传入base_url。pgvector 没有显式传embedding_model_dims默认会采用 1536。Embedder 没有显式传embedding_dims默认也会按 1536 处理。针对该需求需要修改对应的.env 、docker-compose.yaml等文件改动的地方不少.env 配置文件如下所示server.env# Legacy shared OpenAI-compatible credentials. Keep these only when the LLM# and embedder use the same endpoint and API key. Prefer the independent# MEM0_LLM_* and MEM0_EMBEDDER_* variables below for new deployments.OPENAI_API_KEYXXXXXXXXOPENAI_BASE_URLXXXXXXXX# Optional: other bundled LLM/embedder providers (set the key for the one you want to use)# ANTHROPIC_API_KEY# GOOGLE_API_KEY# Postgres — POSTGRES_PASSWORD is required; docker-compose will not start without it.POSTGRES_HOSTpostgres POSTGRES_PORT5432POSTGRES_DBpostgres POSTGRES_USERpostgres POSTGRES_PASSWORDpostgres POSTGRES_COLLECTION_NAMEmemories ADMIN_API_KEYJWT_SECRET61fcd701187483c046f4e020314f0ee1ea982aef227fea626e371646de30223defce62448ab0b1ae59405f3ee14b0884# Local development only. Leave false in production.AUTH_DISABLEDfalse DASHBOARD_URLhttp://192.168.42.244:3000NEXT_PUBLIC_API_URLhttp://192.168.42.244:8888APP_DB_NAMEmem0_app# Independent LLM configuration. The provider must be in BUNDLED_LLM_PROVIDERS# (see server/main.py). MEM0_DEFAULT_LLM_MODEL remains supported as a legacy fallback.MEM0_LLM_PROVIDERopenai MEM0_LLM_API_KEYEMPTY MEM0_LLM_BASE_URLhttp://192.168.8.165:9026/v1 MEM0_LLM_MODELQwen3.5-27B-FP8 MEM0_LLM_TEMPERATURE0.2# Independent embedder configuration. The provider must be in# BUNDLED_EMBEDDER_PROVIDERS. For OpenAI-compatible embedding servers (such as# vLLM), set the base URL to the servers /v1 endpoint.## The embedder and vector store dimensions MUST match. For BAAI/bge-m3 served# by vLLM, use bge-m3-local and 1024 for both values.MEM0_EMBEDDER_PROVIDERopenai MEM0_EMBEDDER_API_KEYEMPTY MEM0_EMBEDDER_BASE_URLhttp://192.168.8.165:9027/v1 MEM0_EMBEDDER_MODELbge-m3-local MEM0_EMBEDDER_DIMENSIONS1024# 嵌入模型的维度MEM0_EMBEDDER_SEND_DIMENSIONSfalse# 当嵌入模型未非OpenAI官方模型并且使用vllm但设为 false 后不会向 vLLM 发送 dimensions 参数MEM0_VECTOR_STORE_DIMENSIONS1024# 向量库数据维度# Legacy model names. They are used only when the corresponding MEM0_LLM_MODEL# or MEM0_EMBEDDER_MODEL variable is empty.MEM0_DEFAULT_LLM_MODELQwen3.5-27B-FP8 MEM0_DEFAULT_EMBEDDER_MODELbge-m3-local# Anonymous telemetry. Sends a single onboarding event per install# (install UUID, email domain, server version, source). No PII.# Set to false to opt out.MEM0_TELEMETRYtrue# Days of request_logs history to keep when make prune-logs runs.# Wire the prune command into cron/systemd in production.REQUEST_LOG_RETENTION_DAYS30docker-compose.yaml配置文件server\docker-compose.yamlname:mem0-dev services:mem0:build:context:..dockerfile:server/dev.Dockerfile args:PIP_INDEX_URL:${PIP_INDEX_URL:-https://mirrors.aliyun.com/pypi/simple}ports:-8888:8000env_file:-.env networks:-mem0_network# Lets a container reach model servers running directly on the Linux Docker host.# Use http://host.docker.internal:port/v1 in MEM0_LLM_BASE_URL or# MEM0_EMBEDDER_BASE_URL. Remove this mapping when all services are on a# Docker network instead.extra_hosts:-host.docker.internal:host-gatewayvolumes:-./history:/app/history-.:/app depends_on:postgres:condition:service_healthy command:sh-calembic upgrade head uvicorn main:app --host 0.0.0.0 --port 8000 --reloadenvironment:-PYTHONDONTWRITEBYTECODE1-PYTHONUNBUFFERED1-PYTHONPATH# Browser origin allowed by the API. Override in .env for remote access.-DASHBOARD_URL${DASHBOARD_URL:-http://localhost:3000}-APP_DB_NAMEmem0_app# Also applies to the startup pip install mem0ai command below.-PIP_INDEX_URL${PIP_INDEX_URL:-https://mirrors.aliyun.com/pypi/simple}-JWT_SECRET${JWT_SECRET}-AUTH_DISABLED${AUTH_DISABLED:-false}-MEM0_TELEMETRY${MEM0_TELEMETRY:-true}postgres:image:pgvector/pgvector:pg17 restart:on-failure shm_size:128mbnetworks:-mem0_network environment:-POSTGRES_USER${POSTGRES_USER:-postgres}-POSTGRES_PASSWORD${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORDin.env}healthcheck:test:[CMD-SHELL,pg_isready -q -d postgres -U ${POSTGRES_USER:-postgres}]interval:5s timeout:5s retries:5volumes:-postgres_db:/var/lib/postgresql/data-./init-db.sh:/docker-entrypoint-initdb.d/init-db.sh ports:-8432:5432mem0-dashboard:build:./dashboard ports:-3000:3000networks:-mem0_network environment:# Used by the Dashboards server-side refresh-token route to decide# whether its session cookie must be Secure. It must be the externally# reachable dashboard URL (not 0.0.0.0).-DASHBOARD_URL${DASHBOARD_URL:-http://localhost:3000}# Browser-facing API address. Do not use localhost when accessing the# dashboard from another computer.-NEXT_PUBLIC_API_URL${NEXT_PUBLIC_API_URL:-http://localhost:8888}-API_INTERNAL_URLhttp://mem0:8000-NEXT_PUBLIC_INSTANCE_NAMEMem0 depends_on:mem0:condition:service_started healthcheck:test:[CMD,wget,-qO-,http://127.0.0.1:3000/api/health]interval:10s timeout:5s retries:3volumes:postgres_db:networks:mem0_network:driver:bridge注意修改的地方不止这两个文件我已经修改完的文件项目上传地址如下https://download.csdn.net/download/guoqingru0311/93690687你的 vLLM 服务还需验证你的 BGE-M3 服务应支持 OpenAI 兼容的/v1/embeddings。vLLM 支持该接口但仅适用于正确以 embedding/pooling 任务运行的模型。vLLM OpenAI 兼容 Embeddings 文档先在 BGE-M3 所在机器测试curl-sShttp://127.0.0.1:9027/v1/embeddings\-HContent-Type: application/json\-d{ model: bge-m3-local, input: Mem0 正在验证 BGE-M3 向量服务。, encoding_format: float }若安装了jq可直接检查维度curl-sShttp://127.0.0.1:9027/v1/embeddings\-HContent-Type: application/json\-d{ model: bge-m3-local, input: Mem0 正在验证 BGE-M3 向量服务。, encoding_format: float }|jq.data[0].embedding | length期望输出1024如果返回 404、task not supported或类似错误说明当前 vLLM 进程没有以 embedding/pooling 模式启动需要结合该机器实际 vLLM 版本调整为--runner pooling或对应的 embedding task 参数后再验证。Docker 网络注意事项如果 Mem0 在 Docker 容器中而两个 vLLM 进程运行在 Docker 宿主机127.0.0.1:9026 127.0.0.1:9027对 Mem0 容器来说并不是宿主机而是容器自身。因此不能将容器内地址填写为127.0.0.1。Linux Docker 下推荐在docker-compose.yaml的mem0服务添加extra_hosts:-host.docker.internal:host-gateway然后才可使用MEM0_LLM_BASE_URLhttp://host.docker.internal:9026/v1 MEM0_EMBEDDER_BASE_URLhttp://host.docker.internal:9027/v1如果 vLLM 在另一台机器则改为那台机器的内网 IP例如MEM0_LLM_BASE_URLhttp://10.0.0.10:9026/v1 MEM0_EMBEDDER_BASE_URLhttp://10.0.0.10:9027/v1最后向量维度一旦已有数据就不能直接改。例如现有memoriescollection 已用 1536 维写入数据切换 BGE-M3 的 1024 维时应新建 collection例如memories_bge_m3或确认无重要数据后重建。下一步实现时建议修改范围为server/main.py读取独立 LLM、Embedder、向量维度配置并加入维度一致性校验server/.env.example提供完整说明和默认值server/docker-compose.yaml仅在 vLLM 与 Mem0 同宿主机时增加host-gateway增加回归测试默认值、独立地址、维度不一致时失败、1024 配置成功。