Skip to content
Querycop Docs

Quick Start Guide Community

Querycop を最速で起動するためのガイドです。3つの方法を紹介します。

Querycop は Community（無料）でローカル評価・1 インスタンス運用ができます。 Pro 機能 (JIT / masking / Slack approval / persistent audit など) を試す 場合は 30 日 Pro trial を開始してください:

Terminal window
querycop-cli trial start --email=ops@your-company.com --company="Your Co."

token は OS の user-config dir に保存され、querycop 起動時に自動 pickup されます。詳細は configuration.md §11 と entitlements.md を参照。

システム要件

Section titled “システム要件”
項目最小要件推奨
OSLinux (x86_64/arm64), macOS, WindowsUbuntu 22.04+ / Alpine 3.19+
Go1.25+1.25+
CPU1 vCPU2+ vCPU
メモリ128MB（AI無効時）512MB〜1GB（AI有効時）
ディスク50MB（バイナリのみ）1GB+（ログ永続化時）
同時接続数目安〜50〜500
Docker24.0+24.0+

注意: AI リスク評価を有効にする場合、AI プロバイダーの API 呼び出しにより追加のメモリとネットワーク帯域が必要です。ローカル Ollama を使用する場合は、モデルサイズに応じて追加の VRAM/RAM が必要です。

Option 1: Docker Compose（推奨）

Section titled “Option 1: Docker Compose（推奨）”

最も簡単な方法です。Docker と Docker Compose がインストールされていれば、1コマンドで起動できます。

起動

Section titled “起動”
Terminal window
docker compose up -d

これにより以下が起動します：

  • PostgreSQL (ポート 5433) - テスト用バックエンドDB
  • Querycop プロキシ (ポート 15432) - クライアント接続用
  • 管理ダッシュボード (http://localhost:8080) - 承認/却下操作用

ビルドと起動

Section titled “ビルドと起動”
Terminal window
go build -o querycop ./cmd/querycop/
./querycop

接続テスト

Section titled “接続テスト”
Terminal window
psql -h 127.0.0.1 -p 15432 -U testuser -d testdb

パスワード: testpassword

動作確認

Section titled “動作確認”
  1. SELECT 1; を実行 → 正常に通過
  2. DELETE FROM users WHERE id=1; を実行 → ブロックされ、ダッシュボードに承認待ちとして表示
  3. ブラウザで http://localhost:8080 を開き、Approve/Reject をクリック

本番環境の注意: Querycop プロキシは TLS 終端を行いません。本番環境ではクライアント-プロキシ間に TLS 終端ロードバランサ（HAProxy, pgbouncer with TLS 等）を配置してください。ADMIN_API_KEY の設定も必須です。

Option 2: バイナリ直接実行

Section titled “Option 2: バイナリ直接実行”

ダウンロード

Section titled “ダウンロード”

GitHub Releases からお使いのOS用のバイナリをダウンロードしてください。

バックエンドDB準備

Section titled “バックエンドDB準備”

テスト用のPostgreSQLをDockerで起動します：

Terminal window
docker run -d --name test-db \
  -e POSTGRES_USER=testuser \
  -e POSTGRES_PASSWORD=testpassword \
  -e POSTGRES_DB=testdb \
  -p 5433:5432 \
  postgres:15-alpine

起動

Section titled “起動”
Terminal window
GATEKEEPER_LISTEN_PORT=5432 ./querycop

デフォルトではバックエンドに localhost:5433 を、管理APIに 8080 ポートを使用します。

環境変数での設定

Section titled “環境変数での設定”
Terminal window
export GATEKEEPER_BACKEND_HOST=localhost
export GATEKEEPER_BACKEND_PORT=5433
export AI_PROVIDER=ollama
./querycop

Ollamaを使用する場合、APIキーは不要です。他のプロバイダー（OpenAI, Anthropic, Gemini）を使用する場合は AI_API_KEY の設定が必要です。

Option 3: ソースからビルド

Section titled “Option 3: ソースからビルド”

前提条件

Section titled “前提条件”
  • Go 1.25以上

ビルド

Section titled “ビルド”
Terminal window
# プロキシサーバー
go build -o querycop ./cmd/querycop


# CLIツール（CI/CDレビュー用）
go build -o querycop-cli ./cmd/querycop-cli

テストの実行

Section titled “テストの実行”
Terminal window
go test ./cmd/... ./pkg/...
# または Makefile / Docker 経由
make test            # ホストの go ツールチェイン
make test-docker     # CI と同じ Linux コンテナ (Windows AppControl 回避)

注意: ./... ではなく ./cmd/... ./pkg/... を使ってください。 ローカルに landing-page/ を vendoring していると、その node_modules/ 配下に紛れ込んだ flatted パッケージの Go ファイルを go list が拾います。 Querycop の本体コードは cmd/ と pkg/ のみなので、明示するのが安全です。 Makefile / scripts/test-docker.{sh,ps1} のデフォルトは既にこの形に揃えています。

Windows + Git Bash / MSYS 利用時の注意

Section titled “Windows + Git Bash / MSYS 利用時の注意”

Windows の Git Bash (MSYS2 / MINGW) を使って docker run や kubectl に Unix 風のパス (/var/log/audit.jsonl, /tmp/foo など) を渡すと、MSYS が自動的に Windows パス (例: C:/Program Files/Git/var/log/audit.jsonl) に変換します。Querycop 自身は変換後の パスを受け取るためファイルが見つからず、以下のような起動エラーになります:

ERROR audit file logger init: open C:/Program Files/Git/var/log/audit.jsonl: no such file or directory

回避策は 3 つ:

  1. 環境変数で抑止 (最も簡単):
    Terminal window
    MSYS_NO_PATHCONV=1 docker run -e GATEKEEPER_AUDIT_FILE=/var/log/audit.jsonl ...
  2. 二重スラッシュ: パスの先頭を // にすると変換されません。
    Terminal window
    docker run -e "GATEKEEPER_AUDIT_FILE=//tmp/audit.jsonl" ...
  3. PowerShell or WSL2 で実行: いずれもパス変換は発生しません。

-v (volume mount) も同じ罠があります。コンテナ内パスを //data のように二重スラッシュ で書くか、MSYS_NO_PATHCONV=1 を付けてください。

影響範囲: Querycop の Docker / Kubernetes 設定例 (GATEKEEPER_AUDIT_FILE, GATEKEEPER_POLICY_FILE, GATEKEEPER_MASKING_FILE, GATEKEEPER_WEBHOOK_FILE, GATEKEEPER_PROXY_TLS_CERT/KEY, GATEKEEPER_TLS_CERT/KEY など、ファイルパスを 受け取る全ての env / フラグ) に該当します。

Windows + Defender Application Control / Smart App Control でテスト exe がブロックされる場合

Section titled “Windows + Defender Application Control / Smart App Control でテスト exe がブロックされる場合”

go test 実行時に以下のエラーで一部パッケージのテストが失敗することがあります：

fork/exec C:\Users\<user>\AppData\Local\Temp\go-build*\b00*\api.test.exe:
An Application Control policy has blocked this file.

これは Windows Defender Application Control (WDAC) や Smart App Control が、 go test が動的に生成する一時 exe を未署名コードとしてブロックするためです。 Defender 設定を変更しなくても、Linux コンテナ内でテストを走らせれば 完全に回避できます (CI が走らせている環境と同等)：

Terminal window
# Bash / Git Bash
./scripts/test-docker.sh
./scripts/test-docker.sh ./pkg/api/...


# PowerShell
.\scripts\test-docker.ps1
.\scripts\test-docker.ps1 ./pkg/api/...


# make 経由 (Makefile 同梱)
make test-docker

これらは golang:1.25.10 イメージに pwd をマウントして go test を実行する ラッパーで、ホストの Defender / Smart App Control の設定を一切変更しません。

macOS / Linux ユーザー: 通常は go test ./... (or make test) で十分です。 Docker 経由は CI と同じ環境で再現確認したい時の補助として使います。

次のステップ

Section titled “次のステップ”