MaxKB4j Docker Compose 部署指南本文档面向零基础用户从零开始讲解如何使用 Docker Compose 部署 MaxKB4j。目录1. 简介2. 环境准备3. 快速部署4. 详细配置说明5. 自定义部署6. 常用操作命令7. 常见问题排查8. 附录1. 简介1.1 什么是 DockerDocker 是一种容器化技术可以把应用程序及其依赖打包成一个独立的容器。你可以把它理解为一个轻量级的虚拟机但比虚拟机更快速、更节省资源。为什么用 Docker一键部署无需手动配置 Java、数据库等环境环境隔离不会影响你电脑上已有的其他软件跨平台Windows、Mac、Linux 都可以用相同的命令1.2 什么是 Docker ComposeDocker Compose 是 Docker 的一个工具用于管理多个容器。MaxKB4j 需要 3 个服务协同工作PostgreSQL (pgvector) - 向量数据库存储知识库数据MongoDB - 文档数据库存储对话记录和配置MaxKB4j - 主应用程序使用 Docker Compose你只需要一个命令就能同时启动这 3 个服务。1.3 本文档适用对象想要快速体验 MaxKB4j 的新用户没有运维经验的开发者需要在本地搭建测试环境的人员2. 环境准备2.1 硬件要求配置项最低要求推荐配置CPU2 核4 核内存4 GB8 GB磁盘空间20 GB50 GB2.2 软件要求你需要安装以下软件Windows 用户安装 Docker Desktop访问 Docker 官网 下载 Docker Desktop for Windows。安装完成后双击桌面图标启动 Docker Desktop。任务栏出现 Docker 鲸鱼图标表示运行成功。验证安装打开 PowerShell 或命令提示符输入docker--versiondockercompose version如果显示版本号说明安装成功。Linux 用户 (以 Ubuntu 为例)# 1. 更新软件包索引sudoapt-getupdate# 2. 安装 Dockercurl-fsSLhttps://get.docker.com|sh# 3. 将当前用户加入 docker 组免 sudosudousermod-aGdocker$USER# 4. 重新登录或执行newgrpdocker# 5. 验证安装docker--versiondockercompose versionmacOS 用户与 Windows 类似下载 Docker Desktop for Mac 安装即可。2.3 端口检查MaxKB4j 需要使用以下端口请确保没有被其他程序占用端口用途8080MaxKB4j Web 界面检查端口是否被占用Windows (PowerShell):netstat-ano|findstr :8080Linux/macOS:lsof-i:8080如果输出为空说明端口可用。3. 快速部署3.1 下载配置文件在项目根目录下已经包含了docker-compose.yml文件。你可以直接使用或者从 GitHub 下载最新版本。3.2 一键启动打开终端Windows 用户打开 PowerShell 或 CMD进入项目目录执行dockercompose 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 Started3.3 访问系统启动成功后打开浏览器访问http://localhost:8080默认管理员账号用户名admin密码tarzan123456安全提示首次登录后请立即修改默认密码4. 详细配置说明4.1 docker-compose.yml 完整解析services:# # PostgreSQL 数据库带 pgvector 扩展# 用于存储向量数据和知识库内容# postgres:# 使用阿里云镜像仓库国内访问更快image:registry.cn-hangzhou.aliyuncs.com/tarzanx/pgvector:0.7.0-pg15container_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.0container_name:maxkb4j-mongorestart:alwaysnetworks:-maxkb4j_networkenvironment: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-appimage:registry.cn-hangzhou.aliyuncs.com/tarzanx/maxkb4j:latestports:-8080:8080# 端口映射主机端口:容器端口networks:-maxkb4j_networkdepends_on:postgres:condition:service_started# 依赖 postgres 先启动mongo:condition:service_started# 依赖 mongo 先启动restart:alwayslogging:options:max-size:30m# 单个日志文件最大 30MBmax-file:3# 保留最近 3 个日志文件environment:# MongoDB 连接字符串-SPRING_DATA_MONGODB_URImongodb://tarzan_mongo:ycn4NRhjN2mongo:27017/MaxKB4j?authSourceadmin# PostgreSQL 连接配置-SPRING_DATASOURCE_URLjdbc:postgresql://postgres:5432/MaxKB4j-SPRING_DATASOURCE_USERNAMEtarzan_postgres-SPRING_DATASOURCE_PASSWORDycn4NRhjN2volumes:-./logs:/logs# 日志持久化entrypoint:sh -c sleep 10; # 等待数据库启动完成 exec java -jar maxkb4j-start.jar # # 网络配置# networks:maxkb4j_network:# 内部网络服务间通过容器名访问4.2 环境变量说明变量名说明默认值POSTGRES_USERPostgreSQL 用户名tarzan_postgresPOSTGRES_PASSWORDPostgreSQL 密码ycn4NRhjN2POSTGRES_DBPostgreSQL 数据库名MaxKB4jMONGO_INITDB_ROOT_USERNAMEMongoDB 管理员用户名tarzan_mongoMONGO_INITDB_ROOT_PASSWORDMongoDB 管理员密码ycn4NRhjN2SPRING_DATA_MONGODB_URIMongoDB 连接字符串-SPRING_DATASOURCE_URLPostgreSQL 连接 URL-4.3 数据卷挂载说明主机路径容器路径说明./postgres/data/var/lib/postgresql/dataPostgreSQL 数据文件./mongo/data/data/dbMongoDB 数据文件./mongo/configdb/data/configdbMongoDB 配置文件./logs/logs应用日志文件重要这些目录中的数据是持久化的即使删除容器数据也不会丢失。4.4 网络配置所有服务都在maxkb4j_network网络中服务间可以通过容器名称互相访问MaxKB4j 应用通过postgres:5432访问 PostgreSQLMaxKB4j 应用通过mongo:27017访问 MongoDB5. 自定义部署5.1 修改端口映射如果你本地的 8080 端口已被占用可以修改为其他端口。方法编辑docker-compose.ymlmaxKB4j:ports:-9090:8080# 改为 9090 端口主机端口:容器端口修改后重启服务dockercompose downdockercompose up-d然后通过http://localhost:9090访问。5.2 修改数据库密码步骤 1修改docker-compose.yml中的密码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_URImongodb://my_mongo_user:my_mongo_passwordmongo:27017/MaxKB4j?authSourceadmin-SPRING_DATASOURCE_USERNAMEmy_user-SPRING_DATASOURCE_PASSWORDmy_password步骤 2删除旧数据首次部署时dockercompose down# 警告这会删除所有数据仅在新部署时执行rm-rf./postgres/data ./mongo/datadockercompose up-d注意如果已有数据修改密码后需要更新数据库中的用户否则应用无法连接。建议在首次部署时就设置好密码。5.3 构建自定义镜像如果你修改了代码想构建自己的镜像步骤 1进入 Dockerfile 目录cdmaxkb4j-start步骤 2构建镜像dockerbuild-tmy-maxkb4j:v1.0.0.步骤 3修改docker-compose.yml使用自定义镜像maxKB4j:image:my-maxkb4j:v1.0.0# ... 其他配置保持不变5.4 配置外部数据库如果你有现成的数据库服务器可以只启动 MaxKB4j 应用方法创建docker-compose.external-db.ymlservices:maxKB4j:container_name:maxkb4j-appimage:registry.cn-hangzhou.aliyuncs.com/tarzanx/maxkb4j:latestports:-8080:8080restart:alwaysenvironment:# 使用外部数据库的连接信息-SPRING_DATA_MONGODB_URImongodb://your_user:your_passwordyour-mongo-host:27017/MaxKB4j?authSourceadmin-SPRING_DATASOURCE_URLjdbc:postgresql://your-pg-host:5432/MaxKB4j-SPRING_DATASOURCE_USERNAMEyour_username-SPRING_DATASOURCE_PASSWORDyour_passwordvolumes:-./logs:/logs启动命令dockercompose-fdocker-compose.external-db.yml up-d6. 常用操作命令6.1 启动/停止/重启# 启动所有服务后台运行dockercompose up-d# 停止所有服务dockercompose down# 重启所有服务dockercompose restart# 只重启单个服务dockercompose restart maxKB4j# 停止并删除所有容器数据卷不会删除dockercompose down# 停止并删除所有容器和数据慎用dockercompose down-v6.2 查看日志# 查看所有服务日志dockercompose logs# 实时跟踪日志dockercompose logs-f# 只看 MaxKB4j 应用日志dockercompose logs-fmaxKB4j# 查看最近 100 行日志dockercompose logs--tail100maxKB4j# 查看主机上的日志文件# Linux/macOStail-f./logs/maxkb4j.log# Windows PowerShellGet-Content .\logs\maxkb4j.log-Tail100-Wait6.3 查看容器状态# 查看所有容器状态dockercomposeps# 查看容器资源占用dockerstats# 进入容器内部调试用dockerexec-itmaxkb4j-app /bin/sh# 进入 PostgreSQL 容器dockerexec-itmaxkb4j-pgvector psql-Utarzan_postgres-dMaxKB4j# 进入 MongoDB 容器dockerexec-itmaxkb4j-mongo mongosh-utarzan_mongo-pycn4NRhjN26.4 数据备份与恢复PostgreSQL 备份# 备份dockerexecmaxkb4j-pgvector pg_dump-Utarzan_postgres MaxKB4jbackup_$(date%Y%m%d).sql# 恢复catbackup_20240101.sql|dockerexec-imaxkb4j-pgvector psql-Utarzan_postgres MaxKB4jMongoDB 备份# 备份dockerexecmaxkb4j-mongo mongodump-utarzan_mongo-pycn4NRhjN2--authenticationDatabaseadmin-dMaxKB4j-o/tmp/backupdockercpmaxkb4j-mongo:/tmp/backup ./mongo_backup# 恢复dockercp./mongo_backup maxkb4j-mongo:/tmp/backupdockerexecmaxkb4j-mongo mongorestore-utarzan_mongo-pycn4NRhjN2--authenticationDatabaseadmin /tmp/backup整体数据目录备份# 直接打包数据目录tar-czvfmaxkb4j_backup_$(date%Y%m%d).tar.gz ./postgres/data ./mongo/data ./logs6.5 更新升级# 1. 拉取最新镜像dockercompose pull# 2. 停止旧容器dockercompose down# 3. 启动新容器数据会自动恢复dockercompose up-d# 或者一条命令完成dockercompose up-d--pullalways7. 常见问题排查7.1 端口冲突错误信息Error: bind: address already in use解决方法查找占用端口的程序# Windowsnetstat-ano|findstr :8080# Linux/macOSlsof-i:8080修改 MaxKB4j 端口见 5.1 修改端口映射7.2 容器无法启动排查步骤查看容器日志dockercompose logs maxKB4j查看容器状态dockercomposeps-a常见原因及解决镜像拉取失败检查网络连接或配置 Docker 镜像加速器内存不足增加 Docker 可用内存Docker Desktop 设置数据目录权限问题确保当前用户对./postgres/data和./mongo/data有写权限7.3 数据库连接失败错误信息Connection refused Authentication failed解决方法确认数据库容器已启动dockercomposeps检查连接配置是否正确用户名、密码是否匹配数据库名称是否正确重启所有容器dockercompose restart7.4 镜像拉取慢国内用户解决方法配置镜像加速器编辑 Docker 配置文件Docker Desktop → Settings → Docker Engine添加{registry-mirrors:[https://registry.cn-hangzhou.aliyuncs.com]}点击 “Apply Restart” 生效。7.5 数据丢失预防措施定期备份数据目录见 6.4 数据备份使用docker compose down而不是docker compose down -v后者会删除数据卷恢复方法如果有备份直接解压到对应目录tar-xzvfmaxkb4j_backup_20240101.tar.gzdockercompose up-d7.6 其他常见错误错误信息可能原因解决方法permission denied权限不足Linux 用户使用sudo或将用户加入 docker 组no space left on device磁盘空间不足清理无用镜像docker system prune -anetwork not found网络未创建先执行docker compose up创建网络container name already in use容器名称冲突删除旧容器docker rm -f maxkb4j-app8. 附录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 系统admintarzan123456管理员账号PostgreSQLtarzan_postgresycn4NRhjN2数据库账号MongoDBtarzan_mongoycn4NRhjN2数据库账号安全警告生产环境部署时请务必修改所有默认密码8.3 开发环境快速启动如果你是开发者只需要本地数据库环境# 仅启动数据库服务dockercompose-fdocker-compose.dev.yml up-d然后使用 IDE 启动 MaxKB4j 应用数据库连接信息PostgreSQL:localhost:5432需要添加端口映射MongoDB:localhost:27017需要添加端口映射如需暴露端口修改docker-compose.dev.ymlservices:postgres:ports:-5432:5432mongo:ports:-27017:270178.4 相关资源链接MaxKB4j GitHub 仓库Docker 官方文档Docker Compose 官方文档PostgreSQL 官方文档MongoDB 官方文档总结按照本文档你应该能够成功部署 MaxKB4j 并访问 Web 界面理解 docker-compose.yml 的配置含义进行基本的自定义配置端口、密码等处理常见的问题和错误如有问题请查阅 常见问题排查 或提交 Issue。
MaxKB4j Docker Compose 部署指南
MaxKB4j Docker Compose 部署指南本文档面向零基础用户从零开始讲解如何使用 Docker Compose 部署 MaxKB4j。目录1. 简介2. 环境准备3. 快速部署4. 详细配置说明5. 自定义部署6. 常用操作命令7. 常见问题排查8. 附录1. 简介1.1 什么是 DockerDocker 是一种容器化技术可以把应用程序及其依赖打包成一个独立的容器。你可以把它理解为一个轻量级的虚拟机但比虚拟机更快速、更节省资源。为什么用 Docker一键部署无需手动配置 Java、数据库等环境环境隔离不会影响你电脑上已有的其他软件跨平台Windows、Mac、Linux 都可以用相同的命令1.2 什么是 Docker ComposeDocker Compose 是 Docker 的一个工具用于管理多个容器。MaxKB4j 需要 3 个服务协同工作PostgreSQL (pgvector) - 向量数据库存储知识库数据MongoDB - 文档数据库存储对话记录和配置MaxKB4j - 主应用程序使用 Docker Compose你只需要一个命令就能同时启动这 3 个服务。1.3 本文档适用对象想要快速体验 MaxKB4j 的新用户没有运维经验的开发者需要在本地搭建测试环境的人员2. 环境准备2.1 硬件要求配置项最低要求推荐配置CPU2 核4 核内存4 GB8 GB磁盘空间20 GB50 GB2.2 软件要求你需要安装以下软件Windows 用户安装 Docker Desktop访问 Docker 官网 下载 Docker Desktop for Windows。安装完成后双击桌面图标启动 Docker Desktop。任务栏出现 Docker 鲸鱼图标表示运行成功。验证安装打开 PowerShell 或命令提示符输入docker--versiondockercompose version如果显示版本号说明安装成功。Linux 用户 (以 Ubuntu 为例)# 1. 更新软件包索引sudoapt-getupdate# 2. 安装 Dockercurl-fsSLhttps://get.docker.com|sh# 3. 将当前用户加入 docker 组免 sudosudousermod-aGdocker$USER# 4. 重新登录或执行newgrpdocker# 5. 验证安装docker--versiondockercompose versionmacOS 用户与 Windows 类似下载 Docker Desktop for Mac 安装即可。2.3 端口检查MaxKB4j 需要使用以下端口请确保没有被其他程序占用端口用途8080MaxKB4j Web 界面检查端口是否被占用Windows (PowerShell):netstat-ano|findstr :8080Linux/macOS:lsof-i:8080如果输出为空说明端口可用。3. 快速部署3.1 下载配置文件在项目根目录下已经包含了docker-compose.yml文件。你可以直接使用或者从 GitHub 下载最新版本。3.2 一键启动打开终端Windows 用户打开 PowerShell 或 CMD进入项目目录执行dockercompose 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 Started3.3 访问系统启动成功后打开浏览器访问http://localhost:8080默认管理员账号用户名admin密码tarzan123456安全提示首次登录后请立即修改默认密码4. 详细配置说明4.1 docker-compose.yml 完整解析services:# # PostgreSQL 数据库带 pgvector 扩展# 用于存储向量数据和知识库内容# postgres:# 使用阿里云镜像仓库国内访问更快image:registry.cn-hangzhou.aliyuncs.com/tarzanx/pgvector:0.7.0-pg15container_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.0container_name:maxkb4j-mongorestart:alwaysnetworks:-maxkb4j_networkenvironment: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-appimage:registry.cn-hangzhou.aliyuncs.com/tarzanx/maxkb4j:latestports:-8080:8080# 端口映射主机端口:容器端口networks:-maxkb4j_networkdepends_on:postgres:condition:service_started# 依赖 postgres 先启动mongo:condition:service_started# 依赖 mongo 先启动restart:alwayslogging:options:max-size:30m# 单个日志文件最大 30MBmax-file:3# 保留最近 3 个日志文件environment:# MongoDB 连接字符串-SPRING_DATA_MONGODB_URImongodb://tarzan_mongo:ycn4NRhjN2mongo:27017/MaxKB4j?authSourceadmin# PostgreSQL 连接配置-SPRING_DATASOURCE_URLjdbc:postgresql://postgres:5432/MaxKB4j-SPRING_DATASOURCE_USERNAMEtarzan_postgres-SPRING_DATASOURCE_PASSWORDycn4NRhjN2volumes:-./logs:/logs# 日志持久化entrypoint:sh -c sleep 10; # 等待数据库启动完成 exec java -jar maxkb4j-start.jar # # 网络配置# networks:maxkb4j_network:# 内部网络服务间通过容器名访问4.2 环境变量说明变量名说明默认值POSTGRES_USERPostgreSQL 用户名tarzan_postgresPOSTGRES_PASSWORDPostgreSQL 密码ycn4NRhjN2POSTGRES_DBPostgreSQL 数据库名MaxKB4jMONGO_INITDB_ROOT_USERNAMEMongoDB 管理员用户名tarzan_mongoMONGO_INITDB_ROOT_PASSWORDMongoDB 管理员密码ycn4NRhjN2SPRING_DATA_MONGODB_URIMongoDB 连接字符串-SPRING_DATASOURCE_URLPostgreSQL 连接 URL-4.3 数据卷挂载说明主机路径容器路径说明./postgres/data/var/lib/postgresql/dataPostgreSQL 数据文件./mongo/data/data/dbMongoDB 数据文件./mongo/configdb/data/configdbMongoDB 配置文件./logs/logs应用日志文件重要这些目录中的数据是持久化的即使删除容器数据也不会丢失。4.4 网络配置所有服务都在maxkb4j_network网络中服务间可以通过容器名称互相访问MaxKB4j 应用通过postgres:5432访问 PostgreSQLMaxKB4j 应用通过mongo:27017访问 MongoDB5. 自定义部署5.1 修改端口映射如果你本地的 8080 端口已被占用可以修改为其他端口。方法编辑docker-compose.ymlmaxKB4j:ports:-9090:8080# 改为 9090 端口主机端口:容器端口修改后重启服务dockercompose downdockercompose up-d然后通过http://localhost:9090访问。5.2 修改数据库密码步骤 1修改docker-compose.yml中的密码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_URImongodb://my_mongo_user:my_mongo_passwordmongo:27017/MaxKB4j?authSourceadmin-SPRING_DATASOURCE_USERNAMEmy_user-SPRING_DATASOURCE_PASSWORDmy_password步骤 2删除旧数据首次部署时dockercompose down# 警告这会删除所有数据仅在新部署时执行rm-rf./postgres/data ./mongo/datadockercompose up-d注意如果已有数据修改密码后需要更新数据库中的用户否则应用无法连接。建议在首次部署时就设置好密码。5.3 构建自定义镜像如果你修改了代码想构建自己的镜像步骤 1进入 Dockerfile 目录cdmaxkb4j-start步骤 2构建镜像dockerbuild-tmy-maxkb4j:v1.0.0.步骤 3修改docker-compose.yml使用自定义镜像maxKB4j:image:my-maxkb4j:v1.0.0# ... 其他配置保持不变5.4 配置外部数据库如果你有现成的数据库服务器可以只启动 MaxKB4j 应用方法创建docker-compose.external-db.ymlservices:maxKB4j:container_name:maxkb4j-appimage:registry.cn-hangzhou.aliyuncs.com/tarzanx/maxkb4j:latestports:-8080:8080restart:alwaysenvironment:# 使用外部数据库的连接信息-SPRING_DATA_MONGODB_URImongodb://your_user:your_passwordyour-mongo-host:27017/MaxKB4j?authSourceadmin-SPRING_DATASOURCE_URLjdbc:postgresql://your-pg-host:5432/MaxKB4j-SPRING_DATASOURCE_USERNAMEyour_username-SPRING_DATASOURCE_PASSWORDyour_passwordvolumes:-./logs:/logs启动命令dockercompose-fdocker-compose.external-db.yml up-d6. 常用操作命令6.1 启动/停止/重启# 启动所有服务后台运行dockercompose up-d# 停止所有服务dockercompose down# 重启所有服务dockercompose restart# 只重启单个服务dockercompose restart maxKB4j# 停止并删除所有容器数据卷不会删除dockercompose down# 停止并删除所有容器和数据慎用dockercompose down-v6.2 查看日志# 查看所有服务日志dockercompose logs# 实时跟踪日志dockercompose logs-f# 只看 MaxKB4j 应用日志dockercompose logs-fmaxKB4j# 查看最近 100 行日志dockercompose logs--tail100maxKB4j# 查看主机上的日志文件# Linux/macOStail-f./logs/maxkb4j.log# Windows PowerShellGet-Content .\logs\maxkb4j.log-Tail100-Wait6.3 查看容器状态# 查看所有容器状态dockercomposeps# 查看容器资源占用dockerstats# 进入容器内部调试用dockerexec-itmaxkb4j-app /bin/sh# 进入 PostgreSQL 容器dockerexec-itmaxkb4j-pgvector psql-Utarzan_postgres-dMaxKB4j# 进入 MongoDB 容器dockerexec-itmaxkb4j-mongo mongosh-utarzan_mongo-pycn4NRhjN26.4 数据备份与恢复PostgreSQL 备份# 备份dockerexecmaxkb4j-pgvector pg_dump-Utarzan_postgres MaxKB4jbackup_$(date%Y%m%d).sql# 恢复catbackup_20240101.sql|dockerexec-imaxkb4j-pgvector psql-Utarzan_postgres MaxKB4jMongoDB 备份# 备份dockerexecmaxkb4j-mongo mongodump-utarzan_mongo-pycn4NRhjN2--authenticationDatabaseadmin-dMaxKB4j-o/tmp/backupdockercpmaxkb4j-mongo:/tmp/backup ./mongo_backup# 恢复dockercp./mongo_backup maxkb4j-mongo:/tmp/backupdockerexecmaxkb4j-mongo mongorestore-utarzan_mongo-pycn4NRhjN2--authenticationDatabaseadmin /tmp/backup整体数据目录备份# 直接打包数据目录tar-czvfmaxkb4j_backup_$(date%Y%m%d).tar.gz ./postgres/data ./mongo/data ./logs6.5 更新升级# 1. 拉取最新镜像dockercompose pull# 2. 停止旧容器dockercompose down# 3. 启动新容器数据会自动恢复dockercompose up-d# 或者一条命令完成dockercompose up-d--pullalways7. 常见问题排查7.1 端口冲突错误信息Error: bind: address already in use解决方法查找占用端口的程序# Windowsnetstat-ano|findstr :8080# Linux/macOSlsof-i:8080修改 MaxKB4j 端口见 5.1 修改端口映射7.2 容器无法启动排查步骤查看容器日志dockercompose logs maxKB4j查看容器状态dockercomposeps-a常见原因及解决镜像拉取失败检查网络连接或配置 Docker 镜像加速器内存不足增加 Docker 可用内存Docker Desktop 设置数据目录权限问题确保当前用户对./postgres/data和./mongo/data有写权限7.3 数据库连接失败错误信息Connection refused Authentication failed解决方法确认数据库容器已启动dockercomposeps检查连接配置是否正确用户名、密码是否匹配数据库名称是否正确重启所有容器dockercompose restart7.4 镜像拉取慢国内用户解决方法配置镜像加速器编辑 Docker 配置文件Docker Desktop → Settings → Docker Engine添加{registry-mirrors:[https://registry.cn-hangzhou.aliyuncs.com]}点击 “Apply Restart” 生效。7.5 数据丢失预防措施定期备份数据目录见 6.4 数据备份使用docker compose down而不是docker compose down -v后者会删除数据卷恢复方法如果有备份直接解压到对应目录tar-xzvfmaxkb4j_backup_20240101.tar.gzdockercompose up-d7.6 其他常见错误错误信息可能原因解决方法permission denied权限不足Linux 用户使用sudo或将用户加入 docker 组no space left on device磁盘空间不足清理无用镜像docker system prune -anetwork not found网络未创建先执行docker compose up创建网络container name already in use容器名称冲突删除旧容器docker rm -f maxkb4j-app8. 附录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 系统admintarzan123456管理员账号PostgreSQLtarzan_postgresycn4NRhjN2数据库账号MongoDBtarzan_mongoycn4NRhjN2数据库账号安全警告生产环境部署时请务必修改所有默认密码8.3 开发环境快速启动如果你是开发者只需要本地数据库环境# 仅启动数据库服务dockercompose-fdocker-compose.dev.yml up-d然后使用 IDE 启动 MaxKB4j 应用数据库连接信息PostgreSQL:localhost:5432需要添加端口映射MongoDB:localhost:27017需要添加端口映射如需暴露端口修改docker-compose.dev.ymlservices:postgres:ports:-5432:5432mongo:ports:-27017:270178.4 相关资源链接MaxKB4j GitHub 仓库Docker 官方文档Docker Compose 官方文档PostgreSQL 官方文档MongoDB 官方文档总结按照本文档你应该能够成功部署 MaxKB4j 并访问 Web 界面理解 docker-compose.yml 的配置含义进行基本的自定义配置端口、密码等处理常见的问题和错误如有问题请查阅 常见问题排查 或提交 Issue。
