PromptX Docker 生产部署指南数据持久化、环境变量与故障排查一次讲透【免费下载链接】PromptXPromptX · 领先的AI 智能体上下文平台 PromptX · Leading AI Agent Context Platform项目地址: https://gitcode.com/Deepractice/PromptXPromptX 是领先的 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 -dCompose 文件默认已配置好端口映射、数据卷、NODE_ENVproduction和自动重启策略适合长期运行。方式三从源码构建镜像如果需要用本地代码构建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目录所有角色与记忆数据都不会丢失。环境变量清单速查变量名作用默认值PROMPTX_DATA自定义数据目录路径./.promptxNODE_ENV运行环境标识production端口服务对外端口5203服务器核心配置端口、主机、传输协议等由 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:latest3. 数据没有持久化常见原因是挂载路径写错。用下面命令确认容器内的挂载点docker inspect promptx | grep -A 5 Mounts4. 查看实时日志docker logs -f promptx5. 健康检查一直不通过确认PROMPTX_DATA目录存在且容器有写入权限重启容器docker restart promptx观察docker logs中是否有依赖加载报错。总结镜像deepracticexs/promptx:latest端口5203MCP 接入地址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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
