1. MaxKB4j 项目概述与核心价值MaxKB4j 是一款基于知识库构建的开源问答系统能够帮助企业快速搭建智能客服、内部知识库等应用场景。它采用前后端分离架构后端基于 Java 开发前端使用 Vue.js 框架通过 RESTful API 进行数据交互。使用 Docker Compose 部署 MaxKB4j 是目前最推荐的方案能够实现一键式环境搭建和依赖管理。在实际生产环境中我们经常遇到以下痛点传统部署方式需要手动安装 JDK、MySQL、Redis 等多个组件各组件版本兼容性问题难以排查系统迁移或升级过程复杂开发、测试、生产环境难以保持一致Docker Compose 方案完美解决了这些问题。通过容器化技术我们可以实现秒级环境搭建确保各服务版本完美兼容轻松实现环境迁移和版本升级保持多环境一致性2. 环境准备与前置条件2.1 硬件与操作系统要求建议部署环境满足以下最低配置CPU2核及以上x86_64架构内存4GB及以上磁盘空间20GB可用空间操作系统Ubuntu 18.04/CentOS 7/Debian 10注意生产环境建议使用 SSD 存储能显著提升数据库性能。如果使用云服务器建议选择计算优化型实例。2.2 基础软件安装首先需要安装 Docker 和 Docker Compose# 安装 Docker curl -fsSL https://get.docker.com | sh sudo systemctl enable --now docker # 安装 Docker Compose sudo curl -L https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose sudo chmod x /usr/local/bin/docker-compose验证安装是否成功docker --version docker-compose --version2.3 网络与防火墙配置确保服务器开放以下端口80/443Web 访问3306MySQL建议仅内网开放6379Redis建议仅内网开放如果使用云服务器还需要在安全组中放行这些端口。3. Docker Compose 文件解析与定制3.1 基础 compose 文件结构创建一个docker-compose.yml文件包含以下核心服务version: 3.8 services: mysql: image: mysql:8.0 container_name: maxkb-mysql environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD} MYSQL_DATABASE: ${MYSQL_DATABASE} MYSQL_USER: ${MYSQL_USER} MYSQL_PASSWORD: ${MYSQL_PASSWORD} volumes: - mysql_data:/var/lib/mysql ports: - 3306:3306 networks: - maxkb-network redis: image: redis:6.2 container_name: maxkb-redis volumes: - redis_data:/data ports: - 6379:6379 networks: - maxkb-network backend: image: maxkb4j/backend:latest container_name: maxkb-backend depends_on: - mysql - redis environment: SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/${MYSQL_DATABASE}?useSSLfalsecharacterEncodingutf8 SPRING_DATASOURCE_USERNAME: ${MYSQL_USER} SPRING_DATASOURCE_PASSWORD: ${MYSQL_PASSWORD} SPRING_REDIS_HOST: redis ports: - 8080:8080 networks: - maxkb-network frontend: image: maxkb4j/frontend:latest container_name: maxkb-frontend depends_on: - backend ports: - 80:80 networks: - maxkb-network volumes: mysql_data: redis_data: networks: maxkb-network: driver: bridge3.2 环境变量配置创建.env文件配置敏感信息MYSQL_ROOT_PASSWORDyour_root_password MYSQL_DATABASEmaxkb MYSQL_USERmaxkb MYSQL_PASSWORDyour_db_password重要安全提示永远不要将 .env 文件提交到版本控制系统建议将其添加到 .gitignore 中。3.3 高级定制选项3.3.1 资源限制为防止单个容器占用过多资源可以添加资源限制services: mysql: deploy: resources: limits: cpus: 1 memory: 2G reservations: memory: 1G3.3.2 健康检查添加健康检查确保服务可用性backend: healthcheck: test: [CMD, curl, -f, http://localhost:8080/actuator/health] interval: 30s timeout: 10s retries: 33.3.3 日志配置配置日志轮转防止日志文件过大services: backend: logging: driver: json-file options: max-size: 10m max-file: 34. 部署与初始化流程4.1 启动服务执行以下命令启动所有服务docker-compose up -d启动后可以使用以下命令查看服务状态docker-compose ps4.2 初始化数据库首次启动需要初始化数据库表结构docker exec -it maxkb-backend sh -c java -jar app.jar --spring.profiles.activeprod --maxkb.init-dbtrue4.3 访问系统服务启动完成后可以通过以下方式访问前端http://your-server-ip后端APIhttp://your-server-ip:8080默认管理员账号用户名admin密码maxkb123安全提示首次登录后请立即修改默认密码5. 运维与常见问题排查5.1 日常运维命令常用 Docker Compose 命令速查表命令说明docker-compose up -d启动所有服务后台运行docker-compose down停止并移除所有容器docker-compose logs -f [service]查看服务日志docker-compose ps查看服务状态docker-compose restart [service]重启指定服务docker-compose pull拉取最新镜像5.2 常见问题解决方案5.2.1 MySQL 连接失败错误现象backend_1 | Caused by: com.mysql.cj.exceptions.CJCommunicationsException: Communications link failure解决方案检查 MySQL 容器是否正常运行docker-compose ps验证网络连接docker exec -it maxkb-backend ping mysql检查 MySQL 日志docker-compose logs mysql5.2.2 前端无法访问后端API错误现象前端页面显示 API 请求失败。解决方案检查前端配置中的 API 地址是否正确验证后端服务是否正常curl http://localhost:8080/actuator/health检查网络配置确保前端容器能访问后端容器5.2.3 容器启动顺序问题错误现象后端启动时 MySQL 还未准备好。解决方案在 compose 文件中添加depends_on和健康检查后端应用添加连接重试逻辑environment: SPRING_DATASOURCE_HIKARI_CONNECTION-TIMEOUT: 30000 SPRING_DATASOURCE_HIKARI_INITIALIZATION-FAIL-TIMEOUT: 600005.3 备份与恢复5.3.1 数据库备份docker exec maxkb-mysql sh -c exec mysqldump --all-databases -uroot -p$MYSQL_ROOT_PASSWORD backup.sql5.3.2 恢复数据库cat backup.sql | docker exec -i maxkb-mysql sh -c exec mysql -uroot -p$MYSQL_ROOT_PASSWORD5.3.3 完整系统备份建议备份以下内容MySQL 数据卷Redis 数据卷应用配置文件Docker Compose 文件6. 性能优化与扩展6.1 数据库优化生产环境建议调整以下 MySQL 参数mysql: command: [ --innodb_buffer_pool_size1G, --innodb_log_file_size256M, --max_connections200 ]6.2 Redis 优化redis: command: [ --maxmemory 1gb, --maxmemory-policy allkeys-lru ]6.3 水平扩展方案对于高并发场景可以考虑后端服务多实例backend: deploy: replicas: 3前端负载均衡frontend: image: nginx:latest ports: - 80:80 volumes: - ./nginx.conf:/etc/nginx/nginx.conf6.4 监控方案推荐使用以下工具监控系统运行状态cAdvisor容器资源监控Prometheus Grafana系统指标监控ELK日志收集与分析7. 安全加固建议7.1 网络隔离建议将内部服务MySQL、Redis放在独立网络networks: maxkb-internal: internal: true maxkb-external: driver: bridge7.2 最小权限原则为 MySQL 创建专用用户而非使用 rootCREATE USER maxkb% IDENTIFIED BY complex_password; GRANT SELECT, INSERT, UPDATE, DELETE ON maxkb.* TO maxkb%; FLUSH PRIVILEGES;7.3 定期更新建议定期更新镜像版本docker-compose pull docker-compose up -d --force-recreate7.4 HTTPS 配置生产环境必须启用 HTTPSfrontend: ports: - 443:443 volumes: - ./ssl:/etc/nginx/ssl8. 版本升级与迁移8.1 版本升级流程备份数据和配置文件停止当前服务docker-compose down更新 compose 文件和镜像版本启动新版本docker-compose up -d执行数据迁移脚本如有8.2 环境迁移步骤在原环境备份数据将备份文件、compose 文件和 .env 复制到新环境在新环境恢复数据启动服务8.3 回滚方案如果升级出现问题可以快速回滚docker-compose down docker-compose up -d --force-recreate backendmaxkb4j/backend:previous-version9. 实际部署经验分享在多个生产环境部署 MaxKB4j 后我总结了以下实战经验资源分配MySQL 和 Redis 对内存敏感建议单独分配足够资源。曾经遇到过一个案例Redis 内存不足导致频繁淘汰缓存系统响应时间从 200ms 飙升到 2s。连接池配置后端应用的数据库连接池大小需要根据实际负载调整。一般建议初始连接数 CPU核心数 × 2最大连接数不超过数据库的 max_connections 的 80%日志收集一定要配置日志轮转和集中收集。有次线上问题排查时发现某个容器的日志已经占满了磁盘空间。健康检查完善的健康检查能帮助快速发现问题。我们曾经因为缺少 Redis 健康检查导致系统在 Redis 宕机后仍接收请求造成大量失败。监控告警基础监控是必须的建议至少监控容器内存/CPU 使用率数据库连接数API 响应时间错误日志关键字测试环境一定要保持测试环境与生产环境配置一致。曾经因为测试环境使用了不同的 MySQL 参数导致一个性能问题直到上线才被发现。文档记录详细记录部署架构图和运维手册。当新人接手或紧急情况发生时完善的文档能节省大量时间。