环境安装

千桐科技2026/11/1大约 4 分钟安装部署

本文是自主部署的第 1 步，示例系统为 Ubuntu 22.04 x86_64。以下操作需要 sudo 权限和可访问官方软件源的网络；其他发行版或 ARM 主机不能直接套用安装包名称。

版本要求

组件	示例版本	用途与安装位置
OpenJDK	17	qOntology API、Neo4j、kkFileView 运行服务器及后端、kkFileView 构建机器
Maven	3.9.x	构建后端或 kkFileView 时需要
Node.js	22.x	仅前端构建机器需要
npm	随 Node.js 安装	安装前端依赖与执行构建

本教程统一使用 JDK 17 运行 qOntology API、Neo4j 和 kkFileView，并用于后端及 kkFileView 的源码构建。后端 POM 指定 Java 17；服务启动时显式指定 Java 17 路径，不依赖全局默认 Java。前端使用 Vite 5，本教程统一选用 Node.js 22。Vite 5 环境要求

一、系统准备

1.1、检查系统与资源

在部署主机执行：

# 确认操作系统与 CPU 架构
cat /etc/os-release
uname -m

# 检查可用内存、磁盘空间及当前监听端口
free -h
df -h / /opt /var
sudo ss -lntp

确认系统为 Ubuntu 22.04、架构输出为 x86_64。对照资源规格参考预留磁盘与内存；确认 8897、8097、3306、6379、7474、7687、8012 未被其他实例占用。

1.2、准备基础工具

# 更新软件索引，安装下载、解压和证书等基础工具
sudo apt update
sudo apt install -y ca-certificates curl wget git tar unzip xz-utils fontconfig

# 创建并进入本次部署使用的下载目录
mkdir -p "$HOME/qontology-packages"
cd "$HOME/qontology-packages"

后续下载包保存在此目录。下载官方归档后按下载页的校验文件核对 SHA256 或 SHA512；不要直接使用其他架构的软件包。

二、JDK 17

2.1、安装

# 安装 Java 17，并通过绝对路径验证运行和编译工具版本
sudo apt install -y openjdk-17-jdk
/usr/lib/jvm/java-17-openjdk-amd64/bin/java -version
/usr/lib/jvm/java-17-openjdk-amd64/bin/javac -version

2.2、配置当前用户的构建环境

在构建用户的 ~/.profile 中添加一次：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH="$JAVA_HOME/bin:$PATH"

使其在当前 Bash 会话生效并检查：

source "$HOME/.profile"
java -version
javac -version

两项应显示主版本 17。Java 17 不需要沿用 JDK 8 的 JRE_HOME 或手工设置 CLASSPATH。systemd 不读取用户的 ~/.profile，后续服务文件会显式指定 Java 可执行文件。

三、Maven

仅在构建机器执行。到 Apache Maven 下载页选择 3.9.x binary tar.gz 及对应校验文件，不选择 Maven 4 或 source 包。

3.1、下载并解压

将下载文件放到 ~/qontology-packages，把下面的文件名替换成实际的 3.9.x 版本。命令中的变量仅代表本次下载包：

# 指定实际下载的 Maven 包，确认文件存在
cd "$HOME/qontology-packages"
MAVEN_ARCHIVE='apache-maven-3.9.x-bin.tar.gz'
test -f "$MAVEN_ARCHIVE"

# 解压至安装目录，去掉压缩包内最外层目录
sudo install -d /opt/maven
sudo tar -xzf "$MAVEN_ARCHIVE" -C /opt/maven --strip-components=1

上述路径用于首次安装，已有 /opt/maven 时先确认版本，不混合覆盖旧文件。

3.2、配置与验证

在 ~/.profile 中添加一次：

export MAVEN_HOME=/opt/maven
export PATH="$MAVEN_HOME/bin:$PATH"

source "$HOME/.profile"
mvn -version

确认 Maven 为 3.9.x，输出的 Java 为 17，Java home 指向 Java 17 安装目录。安装方式参见 Maven 官方安装说明。

四、Node.js 与 npm

仅在前端构建机器执行。到 Node.js 官方下载页选择 22.x、Linux、x64 的 tar.xz 二进制包，并获取对应 SHASUMS256.txt。不要直接采用下载页默认展示的其他主版本。

4.1、解压

将下载包与校验文件放到 ~/qontology-packages，替换实际文件名：

# 指定实际下载的 Node.js 包，并核对 SHA256 校验值
cd "$HOME/qontology-packages"
NODE_ARCHIVE='node-v22.x.y-linux-x64.tar.xz'
grep " $NODE_ARCHIVE\$" SHASUMS256.txt | sha256sum -c -

# 校验通过后解压至安装目录，去掉最外层目录
sudo install -d /opt/node22
sudo tar -xJf "$NODE_ARCHIVE" -C /opt/node22 --strip-components=1

校验失败或没有匹配记录时，停止解压，重新核对文件。/opt/node22 同样按首次安装的空目录使用。

4.2、环境变量与验证

在 ~/.profile 中添加一次：

export PATH="/opt/node22/bin:$PATH"

source "$HOME/.profile"
node -v
npm -v

Node.js 应输出 v22.*，npm 能输出版本号即可；无需额外全局安装 npm、Vue CLI 或 Vite。项目依赖由应用构建页安装。

五、环境检查清单

检查项	预期结果
Java 17 绝对路径执行 `java -version`	输出 17，用于 qOntology API、Neo4j 和 kkFileView
构建机器执行 `mvn -version`	Maven 3.9.x，Java 17
前端构建机器执行 `node -v`、`npm -v`	Node.js 22.x，npm 可运行
磁盘与监听端口	空间足够，计划端口无冲突