1. MaxKB4j 项目概述与部署价值

MaxKB4j 是一个基于知识库构建的智能问答系统，它能够将企业文档、产品手册等非结构化数据转化为可交互的知识库。采用 Docker Compose 部署方式，可以在 10 分钟内完成生产级环境搭建，特别适合需要快速构建内部知识管理系统的技术团队。

我在实际部署中发现，相比传统虚拟机部署方案，Docker Compose 方案具有三大核心优势：

1. 环境隔离性 ：所有服务（MySQL、Redis、MaxKB4j）运行在独立容器中，避免依赖冲突
2. 一键启停 ：通过 compose 文件定义的服务拓扑，可以用单条命令管理整个系统生命周期
3. 版本可控 ：所有镜像版本明确记录在 compose 文件中，方便后续升级和回滚

重要提示：部署前请确保 Docker 已安装且版本不低于 20.10.14，Docker Compose 版本需 v2.5.0 以上。可通过 docker --version 和 docker compose version 命令验证。

2. 部署环境准备与配置解析

2.1 基础环境要求

以下是经过实测的推荐环境配置：

组件	最低配置	推荐配置	说明
CPU	2核	4核	需要支持 AVX 指令集
内存	4GB	8GB	小规模知识库可降至 4GB
磁盘	20GB	50GB	建议使用 SSD 存储
OS	Ubuntu 18.04	Ubuntu 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 docker

2.2 网络与端口规划

MaxKB4j 默认使用以下端口：

• 3000：前端 Web 界面
• 8080：后端 API 服务
• 3306：MySQL 数据库
• 6379：Redis 缓存

如果这些端口已被占用，需要在 compose 文件中修改端口映射。我建议采用以下两种方案之一：

1. 端口映射 ：保持容器内端口不变，修改主机端口（如 "3000:3000" 改为 "3001:3000"）
2. 自定义网络 ：创建独立 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:-MaxKB@123}
      MYSQL_DATABASE: maxkb
      MYSQL_USER: maxkb
      MYSQL_PASSWORD: ${DB_PASSWORD:-MaxKB@456}
    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:-MaxKB@789}

  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?useSSL=false&serverTimezone=UTC
      SPRING_DATASOURCE_USERNAME: maxkb
      SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD:-MaxKB@456}
      SPRING_REDIS_HOST: redis
      SPRING_REDIS_PASSWORD: ${REDIS_PASSWORD:-MaxKB@789}
    ports:
      - "8080:8080"
      - "3000:3000"
    volumes:
      - upload_data:/app/uploads

volumes:
  mysql_data:
  redis_data:
  upload_data:

3.2 关键配置说明

1. 数据库配置 ：

   • 使用环境变量注入密码，避免硬编码
   • 健康检查确保服务依赖顺序
   • 数据卷持久化防止重启丢失

2. Redis 配置 ：

   • 通过 command 参数设置访问密码
   • AOF 持久化默认开启

3. 应用配置 ：

   • depends_on 控制启动顺序
   • 上传目录挂载到数据卷
   • 多端口映射支持前后端分离

安全建议：生产环境务必修改默认密码，可通过创建 .env 文件管理敏感信息：

DB_ROOT_PASSWORD=YourStrongPassword
DB_PASSWORD=YourDBPassword  
REDIS_PASSWORD=YourRedisPass

4. 部署流程与初始化操作

4.1 启动与验证

执行以下命令启动服务：

docker compose up -d

检查服务状态：

docker compose ps

预期输出应显示所有容器状态为 running ：

NAME                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/tcp

4.2 系统初始化

1. 访问 http://服务器IP:3000 进入安装向导
2. 填写管理员账号信息
3. 配置SMTP服务（可选）
4. 上传知识库文档（支持PDF/DOCX/TXT）

常见初始化问题处理：

• 端口无法访问 ：检查防火墙设置 sudo ufw allow 3000/tcp
• 数据库连接失败 ：查看MySQL日志 docker logs maxkb-mysql
• 内存不足 ：调整JVM参数 -Xmx2g -Xms1g

5. 生产环境优化方案

5.1 性能调优建议

修改 app 服务的部署配置：

app:
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 4G
      reservations:
        memory: 2G

推荐JVM参数：

environment:
  JAVA_OPTS: "-server -Xms2g -Xmx2g -XX:+UseG1GC"

5.2 高可用部署

对于关键业务场景，建议：

1. MySQL 配置主从复制
2. Redis 启用哨兵模式
3. 应用服务横向扩展

示例多节点配置：

app:
  image: maxkb4j:latest
  deploy:
    replicas: 3
    update_config:
      parallelism: 1
      delay: 10s

6. 日常维护与问题排查

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 -delete

6.2 典型问题处理指南

问题现象	可能原因	解决方案
502 Bad Gateway	应用服务崩溃	检查JVM内存设置
数据库连接超时	MySQL未启动	查看容器日志
上传失败	磁盘空间不足	执行 docker system prune
搜索无结果	索引未构建	重新导入知识库

我在实际运维中总结的经验：

• 每周检查一次磁盘使用情况
• 每月执行一次数据库优化
• 重大更新前务必备份数据卷