1. MaxKB4j 项目概述与部署价值MaxKB4j 是一个基于知识库构建的智能问答系统它能够将企业文档、产品手册等非结构化数据转化为可交互的知识库。采用 Docker Compose 部署方式可以在 10 分钟内完成生产级环境搭建特别适合需要快速构建内部知识管理系统的技术团队。我在实际部署中发现相比传统虚拟机部署方案Docker Compose 方案具有三大核心优势环境隔离性所有服务MySQL、Redis、MaxKB4j运行在独立容器中避免依赖冲突一键启停通过 compose 文件定义的服务拓扑可以用单条命令管理整个系统生命周期版本可控所有镜像版本明确记录在 compose 文件中方便后续升级和回滚重要提示部署前请确保 Docker 已安装且版本不低于 20.10.14Docker Compose 版本需 v2.5.0 以上。可通过docker --version和docker compose version命令验证。2. 部署环境准备与配置解析2.1 基础环境要求以下是经过实测的推荐环境配置组件最低配置推荐配置说明CPU2核4核需要支持 AVX 指令集内存4GB8GB小规模知识库可降至 4GB磁盘20GB50GB建议使用 SSD 存储OSUbuntu 18.04Ubuntu 22.04需内核版本 ≥ 5.4对于国内用户建议提前配置镜像加速sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json -EOF { registry-mirrors: [https://registry.docker-cn.com] } EOF sudo systemctl restart docker2.2 网络与端口规划MaxKB4j 默认使用以下端口3000前端 Web 界面8080后端 API 服务3306MySQL 数据库6379Redis 缓存如果这些端口已被占用需要在 compose 文件中修改端口映射。我建议采用以下两种方案之一端口映射保持容器内端口不变修改主机端口如 3000:3000 改为 3001:3000自定义网络创建独立 Docker 网络避免端口冲突3. Docker Compose 文件深度解析3.1 标准部署配置创建docker-compose.yml文件内容如下version: 3.8 services: mysql: image: mysql:8.0.32 container_name: maxkb-mysql environment: MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-MaxKB123} MYSQL_DATABASE: maxkb MYSQL_USER: maxkb MYSQL_PASSWORD: ${DB_PASSWORD:-MaxKB456} volumes: - mysql_data:/var/lib/mysql ports: - 3306:3306 healthcheck: test: [CMD, mysqladmin, ping, -h, localhost] interval: 5s timeout: 10s retries: 10 redis: image: redis:7.0.11 container_name: maxkb-redis ports: - 6379:6379 volumes: - redis_data:/data command: redis-server --requirepass ${REDIS_PASSWORD:-MaxKB789} app: image: maxkb4j:latest container_name: maxkb-app depends_on: mysql: condition: service_healthy redis: condition: service_started environment: SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/maxkb?useSSLfalseserverTimezoneUTC SPRING_DATASOURCE_USERNAME: maxkb SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD:-MaxKB456} SPRING_REDIS_HOST: redis SPRING_REDIS_PASSWORD: ${REDIS_PASSWORD:-MaxKB789} ports: - 8080:8080 - 3000:3000 volumes: - upload_data:/app/uploads volumes: mysql_data: redis_data: upload_data:3.2 关键配置说明数据库配置使用环境变量注入密码避免硬编码健康检查确保服务依赖顺序数据卷持久化防止重启丢失Redis 配置通过 command 参数设置访问密码AOF 持久化默认开启应用配置depends_on 控制启动顺序上传目录挂载到数据卷多端口映射支持前后端分离安全建议生产环境务必修改默认密码可通过创建.env文件管理敏感信息DB_ROOT_PASSWORDYourStrongPassword DB_PASSWORDYourDBPassword REDIS_PASSWORDYourRedisPass4. 部署流程与初始化操作4.1 启动与验证执行以下命令启动服务docker compose up -d检查服务状态docker compose ps预期输出应显示所有容器状态为runningNAME COMMAND SERVICE STATUS PORTS maxkb-app java -jar /app.jar app running 0.0.0.0:3000-3000/tcp, 0.0.0.0:8080-8080/tcp maxkb-mysql docker-entrypoint.s… mysql running 0.0.0.0:3306-3306/tcp maxkb-redis docker-entrypoint.s… redis running 0.0.0.0:6379-6379/tcp4.2 系统初始化访问http://服务器IP:3000进入安装向导填写管理员账号信息配置SMTP服务可选上传知识库文档支持PDF/DOCX/TXT常见初始化问题处理端口无法访问检查防火墙设置sudo ufw allow 3000/tcp数据库连接失败查看MySQL日志docker logs maxkb-mysql内存不足调整JVM参数-Xmx2g -Xms1g5. 生产环境优化方案5.1 性能调优建议修改 app 服务的部署配置app: deploy: resources: limits: cpus: 2 memory: 4G reservations: memory: 2G推荐JVM参数environment: JAVA_OPTS: -server -Xms2g -Xmx2g -XX:UseG1GC5.2 高可用部署对于关键业务场景建议MySQL 配置主从复制Redis 启用哨兵模式应用服务横向扩展示例多节点配置app: image: maxkb4j:latest deploy: replicas: 3 update_config: parallelism: 1 delay: 10s6. 日常维护与问题排查6.1 常用运维命令# 查看实时日志 docker compose logs -f app # 执行数据库备份 docker exec maxkb-mysql sh -c exec mysqldump -umaxkb -p$MYSQL_PASSWORD maxkb backup.sql # 清理过期上传文件 docker exec maxkb-app find /app/uploads -type f -mtime 30 -delete6.2 典型问题处理指南问题现象可能原因解决方案502 Bad Gateway应用服务崩溃检查JVM内存设置数据库连接超时MySQL未启动查看容器日志上传失败磁盘空间不足执行docker system prune搜索无结果索引未构建重新导入知识库我在实际运维中总结的经验每周检查一次磁盘使用情况每月执行一次数据库优化重大更新前务必备份数据卷