AgentX 生产环境部署指南：Docker Compose、安全配置与故障排查最佳实践

AgentX是一个让小白也能通过自然语言打造专属 Agent 的智能体构建平台，内置自研 MCP 网关与模型高可用组件。本文面向新手，手把手带你用Docker Compose完成 AgentX 生产环境部署，覆盖一键启动、.env安全配置、数据备份与常见故障排查，帮助你把 AgentX 稳定地跑在生产服务器上。

一、部署前：AgentX 架构与运行环境一览

生产部署前，先花 1 分钟了解 AgentX 由哪些服务组成，出问题时才知道该看哪里：

最低配置建议：4 核 8G 内存、50G 以上磁盘、已安装 Docker + Docker Compose v2。

仓库中与部署相关的核心文件：

• 生产环境编排：production/docker-compose.yml
• 一键部署配置（含开发/生产/外部库三种模式）：deploy/docker-compose.yml
• 官方部署说明：deploy/README.md
• 生产环境配置模板：deploy/.env.production.example

二、快速上手：两条命令启动 AgentX 生产环境

方式 1：一体化镜像一键启动（推荐新手）

无需下载源码，一个docker run命令即可拉起前端、后端、数据库和消息队列：

# 1. 获取配置模板并修改 cp .env.example .env vim .env # 至少修改 JWT_SECRET、管理员密码、数据库密码 # 2. 一键启动 docker run -d \ --name agentx \ -p 3000:3000 \ -p 8088:8088 \ -p 5432:5432 \ -p 5672:5672 \ -p 15672:15672 \ --env-file .env \ -v agentx-data:/var/lib/postgresql/data \ -v agentx-storage:/app/storage \ -v /var/run/docker.sock:/var/run/docker.sock \ --add-host=localhost:host-gateway \ ghcr.nju.edu.cn/lucky-aeon/agentx:latest

💡 镜像采用智能适配设计：前端会自动根据浏览器访问的 IP/域名连接后端 API，无论本地、内网还是公网服务器都无需改动配置。

📌 AgentX 的"容器工作台"功能依赖 Docker，因此需要挂载/var/run/docker.sock。

默认账号（生产环境请立即修改）：

• 管理员：admin@agentx.ai/admin123
• 测试用户：test@agentx.ai/test123

如需启用 API 高可用功能，可额外启动网关容器：

docker run -d --name agentx-gateway -p 8081:8081 ghcr.io/lucky-aeon/api-premium-gateway:latest

方式 2：Docker Compose 源码部署

适合需要二次开发或升级镜像的版本控制：

git clone https://gitcode.com/gh_mirrors/agentx/AgentX cd AgentX/deploy ./start.sh production # 生产模式；也可选 local / external / dev

四种部署模式的区别见 deploy/README.md：production（内置库，中小型生产）、external（外部 PostgreSQL，大型生产）、local（开发调试）、dev（开发 + Adminer 管理界面）。

三、安全配置：生产环境必改的 5 个关键项

.env是所有配置的核心。官方模板 deploy/.env.production.example 已按生产场景预置，启动前请逐项确认：

其他生产加固项（模板中已默认开启）：

SPRING_PROFILES_ACTIVE=prod JPA_DDL_AUTO=validate # 校验表结构，避免运行时意外改表 SHOW_SQL=false LOG_LEVEL_ROOT=warn # 降低日志量 LOG_LEVEL_APP=info NEXT_PUBLIC_API_BASE_URL=https://your-domain.com/api

🔒JPA_DDL_AUTO=validate是生产部署的一个重要细节：首次启动会自动建表，之后若直接改表结构，validate 模式会让启动直接报错而不是静默修改数据。

网络安全三件套：

1. HTTPS：在 Nginx 等反向代理上配置 SSL 证书，只对外暴露 80/443 端口；
2. 收紧端口：5432（数据库）、15672（MQ 管理台）仅允许内网访问，通过防火墙或POSTGRES_PORT等环境变量避免暴露到公网；
3. 最小权限：应用镜像默认以非 root 用户运行，数据库启用scram-sha-256认证，相关定义可见 docker/backend/Dockerfile 与 production/docker-compose.yml。

四、数据管理：备份、恢复与卷说明

所有数据都存放在 Docker volumes 中，备份只需关注三处：

# 备份数据库 docker exec agentx-postgres pg_dump -U agentx_user agentx > agentx-backup.sql # 恢复数据库 docker exec -i agentx-postgres psql -U agentx_user agentx < agentx-backup.sql

⚠️ 使用外部 PostgreSQL 模式时，需先手动执行初始化脚本 docs/sql/01_init.sql 建库建表。建议为备份加上定时任务（如 crontab 每天凌晨执行一次pg_dump），并将备份文件异地存放。

五、故障排查：AgentX 常见问题快速定位清单

日常运维命令速查：

docker compose ps # 查看服务状态 docker compose logs -f agentx-backend # 跟踪后端日志 docker compose restart agentx-backend # 重启单个服务 docker compose down # 停止全部服务

健康检查接口可直接用浏览器或 curl 验证：http://<服务器IP>:8088/api/health，接口实现见 AgentX/src/main/java/org/xhy/interfaces/api/HealthController.java。

六、总结：生产上线检查清单 ✅

• 已修改JWT_SECRET、管理员/数据库/MQ 密码，禁用测试账号
• 通过 Nginx 配置了 HTTPS，数据库与管理端口未暴露公网
• 配置了每日数据库备份，并验证过恢复流程
• docker compose ps全部Up，/api/health返回正常
• 日志级别调为warn/info，确认SHOW_SQL=false
• 可选：部署 API Premium Gateway 并开启HIGH_AVAILABILITY_ENABLED=true，获得多 Key 模型高可用

按这份清单走完，你的 AgentX 平台已经具备了生产级部署的核心要素。更多架构细节可参考 docs/develop_document.md。