メインコンテンツまでスキップ

Yabanin — 開発ガイド

前提条件​

  • Go 1.27+(go version は go1.27.x 以降を報告すること。モジュールは 1.27 で問題なくビルドできます)
  • Docker(Docker Compose v2 付き)
  • make(macOS では Xcode Command Line Tools に同梱されています)
  • psql — 任意。Docker の外でローカルのマイグレーションを実行する場合にだけ必要です

クイックスタート​

# 1. Copy the environment template
cp .env.example .env # edit if you need non-default values

# 2. Bring up Postgres, Redis, and all three services
make docker-up

# 3. Run the smoke test (starts infra if not running, checks health)
bash scripts/smoke_test.sh

# 4. Tear everything down
make docker-down

docker-up のあと、サービスは次の場所で利用できます。

サービス待受(コンテナ)ホスト(compose)ヘルス
ゲートウェイ:80828082/healthz
ゲートウェイ admin/メトリクス:90909090—
admin コントロールプレーン:80869091/health
loggerd:80858085/healthz
mcp SSE:8787—(helm のみ)—

プロジェクト構成​

.
├── services/ # Service binaries (each is its own package)
│ ├── gateway/cmd/main.go # Reverse-proxy / API router (data-plane)
│ ├── loggerd/cmd/main.go # Redis stream consumer → Postgres writer
│ └── admin/cmd/main.go # Admin panel + CRUD APIs (control-plane)
├── pkg/ # Shared library packages
│ ├── config/ # YAML config loading + env-var resolution
│ ├── auth/ # API key & session authentication
│ ├── adminauth/ # Admin-specific HMAC cookie auth
│ ├── adminstore/ # Admin user store (Postgres)
│ ├── rulestore/ # Routing rules CRUD store
│ ├── evaluator/ # Rule matching engine
│ ├── openai/ # OpenAI API request/response types
│ ├── resolver/ # Model routing resolution
│ ├── redisutil/ # Redis client wrapper
│ ├── log/ # Structured logging (slog)
│ ├── logging/ # Logrus bridge / formatting
│ ├── events/ # Event payload types
│ ├── eventpublisher/ # Redis stream publisher interface
│ ├── cli/ # Service lifecycle helpers
│ └── encryption/ # AES-GCM token encryption
├── migrations/ # SQL migration files (applied in lexical order)
│ ├── 0001_init.sql # Core schema: orgs, models, api_keys, sessions, messages, rules, logs
│ ├── 0002_admin_and_teams.sql
│ ├── 0003_audit_logs.sql
│ ├── 0004_updated_at.sql
│ └── 0005_add_api_key_team_id.sql
├── deploy/ # Production deployment artifacts
│ ├── docker-compose.yml # Full stack definition (postgres, redis, gateway, loggerd, admin)
│ ├── .env # Docker Compose environment variables
│ └── secrets/ # Docker secrets (one file per secret)
│ ├── pg_uri
│ ├── pg_password
│ ├── session_key
│ ├── cache_hmac
│ └── admin_secrets
├── scripts/ # Helper scripts
│ └── smoke_test.sh # E2E smoke test (health checks + proxy call)
├── config.yaml # Per-service YAML config (merged with env vars)
├── Dockerfile # Multi-stage Go build for all services
├── Makefile # Build, test, run, docker targets
└── go.mod # Module: github.com/reireirei/yabanin

注: 統合バイナリのソースは cmd/yabanin/ にあります("i" を含む歴史的な綴りです)。バイナリと CLI の名前は yabanin です。新しく yabanin と綴ったパスは作らないでください。

開発ワークフロー​

すべてのコマンドは make 経由です。

ローカルでも、エージェントからでも、将来の CI でも同じ再現可能なインターフェースにするため、まず make quality-changed(計画)から始め、次に make quality-changed QUALITY_EXECUTE=1(実行)を使います。make quality-full はすべての標準プロファイルを実行し、ログと結果を artifacts/quality/ に記録します。前提条件、プロファイル、明示的な Docker 統合、ソースに対するエビデンスの検証については、リポジトリ内の scripts/quality/README.md を参照してください。

コマンド説明
make build3 つのサービスをすべてコンパイルします(yabanin-gateway、yabanin-loggerd、yabanin-admin)
make testレース検出付きですべての単体テストを実行します
make test-integration統合テストを実行します(実際の Postgres/Redis に testcontainers を使います)
make lintgo vet と golangci-lint で完全な静的解析を行います
make analyze-fastGo の編集後に使う、高速な静的解析ループです
make analyze-securityモジュールの検証と、到達可能な脆弱性のスキャンです
make analyze-testsレース検出、テストのシャッフル、カバレッジレポートです
make analyze従来の Go 専用の集約で、lint、セキュリティ、テストを含みます
make tidygo mod tidy
make run-gatewayゲートウェイをフォアグラウンドでビルドして実行します
make run-loggerdloggerd をフォアグラウンドでビルドして実行します
make run-adminadmin をフォアグラウンドでビルドして実行します
make run-mcpMCP パートナーブリッジです(stdio。SSE にするには YABANIN_MCP_HTTP=1 を設定します)
make dev-opencodeOpenCode の設定を生成し、偽のサブスクリプションブリッジを起動します
make opencode-remote-wireOpenCode エージェントを公開の yabanin.ai スタンドに接続します(キー: YABANIN_GATEWAY_API_KEY)
make test-subscription-bridge偽の Codex/Cursor サイドカー契約テストです(Node)
make benchベンチマークを実行します

単一サービスのテストを実行します。

go test -race -count=1 ./services/gateway/...
go test -race -count=1 ./pkg/rulesengine/...

解析ターゲットは、必要に応じて golangci-lint と govulncheck のピン留めされたバージョンを $(go env GOPATH)/bin にインストールします。.opencode/skills/ 配下のプロジェクトローカルな OpenCode スキルは、Go、セキュリティ上重要な変更、依存関係、テスト、または並行性の変更のあと、該当するゲートへエージェントを自動的に誘導します。

OpenCode オーケストレーション(ローカル)​

3 つの別々のワークフローです。

  1. yb audit — オフラインのアナライザです。ゲートウェイも、MCP も、サブスクリプションブリッジも使いません。
  2. 通常のゲートウェイ — Z.AI Coding Plan とローカルモデル向けの、OpenAI 互換 /v1/chat/completions です。機能フラグ YABANIN_ZAI_CODING_ENABLED はデフォルトでオフです。
  3. OpenCode オーケストレーション — OpenCode はチャットとツールのためにゲートウェイと通信し、Codex/Cursor エージェントのためにローカル MCP の tr_delegate と通信します。委譲は YABANIN_DELEGATION_ENABLED=true でない限りオフです。

OpenCode の接続(隔離されたローカルスタンド make stand-opencode は 2026-10-12 に廃止され、そのランチャースクリプトは削除されました):

make opencode-remote-wire # wires global OpenCode agents (yabanin, luna, sol-review) to https://yabanin.ai/gw

この wire ターゲットには YABANIN_GATEWAY_API_KEY(オペレーターが発行したスタンド/組織キー)と、MCP サーバー用にローカルでビルドした yabanin バイナリ(make build)が必要です。~/.local/share/opencode/auth.json と ~/.config/opencode/opencode.jsonc を更新します(どちらも chmod 600)。OpenCode を再起動し、Tab でエージェントに切り替えてください。

資格情報はマシン上に残します。ゲートウェイのキーは auth.json に置きます(決してコミットしないでください)。Codex は ~/.codex/auth.json から、Cursor は公式の agent login から取得します(サブスクリプションであり、ダッシュボードの API キーではありません)。

ワンコマンドのローカルモックループ:

make docker-up # or make run-gateway against local infra
export YABANIN_API_KEY=... # gateway client key; do not commit
export YABANIN_PARTNER_API_KEY=... # MCP → gateway key; do not commit
make dev-opencode # writes examples/opencode.generated.json and starts a fake bridge on :8091

その後、OpenCode を生成された設定に向けるか、examples/opencode.json をコピーしてください。実エージェントへのログインは公式 CLI のままです。

  • Z.AI Coding Plan: YABANIN_ZAI_CODING_ENABLED=true を有効にし、Coding Plan のキーをレジストリの zai-coding モデルに保存します(コミットしないでください)
  • Codex: 公式の codex ログイン、または CODEX_API_KEY(ブラウザの Cookie は決して使わないでください)
  • Cursor: 公式の agent login(Cursor のサブスクリプション)。CURSOR_API_KEY は設定しないでください

services/subscription-bridge/ のサイドカーに公式 SDK を呼ばせたいときは、YABANIN_BRIDGE_FAKE=0 を設定します。主導モデルは通常の作業にネイティブの OpenCode ツールを使い、難しいコーディングタスクにだけ tr_delegate を使ってください。詳細は examples/opencode-yabanin.md を参照してください。

Docker 導入​

docker-compose.yml​

deploy/docker-compose.yml は 5 つのサービスを定義します。

  • postgres — PostgreSQL 16 Alpine。ヘルスチェック付き。読み取り専用ファイルシステム
  • redis — AOF 永続化付きの Redis 7 Alpine。読み取り専用
  • migrate — すべての migrations/*.sql を Postgres に対して実行するワンショットコンテナです(最初の up で一度だけ実行されます)
  • ゲートウェイ — データプレーンのリバースプロキシです(イメージ: yabanin-gateway:latest)
  • loggerd — 非同期ログコンシューマです(イメージ: yabanin-loggerd:latest)
  • admin — コントロールプレーンの管理パネルです(イメージ: yabanin-admin:latest)

すべてのアプリサービスは app-internal ブリッジネットワーク上にあります。ポート 8082、8085、9091、および 5432/6379 はローカル開発用に公開されています。

イメージのビルド​

# Build all three service images locally
make docker-build-all

# Each image is tagged: yabanin-gateway, yabanin-loggerd, yabanin-admin

Dockerfile は、マルチステージビルドとキャッシュマウントを備えた Go 1.25 Alpine ビルダーを使います。最終ステージは非 root ユーザー(yabanin)として実行します。

シークレット管理​

シークレットは Docker シークレット(/run/secrets/<name> にマウント)として渡され、_FILE 環境変数の規約を通じて利用されます。

シークレットファイルアプリが使う環境変数
deploy/secrets/pg_uriYABANIN_PG_URI_FILE → DB 接続文字列を読み取ります
deploy/secrets/session_keyYABANIN_SESSION_KEY_FILE → HMAC Cookie の署名キー
deploy/secrets/cache_hmacYABANIN_CACHE_HMAC_SECRET_FILE → Redis レスポンスの署名

新しいシークレットを追加するには、次の手順です。

  1. ファイルを作成します: echo -n "my-secret-value" > deploy/secrets/my_secret
  2. .dockerignore に追加します(シークレットは決してコミットしないでください)
  3. deploy/docker-compose.yml の secrets: に宣言し、サービスごとに参照します
  4. _FILE 接尾辞は pkg/config/env() が自動的に解決します

テスト​

単体テスト​

make test # all packages, race detector enabled
go test -race -count=1 ./pkg/rulesengine/... # single package

統合テスト​

統合テストは testcontainers-go を使い、実際の Postgres と Redis のコンテナを起動します。

make test-integration # runs services/gateway/integration/...
go test -race -count=1 ./services/loggerd/integration/...

テストヘルパーは各サービスの integration/ サブディレクトリにあります。共有セットアップ(シードデータ、クライアント作成)には test_helpers.go を、テストケースには *_test.go を使います。

スモーク / E2E テスト​

bash scripts/smoke_test.sh # starts compose, waits for health, proxies a request, tears down

新しいサービスの追加​

ディレクトリ構成を作成します:

mkdir -p services/<name>/cmd

services/<name>/cmd/main.go を書きます。既存のパターンに従ってください:

package main

import (
"github.com/reireirei/yabanin/pkg/config"
"github.com/reireirei/yabanin/pkg/logging"
)

func main() {
cfg, _ := config.Load("config.yaml")
// validate cfg.<ServiceName>, connect to Postgres/Redis, start server
}

Makefile に make ターゲットを追加します:

<name>:
go build -o yabanin-<name> ./services/<name>/cmd/...

run-<name>: build
./yabanin-<name>

<name> を .PHONY 行と build: の依存関係に追加します。

pkg/config/config.go に設定フィールドを追加します:

type MyService struct { ... }
func DefaultMyService() MyService { ... }
func (c MyService) Validate() error { ... }
// Add to All struct and DefaultAll()

Docker サポートを追加します:

  • deploy/docker-compose.yml のサービスブロックを、既存サービスからテンプレートとしてコピーします
  • SERVICE ビルド引数、ポート、ヘルスチェック、シークレットを更新します
  • イメージをビルドするため make docker-build-all を実行します

テストを追加します。統合カバレッジが必要な場合は services/<name>/integration/ 配下に置きます。

マイグレーション​

マイグレーションファイルは migrations/ にあり、辞書順で適用されます(ファイル名の接頭辞が順序を決めます)。各ファイルは、可能な限りべき等にしてください(CREATE TABLE IF NOT EXISTS)。

マイグレーションの実行​

# Via Docker compose (uses the migrate one-shot service)
make docker-up # migrate runs automatically on first up

# Via local psql
export YABANIN_PG_URI="postgres://yabanin:yabanin@localhost/yabanin?sslmode=disable"
make migrate-up

# Manually
for f in migrations/*.sql; do psql $YABANIN_PG_URI -f "$f"; done

新しいマイグレーションの作成​

  1. migrations/0006_<description>.sql を作成します(次の連番)
  2. CREATE TABLE IF NOT EXISTS、ALTER TABLE などを使います
  3. ローカルでテストします。新しい DB に対して make migrate-up を実行します
  4. Docker Compose の migrate サービスは、毎回の up でマイグレーションを実行します。完全なリセットをテストするには docker compose down --volumes && make docker-up を使います

設定​

config.yaml​

プロジェクトルートの単一の config.yaml に、すべてのサービス設定が入ります。各サービスは、それぞれ独自のトップレベルキーの下にあります。

gateway:
listen_address: ":8082"
admin_listen: ":9090"
provider: "localhost:8081"
redis_addr: "redis:6379"
pg_uri: "postgres://yabanin:yabanin@postgres/yabanin?sslmode=disable"
log_level: "info"
log_format: "json"
auth_mode: "header" # header | strict
api_key: ""
fallback_api_key: "yabanin-dev-key"
fallback_model: "smart" # smart | cheap | turbo
event_stream: "events:queue"

loggerd:
listen_address: ":8085"
stream_name: "events:queue"
redis_addr: "redis:6379"
pg_uri: "postgres://yabanin:yabanin@postgres/yabanin?sslmode=disable"
log_level: "info"
log_format: "json"

admin:
listen_address: ":8086"
pg_uri: "postgres://yabanin:yabanin@postgres/yabanin?sslmode=disable"
session_key: "" # HMAC signing key for admin cookies
admin_domain: "localhost"
encryption_key: "" # 32-byte key for AES-GCM token encryption

環境変数​

すべての設定フィールドは、YABANIN_* 環境変数で上書きできます。_FILE 接尾辞はファイルから値を読み取ります(Docker シークレット / Kubernetes 向けです)。

環境変数デフォルト説明
YABANIN_CONFIGconfig.yamlYAML 設定ファイルへのパス
YABANIN_CONFIG_STRICTオフCI 向けのフェイルクローズな環境変数パースです。1/true にすると、不正な数値の環境変数値(YABANIN_* の int/float)は、変数名を示したうえで設定の読み込みに失敗します。デフォルト(未設定/0)では警告し、組み込みのデフォルトを維持します。期間フィールド(*_timeout、*_ttl、stream_max_duration など)は、このフラグに関係なく常に Validate() で検査されます
YABANIN_GATEWAY_LISTEN:8082ゲートウェイの HTTP 待受アドレス
YABANIN_GATEWAY_ADMIN:9090ゲートウェイ admin のメトリクスエンドポイント
YABANIN_PROVIDER_ADDRlocalhost:8081上流 API プロバイダのアドレス
YABANIN_REDIS_ADDRlocalhost:6379Redis の接続アドレス
YABANIN_PG_URI—PostgreSQL DSN(必須)
YABANIN_LOG_LEVELinfoログレベル: debug、info、warn、error
YABANIN_LOGGERD_STREAMevents:queueRedis ストリーム名
YABANIN_ADMIN_LISTEN:8086管理パネルの待受アドレス
YABANIN_ADMIN_DOMAINlocalhostadmin セッション用の Cookie ドメイン
YABANIN_SESSION_KEY—HMAC 署名キー(admin に必須)
YABANIN_CACHE_HMAC_SECRET—Redis にキャッシュしたレスポンスへ署名するためのシークレット

設定の読み込み優先順位​

  1. デフォルト — pkg/config/*.go にハードコードされています
  2. YAML 設定ファイル — YABANIN_CONFIG のパス(または config.yaml)から読み込みます
  3. 環境変数 — YAML の値を上書きします。_FILE 接尾辞はファイルパスから読み取ります

解決順序は、デフォルト → YAML のマージ → 環境変数による上書きです。シークレットには _FILE バリアントを使い、Docker シークレットのマウント先を指してください。

不正な数値の環境変数値(YABANIN_CIRCUIT_FAILURE_THRESHOLD=abc など)は、常に変数名を含む起動時警告を出し、組み込みのデフォルトを維持します。その警告を読み込み失敗にするには YABANIN_CONFIG_STRICT=1(CI では推奨)を設定します。不正な期間の値(YAML または環境変数)は、どちらのモードでも起動時に Validate() で失敗します。既存の妥当な設定には影響しません。

ブール値の環境変数は、ちょうど 1 または true(大文字小文字を区別しません)だけを true として受け付けます。それ以外の空でない値(0、false、yes、ごみ値、トリムしていない値)は false であり、フォールバックではありません。未設定または空のときだけデフォルトを維持します。したがって、デフォルトが true のフラグでは、その値を保つために変数を未設定のままにする必要があります。これは暗黙の契約です。ブール値のパースは警告を出さず、YABANIN_CONFIG_STRICT も適用されません。