メインコンテンツへスキップ

ソースコードからローカル起動

千桐テクノロジー2026/11/01約8分デプロイソースからの起動結合検証開発

機能の結合検証や日常開発に向けて、qOntology をソースからローカル起動する手順を説明します。環境準備、ミドルウェア起動、バックエンド設定、フロントエンド起動を順に完了すると、ブラウザーからアクセスできます。

本ページの起動方式

MySQL、Redis、Neo4j、kkFileView は Docker で実行し、qOntology バックエンドは IntelliJ IDEA、フロントエンドは Vite 開発サーバーで実行します。すべて同じ開発マシン上に配置し、コンテナー版 API と Nginx は起動しません。

システム全体を直接デプロイする場合は Docker Compose によるデプロイ、サーバーにネイティブインストールする場合は手動デプロイを参照してください。

1. 前提条件

1.1. 開発環境の準備

Git、IntelliJ IDEA、下表の開発ツールをインストールします。コンテナー、IDEA、Java、フロントエンドビルドに必要なメモリとディスクを確保し、Docker Desktop の割り当てもミドルウェアの必要量を満たしてください。サーバーの容量計画はリソース仕様の目安を参照できます。

OSDocker 環境とコマンド
LinuxDocker Engine と Compose プラグインをインストールし、現在のユーザーがエンジンに接続できることを確認
macOSIntel／Apple Silicon に対応した Docker Desktop をインストールし、起動後にエンジンの準備を待つ
WindowsDocker Desktop をインストール・起動し、Linux コンテナーを使用。コマンドは PowerShell で実行

Apple Silicon などの ARM では、特に MySQL 5.7 を含む全イメージの対応アーキテクチャを確認してください。不一致の場合は互換性のある x86_64 開発環境を使用するか、選んだイメージの適合性を先に検証します。データベースのメジャーバージョンを安易に置き換えないでください。

1.2. Docker の確認

docker version
docker compose version
docker info

Docker Client と Server に接続でき、Compose が 2.23.2 以上であることを確認します。本ページは空白区切りの docker compose を使用します。構成は include を使用するため、旧 docker-compose の方法をそのまま適用しないでください。

2. バージョン要件

本ページでは以下のツール構成を使用します。Java はソースルートの pom.xml に合わせ、Maven と Node.js はアプリケーションのビルドガイドと同じ推奨バージョンです。

コンポーネントバージョン・要件
JDK17
Maven3.9.x 推奨
Node.js22.x 推奨
npmNode.js に同梱のバージョン
Gitプロジェクトを正常にクローンできること
Dockerリポジトリが必要とする Linux イメージを実行できること
Docker Compose2.23.2 以上

端末で確認します。

java -version
mvn -version
node -v
npm -v
git --version

java -version と mvn -version の Java は、どちらも 17 であることを確認します。IDEA の Project SDK、Maven インポート、バックエンドの実行環境を JDK 17 に設定し、端末、IDEA、Maven、バックエンドで使用する JDK を統一してください。

3. qOntology リポジトリのクローン

git clone https://gitee.com/qiantongtech/qOntology.git
cd qOntology
git rev-parse HEAD

ソースが既にある場合はルートに移動し、現在のコミットを記録します。指定バージョンが必要なら先にタグまたはコミットへ切り替え、バックエンド、フロントエンド、設定、初期化 SQL を同じバージョンに揃えます。

主なディレクトリは以下のとおりです。

qOntology/
├── pom.xml
├── docker/
│   ├── .env
│   ├── docker-compose.yml
│   ├── docker-compose-base.yml
│   ├── docker-compose-qontology.yml
│   └── qOntology/mysql/init/
│       ├── init-system.sql
│       └── init-show.sql
├── qontology-server/          # バックエンド起動モジュール
├── qontology-framework/       # AI、ファイル保存、グラフデータベースなどの設定
└── qontology-ui/              # フロントエンドプロジェクト

以降の「ソースルート」は最上位の pom.xml がある qOntology/ を指します。ドキュメントサイトや qontology-server/ ではありません。

4. Docker Compose でミドルウェアを起動

4.1. 接続情報の確認

ミドルウェアはリポジトリの docker/ 構成を使用します。.env と docker-compose-base.yml を確認し、バックエンドの接続には ホスト側ポートを使用します。

ミドルウェアホスト側アドレス用途
MySQL 5.7127.0.0.1:33067qontology データベース
Redis 6127.0.0.1:63897キャッシュ。バックエンドは論理データベース 3 を使用
Neo4j 4.4.40bolt://127.0.0.1:17687グラフデータベース接続
Neo4j Browserhttp://localhost:17474グラフ管理画面
kkFileViewhttp://localhost:8017/kkfileview/ファイルプレビュー

MySQL パスワードは docker-compose-base.yml の mysql57.environment.MYSQL_ROOT_PASSWORD、Redis は .env の REDIS_PASSWORD、Neo4j は neo4j.environment.NEO4J_AUTH の username/password 形式から確認します。後述の YAML のプレースホルダーは、起動前に実際のローカル値へ置き換えてください。

パスワードを変更したら、サービス認証とヘルスチェックも確認します。初期化用環境変数を変更しても既存のデータベースパスワードは自動変更されません。ポート変更時はバックエンド接続やフロントエンドプロキシも更新してください。

4.2. 起動と確認

ソースルートから docker/ に移動して実行します。

cd docker
docker compose -p qontology --profile base config -q
docker compose -p qontology --profile base up -d mysql57 redis neo4j kkfileview
docker compose -p qontology --profile base ps -a

本手順は 4 サービスを明示指定します。名前を省略して base 全体を起動しないでください。そこにはコンテナー版 API と Nginx も含まれます。完全デプロイ用の all も不要です。

初回はイメージ取得とサービス初期化が行われます。4 サービスすべてが healthy になるまで待ち、必要に応じてログを確認します。

docker compose -p qontology --profile base logs -f --tail=100 mysql57 redis neo4j kkfileview

Ctrl+C はログ表示のみ終了し、コンテナーは停止しません。イメージ取得失敗、再起動の繰り返し、ヘルスチェック失敗は、バックエンド起動前に解消してください。

4.3. 初回初期化の確認

MySQL は 空のデータディレクトリでの初回起動時に、マウントされた init-system.sql と init-show.sql を自動実行し、システム・業務テーブルを準備します。別の初期化スクリプトを手動で追加インポートする必要はありません。

docker/ からデータベースクライアントを開き、要求に従って MySQL パスワードを入力します。

docker compose -p qontology --profile base exec mysql57 mysql -uroot -p qontology

MySQL 内で確認します。

SHOW TABLES;
SELECT COUNT(*) AS system_users FROM system_user;
EXIT;

既存環境を再初期化しない

初期化 SQL はテーブルを削除・再作成します。既存のデータディレクトリは自動再初期化されません。通常の接続エラーを、SQL 再インポート、リセットスクリプト、ボリューム削除で修復しないでください。過去の初期化ファイルや全アップグレードスクリプトの追加実行も避けてください。

Neo4j は既存のマウント先で起動します。本手順はデモグラフを自動復元しません。新規データベースにノードがなくても起動失敗ではありません。

5. バックエンドの設定と起動

5.1. IDEA でプロジェクトを開く

IntelliJ IDEA でソースルートを開き、最上位の pom.xml から Maven プロジェクトをインポートして、依存関係の取得を待ちます。Project SDK と Maven が JDK 17 であることを確認します。

バックエンドの既定 HTTP ポートは 8099、主設定は qontology-server/src/main/resources/application.yml です。有効なプロファイルに応じてサーバー、AI、ファイル保存、システム、グラフ設定をインポートします。ローカルでは dev を使用します。

5.2. MySQL と Redis の設定

qontology-server/src/main/resources/application-dev.yml の 既存の該当ノード内を編集し、他のプール設定は維持します。2 つ目の spring: や mysql: を追記しないでください。

datasource:
  type: mysql

mysql:
  driver-class-name: com.mysql.cj.jdbc.Driver
  url: 'jdbc:mysql://127.0.0.1:33067/qontology?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai'
  username: root
  password: '<MYSQL_PASSWORD>'

spring:
  data:
    redis:
      host: 127.0.0.1
      port: 63897
      database: 3
      password: '<REDIS_PASSWORD>'

既存の spring.datasource.dynamic.datasource.master は datasource.type 経由でデータベース設定を参照するため、その参照を維持します。ここでの root は標準のローカル開発初期化に対応します。アプリケーション用アカウントを作成済みならその認証情報を指定し、qontology への権限を確認してください。

5.3. Neo4j の設定

qontology-framework/qontology-graphis/qontology-graphis-starter/src/main/resources/application-graphis-dev.yml の既存ノードを編集します。

graphis:
  type: neo4j

neo4j:
  uri: bolt://127.0.0.1:17687
  user: neo4j
  password: '<NEO4J_PASSWORD>'

本プロジェクトはトップレベルの neo4j.* を使用します。Java はホスト上で動くため、コンテナー内部の 7687 ではなく、マッピング後の 17687 に接続します。

5.4. ローカルファイル保存の設定

application.yml のアップロード先を確認します。

qontology:
  profile: ${user.dir}/upload/

qontology-framework/qontology-file/src/main/resources/application-file-dev.yml の対応ノードを確認・編集します。

dromara:
  x-file-storage:
    default-platform: local
    local-plus:
      - platform: local
        enable-storage: true
        enable-access: false
        domain: ''
        path-patterns: /**
        base-path: /
        storage-path: ${user.dir}/upload/

未設定のサンプル OSS を読み込まないよう、既存の aliyun-oss の enable-storage を false にします。${user.dir} は Java プロセスの作業ディレクトリです。両アップロード先を一致させ、現在のユーザーに書き込み権限があることを確認してください。

5.5. AI 開発モードの設定

qontology-framework/qontology-ai/src/main/resources/application-ai-dev.yml の既存ノードを編集し、タイムアウトなど他の設定は維持します。

qontology:
  ai:
    enabled: true
    vector-store: memory

ローカル起動ではインメモリのベクトル保存を使用し、Weaviate の追加インストールは不要です。バックエンド再起動でベクトルは失われます。 永続化が必要になったら、利用可能な Weaviate と認証を設定してください。AI 抽出・質問応答には実際のモデル、エンドポイント、認証情報も必要で、ログイン成功だけでは AI の動作確認にはなりません。

5.6. ビルドと起動

ソースルートで実行します。まだ docker/ にいる場合は先に cd .. を実行してください。1 行のままで Linux、macOS、PowerShell で使用できます。

mvn clean install -pl qontology-server -am -Ddocker.print.skip=true -Ddocker.build.skip=true -Ddocker.push.skip=true

-am は依存モジュールもビルドし、install は成果物をローカル Maven リポジトリに登録します。3 つの docker.*.skip はコマンド表示、イメージ作成、push を省略します。ローカル検証でテスト省略が許可される場合は -DskipTests を追加できますが、パッケージ作成成功はテスト合格を意味しません。

IDEA の実行構成を作成または確認します。

設定項目値
起動モジュールqontology-server
メインクラスtech.qiantong.qontology.server.QOntologyApplication
JREJDK 17
Working directoryqOntology ソースルートの絶対パス
Program arguments--spring.profiles.active=dev --server.port=8099 --user.password.universalPassword=

最後の引数は組み込みの共通ログインパスワードを空にし、実際のユーザーパスワードでログインさせます。起動クラスは qontology-server/src/main/java/tech/qiantong/qontology/server/QOntologyApplication.java です。

起動ログで dev の有効化、8099 の待ち受け、データベース・Redis・グラフの接続エラーが継続していないことを確認します。CAPTCHA エンドポイントを検証します。

curl -fsS http://127.0.0.1:8099/captchaImage

Windows PowerShell では curl.exe を使用します。接続失敗や HTML エラーではなく、業務 JSON が返ることを確認してください。

6. フロントエンドの設定と起動

6.1. ローカル環境変数の設定

ソースルートからフロントエンドへ移動します。

cd qontology-ui

.env.development.local を作成し、開発用サンプル設定を以下で上書きします。

VITE_APP_BASE_API=/dev-api
VITE_APP_AUTH_TYPE=client
VITE_APP_THIS_APP_URL=http://localhost:5173
VITE_APP_WEBSOCKET_API=ws://127.0.0.1:8099
VITE_APP_FILE_VIEW=/kkfileview
VITE_APP_MODE=development

client はサンプルの統合認証サービスを使わずローカルログインを行い、development は demo 画面モードの使用を避けます。VITE_* にサーバー側の秘密情報を保存しないでください。環境変数を変えたら開発サーバーを再起動します。

6.2. 開発プロキシの確認

qontology-ui/vite.config.js の server.proxy にある次の 3 プロキシを確認します。プラグインやビルドなど他の設定を維持し、対応するプロキシ項目だけを変更してください。

proxy: {
  '/dev-api': {
    target: 'http://127.0.0.1:8099',
    changeOrigin: true,
    rewrite: (p) => p.replace(/^\/dev-api/, '')
  },
  '/v3/api-docs': {
    target: 'http://127.0.0.1:8099',
    changeOrigin: true
  },
  '/kkfileview': {
    target: 'http://127.0.0.1:8017',
    changeOrigin: true
  }
}

プレビュープロキシがまだ 28012 を指している場合は、実際の Compose マッピング 8017 に変更します。kkFileView は /kkfileview コンテキストを持つため、プレフィックスを保持します。一方 /dev-api は除去してバックエンドに転送します。

6.3. 依存関係のインストールと起動

qontology-ui/ で実行します。

npm install
npm run dev -- --port 5173 --strictPort

現在のソースにはロックファイルがないため、初回は npm install を使用します。後続リリースに有効な package-lock.json がある場合は、その手順に従って npm ci を使用できます。

コマンドで 5173 を指定して既定の 80 を上書きし、ローカルドキュメントの 8080 も避けます。--strictPort は競合時にエラーとし、自動変更による URL と設定の不一致を防ぎます。端末は起動したままにし、プロキシ変更後は再起動してください。

7. qOntology へのアクセスと検証

7.1. ログインと基本機能の確認

ブラウザーで http://localhost:5173 を開きます。

ログイン情報は 同一リリースの初期化説明または納品記録を基準にしてください。公開デモのアカウントはローカル初期パスワードの根拠にはなりません。忘れた場合は対象バージョンの復旧手順に従い、他製品のリセット SQL を直接実行しないでください。

フロントエンドのプロキシも確認できます。

curl -fsS http://localhost:5173/dev-api/captchaImage

Windows は curl.exe を使用し、バックエンドの CAPTCHA と同種の業務 JSON が返ることを確認します。

確認項目合格基準
ログイン画面ページ、スタイル、CAPTCHA が正常に読み込まれる
ログインとメニュー有効なアカウントで許可されたメニューとページが表示される
プロジェクトとオントロジー権限に応じてテストプロジェクト・オントロジーデータを作成・検索できる
グラフデータベース自作データで検索・書き込みを検証し、接続・認証エラーがない
WebSocket実際の /websocket/ が 8099 に接続し、ハンドシェイクが成功
アップロードと取得小さいファイルのアップロードで到達可能な URL が返り、正常に取得できる
ファイルプレビュー次節のネットワーク確認後、PDF・Office を正常にプレビューできる
AI（任意）実際のモデル・認証情報を設定後、抽出や質問応答を検証

7.2. プレビューのネットワーク接続を確認

ブラウザーは Vite の /kkfileview で画面を開きますが、元ファイルを取得するのは kkFileView コンテナーです。アップロード結果が http://127.0.0.1:8099/profile/... の場合、127.0.0.1 はコンテナー自身を指します。ブラウザーでダウンロードできてもプレビューは失敗します。

プレビューの結合検証では次を行います。

  1. 開発マシンの LAN IP を調べ、ブラウザーと Docker コンテナーの両方からその IP の 8099 に接続できることを確認します。バックエンドをループバックのみに限定せず、ファイアウォールは必要な開発ネットワークにのみ許可します。
  2. Vite の /dev-api の target を http://<DEV_LAN_IP>:8099 にし、changeOrigin: true を維持します。アップロード処理はリクエストアドレスからファイル URL を生成するため、再アップロード時にこのホストアドレスが使用されます。
  3. フロントエンドを再起動して新しくテストファイルをアップロードし、URL に到達可能なホスト IP、8099、/profile/ が含まれることを確認します。既存のループバック URL は自動更新されません。
  4. ソースの docker/ で以下を実行し、プレースホルダーを新しいファイルの完全な URL に置き換えます。成功の HTTP ステータスを確認してからプレビューを開いてください。
docker compose -p qontology --profile base exec kkfileview curl -fI 'http://<DEV_LAN_IP>:8099/profile/<ACTUAL_FILE_PATH>'

Docker Desktop や本リポジトリで host-gateway を設定したコンテナーは、調査時に host.docker.internal でもホストへ接続できます。ただしブラウザー向け URL は、ブラウザーとコンテナー双方が解決・到達できるアドレスにしてください。ファイルに認証が必要ならプレビュー方式に沿って認可を処理し、ブラウザーのログインだけで取得可能とは判断しないでください。

8. サービス停止とよくある問題

フロントエンド端末で Ctrl+C、IDEA でバックエンドを停止します。ミドルウェアは docker/ で次のコマンドを使用し、コンテナーとデータを保持して停止・再開します。

docker compose -p qontology --profile base stop mysql57 redis neo4j kkfileview
docker compose -p qontology --profile base start mysql57 redis neo4j kkfileview

再開時はミドルウェアの正常性を確認してからバックエンドとフロントエンドを起動します。通常の停止に down -v やボリューム削除は使用しません。

現象優先確認項目
Compose が include 非対応docker compose version を確認し、必要なバージョンへ更新
イメージ取得・アーキテクチャエラーネットワーク、権限、CPU、MySQL 5.7 などの対応プラットフォーム
33067／63897 などが競合既存サービスを確認し、マッピング変更時はバックエンドも更新。内部ポートは変更しない
MySQL 接続失敗・テーブル不足mysql57 ログ、DB 名、実パスワード、両 SQL の初回実行結果
Redis 認証失敗.env とバックエンドのパスワード、論理データベース 3
Neo4j 接続失敗neo4j.*、ホストの Bolt 17687、実際の認証情報
Java ビルド・起動失敗端末・IDEA・Maven の JDK 17、最初のコンパイル・起動例外
YAML 変更が未反映dev 有効化、実際のインポート先、再ビルドと再起動
Weaviate 接続を要求されるapplication-ai-dev.yml の vector-store が memory か確認
5173 が競合不要と確認したプロセスを停止するか、起動ポート・アプリ URL・アクセス URL を同時変更
CAPTCHA・API 失敗8099 に直接接続後、/dev-api の転送先とプレフィックス除去を確認
WebSocket が 8080 に接続.env.development.local のアドレス、Vite の再起動
プレビューが開かない・404プロキシ 8017、/kkfileview、コンテナーの正常性
取得可能だがプレビュー失敗7.2 節でコンテナーから実 URL を確認し、ループバック・認証・ファイアウォールを調査
アップロード失敗・ファイル不明IDEA の作業場所、両アップロード先の一致、書き込み権限

基本開発環境を確認後、必要に応じて実モデル、永続化ベクトル保存、その他の業務サービスを接続します。サーバー用成果物を作成する場合はアプリケーションのビルドへ進んでください。

最終更新:
qOntology オープンソース本体エンジニアリングプラットフォーム — ビジネスの意味を統一し、知識とインテリジェンスをつなぐ
Copyright © 2026 千桐テクノロジー