MaxKB4j Docker Compose 部署指南

本文档面向零基础用户，从零开始讲解如何使用 Docker Compose 部署 MaxKB4j。

1. 简介

1.1 什么是 Docker？

Docker 是一种容器化技术，可以把应用程序及其依赖打包成一个独立的"容器"。你可以把它理解为一个轻量级的虚拟机，但比虚拟机更快速、更节省资源。

为什么用 Docker？

一键部署：无需手动配置 Java、数据库等环境
环境隔离：不会影响你电脑上已有的其他软件
跨平台：Windows、Mac、Linux 都可以用相同的命令

1.2 什么是 Docker Compose？

Docker Compose 是 Docker 的一个工具，用于管理多个容器。MaxKB4j 需要 3 个服务协同工作：

PostgreSQL (pgvector) - 向量数据库，存储知识库数据
MongoDB - 文档数据库，存储对话记录和配置
MaxKB4j - 主应用程序

使用 Docker Compose，你只需要一个命令就能同时启动这 3 个服务。

1.3 本文档适用对象

想要快速体验 MaxKB4j 的新用户
没有运维经验的开发者
需要在本地搭建测试环境的人员

2. 环境准备

2.1 硬件要求

配置项	最低要求	推荐配置
CPU	2 核	4 核+
内存	4 GB	8 GB+
磁盘空间	20 GB	50 GB+

2.2 软件要求

你需要安装以下软件：

Windows 用户

安装 Docker Desktop

访问 Docker 官网下载 Docker Desktop for Windows。

安装完成后，双击桌面图标启动 Docker Desktop。任务栏出现 Docker 鲸鱼图标表示运行成功。
验证安装

打开 PowerShell 或命令提示符，输入：
bash 复制代码
```
docker --version
docker compose version
```
如果显示版本号，说明安装成功。

Linux 用户 (以 Ubuntu 为例)

bash 复制代码

# 1. 更新软件包索引
sudo apt-get update

# 2. 安装 Docker
curl -fsSL https://get.docker.com | sh

# 3. 将当前用户加入 docker 组（免 sudo）
sudo usermod -aG docker $USER

# 4. 重新登录或执行
newgrp docker

# 5. 验证安装
docker --version
docker compose version

macOS 用户

与 Windows 类似，下载 Docker Desktop for Mac 安装即可。

2.3 端口检查

MaxKB4j 需要使用以下端口，请确保没有被其他程序占用：

端口	用途
8080	MaxKB4j Web 界面

检查端口是否被占用：

Windows (PowerShell):
powershell 复制代码
```
netstat -ano | findstr :8080
```
Linux/macOS:
bash 复制代码
```
lsof -i :8080
```

如果输出为空，说明端口可用。

3. 快速部署

3.1 下载配置文件

在项目根目录下，已经包含了 docker-compose.yml 文件。你可以直接使用，或者从 GitHub 下载最新版本。

3.2 一键启动

打开终端（Windows 用户打开 PowerShell 或 CMD），进入项目目录，执行：

bash 复制代码

docker compose up -d

参数说明：

up - 创建并启动容器
-d - 后台运行（detached mode）

预期输出：

复制代码

[+] Running 4/4
 ✔ Network maxkb4j_maxkb4j_network    Created
 ✔ Container maxkb4j-pgvector         Started
 ✔ Container maxkb4j-mongo            Started
 ✔ Container maxkb4j-app              Started

3.3 访问系统

启动成功后，打开浏览器访问：

复制代码

http://localhost:8080

默认管理员账号：

用户名：admin
密码：tarzan@123456

安全提示： 首次登录后请立即修改默认密码！

4. 详细配置说明

4.1 docker-compose.yml 完整解析

yaml 复制代码

services:
  # ========================================
  # PostgreSQL 数据库（带 pgvector 扩展）
  # 用于存储向量数据和知识库内容
  # ========================================
  postgres:
    # 使用阿里云镜像仓库，国内访问更快
    image: registry.cn-hangzhou.aliyuncs.com/tarzanx/pgvector:0.7.0-pg15
    container_name: maxkb4j-pgvector    # 容器名称，便于识别
    restart: always                      # 容器崩溃后自动重启
    networks:
      - maxkb4j_network                  # 加入内部网络
    environment:
      POSTGRES_USER: tarzan_postgres     # 数据库用户名
      POSTGRES_PASSWORD: ycn4NRhjN2      # 数据库密码（生产环境请修改！）
      POSTGRES_DB: MaxKB4j               # 数据库名称
    volumes:
      - ./postgres/data:/var/lib/postgresql/data  # 数据持久化

  # ========================================
  # MongoDB 数据库
  # 用于存储对话记录、工作流配置等
  # ========================================
  mongo:
    image: registry.cn-hangzhou.aliyuncs.com/tarzanx/mongo:8.0
    container_name: maxkb4j-mongo
    restart: always
    networks:
      - maxkb4j_network
    environment:
      TZ: 'Asia/Shanghai'                # 时区设置
      MONGO_INITDB_ROOT_USERNAME: tarzan_mongo    # 管理员用户名
      MONGO_INITDB_ROOT_PASSWORD: ycn4NRhjN2      # 管理员密码（生产环境请修改！）
    volumes:
      - ./mongo/data:/data/db            # 数据持久化
      - ./mongo/configdb:/data/configdb   # 配置持久化

  # ========================================
  # MaxKB4j 主应用
  # ========================================
  maxKB4j:
    container_name: maxkb4j-app
    image: registry.cn-hangzhou.aliyuncs.com/tarzanx/maxkb4j:latest
    ports:
      - "8080:8080"                       # 端口映射：主机端口:容器端口
    networks:
      - maxkb4j_network
    depends_on:
      postgres:
        condition: service_started        # 依赖 postgres 先启动
      mongo:
        condition: service_started        # 依赖 mongo 先启动
    restart: always
    logging:
      options:
        max-size: "30m"                   # 单个日志文件最大 30MB
        max-file: "3"                     # 保留最近 3 个日志文件
    environment:
      # MongoDB 连接字符串
      - SPRING_DATA_MONGODB_URI=mongodb://tarzan_mongo:ycn4NRhjN2@mongo:27017/MaxKB4j?authSource=admin
      # PostgreSQL 连接配置
      - SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/MaxKB4j
      - SPRING_DATASOURCE_USERNAME=tarzan_postgres
      - SPRING_DATASOURCE_PASSWORD=ycn4NRhjN2
    volumes:
      - ./logs:/logs                      # 日志持久化
    entrypoint: >
      sh -c "
      sleep 10;                           # 等待数据库启动完成
      exec java -jar maxkb4j-start.jar
      "

# ========================================
# 网络配置
# ========================================
networks:
  maxkb4j_network:                         # 内部网络，服务间通过容器名访问

4.2 环境变量说明

变量名	说明	默认值
`POSTGRES_USER`	PostgreSQL 用户名	`tarzan_postgres`
`POSTGRES_PASSWORD`	PostgreSQL 密码	`ycn4NRhjN2`
`POSTGRES_DB`	PostgreSQL 数据库名	`MaxKB4j`
`MONGO_INITDB_ROOT_USERNAME`	MongoDB 管理员用户名	`tarzan_mongo`
`MONGO_INITDB_ROOT_PASSWORD`	MongoDB 管理员密码	`ycn4NRhjN2`
`SPRING_DATA_MONGODB_URI`	MongoDB 连接字符串	-
`SPRING_DATASOURCE_URL`	PostgreSQL 连接 URL	-

4.3 数据卷挂载说明

主机路径	容器路径	说明
`./postgres/data`	`/var/lib/postgresql/data`	PostgreSQL 数据文件
`./mongo/data`	`/data/db`	MongoDB 数据文件
`./mongo/configdb`	`/data/configdb`	MongoDB 配置文件
`./logs`	`/logs`	应用日志文件

重要： 这些目录中的数据是持久化的，即使删除容器，数据也不会丢失。

4.4 网络配置

所有服务都在 maxkb4j_network 网络中，服务间可以通过容器名称互相访问：

MaxKB4j 应用通过 postgres:5432 访问 PostgreSQL
MaxKB4j 应用通过 mongo:27017 访问 MongoDB

5. 自定义部署

5.1 修改端口映射

如果你本地的 8080 端口已被占用，可以修改为其他端口。

方法：编辑 docker-compose.yml

yaml 复制代码

maxKB4j:
  ports:
    - "9090:8080"    # 改为 9090 端口（主机端口:容器端口）

修改后重启服务：

bash 复制代码

docker compose down
docker compose up -d

然后通过 http://localhost:9090 访问。

5.2 修改数据库密码

步骤 1：修改 docker-compose.yml 中的密码

yaml 复制代码

services:
  postgres:
    environment:
      POSTGRES_USER: my_user           # 新用户名
      POSTGRES_PASSWORD: my_password   # 新密码

  mongo:
    environment:
      MONGO_INITDB_ROOT_USERNAME: my_mongo_user     # 新用户名
      MONGO_INITDB_ROOT_PASSWORD: my_mongo_password # 新密码

  maxKB4j:
    environment:
      - SPRING_DATA_MONGODB_URI=mongodb://my_mongo_user:my_mongo_password@mongo:27017/MaxKB4j?authSource=admin
      - SPRING_DATASOURCE_USERNAME=my_user
      - SPRING_DATASOURCE_PASSWORD=my_password

步骤 2：删除旧数据（首次部署时）

bash 复制代码

docker compose down
# 警告：这会删除所有数据！仅在新部署时执行
rm -rf ./postgres/data ./mongo/data
docker compose up -d

注意： 如果已有数据，修改密码后需要更新数据库中的用户，否则应用无法连接。建议在首次部署时就设置好密码。

5.3 构建自定义镜像

如果你修改了代码，想构建自己的镜像：

步骤 1：进入 Dockerfile 目录

bash 复制代码

cd maxkb4j-start

步骤 2：构建镜像

bash 复制代码

docker build -t my-maxkb4j:v1.0.0 .

步骤 3：修改 docker-compose.yml 使用自定义镜像

yaml 复制代码

maxKB4j:
  image: my-maxkb4j:v1.0.0
  # ... 其他配置保持不变

5.4 配置外部数据库

如果你有现成的数据库服务器，可以只启动 MaxKB4j 应用：

方法：创建 docker-compose.external-db.yml

yaml 复制代码

services:
  maxKB4j:
    container_name: maxkb4j-app
    image: registry.cn-hangzhou.aliyuncs.com/tarzanx/maxkb4j:latest
    ports:
      - "8080:8080"
    restart: always
    environment:
      # 使用外部数据库的连接信息
      - SPRING_DATA_MONGODB_URI=mongodb://your_user:your_password@your-mongo-host:27017/MaxKB4j?authSource=admin
      - SPRING_DATASOURCE_URL=jdbc:postgresql://your-pg-host:5432/MaxKB4j
      - SPRING_DATASOURCE_USERNAME=your_username
      - SPRING_DATASOURCE_PASSWORD=your_password
    volumes:
      - ./logs:/logs

启动命令：

bash 复制代码

docker compose -f docker-compose.external-db.yml up -d

6. 常用操作命令

6.1 启动/停止/重启

bash 复制代码

# 启动所有服务（后台运行）
docker compose up -d

# 停止所有服务
docker compose down

# 重启所有服务
docker compose restart

# 只重启单个服务
docker compose restart maxKB4j

# 停止并删除所有容器（数据卷不会删除）
docker compose down

# 停止并删除所有容器和数据（慎用！）
docker compose down -v

6.2 查看日志

bash 复制代码

# 查看所有服务日志
docker compose logs

# 实时跟踪日志
docker compose logs -f

# 只看 MaxKB4j 应用日志
docker compose logs -f maxKB4j

# 查看最近 100 行日志
docker compose logs --tail=100 maxKB4j

# 查看主机上的日志文件
# Linux/macOS
tail -f ./logs/maxkb4j.log

# Windows PowerShell
Get-Content .\logs\maxkb4j.log -Tail 100 -Wait

6.3 查看容器状态

bash 复制代码

# 查看所有容器状态
docker compose ps

# 查看容器资源占用
docker stats

# 进入容器内部（调试用）
docker exec -it maxkb4j-app /bin/sh

# 进入 PostgreSQL 容器
docker exec -it maxkb4j-pgvector psql -U tarzan_postgres -d MaxKB4j

# 进入 MongoDB 容器
docker exec -it maxkb4j-mongo mongosh -u tarzan_mongo -p ycn4NRhjN2

6.4 数据备份与恢复

PostgreSQL 备份

bash 复制代码

# 备份
docker exec maxkb4j-pgvector pg_dump -U tarzan_postgres MaxKB4j > backup_$(date +%Y%m%d).sql

# 恢复
cat backup_20240101.sql | docker exec -i maxkb4j-pgvector psql -U tarzan_postgres MaxKB4j

MongoDB 备份

bash 复制代码

# 备份
docker exec maxkb4j-mongo mongodump -u tarzan_mongo -p ycn4NRhjN2 --authenticationDatabase admin -d MaxKB4j -o /tmp/backup
docker cp maxkb4j-mongo:/tmp/backup ./mongo_backup

# 恢复
docker cp ./mongo_backup maxkb4j-mongo:/tmp/backup
docker exec maxkb4j-mongo mongorestore -u tarzan_mongo -p ycn4NRhjN2 --authenticationDatabase admin /tmp/backup

整体数据目录备份

bash 复制代码

# 直接打包数据目录
tar -czvf maxkb4j_backup_$(date +%Y%m%d).tar.gz ./postgres/data ./mongo/data ./logs

6.5 更新升级

bash 复制代码

# 1. 拉取最新镜像
docker compose pull

# 2. 停止旧容器
docker compose down

# 3. 启动新容器（数据会自动恢复）
docker compose up -d

# 或者一条命令完成
docker compose up -d --pull always

7. 常见问题排查

7.1 端口冲突

错误信息：

复制代码

Error: bind: address already in use

解决方法：

查找占用端口的程序：

bash 复制代码

# Windows
netstat -ano | findstr :8080

# Linux/macOS
lsof -i :8080

修改 MaxKB4j 端口（见 [5.1 修改端口映射](#5.1 修改端口映射)）

7.2 容器无法启动

排查步骤：

查看容器日志：
bash 复制代码
```
docker compose logs maxKB4j
```
查看容器状态：
bash 复制代码
```
docker compose ps -a
```
常见原因及解决：
- 镜像拉取失败：检查网络连接，或配置 Docker 镜像加速器
- 内存不足：增加 Docker 可用内存（Docker Desktop 设置）
- 数据目录权限问题 ：确保当前用户对 ./postgres/data 和 ./mongo/data 有写权限

7.3 数据库连接失败

错误信息：

复制代码

Connection refused
Authentication failed

解决方法：

确认数据库容器已启动：
bash 复制代码
```
docker compose ps
```
检查连接配置是否正确：
- 用户名、密码是否匹配
- 数据库名称是否正确
重启所有容器：
bash 复制代码
```
docker compose restart
```

7.4 镜像拉取慢（国内用户）

解决方法：配置镜像加速器

编辑 Docker 配置文件（Docker Desktop → Settings → Docker Engine），添加：

json 复制代码

{
  "registry-mirrors": [
    "https://registry.cn-hangzhou.aliyuncs.com"
  ]
}

点击 "Apply & Restart" 生效。

7.5 数据丢失

预防措施：

定期备份数据目录（见 [6.4 数据备份](#6.4 数据备份)）
使用 docker compose down 而不是 docker compose down -v（后者会删除数据卷）

恢复方法：

如果有备份，直接解压到对应目录：

bash 复制代码

tar -xzvf maxkb4j_backup_20240101.tar.gz
docker compose up -d

7.6 其他常见错误

错误信息	可能原因	解决方法
`permission denied`	权限不足	Linux 用户使用 `sudo` 或将用户加入 docker 组
`no space left on device`	磁盘空间不足	清理无用镜像：`docker system prune -a`
`network not found`	网络未创建	先执行 `docker compose up` 创建网络
`container name already in use`	容器名称冲突	删除旧容器：`docker rm -f maxkb4j-app`

8. 附录

8.1 目录结构说明

复制代码

MaxKB4j/
├── docker-compose.yml          # 生产环境部署配置
├── docker-compose.dev.yml      # 开发环境配置（仅数据库）
├── maxkb4j-start/
│   └── Dockerfile              # 应用镜像构建文件
├── postgres/
│   └── data/                   # PostgreSQL 数据（自动创建）
├── mongo/
│   ├── data/                   # MongoDB 数据（自动创建）
│   └── configdb/               # MongoDB 配置（自动创建）
└── logs/                       # 应用日志（自动创建）

8.2 默认账号密码汇总

服务	用户名	密码	说明
MaxKB4j 系统	admin	tarzan@123456	管理员账号
PostgreSQL	tarzan_postgres	ycn4NRhjN2	数据库账号
MongoDB	tarzan_mongo	ycn4NRhjN2	数据库账号

安全警告： 生产环境部署时，请务必修改所有默认密码！

8.3 开发环境快速启动

如果你是开发者，只需要本地数据库环境：

bash 复制代码

# 仅启动数据库服务
docker compose -f docker-compose.dev.yml up -d

然后使用 IDE 启动 MaxKB4j 应用，数据库连接信息：

PostgreSQL: localhost:5432（需要添加端口映射）
MongoDB: localhost:27017（需要添加端口映射）

如需暴露端口，修改 docker-compose.dev.yml：

yaml 复制代码

services:
  postgres:
    ports:
      - "5432:5432"
  mongo:
    ports:
      - "27017:27017"

8.4 相关资源链接

总结

按照本文档，你应该能够：

成功部署 MaxKB4j 并访问 Web 界面
理解 docker-compose.yml 的配置含义
进行基本的自定义配置（端口、密码等）
处理常见的问题和错误

如有问题，请查阅常见问题排查或提交 Issue。