Memorix Docker 部署指南:如何在 VPS 上一键部署共享 MCP 端点与 Dashboard

原创2026-10-25 14:58:591,877 阅读

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
  • 不适用场景:它不是 stdio MCP(memorix serve)的容器化形态。本地开发直接跑 Node 服务即可,无需为此启动 Docker。

官方提供的是多阶段生产镜像 + 示例 compose 文件 + 带健康检查的 HTTP 部署,详见 Dockerfile 和 compose.yaml,官方说明见 docs/DOCKER.md。

Memorix 记忆控制面工作台界面

部署成功后,你就能看到类似上图的 Memorix 控制面:项目记忆统计、检索模式(如 BM25 full-text)、会话状态和快捷操作一目了然。

二、部署前准备:VPS 环境与仓库

一台可运行的 VPS 需要满足:

  1. 已安装 Docker 和 Docker Compose;
  2. 有外网入站能力(端口将通过反向代理暴露,稍后说明);
  3. 克隆 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。
登录后查看全文
memorix