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) | ヘルス |
|---|---|---|---|
| ゲートウェイ | :8082 | 8082 | /healthz |
| ゲートウェイ admin/メトリクス | :9090 | 9090 | — |
| admin コントロールプレーン | :8086 | 9091 | /health |
| loggerd | :8085 | 8085 | /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 build | 3 つのサービスをすべてコンパイルします(yabanin-gateway、yabanin-loggerd、yabanin-admin) |
make test | レース検出付きですべての単体テストを実行します |
make test-integration | 統合テストを実行します(実際の Postgres/Redis に testcontainers を使います) |
make lint | go vet と golangci-lint で完全な静的解析を行います |
make analyze-fast | Go の編集後に使う、高速な静的解析ループです |
make analyze-security | モジュールの検証と、到達可能な脆弱性のスキャンです |
make analyze-tests | レース検出、テストのシャッフル、カバレッジレポートです |
make analyze | 従来の Go 専用の集約で、lint、セキュリティ、テストを含みます |
make tidy | go mod tidy |
make run-gateway | ゲートウェイをフォアグラウンドでビルドして実行します |
make run-loggerd | loggerd をフォアグラウンドでビルドして実行します |
make run-admin | admin をフォアグラウンドでビルドして実行します |
make run-mcp | MCP パートナーブリッジです(stdio。SSE にするには YABANIN_MCP_HTTP=1 を設定します) |
make dev-opencode | OpenCode の設定を生成し、偽のサブスクリプションブリッジを起動します |
make opencode-remote-wire | OpenCode エージェントを公開の 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 つの別々のワークフローです。
yb audit— オフラインのアナライザです。ゲートウェイも、MCP も、サブスクリプションブリッジも使いません。- 通常のゲートウェイ — Z.AI Coding Plan とローカルモデル向けの、OpenAI 互換
/v1/chat/completionsです。機能フラグYABANIN_ZAI_CODING_ENABLEDはデフォルトでオフです。 - 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)として実行します。