跳至主要內容

Docker Compose 部署

千桐科技2026/11/1大约 7 分钟安装部署Docker Compose开源版

说在前面

适用对象

适合了解 Docker 基本命令，需要在单台服务器上首次部署 qOntology 开源版，或查看启动、停止与排障命令的用户。

部署前请确认

  • 部署主机能够访问镜像仓库，Docker 可运行 Linux 容器，Compose 版本不低于 2.23.2。
  • 镜像、前端、SQL 和配置使用同一发布版本；全部镜像需匹配主机架构，内存和磁盘按数据量及并发预留。
  • 本文用于首次部署。已有业务数据的环境先备份，并按升级方案处理。

本指南使用完整部署包，包含预设环境变量、Docker Compose 配置、初始化 SQL、应用配置和已打包的前端资源。默认部署使用 MySQL、Redis、Neo4j、kkFileView、qOntology API 和 Nginx。

命令执行位置

除特别说明外，命令在部署包解压后的 docker/ 目录执行，并保持 -p qontology --profile all。已有环境沿用原项目名；<服务器IP>、/实际路径/ 等占位内容需替换。

部署流程

先按部署主机的操作系统完成第 1 步，再依次完成下方共用的第 2～4 步：下载并解压部署包、启动服务、访问系统。

第 1 步：安装 Docker 和 Docker Compose

Linux

按所用发行版的 Docker Engine 安装说明安装 Engine 和 Compose 插件。在部署服务器终端执行：

docker version
docker compose version
docker info

检查通过： Client / Server 均可连接，Compose ≥ 2.23.2。核对主机内存、可用磁盘和镜像架构。

第 2 步：下载并解压部署包

下载完整部署包并解压，得到 docker/ 文件夹。Linux、macOS 和 Windows 均需完成此步骤，并保留隐藏文件 .env 和包内目录结构。

部署目录应包含以下文件，前端资源已随包提供：

docker/                              # 后续 Compose 命令的执行目录
├── .env                             # 预设镜像、密码与端口
├── docker-compose.yml               # 主入口
├── docker-compose-base.yml          # 中间件与 Nginx
├── docker-compose-qontology.yml     # API
└── qOntology/
    ├── mysql/                       # conf.d/my.cnf、init/*.sql
    ├── nginx/                       # dist/index.html、nginx.conf、sites/
    └── server/                      # application.yml、application-prod.yml、upload/

第 3 步：启动 qOntology

3.1 进入部署目录

Linux / macOS： 在终端中进入解压后的 docker/ 文件夹，将示例路径替换为实际位置：

cd "/实际路径/docker"

Windows： 在文件资源管理器中打开解压后的 docker 文件夹，在地址栏输入 powershell 后回车，即可在该目录打开终端。

确认当前目录中包含 .env 和 docker-compose.yml，后续命令均在此目录执行。

3.2 使用默认配置启动

完整部署包按默认配置部署，通常无需先编辑配置文件。在终端或 PowerShell 中执行：

docker compose -p qontology --profile all up -d
docker compose -p qontology --profile all ps -a

首次启动会拉取本机缺少的镜像、创建容器，并在 MySQL 空数据目录中执行初始化 SQL。请等待镜像下载和服务初始化完成，耗时取决于网络和主机性能。

3.3 确认服务就绪

服务列表应包含 mysql57、redis、neo4j、kkfileview、qontology-api 和 nginx。等待中间件健康检查显示 healthy，API 和 Nginx 保持运行，再继续第 4 步。

需要查看启动进度时执行：

docker compose -p qontology --profile all logs -f --tail=200 qontology-api nginx

API 日志应显示应用启动完成，无持续的连接或认证错误。按 Ctrl+C 退出日志查看，不会停止容器。仅显示 Up 不代表应用已经就绪；持续启动失败时参见“常见问题”。

初始化仅用于新环境

已有数据目录不会自动重跑初始化 SQL。不要在业务库中重复导入初始化 SQL，也不要执行会重置业务数据的 reset.sh。

第 4 步：访问 qOntology

部署完成，访问系统

  • 访问地址： http://<服务器IP>:8897
  • 初始账号： qOntology
  • 初始密码： qOntology123

在部署主机本机访问时，可将 <服务器IP> 替换为 localhost。账号信息以部署包的实际初始化版本为准；修改过入口端口时使用实际端口，首次登录后修改密码。

也可在服务器上检查首页和验证码接口：

curl -I http://127.0.0.1:8897/
curl -fsS http://127.0.0.1:8897/prod-api/captchaImage

Windows PowerShell 将 curl 换成 curl.exe。首页应正常返回，验证码接口应返回业务 JSON。

登录后完成以下检查：

验证项通过标准
登录与项目管理能登录、打开菜单，按权限创建并查询测试项目
上传、下载与预览小文件上传后可查询、下载，并通过 /kkfileview/ 正常预览
图谱（按需）使用自建测试数据验证读写；本流程不自动恢复 neo4j-init 样例图数据
AI（按需）配置可用模型和凭据后调用成功；启用向量功能时另验存储与检索

常用运维命令

# 状态与日志；按需将服务名替换为 mysql57、redis、neo4j 等
docker compose -p qontology --profile all ps -a
docker compose -p qontology --profile all logs --tail=200 qontology-api nginx
# 日常停止与恢复，保留容器和数据
docker compose -p qontology --profile all stop
docker compose -p qontology --profile all start

修改 .env 或 Compose 环境变量后，restart 不会应用新配置，需重建受影响服务。例如仅修改 API 时：

docker compose -p qontology --profile all up -d --no-deps --force-recreate qontology-api
docker compose -p qontology --profile all exec nginx nginx -t
docker compose -p qontology --profile all exec nginx nginx -s reload

升级前备份数据库、图数据、上传文件和配置。未确认数据挂载与备份前，不执行 down -v 或清理数据卷；日常停机使用 stop。

常见问题

现象检查方法
Compose 不存在 / 不支持 include检查插件安装及版本；可执行 docker compose -p qontology --profile all config -q 校验配置
镜像拉取失败核对仓库权限、名称、标签和架构；不要随意换成不配套版本
中间件 unhealthy查看对应服务日志；如曾修改密码，核对服务端认证、API 连接配置及健康检查是否一致
白屏、403、502确认部署包内存在 qOntology/nginx/dist/index.html，并按第 3.3 节检查 API 日志；可执行 docker compose -p qontology --profile all exec nginx nginx -t 检查 Nginx 配置
host not found in upstream确认 API 和 kkFileView 已就绪；若 Nginx 仍持续报错，执行 docker compose -p qontology --profile all restart nginx 后重试
仅服务器本机可访问检查入口端口、防火墙、云安全组及客户端网络
上传成功但预览失败检查 kkFileView 健康状态、前端预览地址和容器对文件 URL 的可达性；容器内 127.0.0.1 指向自身
AI / 图数据库配置未生效确认配置文件实际加载路径和对应环境变量
最近更新：