数据库与中间件部署

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

完成环境安装后，在 Ubuntu 22.04 x86_64 部署主机执行本页步骤。本页只安装服务；qOntology 业务库内容在下一页导入。所有配置中的 <……密码> 和 <服务器IP> 必须替换。

单机示例只将 Nginx 的 8897 作为访问入口，中间件监听 127.0.0.1。以下用户、安装目录和数据目录均按新环境准备；发现同名服务或已有数据时，先核对实例，勿重新初始化。

从 MySQL 官方归档选择 5.7.44、Linux Generic、x86_64 的 glibc 2.12 二进制包，上传至 ~/qontology-packages。示例文件名为 mysql-5.7.44-linux-glibc2.12-x86_64.tar.gz；如下载包不同，按其实际名称和运行库要求调整。不要用 Ubuntu 默认的 apt install mysql-server 代替这一步。

# 更新软件索引并安装 MySQL 二进制包所需的运行库
sudo apt update
sudo apt install -y libaio1 libnuma1 libncurses5 libtinfo5

# 创建数据库服务用户，准备安装目录并解压软件包
sudo useradd --system --user-group --home-dir /var/lib/mysql57 --shell /usr/sbin/nologin mysql57
sudo install -d /opt/mysql57
cd "$HOME/qontology-packages"
sudo tar -xzf mysql-5.7.44-linux-glibc2.12-x86_64.tar.gz -C /opt/mysql57 --strip-components=1

# 创建数据和日志目录，交由数据库服务用户写入
sudo install -d -o mysql57 -g mysql57 -m 750 /var/lib/mysql57 /var/log/mysql57

# 检查 MySQL 版本与动态库依赖，确认没有缺失库
/opt/mysql57/bin/mysqld --version
ldd /opt/mysql57/bin/mysqld

版本应为 5.7.44，ldd 不应出现 not found。缺库时先补齐实际缺失的兼容库，不把不同 ABI 的库文件强行软链接。安装依据：MySQL 通用二进制安装说明。

1.2、配置与首次初始化

执行 sudoedit /etc/mysql57.cnf，写入：

[mysqld]
user=mysql57
basedir=/opt/mysql57
datadir=/var/lib/mysql57
port=3306
bind-address=127.0.0.1
socket=/var/lib/mysql57/mysql.sock
pid-file=/var/lib/mysql57/mysql.pid
log-error=/var/log/mysql57/error.log
character-set-server=utf8mb4
collation-server=utf8mb4_general_ci
explicit_defaults_for_timestamp=1

[client]
socket=/var/lib/mysql57/mysql.sock
default-character-set=utf8mb4

仅在数据目录为空时执行一次：

sudo /opt/mysql57/bin/mysqld --defaults-file=/etc/mysql57.cnf --initialize --user=mysql57
sudo grep 'temporary password' /var/log/mysql57/error.log

记录本机生成的 root 临时密码，下一步首次登录时修改。不要把该日志或密码粘贴到公开问题记录。

1.3、配置 systemd

执行 sudoedit /etc/systemd/system/mysql57.service：

[Unit]
Description=MySQL 5.7 for qOntology
After=network.target

[Service]
Type=simple
User=mysql57
Group=mysql57
ExecStart=/opt/mysql57/bin/mysqld --defaults-file=/etc/mysql57.cnf
Restart=on-failure
TimeoutStopSec=300
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

# 加载服务定义，启动 MySQL 并设置开机自启
sudo systemctl daemon-reload
sudo systemctl enable --now mysql57

# 确认服务状态后，使用临时密码登录并准备修改密码
sudo systemctl status mysql57 --no-pager
MYSQL_HISTFILE=/dev/null /opt/mysql57/bin/mysql --defaults-file=/etc/mysql57.cnf -uroot -p --connect-expired-password

输入临时密码进入 MySQL 后执行，先替换新密码；如密码包含单引号，按 SQL 字符串规则转义：

ALTER USER 'root'@'localhost' IDENTIFIED BY '<MySQL管理员新密码>';
SELECT VERSION();
EXIT;

应用账号将在数据初始化中创建，API 不使用 root 连接。

二、Redis 6.x

2.1、安装与配置

# 安装 Redis 并核对版本
sudo apt install -y redis-server
redis-server --version

# 编辑缓存服务的监听、认证和持久化配置
sudoedit /etc/redis/redis.conf

确认安装的是 6.x。编辑文件中对应配置项，修改原值，不重复追加：

bind 127.0.0.1 ::1
protected-mode yes
port 6379
requirepass <Redis密码>
dir /var/lib/redis
appendonly yes

密码包含空格或特殊字符时，按 Redis 配置字符串规则加双引号并转义。保留软件包自带的 systemd、日志及进程管理配置；数据目录由 Redis 用户持有。AOF 用于持久化，备份空间仍需独立规划。

2.2、启动与验证

# 设置开机自启，并重启 Redis 使配置生效
sudo systemctl enable redis-server
sudo systemctl restart redis-server

# 查看服务状态，通过密码认证检查连接
sudo systemctl status redis-server --no-pager
redis-cli -h 127.0.0.1 -p 6379 --askpass PING

按提示输入密码，预期返回 PONG。qOntology 使用 Redis 的 3 号逻辑库，后续配置保持一致。失败时检查 journalctl -u redis-server 和 /var/log/redis/redis-server.log。

三、Neo4j Community 4.4.40

3.1、下载与目录准备

从 Neo4j 历史版本选择 Community 4.4.40 Linux tar 包，或使用该版本官方分发地址：

# 进入下载目录，获取指定版本的 Neo4j 安装包
cd "$HOME/qontology-packages"
curl -fLO https://dist.neo4j.org/neo4j-community-4.4.40-unix.tar.gz

# 创建服务用户，准备安装目录并解压
sudo useradd --system --user-group --home-dir /var/lib/neo4j --shell /usr/sbin/nologin neo4j
sudo install -d /opt/neo4j
sudo tar -xzf neo4j-community-4.4.40-unix.tar.gz -C /opt/neo4j --strip-components=1

# 准备数据、日志及运行目录，并赋予服务用户写入权限
sudo install -d -o neo4j -g neo4j -m 750 /var/lib/neo4j /var/log/neo4j /opt/neo4j/run
sudo chown -R neo4j:neo4j /opt/neo4j/run

3.2、配置 Java、数据目录与连接

执行 sudoedit /opt/neo4j/conf/neo4j.conf，修改原有对应项：

dbms.directories.data=/var/lib/neo4j
dbms.directories.logs=/var/log/neo4j
dbms.directories.run=/opt/neo4j/run
dbms.default_listen_address=127.0.0.1
dbms.default_advertised_address=127.0.0.1
dbms.connector.bolt.enabled=true
dbms.connector.bolt.listen_address=:7687
dbms.connector.http.enabled=true
dbms.connector.http.listen_address=:7474
dbms.connector.https.enabled=false
dbms.memory.heap.initial_size=512m
dbms.memory.heap.max_size=2G
dbms.memory.pagecache.size=1G

内存值为起步示例，需结合整机剩余内存与图数据规模调整。不要给每个服务都分配整机内存。首次启动前设置密码，命令在 Bash 中执行：

# 读取初始密码，输入过程不回显
read -rsp 'Neo4j 初始密码: ' NEO4J_INITIAL_PASSWORD
printf '\n'

# 使用 Java 17 为新库设置密码，完成后清除临时变量
sudo -u neo4j env JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
  /opt/neo4j/bin/neo4j-admin set-initial-password "$NEO4J_INITIAL_PASSWORD"
unset NEO4J_INITIAL_PASSWORD

此操作用于新库，不用于重设已有数据库密码。

3.3、服务管理与验证

执行 sudoedit /etc/systemd/system/neo4j.service：

[Unit]
Description=Neo4j for qOntology
After=network.target

[Service]
Type=simple
User=neo4j
Group=neo4j
Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
WorkingDirectory=/opt/neo4j
ExecStart=/opt/neo4j/bin/neo4j console
Restart=on-failure
LimitNOFILE=60000
TimeoutStopSec=120

[Install]
WantedBy=multi-user.target

# 加载服务定义，启动 Neo4j 并设置开机自启
sudo systemctl daemon-reload
sudo systemctl enable --now neo4j

# 检查服务状态，使用 Java 17 打开图数据库查询终端
sudo systemctl status neo4j --no-pager
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
  /opt/neo4j/bin/cypher-shell -a bolt://127.0.0.1:7687 -u neo4j

输入密码后执行 RETURN 1;，应返回 1；使用 :exit 退出。HTTP 验证可在服务器执行 curl -I http://127.0.0.1:7474/，不要为远程访问临时把图数据库直接开放到公网。

四、kkFileView 4.4.0

4.1、获取固定版本产物

使用 kkFileView 4.4.0 官方发布页提供的 Linux 发行包。若发布页没有直接可获取的二进制包，可在已准备 Maven 的构建机器执行以下源码构建；此过程需要访问该项目依赖仓库：

# 获取 kkFileView 4.4.0 源码并进入项目目录
git clone --branch v4.4.0 --depth 1 https://github.com/kekingcn/kkFileView.git kkFileView-4.4.0
cd kkFileView-4.4.0

# 使用 Java 17 构建，跳过测试执行
env JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
  PATH="/usr/lib/jvm/java-17-openjdk-amd64/bin:$PATH" \
  mvn clean package -DskipTests

# 确认构建产物与对应版本的配置文件存在
test -f server/target/kkFileView-4.4.0.jar
test -f server/src/main/config/application.properties

-DskipTests 跳过测试执行，构建成功不代表测试通过。将上述 JAR 和同一标签的 application.properties 上传到服务器的 ~/qontology-packages/kkfileview/。使用发行包时，从解压目录的 bin/、config/ 获取同名文件放到这个暂存目录；不要混入 5.x 配置。

4.2、安装 Office 与服务文件

# 安装 Office 转换组件及中文字体，并检查 Office 版本
sudo apt install -y libreoffice fonts-noto-cjk
libreoffice --version

# 创建服务用户及安装、数据和日志目录
sudo useradd --system --user-group --home-dir /var/lib/kkfileview --shell /usr/sbin/nologin kkfileview
sudo install -d /opt/kkfileview/bin /opt/kkfileview/config
sudo install -d -o kkfileview -g kkfileview -m 750 /var/lib/kkfileview /var/lib/kkfileview/files /var/log/kkfileview

# 安装 JAR 和配置文件，再编辑预览服务配置
sudo install -m 644 "$HOME/qontology-packages/kkfileview/kkFileView-4.4.0.jar" /opt/kkfileview/bin/
sudo install -o root -g kkfileview -m 640 "$HOME/qontology-packages/kkfileview/application.properties" /opt/kkfileview/config/
sudoedit /opt/kkfileview/config/application.properties

修改原有对应项，其余配置保留 4.4.0 原文件：

server.port=8012
server.address=127.0.0.1
server.servlet.context-path=/kkfileview
office.home=/usr/lib/libreoffice
file.dir=/var/lib/kkfileview/files/
cache.type=jdk
base.url=http://<服务器IP>:8897/kkfileview/
trust.host=<服务器IP>
file.upload.disable=true

trust.host 填浏览器实际使用的主机名或 IP，不带协议和端口；使用多个访问域名时按该版本规则用逗号分隔。该限制应与文件来源一致。这里保留应用内的预览入口，关闭 kkFileView 首页独立上传功能。修改 base.url、上下文路径后需要重启。4.4.0 配置定义

4.3、配置 systemd 并启动

执行 sudoedit /etc/systemd/system/kkfileview.service：

[Unit]
Description=kkFileView for qOntology
After=network.target

[Service]
Type=simple
User=kkfileview
Group=kkfileview
Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
Environment=HOME=/var/lib/kkfileview
Environment=KKFILEVIEW_BIN_FOLDER=/opt/kkfileview/bin
WorkingDirectory=/opt/kkfileview/bin
ExecStart=/usr/lib/jvm/java-17-openjdk-amd64/bin/java -Xms512m -Xmx1024m -Dfile.encoding=UTF-8 -Dspring.config.location=/opt/kkfileview/config/application.properties -jar /opt/kkfileview/bin/kkFileView-4.4.0.jar
Restart=on-failure
TimeoutStopSec=120

[Install]
WantedBy=multi-user.target

# 加载服务定义，启动预览服务并设置开机自启
sudo systemctl daemon-reload
sudo systemctl enable --now kkfileview

# 检查服务状态、初始化日志和 HTTP 响应
sudo systemctl status kkfileview --no-pager
sudo journalctl -u kkfileview -n 100 --no-pager
curl -I http://127.0.0.1:8012/kkfileview/

Office 初次启动可能需要较长时间。此时只检查服务响应与转换进程初始化，完整 Office/PDF 预览在 Nginx 和应用部署后验证。Java 堆上限不包含 LibreOffice 子进程的内存。

五、中间件检查清单

服务	检查方式	预期结果
MySQL	登录后 `SELECT VERSION();`	5.7.44，管理员认证正常
Redis	`redis-cli --askpass PING`	`PONG`
Neo4j	cypher-shell 执行 `RETURN 1;`	返回 1
kkFileView	请求 `/kkfileview/`、查看 journal	HTTP 服务可响应，Office 初始化无错误

通过 sudo ss -lntp 确认监听地址和端口。使用 sudo systemctl stop <服务名> 停止、sudo systemctl restart <服务名> 重启；MySQL 错误日志在 /var/log/mysql57/，Neo4j 日志在 /var/log/neo4j/，kkFileView 控制台日志由 journal 收集。

下一步：数据初始化。