自主部署（纯手工安装）

本系列介绍如何在 Ubuntu 22.04 x86_64 上原生安装 qOntology，使用 systemd 管理服务。适合能够使用 Linux 命令、修改配置文件和排查服务日志的部署人员。

部署流程

本目录共 1 个目录首页和 5 个内容子页。首次部署按以下顺序执行：

顺序	页面	完成后得到什么
1	环境安装	Java 运行环境，以及按需安装的 Maven、Node.js 构建工具
2	数据库与中间件部署	可连接的 MySQL、Redis、Neo4j 和文件预览服务
3	数据初始化	初始化后的业务库、应用数据库账号与图数据库连接
4	应用构建	后端 JAR 和前端 dist 目录
5	qOntology 服务部署	后端服务、Nginx 入口及完整访问验证

使用同一发布版本的已构建产物时，可以跳过第 4 步。Maven、Node.js 只需安装在构建机器；从源码构建 kkFileView 时，构建机器还需要 Java 17。qOntology API、Neo4j 和 kkFileView 运行服务器也统一使用 JDK 17。

服务与部署基准

服务	本系列示例	职责
Nginx	Ubuntu 软件源版本，入口 8897	前端静态资源、接口与文件预览请求转发
qOntology API	Java 17，端口 8097	业务接口、权限及本体相关处理
MySQL	5.7.44，端口 3306	关系型业务数据
Redis	6.x，端口 6379	缓存及会话相关数据
Neo4j Community	4.4.40、Java 17，端口 7474/7687	图数据存储与查询
kkFileView	4.4.0、Java 17，端口 8012	文件转换和预览

本系列沿用项目 MySQL 5.7、Neo4j 4.4 的配置基线。kkFileView 固定为 4.4.0，以便核对原生安装步骤；项目 Compose 中的 latest 不代表此版本。版本表是教程示例，不代表整套环境已完成兼容性或容量认证。旧版本组件的维护周期与升级兼容性需在生产选型时另外评估。

AI 模型和持久化向量服务按需接入，不属于这六个服务。默认示例使用临时内存向量存储；需要重启后保留向量数据时，应另外配置持久化向量服务。

统一目录与访问约定

/opt/qontology/
├── server/          # qontology-server.jar
├── config/          # deploy.yml 外置覆盖配置
└── web/             # 前端 dist 内的文件

/var/lib/qontology/
└── upload/          # 上传文件

/var/log/qontology/  # 后端日志

数据库与预览服务分别使用独立数据目录。浏览器统一访问 http://<服务器IP>:8897；单机示例中的数据库、缓存、图数据库和 API 只监听回环地址。迁移为多机部署时，需要同步调整监听地址、连接地址及网络访问规则。

<服务器IP>、<发布标签或提交> 和 <……密码> 均需替换为实际值。命令按代码块前说明的目录执行；文件编辑使用 sudoedit，配置片段是文件内容，不是 Shell 命令。

首次部署范围

本系列针对新环境。初始化 SQL 含删表语句，不可在已有业务库上直接重放。应用、初始化文件和配置应来自同一发布版本；升级已有系统时应采用对应升级脚本并先备份。

本系列为单机部署，不包含多副本高可用或自动扩容。资源规划可查看部署服务器资源规格参考；组件关系可查看部署架构图，其中图示是 Docker Compose 部署边界。需要容器部署时请使用 Docker Compose 部署。

页面组织参考 qData 自主部署教程，实际组件、命令和路径按 qOntology 调整。

目录

• 环境安装
• 数据库与中间件部署
• 数据初始化
• 应用构建
• qOntology 服务部署