跳至主要內容

使用源代码本地启动

千桐科技2026/11/1大约 14 分钟安装部署源码启动功能联调日常开发

本文介绍如何基于源码在本地启动 qOntology，适用于功能联调和日常开发。按顺序完成环境准备、中间件启动、后端配置和前端启动后，即可在浏览器中访问系统。

本文的启动方式

MySQL、Redis、Neo4j 和 kkFileView 通过 Docker 运行；qOntology 后端在 IntelliJ IDEA 中运行，前端通过 Vite 开发服务运行。全部服务部署在同一台开发机器上，不需要启动容器版 API 和 Nginx。

需要直接部署完整系统时，请参考 Docker Compose 部署；需要在服务器上原生安装时，请参考自主部署。

1、前提条件

1.1、准备开发环境

安装 Git、IntelliJ IDEA，以及下方版本表中的开发工具。预留容器、IDEA、Java 和前端构建所需的内存与磁盘空间；Docker Desktop 的资源配额也需要覆盖中间件运行需求。服务器容量规划可参考部署服务器资源规格参考。

操作系统Docker 环境与命令说明
Linux安装 Docker Engine 和 Compose 插件，确保当前用户可以连接 Docker 引擎
macOS按 Intel 或 Apple Silicon 架构安装 Docker Desktop，启动后等待引擎就绪
Windows安装并启动 Docker Desktop，使用 Linux 容器；命令在 PowerShell 中执行

Apple Silicon 等 ARM 设备需确认所有镜像均支持当前架构，特别是仓库使用的 MySQL 5.7 镜像。若出现镜像架构不匹配，使用兼容的 x86_64 开发环境，或先完成所选镜像的适配验证；不要直接替换数据库大版本。

1.2、检查 Docker

docker version
docker compose version
docker info

确认 Docker Client 和 Server 均可连接，Compose 版本不低于 2.23.2。本文使用带空格的 docker compose 命令，仓库编排使用 include，不能照搬旧版 docker-compose 的使用方式。

2、版本要求

以下为本文采用的开发工具版本组合。Java 版本与源码根目录的 pom.xml 保持一致，Maven 和 Node.js 使用与现有应用构建指南一致的推荐版本。

组件本文使用版本或要求
JDK17
Maven推荐 3.9.x
Node.js推荐 22.x
npm使用 Node.js 配套版本
Git能正常克隆项目仓库
Docker能运行仓库所需的 Linux 容器镜像
Docker Compose2.23.2 或更高版本

在终端中检查：

java -version
mvn -version
node -v
npm -v
git --version

java -version 和 mvn -version 输出中的 Java 版本均应为 17。IDEA 的 Project SDK、Maven 导入和后端运行环境均选择 JDK 17，确保终端、IDEA、Maven 和后端统一使用 JDK 17。

3、克隆 qOntology 仓库

git clone https://gitee.com/qiantongtech/qOntology.git
cd qOntology
git rev-parse HEAD

已有源码时直接进入源码根目录，记录当前提交。需要指定版本时先切换到对应发布标签或提交；后端、前端、配置及初始化 SQL 均使用同一版本。

本文涉及的主要目录如下：

qOntology/
├── pom.xml
├── docker/
│   ├── .env
│   ├── docker-compose.yml
│   ├── docker-compose-base.yml
│   ├── docker-compose-qontology.yml
│   └── qOntology/mysql/init/
│       ├── init-system.sql
│       └── init-show.sql
├── qontology-server/          # 后端启动模块
├── qontology-framework/       # AI、文件存储及图数据库等配置
└── qontology-ui/              # 前端工程

下文所说的“源码根目录”指包含顶层 pom.xml 的 qOntology/，不是文档站目录，也不是 qontology-server/。

4、使用 Docker Compose 启动中间件

4.1、检查连接信息

中间件使用仓库中的 docker/ 编排文件。检查 .env 和 docker-compose-base.yml，后端连接时使用宿主机端口：

中间件宿主机地址用途
MySQL 5.7127.0.0.1:33067qontology 数据库
Redis 6127.0.0.1:63897缓存，后端使用 3 号逻辑库
Neo4j 4.4.40bolt://127.0.0.1:17687图数据库连接
Neo4j Browserhttp://localhost:17474图数据库管理界面
kkFileViewhttp://localhost:8017/kkfileview/文件预览

MySQL 密码取自 docker-compose-base.yml 中 mysql57.environment.MYSQL_ROOT_PASSWORD；Redis 密码取自 .env 的 REDIS_PASSWORD；Neo4j 用户和密码取自 neo4j.environment.NEO4J_AUTH，格式为 用户名/密码。后面的 YAML 示例使用占位符，请填入本机实际值，不要把占位符直接用于启动。

若修改密码，同步核对服务认证和健康检查；已有数据库的实际密码不会因修改初始化环境变量而自动改变。修改端口后，也要同步修改本文后端连接或前端代理中的端口。

4.2、启动与检查

从源码根目录进入 docker/ 执行：

cd docker
docker compose -p qontology --profile base config -q
docker compose -p qontology --profile base up -d mysql57 redis neo4j kkfileview
docker compose -p qontology --profile base ps -a

本流程显式指定四个服务。不要省略服务名直接启动整个 base profile，因为其中还包含容器版 API 和 Nginx；也不需要使用完整部署的 all profile。

首次启动需要拉取镜像并初始化服务。等待这四个服务的健康检查显示 healthy，必要时查看日志：

docker compose -p qontology --profile base logs -f --tail=100 mysql57 redis neo4j kkfileview

按 Ctrl+C 退出日志查看，不会停止容器。镜像拉取失败、容器持续重启或健康检查不通过时，先处理对应错误，再启动后端。

4.3、确认首次初始化

MySQL 在空数据目录首次启动时自动执行挂载的 init-system.sql 和 init-show.sql，准备系统表与业务表，不需要再手工导入另一套初始化脚本。

在 docker/ 目录打开数据库客户端，按提示输入 MySQL 密码：

docker compose -p qontology --profile base exec mysql57 mysql -uroot -p qontology

进入 MySQL 后检查：

SHOW TABLES;
SELECT COUNT(*) AS system_users FROM system_user;
EXIT;

已有环境不要重复初始化

初始化 SQL 包含删除并重建表的语句。已有数据目录不会自动重跑初始化，不能通过重复导入 SQL、执行重置脚本或删除数据卷来修复普通连接错误。不要叠加导入历史初始化文件或全部升级脚本。

Neo4j 默认按现有挂载目录启动；本流程不自动恢复演示图数据。新库没有图节点不代表启动失败。

5、配置并启动后端

5.1、在 IDEA 中打开项目

使用 IntelliJ IDEA 打开源码根目录，以顶层 pom.xml 导入 Maven 项目，等待依赖下载完成。确认项目 SDK 和 Maven 使用 JDK 17。

后端默认 HTTP 端口为 8099，主配置位于 qontology-server/src/main/resources/application.yml。该文件按激活环境导入服务端以及 AI、文件存储、系统、图数据库配置；本地启动使用 dev。

5.2、配置 MySQL 和 Redis

编辑 qontology-server/src/main/resources/application-dev.yml，在已有对应节点内修改以下配置，保留其余连接池设置；不要重复追加第二个 spring: 或 mysql: 节点。

datasource:
  type: mysql

mysql:
  driver-class-name: com.mysql.cj.jdbc.Driver
  url: 'jdbc:mysql://127.0.0.1:33067/qontology?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai'
  username: root
  password: '<MySQL密码>'

spring:
  data:
    redis:
      host: 127.0.0.1
      port: 63897
      database: 3
      password: '<Redis密码>'

现有 spring.datasource.dynamic.datasource.master 通过 datasource.type 引用对应数据库配置，保留这些引用即可。这里的 root 对应仓库默认的本地开发初始化方式；如果已创建应用数据库账号，则填写实际账号及密码，并确认具有访问 qontology 库的权限。

5.3、配置 Neo4j

编辑 qontology-framework/qontology-graphis/qontology-graphis-starter/src/main/resources/application-graphis-dev.yml，修改已有节点：

graphis:
  type: neo4j

neo4j:
  uri: bolt://127.0.0.1:17687
  user: neo4j
  password: '<Neo4j密码>'

本项目使用顶层 neo4j.* 配置。Java 在宿主机运行，因此连接映射后的 17687，不是容器内部的 7687。

5.4、配置本地文件存储

确认 application.yml 中的上传目录为：

qontology:
  profile: ${user.dir}/upload/

编辑 qontology-framework/qontology-file/src/main/resources/application-file-dev.yml，检查并修改对应节点：

dromara:
  x-file-storage:
    default-platform: local
    local-plus:
      - platform: local
        enable-storage: true
        enable-access: false
        domain: ''
        path-patterns: /**
        base-path: /
        storage-path: ${user.dir}/upload/

将已有 aliyun-oss 配置项中的 enable-storage 改为 false，避免加载未配置的示例 OSS 存储。${user.dir} 是 Java 进程的工作目录，两个上传目录应保持一致，并确保当前用户有写入权限。

5.5、配置 AI 开发模式

编辑 qontology-framework/qontology-ai/src/main/resources/application-ai-dev.yml，修改已有节点，保留其他超时等设置：

qontology:
  ai:
    enabled: true
    vector-store: memory

本地启动先使用内存向量存储，无需额外安装 Weaviate。内存中的向量在后端重启后不保留；需要持久化向量时，再配置可用的 Weaviate 地址及认证。AI 抽取、问答等功能还需要在系统中配置真实模型、接口和凭据，基础登录成功不代表 AI 功能已可用。

5.6、构建与启动

在源码根目录执行以下命令；如果终端仍在 docker/，先执行 cd ..。命令保持为一行，Linux、macOS 和 PowerShell 均可使用：

mvn clean install -pl qontology-server -am -Ddocker.print.skip=true -Ddocker.build.skip=true -Ddocker.push.skip=true

-am 同时构建依赖模块，install 将产物安装到本机 Maven 仓库。三个 docker.*.skip 参数跳过镜像命令打印、构建及推送。若仅为本地联调且允许跳过测试，可额外添加 -DskipTests，但打包成功不代表测试通过。

在 IDEA 中创建或检查运行配置：

配置项值
启动模块qontology-server
主类tech.qiantong.qontology.server.QOntologyApplication
JREJDK 17
工作目录（Working directory）qOntology 源码根目录的绝对路径
程序参数（Program arguments）--spring.profiles.active=dev --server.port=8099 --user.password.universalPassword=

最后一个参数将内置通用登录口令置空，本地登录使用实际用户密码。启动类文件为 qontology-server/src/main/java/tech/qiantong/qontology/server/QOntologyApplication.java。

运行后确认日志显示激活 dev、监听 8099，并且没有持续的数据库、Redis 或图数据库连接错误。检查验证码接口：

curl -fsS http://127.0.0.1:8099/captchaImage

Windows PowerShell 使用 curl.exe。接口应返回业务 JSON，而不是连接失败或 HTML 错误页。

6、配置并启动前端

6.1、配置本地环境变量

从源码根目录进入前端工程：

cd qontology-ui

创建 .env.development.local，写入以下内容覆盖仓库的开发示例值：

VITE_APP_BASE_API=/dev-api
VITE_APP_AUTH_TYPE=client
VITE_APP_THIS_APP_URL=http://localhost:5173
VITE_APP_WEBSOCKET_API=ws://127.0.0.1:8099
VITE_APP_FILE_VIEW=/kkfileview
VITE_APP_MODE=development

client 使用本地登录，不需要连接示例统一身份认证服务；development 避免沿用仓库中的 demo 页面模式。不要在 VITE_* 变量中保存服务端密钥，修改环境变量后需要重启前端开发服务。

6.2、核对开发代理

编辑 qontology-ui/vite.config.js 的 server.proxy，核对下方三个已有代理。保留文件中的插件、构建等其他配置，只修改对应代理项：

proxy: {
  '/dev-api': {
    target: 'http://127.0.0.1:8099',
    changeOrigin: true,
    rewrite: (p) => p.replace(/^\/dev-api/, '')
  },
  '/v3/api-docs': {
    target: 'http://127.0.0.1:8099',
    changeOrigin: true
  },
  '/kkfileview': {
    target: 'http://127.0.0.1:8017',
    changeOrigin: true
  }
}

仓库中的预览代理可能仍指向 28012，本流程应改为 Compose 实际映射的 8017。kkFileView 已配置 /kkfileview 上下文，因此这个代理不去除路径前缀；/dev-api 则需去掉前缀再转给后端。

6.3、安装依赖并启动

在 qontology-ui/ 执行：

npm install
npm run dev -- --port 5173 --strictPort

当前源码没有前端锁文件，首次安装使用 npm install；后续版本若提供有效的 package-lock.json，可按该版本流程使用 npm ci。

命令显式使用 5173，覆盖源码默认的 80 端口，也避开本地文档站使用的 8080。--strictPort 会在端口占用时报错，避免自动换端口后访问地址和配置不一致。保持该终端运行，修改代理后重启开发服务。

7、访问 qOntology 与验证

7.1、登录并检查基础功能

浏览器打开 http://localhost:5173。

登录账号和初始密码以同版本初始化说明或交付记录为准；演示站的公开账号不作为本机初始密码的依据。忘记密码时按该版本的账号恢复流程处理，不直接执行其他产品的密码重置 SQL。

也可以检查前端代理是否正常：

curl -fsS http://localhost:5173/dev-api/captchaImage

Windows 使用 curl.exe。接口应返回与后端验证码接口相同类型的业务 JSON。

验证项通过标准
登录页页面、样式和验证码正常加载
登录与菜单使用有效账号登录后，授权菜单和页面正常显示
项目与本体能按权限创建、查询测试项目及本体数据
图数据库使用自建测试数据验证图查询或写入，无连接认证错误
WebSocket页面实际发起的 /websocket/ 连接到 8099，握手成功
上传与下载小文件上传后返回可访问的文件地址，下载正常
文件预览完成下节网络检查后，PDF 和 Office 预览正常
AI（按需）配置真实模型及凭据后再验证抽取、问答等功能

7.2、检查文件预览的网络访问

浏览器通过 Vite 的 /kkfileview 代理打开预览页，但文件原文由 kkFileView 容器下载。如果上传结果中的文件 URL 是 http://127.0.0.1:8099/profile/...，容器中的 127.0.0.1 指向容器自身，预览会失败，即使浏览器能下载这个文件。

需要联调文件预览时，按以下步骤处理：

  1. 找到开发机器的实际局域网 IP，确认浏览器和 Docker 容器均能访问这个 IP 的 8099 端口；后端不要仅监听回环地址，防火墙仅允许需要的开发网络访问。
  2. 将 Vite 中 /dev-api 的 target 改为 http://<开发机器局域网IP>:8099，保留 changeOrigin: true。当前上传逻辑根据请求地址生成文件 URL，这样通过前端重新上传时会使用该宿主机地址。
  3. 重启前端并重新上传测试文件，核对返回的实际文件 URL 包含可达的宿主机 IP、8099 端口和 /profile/ 路径。之前保存的回环地址不会自动更新。
  4. 在源码 docker/ 目录运行下方命令，把占位符替换为刚上传文件的完整 URL；确认返回成功的 HTTP 状态后再打开预览。
docker compose -p qontology --profile base exec kkfileview curl -fI 'http://<开发机器局域网IP>:8099/profile/<实际文件路径>'

Docker Desktop 以及本仓库配置了 host-gateway 的容器还可通过 host.docker.internal 访问宿主机，用于容器侧排查；面向浏览器的文件 URL 仍应使用浏览器和容器都能解析、访问的地址。若文件接口需要认证，还需按实际预览机制处理授权，不能仅凭浏览器已登录判断容器能够下载文件。

8、停止服务与常见问题

前端终端按 Ctrl+C，后端在 IDEA 中停止运行。中间件在 docker/ 目录使用以下命令停止和恢复，保留现有容器及数据：

docker compose -p qontology --profile base stop mysql57 redis neo4j kkfileview
docker compose -p qontology --profile base start mysql57 redis neo4j kkfileview

恢复时先确认中间件健康，再启动后端和前端。本流程不使用 down -v 或清理数据卷作为日常停机方式。

现象优先检查
Compose 不支持 include检查 docker compose version，升级到本文要求的版本
镜像拉取或架构错误检查网络、镜像仓库权限和 CPU 架构；核对 MySQL 5.7 等镜像的可用平台
33067、63897 等端口占用先确认已有服务；需要改映射时同步更新后端配置，不修改容器内部端口
MySQL 无法连接或缺表检查 mysql57 日志、数据库名、实际密码及两份 SQL 首次初始化结果
Redis 认证失败核对 .env 的密码、后端密码和 3 号逻辑库配置
Neo4j 连接失败检查 neo4j.* 配置、宿主机 Bolt 端口 17687 和实际认证信息
Java 编译或启动失败核对终端、IDEA 和 Maven 的 JDK 17，查看首个编译或启动异常
修改 YAML 后未生效确认激活 dev、修改的是实际导入的模块配置，重新构建并重启后端
提示连接 Weaviate检查 application-ai-dev.yml 中 vector-store 是否为 memory
前端 5173 被占用停止确认不再需要的占用进程，或同步修改启动端口、应用 URL 和访问地址
验证码或接口失败先测试 8099 直连接口，再检查 /dev-api 代理地址和去前缀规则
WebSocket 连接到 8080检查 .env.development.local 的 WebSocket 地址，重启 Vite
预览页打不开或资源 404检查预览代理端口 8017、/kkfileview 路径前缀及容器健康状态
能下载文件但预览失败按第 7.2 节从容器检查实际文件 URL，排除回环地址、认证及防火墙问题
上传失败或文件找不到检查 IDEA 工作目录、两个上传目录是否一致及目录写入权限

基础开发环境确认可用后，再按需要接入真实模型、持久化向量存储和其他业务服务。需要交付服务器运行产物时，继续参考应用构建。

最近更新：