qOntology サービスのデプロイ

先にミドルウェアのデプロイとデータの初期化を完了し、アプリケーションのビルドで生成した JAR とフロントエンドを準備します。以下は Ubuntu 22.04 x86_64 の 実行サーバーで実行してください。

1. ディレクトリと実行ユーザーの準備

一時配置ディレクトリは次の構成にします。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. バックエンドの設定

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 の単一引用符内に単一引用符がある場合は 2 個に重ねてエスケープします。<RANDOM_SIGNING_SECRET> は 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_PASSWORD>'
  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_APP_PASSWORD>'

graphis:
  type: neo4j
neo4j:
  uri: bolt://127.0.0.1:7687
  user: neo4j
  password: '<NEO4J_PASSWORD>'

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: '<RANDOM_SIGNING_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 の転送ヘッダーにより、生成 URL に外部ホストと 8897 を保持します。

未設定の OSS、組み込みの共通ログインパスワード、API ドキュメントは無効化します。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

3. 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 の待ち受けポートと CAPTCHA エンドポイントの応答を確認
sudo ss -lntp | grep ':8097'
curl -sS http://127.0.0.1:8097/captchaImage

ログで prod が有効、ポートが 8097 であり、データベース・Redis・Neo4j の認証や設定読み込みにエラーがないことを確認します。CAPTCHA はアプリケーションの JSON を返す必要があり、内容は対象バージョンに応じて判断してください。ポートが開くだけでは起動成功とは判断できません。ログは既定で /var/log/qontology/ にあり、起動例外は journal でも確認できます。

4. 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 末尾の / は API プレフィックスを除去します。他の 3 経路は元のパスを保持します。/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

# 共通入口からトップページと業務 API を確認
curl -I http://127.0.0.1:8897/
curl -sS http://127.0.0.1:8897/prod-api/captchaImage

同名リンクがある場合は再作成せず、リンク先を確認します。nginx -t が失敗したら、再読み込み前に修正してください。ファイアウォールやクラウドのセキュリティグループでは、必要なクライアントにのみ TCP 8897 を許可し、データベースなどの内部ポートは公開しません。

5. アクセスと機能の検証

ブラウザーで http://<SERVER_IP>:8897 を開きます。ログイン情報と初期パスワードは同一リリースの説明または納品記録を確認し、初回ログイン後に変更してください。

確認項目	操作と期待結果
ページリソース	ログイン画面が表示され、JS／CSS に 404 がなく、業務画面を再読み込みしても表示できる
業務 API	/prod-api/ がアプリケーション応答を返し、Nginx 502 やフロントエンド HTML にならない
ログインと権限	有効なアカウントでログインでき、メニューと許可されたページが正常に読み込まれる
グラフデータベース	権限のあるクエリで接続・認証が成功。空のグラフにデモノードがないのは正常
WebSocket	実際の /websocket/ リクエストでハンドシェイクが成功し、接続が維持される
ファイルアクセス	テストファイルをアップロードし、URL が実サイトの /profile/ を指し、権限設計に従ってアクセスできる
ファイルプレビュー	PDF と Office を個別に試し、プレビュー画面と変換済みリソースが /kkfileview/ から読み込まれる

プレビューサービスは、アップロード API が返すファイル URL をサーバー側から取得する必要があります。実行サーバーで curl -I 'ACTUAL_FILE_URL' を実行し、経路と到達性を確認します。URL にコンテナーサービス名、開発用アドレス、誤ったポートを残さないでください。認証が必要なファイルは、対象バージョンのプレビュー方式に従って認可情報を渡すか、制御された取得方法を用意します。ブラウザーでログイン済みでも kkFileView が取得できるとは限りません。

AI 抽出、質問応答、ベクトル検索には対応するモデル設定と認証情報も必要です。基本画面が開くだけでは、これらが利用可能とは限りません。この例ではローカルモデルと Weaviate はインストールせず、ローカル GPU も不要です。

6. 日常の起動・停止とトラブル対応

起動時は先に 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 502	API・プレビューの起動、上流ポート、/var/log/nginx/error.log
再読み込みで 404	フロントエンドのディレクトリ階層、リソース、try_files
WebSocket 失敗	パス保持、HTTP 1.1、Upgrade／Connection ヘッダー
アップロード URL が不正	転送ヘッダー、外部ポート、/profile/、両アップロードディレクトリの一致
プレビューリソース 404	base.url、/kkfileview コンテキスト、パス保持
Office 変換失敗	LibreOffice パス、フォント、実行ユーザーの HOME・権限、空きメモリ

API の上書き設定変更後は sudo systemctl restart qontology、kkFileView 設定変更後は kkfileview を再起動します。systemd ファイルの変更後は先に sudo systemctl daemon-reload を実行してください。フロントエンドの環境変数は再ビルドしてから静的リソースを置き換えます。

以上が単一サーバーのネイティブデプロイ手順です。本番運用前に実データと負荷に基づき、バックアップ、ディスク増加量、リソース配分を確認してください。サーバーリソース仕様の目安を参照し、手動デプロイ目次に戻れます。