PromptX Docker 生产部署指南：数据持久化、环境变量与故障排查一次讲透

PromptX Docker 生产部署指南：数据持久化、环境变量与故障排查一次讲透

【免费下载链接】PromptXPromptX · 领先的AI 智能体上下文平台 ｜ PromptX · Leading AI Agent Context Platform项目地址: https://gitcode.com/Deepractice/PromptX

PromptX 是领先的 AI 智能体上下文平台（PromptX · Leading AI Agent Context Platform），基于 MCP 协议，可以用一行命令为 Claude、Cursor 等 AI 应用注入专业能力。本文面向新手和普通用户，手把手教你用 Docker 把 PromptX MCP Server 部署到生产环境，重点讲透数据持久化、环境变量配置与常见故障排查三大核心问题，让你少走弯路、一次跑通。

部署后，PromptX 会以 HTTP 服务形式运行在5203 端口，AI 客户端通过http://127.0.0.1:5203/mcp地址即可接入，开箱即用。

为什么选择 Docker 部署

相比手动安装 Node 环境再跑脚本，Docker 部署有三大好处：

• 环境一致：镜像基于node:20-alpine，依赖版本固定，不会出现"在我机器上能跑"的问题。
• 安全隔离：容器内以非 root 用户运行，降低生产环境风险。
• 一键启停：配合restart: unless-stopped，服务器重启后服务自动拉起。

官方镜像文件位于 Dockerfile，编排文件位于 docker-compose.yml，部署文档见 docker/README.md。

三种快速启动方式

方式一：直接运行官方镜像（推荐新手）

一条命令即可拉起服务，并把数据目录挂载到本地：

docker run -d \ -p 5203:5203 \ -v $(pwd)/.promptx:/root/.promptx \ --name promptx \ deepracticexs/promptx:latest

参数说明：

• -p 5203:5203：把容器内的 5203 端口映射到宿主机。
• -v $(pwd)/.promptx:/root/.promptx：把本地.promptx目录挂载进容器，这是数据持久化的关键。
• --name promptx：给容器起名，方便后续管理。

方式二：Docker Compose 编排（推荐生产）

进入docker目录后执行：

cd docker docker-compose up -d

Compose 文件默认已配置好端口映射、数据卷、NODE_ENV=production和自动重启策略，适合长期运行。

方式三：从源码构建镜像

如果需要用本地代码构建：

docker build -t deepracticexs/promptx -f docker/Dockerfile . docker run -d \ -p 5203:5203 \ -v $(pwd)/.promptx:/root/.promptx \ --name promptx \ deepracticexs/promptx

数据持久化配置详解

这是生产部署最容易踩坑的环节。PromptX 会把用户角色、记忆数据、配置文件统一存放在数据目录中。

默认数据位置

使用 Docker Compose 时，数据默认保存在docker-compose.yml旁边的.promptx文件夹里。Compose 文件中的卷映射为：

volumes: - ${PROMPTX_DATA:-./.promptx}:/root/.promptx

含义是：读取环境变量PROMPTX_DATA，若未设置则回退到默认的./.promptx。

自定义数据目录

当你想把数据放到专门的盘符或备份目录时，只需设置PROMPTX_DATA环境变量：

# 临时指定 PROMPTX_DATA=/path/to/data docker-compose up -d # 或导出后使用 export PROMPTX_DATA=/home/user/.promptx docker-compose up -d

💡生产建议：把数据目录放在独立磁盘并纳入定期备份，升级镜像时只要保留.promptx目录，所有角色与记忆数据都不会丢失。

环境变量清单速查

服务器核心配置（端口、主机、传输协议等）由 serverConfigManager 管理，默认端口正是5203，配置文件持久化在.promptx目录中。

AI 客户端接入配置

服务跑起来后，把下面这段填进 Claude Desktop 的 MCP 配置即可：

{ "mcpServers": { "promptx": { "type": "streamable-http", "url": "http://127.0.0.1:5203/mcp" } } }

接入成功后，PromptX 会暴露discover、action、project、recall、remember、toolx等工具，工具集合定义见 tools/index.ts。

故障排查清单

遇到服务异常时，按下面顺序逐一排查，能解决 90% 的问题。

1. 用健康检查接口验证服务

镜像内置了健康检查，直接访问：

curl http://localhost:5203/health

正常应返回：

{ "status": "ok", "service": "mcp-server", "version": "2.4.1", "sessions": 0, "uptime": 12.3 }

健康检查逻辑实现于 StreamableHttpMCPServer，每 30 秒自动探测一次。

2. 端口被占用

如果启动时报端口冲突，换一个映射端口即可：

docker run -d -p 6000:5203 -v $(pwd)/.promptx:/root/.promptx deepracticexs/promptx:latest

3. 数据没有持久化

常见原因是挂载路径写错。用下面命令确认容器内的挂载点：

docker inspect promptx | grep -A 5 Mounts

4. 查看实时日志

docker logs -f promptx

5. 健康检查一直不通过

• 确认PROMPTX_DATA目录存在且容器有写入权限；
• 重启容器：docker restart promptx；
• 观察docker logs中是否有依赖加载报错。

总结

• 镜像：deepracticexs/promptx:latest，端口5203，MCP 接入地址http://127.0.0.1:5203/mcp。
• 持久化：把.promptx目录挂载到宿主机，或用PROMPTX_DATA自定义路径。
• 生产要点：开启restart: unless-stopped，纳入数据备份，用/health接口做服务监控。

按照本文步骤操作，你应当能用一条命令稳定跑起 PromptX 生产服务，并随时快速定位故障。祝部署顺利 🚀

【免费下载链接】PromptXPromptX · 领先的AI 智能体上下文平台 ｜ PromptX · Leading AI Agent Context Platform项目地址: https://gitcode.com/Deepractice/PromptX