跳至主要內容

qOntology 服务部署

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

执行本页前，完成中间件部署和数据初始化，并准备应用构建交付的 JAR 与前端文件。以下命令在 Ubuntu 22.04 x86_64 运行服务器执行。

一、准备目录与运行用户

暂存目录应如下所示，web/ 下直接包含前端文件，不再嵌套一层 dist/：

~/qontology-release/
├── qontology-server.jar
└── web/
    ├── index.html
    └── …

首次部署执行：

# 检查后端 JAR 和前端入口文件是否存在且非空
test -s "$HOME/qontology-release/qontology-server.jar"
test -s "$HOME/qontology-release/web/index.html"

# 创建服务运行用户和同名用户组，禁止交互登录
sudo useradd --system --user-group --home-dir /var/lib/qontology --shell /usr/sbin/nologin qontology

# 创建部署目录；配置由 root 管理，数据和日志目录允许服务用户写入
sudo install -d -m 755 /opt/qontology /opt/qontology/server /opt/qontology/web
sudo install -d -o root -g qontology -m 750 /opt/qontology/config
sudo install -d -o qontology -g qontology -m 750 /var/lib/qontology /var/lib/qontology/upload /var/log/qontology

# 复制后端和前端产物，并设置前端目录及文件的读取权限
sudo install -m 644 "$HOME/qontology-release/qontology-server.jar" /opt/qontology/server/
sudo cp -R "$HOME/qontology-release/web/." /opt/qontology/web/
sudo find /opt/qontology/web -type d -exec chmod 755 {} +
sudo find /opt/qontology/web -type f -exec chmod 644 {} +

# 将应用的 logs 目录链接到统一日志目录
sudo ln -s /var/log/qontology /opt/qontology/server/logs

源码的 Logback 配置写入工作目录下的 logs/，因此这里将其链接到 /var/log/qontology/。已有 logs 文件或目录时先确认内容，不强制覆盖链接。运行用户只需写入数据与日志目录，JAR、前端和配置由部署管理员维护。

二、配置后端

2.1、外置配置加载方式

项目内置 application.yml 会导入生产环境及 AI、文件存储、系统、图数据库等模块配置。启动时使用：

--spring.profiles.active=prod
--spring.config.additional-location=file:/opt/qontology/config/deploy.yml

保留内置配置作为基础，由 deploy.yml 覆盖本机部署值。不要把 spring.config.location 直接替换成只有连接信息的小文件，也不要假定在外部放置同名模块 YAML 就会替代内置的 classpath: 导入。Spring Boot 外置配置说明

2.2、编写部署覆盖文件

执行 sudoedit /opt/qontology/config/deploy.yml，写入以下内容。所有密码分别对应前文实际设置的值；YAML 单引号内若含单引号，用两个单引号转义。<独立随机签名密钥> 可使用 openssl rand -hex 32 生成后填入，不能保留占位符。

server:
  address: 127.0.0.1
  port: 8097
  forward-headers-strategy: framework

qontology:
  profile: /var/lib/qontology/upload/
  ai:
    enabled: true
    vector-store: memory

datasource:
  type: mysql

spring:
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      database: 3
      password: '<Redis密码>'
  datasource:
    druid:
      stat-view-servlet:
        enabled: false
    dynamic:
      primary: master
      datasource:
        master:
          driver-class-name: com.mysql.cj.jdbc.Driver
          url: 'jdbc:mysql://127.0.0.1:3306/qontology?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai'
          username: qontology
          password: '<MySQL应用密码>'

graphis:
  type: neo4j
neo4j:
  uri: bolt://127.0.0.1:7687
  user: neo4j
  password: '<Neo4j密码>'

dromara:
  x-file-storage:
    default-platform: local
    local-plus:
      - platform: local
        enable-storage: true
        enable-access: false
        domain: ''
        path-patterns: /**
        base-path: /
        storage-path: /var/lib/qontology/upload/
    aliyun-oss:
      - platform: unused-oss
        enable-storage: false
        access-key: ''
        secret-key: ''
        end-point: ''
        bucket-name: ''
        domain: ''

token:
  secret: '<独立随机签名密钥>'
user:
  password:
    universalPassword: ''
springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false
knife4j:
  enable: false

这里直接覆盖 spring.datasource.dynamic.datasource.master，避免仍引用包内示例数据库地址；Neo4j 使用项目实际的顶层 neo4j.uri/user/password，不是另一套 spring.neo4j 配置。

文件存储保留相对地址，qontology.profile 和 storage-path 指向同一上传目录。文件服务代码使用 /profile/ 生成访问路径，因此后面同时配置此路径的反向代理。server.forward-headers-strategy 配合 Nginx 转发头，使生成的文件地址保留外部主机和 8897 端口。

示例关闭未配置的 OSS、内置通用登录口令和接口文档页面。AI 服务保留启用并使用 memory 向量存储，避免基础部署依赖外部 Weaviate；内存向量重启后丢失，模型调用也仍需另行配置有效模型和密钥。需要持久化向量时，按项目 qontology.ai.weaviate 配置接入，勿照搬包内示例地址。

保存后收紧配置文件权限：

# 设置配置文件的所有者及权限，仅允许 root 修改、服务用户组读取
sudo chown root:qontology /opt/qontology/config/deploy.yml
sudo chmod 640 /opt/qontology/config/deploy.yml

# 以服务用户身份检查配置可读、上传目录可写
sudo -u qontology test -r /opt/qontology/config/deploy.yml
sudo -u qontology test -w /var/lib/qontology/upload

三、启动 qOntology API

3.1、配置 systemd

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

[Unit]
Description=qOntology API
Wants=network-online.target
After=network-online.target mysql57.service redis-server.service neo4j.service

[Service]
Type=simple
User=qontology
Group=qontology
WorkingDirectory=/opt/qontology/server
Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
ExecStart=/usr/lib/jvm/java-17-openjdk-amd64/bin/java -Xms512m -Xmx2g -Dfile.encoding=UTF-8 -jar /opt/qontology/server/qontology-server.jar --spring.profiles.active=prod --spring.config.additional-location=file:/opt/qontology/config/deploy.yml
Restart=on-failure
RestartSec=10
TimeoutStopSec=120
UMask=0027

[Install]
WantedBy=multi-user.target

After 仅表示启动顺序，不保证数据库已经可接受连接。首次启动前先完成中间件验证；Java 堆上限也不是 API 进程的全部内存需求。

3.2、启动与检查

# 重新加载服务定义，启动 API 并设置开机自启
sudo systemctl daemon-reload
sudo systemctl enable --now qontology

# 查看服务状态和最近的启动日志
sudo systemctl status qontology --no-pager
sudo journalctl -u qontology -n 100 --no-pager

# 检查 API 监听端口与验证码接口响应
sudo ss -lntp | grep ':8097'
curl -sS http://127.0.0.1:8097/captchaImage

确认日志激活的是 prod，端口为 8097，无数据库、Redis、Neo4j 认证或配置加载错误。验证码接口应返回应用 JSON；接口返回值需结合当前版本判断，不仅以端口打开作为启动成功。日志默认位于 /var/log/qontology/，启动阶段异常也可从 journal 查看。

四、部署 Nginx 与前端

4.1、安装与站点配置

# 安装 Nginx 并查看版本
sudo apt install -y nginx
nginx -v

# 编辑本站点配置，内容见下方示例
sudoedit /etc/nginx/sites-available/qontology

写入以下站点配置。此文件通过 Ubuntu 默认 sites-enabled 在 http 上下文加载，不替换整份 /etc/nginx/nginx.conf：

server {
    listen 8897;
    server_name _;
    root /opt/qontology/web;
    index index.html;
    client_max_body_size 100m;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /prod-api/ {
        proxy_pass http://127.0.0.1:8097/;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 600s;
    }

    location /websocket/ {
        proxy_pass http://127.0.0.1:8097;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 600s;
    }

    location /profile/ {
        proxy_pass http://127.0.0.1:8097;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /kkfileview/ {
        proxy_pass http://127.0.0.1:8012;
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 600s;
    }
}

/prod-api/ 的 proxy_pass 末尾有 /，用于去除接口前缀；其他三条保留原路径。/profile/ 转发至现有文件资源处理，不将整个应用或配置目录暴露为静态目录。上传大小在 Nginx、API 和预览服务之间需要匹配，本例入口限制为 100 MB。

4.2、启用与验证

# 启用站点并检查 Nginx 配置语法
sudo ln -s /etc/nginx/sites-available/qontology /etc/nginx/sites-enabled/qontology
sudo nginx -t

# 配置检查通过后启动 Nginx，设置开机自启并加载站点配置
sudo systemctl enable --now nginx
sudo systemctl reload nginx

# 通过统一入口验证首页与业务接口
curl -I http://127.0.0.1:8897/
curl -sS http://127.0.0.1:8897/prod-api/captchaImage

已存在同名链接时检查目标，不重复创建。nginx -t 失败时先修复配置，不继续重载。防火墙或云安全组仅向需要访问的客户端放行 TCP 8897；保持数据库等内部端口不对外开放。

五、访问与功能验证

浏览器打开 http://<服务器IP>:8897。登录账号和初始口令以同版本发布说明或交付记录为准，首次登录后修改初始口令。

验证项操作与预期结果
页面资源登录页正常显示，JS/CSS 无 404；刷新业务页面仍能显示
业务接口/prod-api/ 请求返回应用响应，不是 Nginx 502 或前端 HTML
登录与权限使用有效账号登录，菜单及授权页面正常加载
图数据库执行有权限的图查询，连接和认证正常；空图没有演示节点属于正常情况
WebSocket检查页面实际发起的 /websocket/ 请求，握手成功并保持连接
文件访问上传一个测试文件，返回地址指向实际站点的 /profile/，可按应用权限设计访问
文件预览分别测试 PDF 和 Office 文件，预览页及转换后资源均从 /kkfileview/ 加载

预览服务需要从服务器侧获取上传接口返回的文件 URL。在运行服务器用 curl -I '实际文件URL' 检查路由和可达性，URL 中不要残留容器服务名、开发地址或错误端口。如果文件需要认证，必须按该版本预览机制传递授权或提供受控文件访问方式，不能仅以浏览器已登录推断 kkFileView 也能下载文件。

AI 抽取、问答与向量检索还需要对应模型配置和凭据；基础页面能访问不等于这些能力已经可用。本例没有安装本地模型或 Weaviate，也不要求本机 GPU。

六、日常启停与排障

启动时先检查 MySQL、Redis、Neo4j，再启动 API、预览和入口：

# 先启动数据库、缓存和图数据库
sudo systemctl start mysql57 redis-server neo4j

# 完成前页的连接验证后继续
sudo systemctl start qontology kkfileview nginx

维护停机先停止应用入口与应用，再停止数据服务。本命令假设 Nginx 专用于本部署；若承载其他站点，应仅维护本站点：

# 先停止入口、API 和文件预览服务
sudo systemctl stop nginx qontology kkfileview

# 应用停止后，再停止图数据库、缓存和关系数据库
sudo systemctl stop neo4j redis-server mysql57
现象优先检查
API 无法启动journal 中首个异常、Java 17、prod 环境、外置文件权限和 YAML 缩进
MySQL 连接失败3306、应用账号授权、数据库名、密码及初始化是否完成
Redis 认证失败Redis 配置与 API 密码是否一致，是否使用 3 号逻辑库
图数据库连接失败Java 17、Neo4j 日志、Bolt 7687 及顶层 neo4j.* 配置
Nginx 502API/预览是否启动、上游端口、/var/log/nginx/error.log
页面刷新 404前端目录层级、资源文件及 try_files 回退规则
WebSocket 失败路径是否保留、HTTP 1.1 和 Upgrade/Connection 头
上传文件地址错误转发头、外部端口、/profile/ 代理、两个上传目录是否一致
预览资源 404base.url、/kkfileview 上下文、转发是否保留路径
Office 转换失败LibreOffice 路径、字体、服务用户 HOME/目录权限和剩余内存

修改 API 覆盖配置后执行 sudo systemctl restart qontology；修改 kkFileView 配置后重启 kkfileview；修改 systemd 文件后先执行 sudo systemctl daemon-reload。更新前端环境变量需重新构建，再替换静态资源。

本系列完成的是单机原生部署流程。正式运行前应按实际数据与负载检查备份、磁盘增长及资源配置，参考部署服务器资源规格参考。返回自主部署目录。

最近更新：