Pro Container Guide Pro

Querycop Pro をコンテナ（Docker / Kubernetes）で動かすためのガイドです。

Pro イメージは専用レジストリ registry.querycop.com から配布され、pull には有効な Pro ライセンス token が必要です。1 つの token が イメージの pull 資格 と Pro 機能の有効化 の両方を兼ねます。

Community 版（無料）のコンテナ利用は quickstart.md を参照してください。このガイドは Pro サブスクリプション購入者向けです。

前提

Pro サブスクリプションを購入済みであること
購入確認メール（レシート）に記載の 注文番号 と 購入時メールアドレス が手元にあること
Docker 24.0+（Kubernetes の場合は Helm 3+ も）

Step 1: ライセンス token の取得

購入情報を claim エンドポイントに POST すると license token が返ります。 HTTP だけで完結するので、バイナリのダウンロードは不要です:

curl -X POST https://api.querycop.com/v1/license/claim \
  -H "Content-Type: application/json" \
  -d '{"order_id":"<注文番号>","email":"<購入時メール>"}'

レスポンス例:

{"token":"<license token>","license_id":"lic_...","expires_at":1815000000,"tier":"pro"}

token の値を控えてください。以降の手順すべてでこの token を使います。

querycop-cli が手元にある場合は querycop-cli license claim --order=<注文番号> --email=<購入時メール> でも取得できます。token の有効期間や heartbeat による失効管理の詳細は configuration.md §11.4 を参照してください。

取得した token をパスワードとして login します（ユーザー名は license を指定してください — 認証は token 側で行われます）:

echo '<token>' | docker login registry.querycop.com -u license --password-stdin
docker pull registry.querycop.com/querycop/pro:stable

本番環境ではサプライチェーン対策として、:stable タグではなく registry.querycop.com/querycop/pro@sha256:<digest> 形式の digest 固定 pull を推奨します。現在の :stable の公式 digest:

registry.querycop.com/querycop/pro@sha256:ad2700beddf1159fb6bdef32a55535763d996c7a4c4d1bcbc16cb54e9baae6bc

pull した image がこの digest と一致することを docker buildx imagetools inspect registry.querycop.com/querycop/pro:stable （または docker inspect --format '{{index .RepoDigests 0}}' registry.querycop.com/querycop/pro:stable）で確認できます。新しいリリースのたびにこの digest は更新されます。

Step 3: 起動

環境変数 QUERYGUARD_LICENSE_KEY に token を渡して起動すると Pro が有効化されます:

docker run -d --name querycop-pro \
  -e QUERYGUARD_LICENSE_KEY='<token>' \
  -e GATEKEEPER_LISTEN_ADDR=0.0.0.0 \
  -e GATEKEEPER_LISTEN_PORT=5432 \
  -e GATEKEEPER_BACKEND_HOST=<バックエンドDBホスト> \
  -e GATEKEEPER_BACKEND_PORT=5432 \
  -e ADMIN_API_KEY=<ランダムな強い値> \
  -p 127.0.0.1:15432:5432 \
  -p 127.0.0.1:8080:8080 \
  registry.querycop.com/querycop/pro:stable

GATEKEEPER_* の基本設定（プロキシ・AI リスク評価・監査ログなど）は Community 版と共通です。quickstart.md と configuration.md を参照してください。

Kubernetes (Helm)

pull 資格を imagePullSecret として作成します:

kubectl create secret docker-registry querycop-pro-pull \
  --docker-server=registry.querycop.com \
  --docker-username=license \
  --docker-password='<license token>'

values override で Pro イメージに切り替えます:

license token 用の Secret も作成します（チャートが QUERYGUARD_LICENSE_KEY として Pod に注入します）:

kubectl create secret generic querycop-license \
  --from-literal=license='<license token>'

values override で Pro イメージとライセンスを設定します:

# values-pro.yaml — Pro image override (the public chart default stays Community)
image:
  repository: registry.querycop.com/querycop/pro
  tag: "stable@sha256:ad2700beddf1159fb6bdef32a55535763d996c7a4c4d1bcbc16cb54e9baae6bc"   # digest pin 推奨（現行 digest。Step 2 参照）
imagePullSecrets:
  - name: querycop-pro-pull
license:
  existingSecret: querycop-license   # ↑で作成した Secret（key はデフォルト "license"）
  # または existingSecret を使わず直接: license.value: "<license token>"

helm upgrade --install querycop charts/querycop -f values-pro.yaml

注: imagePullSecrets と license.* values はチャートバージョン 0.2.0 以降で対応しています。それより古いチャートでは、これらの values を設定しても Pod には反映されません（helm show chart <chart> でバージョンを確認できます）。

解約時の挙動

サブスクリプションを解約しても、支払い済み期間の満了までは pull も Pro 機能もそのまま利用できます。期間満了後は license token が失効し、 registry.querycop.com からの pull と、実行中インスタンスの Pro 機能（heartbeat 経由で失効が反映されます）の両方が無効になります。 Community 機能はその後も引き続き利用できます。

次のステップ

configuration.md - 全環境変数の詳細設定（ライセンス設定は §11）
quickstart.md - 基本的な起動・接続確認の手順
api.md - Admin API リファレンス