Memorix Docker 部署指南:如何在 VPS 上一键部署共享 MCP 端点与 Dashboard
Memorix Docker 部署指南:如何在 VPS 上一键部署共享 MCP 端点与 Dashboard
Memorix 是一款开源的跨 Agent 记忆层,通过 MCP 为 Claude Code、Codex、Cursor、Windsurf、Gemini CLI 等编码 Agent 提供统一的长期记忆。本指南将带你用 Docker 把 Memorix 部署到 VPS,获得一个团队共享的 HTTP MCP 端点(/mcp)和可视化 Dashboard,让所有 Agent 共享同一份记忆。
一、Docker 部署是做什么的?🐳
在动手之前,先明确 Memorix 的 Docker 支持定位:
- 适用场景:长期运行的
serve-http服务,对外提供 Dashboard 和 HTTP MCP 端点; - 三个核心地址(默认端口
3211):- Dashboard:
http://<host>:3211 - MCP 端点:
http://<host>:3211/mcp - 健康检查:
http://<host>:3211/health
- Dashboard:
- 不适用场景:它不是 stdio MCP(
memorix serve)的容器化形态。本地开发直接跑 Node 服务即可,无需为此启动 Docker。
官方提供的是多阶段生产镜像 + 示例 compose 文件 + 带健康检查的 HTTP 部署,详见 Dockerfile 和 compose.yaml,官方说明见 docs/DOCKER.md。
部署成功后,你就能看到类似上图的 Memorix 控制面:项目记忆统计、检索模式(如 BM25 full-text)、会话状态和快捷操作一目了然。
二、部署前准备:VPS 环境与仓库
一台可运行的 VPS 需要满足:
- 已安装 Docker 和 Docker Compose;
- 有外网入站能力(端口将通过反向代理暴露,稍后说明);
- 克隆 Memorix 仓库到服务器:
git clone https://gitcode.com/gh_mirrors/mem/memorix.git
cd memorix
💡 关键认知:VPS 上的容器必须能看到它要绑定的代码仓库。Git 根检测、项目绑定、项目级
memorix.toml和.env、Git Memory 等功能,都依赖 HTTP 服务能访问到仓库路径。官方 compose.yaml 已把仓库挂载到容器内的/workspace并设置了MEMORIX_PROJECT_ROOT=/workspace,开箱即用。
三、一键启动:docker compose 最快部署步骤 🚀
在仓库根目录执行:
docker compose up --build -d
一条命令完成构建镜像、启动容器、设置健康检查。官方 compose 文件(compose.yaml)帮你做了这些事:
| 配置项 | 作用 |
|---|---|
memorix-data:/data 命名卷 |
持久化 Memorix 状态数据 |
./:/workspace 挂载 |
让容器看到你的仓库,启用项目级功能 |
restart: unless-stopped |
开机/异常自动拉起 |
MEMORIX_SESSION_TIMEOUT_MS: 86400000 |
HTTP MCP 会话空闲上限提升到 24 小时,适合 IDE 长会话 |
| healthcheck | 每 30 秒探测 /health,保障服务自愈判断 |
启动后依次验证:
curl http://localhost:3211/health # 应返回 200
curl http://localhost:3211/api/stats
docker compose ps # 状态应为 healthy
docker compose logs -f memorix # 实时跟踪日志
访问 http://<VPS_IP>:3211 即可打开 Dashboard。Dashboard 提供 Overview、Git Memory、Knowledge、Memory Map、Evidence 等页面,还能执行 Cleanup / Consolidate / Deduplicate 等显式维护操作,详见 docs/DASHBOARD.md。
停止服务:
docker compose down
四、远程接入配置:安全暴露端口到公网 🔐
这是 VPS 部署最重要的一步。官方 compose 文件默认把端口绑定到 127.0.0.1:3211(仅本机回环),不要把这个无鉴权的控制面直接暴露到公网。
方案 A(推荐):Bearer Token 鉴权
在 compose.yaml 的 environment 中加入令牌:
environment:
MEMORIX_HTTP_AUTH_TOKEN: "你的强随机令牌"
远程客户端连接时在请求头携带:
Authorization: Bearer <token>
注意 /health 端点保持无鉴权,方便探活;其余端点均需令牌。
方案 B:反代 + 私有网络边界
将 Memorix 放在带鉴权的反向代理(如 Nginx + OAuth/Basic Auth)或 VPN 之后,再放行远程客户端。若确需容器内监听 0.0.0.0 的无鉴权绑定,必须显式设置 MEMORIX_HTTP_ALLOW_UNAUTHENTICATED_BIND=1 且保证只发布到回环地址——这正是官方 compose 的做法。
其他可调参数:
MEMORIX_HTTP_MAX_BODY_BYTES:HTTP JSON 请求体上限,默认 10 MiB,最大可设 64 MiB(Dashboard 维护请求固定 1 MiB 子限制);- 会话超时会话过期后,服务会快速返回
404,客户端自动初始化新的 MCP 会话,无需人工干预。
五、客户端接入:IDE 和 Agent 连接共享端点 🔌
服务跑起来后,支持 HTTP MCP 的客户端把地址指向 VPS 即可,例如在 Agent 的 MCP 配置中:
{
"mcpServers": {
"memorix": {
"url": "http://<你的VPS_IP>:3211/mcp"
}
}
}
各 Agent 的完整接入方式(含 --mcp http 参数写法)见 docs/INTEGRATIONS.md。此时 Claude Code、Codex、Cursor 等多个 Agent 将共享同一份记忆,团队协作场景价值最大。
六、备选方案:不用 compose,直接 docker run
偏好手动控制的可以单独构建镜像:
docker build -t memorix:local .
docker run --rm -p 127.0.0.1:3211:3211 \
-e MEMORIX_HTTP_ALLOW_UNAUTHENTICATED_BIND=1 \
-v memorix-data:/data memorix:local
镜像内部默认以 node 用户运行 serve-http --host 0.0.0.0 --port 3211(见 Dockerfile 的 ENTRYPOINT),状态目录为 /data/.memorix/data。
七、避坑指南:项目路径可见性限制 ⚠️
这是官方文档明确指出的运行时限制:
- 如果机器 A 上的 IDE 发送
projectRoot=/Users/alice/code/app,而机器 B 上的容器看不到这个路径,项目级的 Git/配置语义就无法生效; - 但此时全局/共享记忆依然可用,HTTP 连通性不受影响;
- 解决办法:把仓库挂载进容器(官方 compose 已处理),并用容器内可见的路径调用
memorix_session_start(projectRoot=...),例如/workspace。
八、日常运维速查表 📋
docker compose logs -f memorix # 看日志
docker compose ps # 查状态
docker compose down && docker compose up -d # 重启
docker compose up --build -d # 拉新代码后重新构建
健康检查失败、端口占用、令牌配置错误是最常见三类问题,日志里通常有明确提示;健康探针本身由镜像内置(Dockerfile 第 63 行)。
总结
- Memorix 的 Docker 部署专为共享 HTTP MCP 服务设计,一条
docker compose up --build -d即可在 VPS 上跑起记忆服务 + Dashboard; - 安全是核心:先鉴权(
MEMORIX_HTTP_AUTH_TOKEN)或反代,再暴露端口; - 容器必须能看到要绑定的仓库路径,项目级功能才能完整生效;
- 更多细节可查阅 docs/DOCKER.md、docs/DASHBOARD.md 与 docs/CONFIGURATION.md。
