1. MaxKB4j 与 Docker Compose 技术背景

MaxKB4j 是一个基于知识库的问答系统框架，它能够帮助企业或个人快速构建智能问答系统。而 Docker Compose 则是目前最流行的容器编排工具之一，它允许我们通过一个简单的 YAML 文件来定义和运行多容器应用。

在实际部署中，使用 Docker Compose 来部署 MaxKB4j 有几个显著优势：

• 环境隔离：每个服务运行在独立的容器中，避免依赖冲突
• 一键部署：通过 compose 文件定义所有服务，实现快速部署
• 易于维护：配置集中管理，升级和回滚更加方便
• 资源可控：可以精确控制每个容器的资源使用

2. 部署环境准备

2.1 系统要求

在开始部署前，我们需要确保系统满足以下最低要求：

• 操作系统：Ubuntu 18.04+ / CentOS 7+ / Debian 10+
• 内存：至少 4GB（生产环境建议 8GB 以上）
• 存储：至少 20GB 可用空间
• Docker 版本：20.10.0+
• Docker Compose 版本：1.29.0+

提示：可以通过 docker --version 和 docker-compose --version 命令检查当前安装的版本。

2.2 Docker 和 Docker Compose 安装

如果你的系统尚未安装 Docker 和 Docker Compose，可以按照以下步骤进行安装：

对于 Ubuntu/Debian 系统：

# 安装 Docker
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

对于 CentOS/RHEL 系统：

# 安装 Docker
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io
sudo systemctl start docker
sudo systemctl enable docker

# 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

3. MaxKB4j Docker Compose 部署

3.1 准备部署文件

首先创建一个项目目录并下载必要的配置文件：

mkdir maxkb4j-deploy && cd maxkb4j-deploy
curl -O https://raw.githubusercontent.com/maxkb4j/maxkb4j/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/maxkb4j/maxkb4j/main/.env.example
cp .env.example .env

3.2 配置环境变量

编辑 .env 文件，根据你的需求修改以下关键配置：

# MaxKB4j 服务配置
MAXKB4J_VERSION=latest
MAXKB4J_PORT=8080

# 数据库配置
POSTGRES_DB=maxkb4j
POSTGRES_USER=maxkb4j
POSTGRES_PASSWORD=your_strong_password

# Redis 配置
REDIS_PASSWORD=your_redis_password

3.3 启动服务

使用以下命令启动所有服务：

docker-compose up -d

这个命令会执行以下操作：

1. 拉取所需的 Docker 镜像（如果本地不存在）
2. 创建定义的所有服务容器
3. 按照依赖关系顺序启动服务
4. 将容器放入后台运行

3.4 验证部署

部署完成后，可以通过以下方式验证服务是否正常运行：

# 检查容器状态
docker-compose ps

# 查看日志
docker-compose logs -f

如果一切正常，你应该能看到类似如下的输出：

      Name                    Command               State           Ports         
--------------------------------------------------------------------------------
maxkb4j-db       docker-entrypoint.sh postgres    Up      5432/tcp              
maxkb4j-redis    docker-entrypoint.sh redis ...   Up      6379/tcp              
maxkb4j-server   /docker-entrypoint.sh            Up      0.0.0.0:8080->8080/tcp

4. 高级配置与优化

4.1 自定义端口配置

如果你想修改默认的 8080 端口，可以在 .env 文件中修改 MAXKB4J_PORT 变量，然后重新创建容器：

docker-compose down
docker-compose up -d

4.2 数据持久化

默认配置下，数据库数据会存储在名为 maxkb4j-db-data 的 Docker 卷中。如果你想将数据存储在主机特定目录，可以修改 docker-compose.yml 文件中的 volumes 部分：

services:
  db:
    volumes:
      - /path/to/your/data:/var/lib/postgresql/data

4.3 资源限制

为了防止容器占用过多系统资源，可以在 docker-compose.yml 中添加资源限制：

services:
  server:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

4.4 健康检查

添加健康检查可以确保服务在完全就绪后才接受请求：

services:
  server:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

5. 常见问题排查

5.1 端口冲突

如果遇到端口冲突错误（如 8080 端口已被占用），可以：

1. 修改 .env 文件中的 MAXKB4J_PORT 变量
2. 停止占用端口的其他服务
3. 重新运行 docker-compose up -d

5.2 容器启动失败

如果容器启动失败，可以查看详细日志：

docker-compose logs <service_name>

常见原因包括：

• 数据库初始化失败
• 内存不足
• 网络配置问题

5.3 数据库连接问题

如果 MaxKB4j 无法连接数据库，检查：

1. .env 文件中的数据库配置是否正确
2. 数据库容器是否正常运行
3. 网络配置是否允许容器间通信

5.4 性能优化

如果系统响应缓慢，可以考虑：

1. 增加容器资源限制
2. 优化数据库配置
3. 添加 Redis 缓存
4. 启用负载均衡

6. 日常维护操作

6.1 服务启停

停止所有服务：

docker-compose down

启动服务：

docker-compose up -d

重启单个服务：

docker-compose restart <service_name>

6.2 备份与恢复

备份数据库：

docker-compose exec db pg_dump -U maxkb4j maxkb4j > backup.sql

恢复数据库：

cat backup.sql | docker-compose exec -T db psql -U maxkb4j maxkb4j

6.3 升级版本

升级 MaxKB4j 版本：

1. 修改 .env 文件中的 MAXKB4J_VERSION
2. 重新拉取镜像并创建容器：

docker-compose pull
docker-compose up -d

6.4 监控与日志

查看实时日志：

docker-compose logs -f

监控容器资源使用：

docker stats

7. 安全最佳实践

7.1 修改默认密码

部署后第一件事应该是修改所有默认密码，包括：

• 数据库密码（POSTGRES_PASSWORD）
• Redis 密码（REDIS_PASSWORD）
• MaxKB4j 管理员密码

7.2 网络隔离

考虑将服务放在独立的 Docker 网络中：

networks:
  maxkb4j-net:
    driver: bridge

services:
  db:
    networks:
      - maxkb4j-net
  redis:
    networks:
      - maxkb4j-net
  server:
    networks:
      - maxkb4j-net

7.3 定期更新

定期检查并更新：

• Docker 和 Docker Compose 版本
• MaxKB4j 镜像版本
• 基础镜像版本

7.4 访问控制

限制外部访问：

• 使用防火墙规则限制访问 IP
• 考虑添加 HTTPS 支持
• 启用认证和授权机制

我在实际部署 MaxKB4j 时发现，合理配置数据库连接池参数可以显著提升性能。建议在 application.properties 中添加以下配置：

spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.idle-timeout=30000
spring.datasource.hikari.max-lifetime=1800000

另外，如果部署在云环境，建议为数据库配置定期自动备份，可以使用以下 cron 任务：

0 3 * * * docker-compose -f /path/to/maxkb4j-deploy/docker-compose.yml exec -T db pg_dump -U maxkb4j maxkb4j | gzip > /backups/maxkb4j-$(date +\%Y\%m\%d).sql.gz