Skip to main content

Yabanin — Panduan Pembangunan

Prasyarat​

  • Go 1.27+ (go version patut melaporkan go1.27.x atau lebih baharu; modul dibina dengan bersih pada 1.27)
  • Docker dengan Docker Compose v2
  • make (dibekalkan bersama Xcode Command Line Tools pada macOS)
  • psql — pilihan, diperlukan hanya untuk larian migrasi tempatan di luar Docker

Permulaan pantas​

# 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

Selepas docker-up perkhidmatan tersedia di:

PerkhidmatanAlamat dengar (kontena)Hos (compose)Kesihatan
gerbang:80828082/healthz
admin/metrik gerbang:90909090—
satah kawalan admin:80869091/health
loggerd:80858085/healthz
mcp SSE:8787— (helm sahaja)—

Struktur projek​

.
├── 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

Nota: sumber binari bersatu berada dalam cmd/yabanin/ (ejaan sejarah dengan "i"); binari dan CLI dinamakan yabanin. Jangan cipta laluan baharu yang dieja yabanin.

Aliran kerja pembangunan​

Semua arahan melalui make:

Bagi antara muka yang boleh diulang yang sama secara tempatan, daripada ejen, atau dalam CI pada masa hadapan, mulakan dengan make quality-changed (rancangan), kemudian make quality-changed QUALITY_EXECUTE=1 (laksana). make quality-full menjalankan semua profil standard dan merekod log/hasil dalam artifacts/quality/. Lihat scripts/quality/README.md dalam repositori untuk prasyarat, profil, integrasi Docker yang eksplisit, dan pengesahan bukti terhadap sumber.

ArahanPerihalan
make buildKompilkan ketiga-tiga perkhidmatan (yabanin-gateway, yabanin-loggerd, yabanin-admin)
make testJalankan semua ujian unit dengan pengesanan race
make test-integrationJalankan ujian integrasi (menggunakan testcontainers untuk Postgres/Redis sebenar)
make lintAnalisis statik penuh dengan go vet dan golangci-lint
make analyze-fastGelung analisis statik yang pantas selepas suntingan Go
make analyze-securityPengesahan modul dan imbasan kerentanan yang boleh dicapai
make analyze-testsPengesan race, ujian yang dikocok, dan laporan liputan
make analyzeAgregat Go sahaja yang legasi: lint, keselamatan, dan ujian
make tidygo mod tidy
make run-gatewayBina dan jalankan gerbang di latar depan
make run-loggerdBina dan jalankan loggerd di latar depan
make run-adminBina dan jalankan admin di latar depan
make run-mcpJambatan rakan MCP (stdio; tetapkan YABANIN_MCP_HTTP=1 untuk SSE)
make dev-opencodeJana konfigurasi OpenCode dan mulakan jambatan langganan palsu
make opencode-remote-wireSambungkan ejen OpenCode ke stand awam yabanin.ai (kunci: YABANIN_GATEWAY_API_KEY)
make test-subscription-bridgeUjian kontrak sidecar Codex/Cursor palsu (Node)
make benchJalankan penanda aras

Jalankan ujian bagi satu perkhidmatan:

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

Sasaran analisis memasang versi yang dipinkan bagi golangci-lint dan govulncheck ke dalam $(go env GOPATH)/bin apabila perlu. Kemahiran OpenCode yang setempat pada projek di bawah .opencode/skills/ secara automatik menghalakan ejen ke pintu yang terpakai selepas perubahan pada Go, bahagian yang sensitif keselamatan, kebergantungan, ujian, atau konkurensi.

Orkestrasi OpenCode (tempatan)​

Tiga aliran kerja yang berasingan:

  1. yb audit — penganalisis luar talian. Tiada gerbang, tiada MCP, tiada jambatan langganan.
  2. Gerbang biasa — /v1/chat/completions serasi OpenAI untuk Z.AI Coding Plan dan model tempatan. Bendera ciri YABANIN_ZAI_CODING_ENABLED dimatikan secara lalai.
  3. Orkestrasi OpenCode — OpenCode bercakap dengan gerbang untuk chat/alat, dan dengan MCP tempatan tr_delegate untuk ejen Codex/Cursor. Pewakilan dimatikan melainkan YABANIN_DELEGATION_ENABLED=true.

Pendawaian OpenCode (stand tempatan yang terpencil make stand-opencode telah ditamatkan pada 2026-10-12; skrip pelancarnya telah dibuang):

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

Sasaran pendawaian memerlukan YABANIN_GATEWAY_API_KEY (kunci stand/organisasi yang dikeluarkan oleh pengendali) dan binari yabanin yang dibina secara tempatan untuk pelayan MCP (make build). Ia mengemas kini ~/.local/share/opencode/auth.json dan ~/.config/opencode/opencode.jsonc (kedua-duanya chmod 600). Mulakan semula OpenCode dan tukar tab ke ejen.

Kelayakan kekal pada mesin: kunci gerbang dalam auth.json (tidak pernah dikomit), Codex daripada ~/.codex/auth.json, Cursor daripada agent login rasmi (langganan, bukan kunci API papan pemuka).

Gelung tiruan tempatan satu arahan:

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

Kemudian halakan OpenCode ke konfigurasi yang dijana (atau salin examples/opencode.json). Log masuk untuk ejen sebenar kekal dalam CLI rasmi:

  • Z.AI Coding Plan: dayakan YABANIN_ZAI_CODING_ENABLED=true dan simpan kunci Coding Plan pada model zai-coding dalam registri (jangan komit)
  • Codex: log masuk codex rasmi atau CODEX_API_KEY (jangan sekali-kali kuki pelayar)
  • Cursor: agent login rasmi (langganan Cursor). Jangan tetapkan CURSOR_API_KEY

Tetapkan YABANIN_BRIDGE_FAKE=0 apabila anda mahu sidecar dalam services/subscription-bridge/ memanggil SDK rasmi. Model utama patut menggunakan alat OpenCode asli untuk kerja biasa dan tr_delegate hanya untuk tugas pengekodan yang sukar; lihat examples/opencode-yabanin.md.

Pelaksanaan Docker​

docker-compose.yml​

deploy/docker-compose.yml mentakrifkan lima perkhidmatan:

  • postgres — PostgreSQL 16 Alpine, dengan semakan kesihatan, filesystem baca sahaja
  • redis — Redis 7 Alpine dengan persistensi AOF, baca sahaja
  • migrate — kontena sekali larian yang menjalankan semua migrations/*.sql terhadap Postgres (berjalan sekali pada up pertama)
  • gateway — proxy songsang satah data (imej: yabanin-gateway:latest)
  • loggerd — pengguna log tak segerak (imej: yabanin-loggerd:latest)
  • admin — panel pentadbir satah kawalan (imej: yabanin-admin:latest)

Semua perkhidmatan aplikasi berada pada rangkaian jambatan app-internal. Port 8082, 8085, 9091, dan 5432/6379 didedahkan untuk pembangunan tempatan.

Membina imej​

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

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

Dockerfile menggunakan pembina Go 1.25 Alpine dengan binaan berbilang peringkat dan lekapan cache. Peringkat akhir berjalan sebagai pengguna bukan root (yabanin).

Pengurusan rahsia​

Rahsia dihantar melalui rahsia Docker (dilekapkan pada /run/secrets/<name>) dan digunakan melalui konvensyen pemboleh ubah persekitaran _FILE:

File rahsiaPemboleh ubah persekitaran yang digunakan oleh aplikasi
deploy/secrets/pg_uriYABANIN_PG_URI_FILE → membaca rentetan sambungan DB
deploy/secrets/session_keyYABANIN_SESSION_KEY_FILE → kunci penandatanganan kuki HMAC
deploy/secrets/cache_hmacYABANIN_CACHE_HMAC_SECRET_FILE → penandatanganan respons Redis

Untuk menambah rahsia baharu:

  1. Cipta file: echo -n "my-secret-value" > deploy/secrets/my_secret
  2. Tambahkannya pada .dockerignore (jangan sekali-kali komit rahsia)
  3. Isytiharkan dalam deploy/docker-compose.yml di bawah secrets: dan rujuk bagi setiap perkhidmatan
  4. Akhiran _FILE diselesaikan secara automatik oleh pkg/config/env()

Pengujian​

Ujian unit​

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

Ujian integrasi​

Ujian integrasi menggunakan testcontainers-go untuk menaikkan kontena Postgres dan Redis sebenar:

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

Pembantu ujian berada dalam subdirektori integration/ setiap perkhidmatan. Gunakan test_helpers.go untuk persediaan yang dikongsi (data benih, penciptaan klien) dan *_test.go untuk kes ujian.

Ujian asap / E2E​

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

Menambah perkhidmatan baharu​

Cipta struktur direktori:

mkdir -p services/<name>/cmd

Tulis services/<name>/cmd/main.go mengikut corak sedia ada:

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
}

Tambah sasaran make dalam Makefile:

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

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

Tambah <name> pada baris .PHONY dan pada kebergantungan build:.

Tambah medan konfigurasi dalam pkg/config/config.go:

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

Tambah sokongan Docker:

  • Salin blok perkhidmatan dalam deploy/docker-compose.yml daripada perkhidmatan sedia ada sebagai templat
  • Kemas kini arg binaan SERVICE, ports, healthcheck, secrets
  • Jalankan make docker-build-all untuk membina imej

Tambah ujian di bawah services/<name>/integration/ jika ia memerlukan liputan integrasi.

Migrasi​

File migrasi berada dalam migrations/ dan digunakan dalam tertib leksikal (awalan nama file menentukan urutan). Setiap file patut idempoten jika boleh (CREATE TABLE IF NOT EXISTS).

Menjalankan migrasi​

# 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

Menulis migrasi baharu​

  1. Cipta migrations/0006_<description>.sql (nombor berurutan seterusnya)
  2. Gunakan CREATE TABLE IF NOT EXISTS, ALTER TABLE, dan sebagainya.
  3. Uji secara tempatan: jalankan make migrate-up terhadap DB yang baharu
  4. Perkhidmatan Docker Compose migrate menjalankan migrasi pada setiap up — gunakan docker compose down --volumes && make docker-up untuk menguji tetapan semula penuh

Konfigurasi​

config.yaml​

Satu config.yaml di akar projek memegang semua konfigurasi perkhidmatan, masing-masing di bawah kunci aras atasnya sendiri:

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

Pemboleh ubah persekitaran​

Setiap medan konfigurasi boleh ditindih melalui pemboleh ubah persekitaran YABANIN_*. Akhiran _FILE membaca nilai daripada file (untuk rahsia Docker / Kubernetes):

Pemboleh ubah persekitaranLalaiPerihalan
YABANIN_CONFIGconfig.yamlLaluan ke file konfigurasi YAML
YABANIN_CONFIG_STRICTmatiPenghuraian persekitaran fail-closed untuk CI: 1/true menyebabkan nilai persekitaran numerik yang cacat (YABANIN_* int/float) menggagalkan pemuatan konfigurasi dengan pemboleh ubah dinamakan; lalai (tidak ditetapkan/0) memberi amaran dan mengekalkan lalai terbina dalam. Medan tempoh (*_timeout, *_ttl, stream_max_duration, …) sentiasa disemak oleh Validate() tanpa mengira bendera ini
YABANIN_GATEWAY_LISTEN:8082Alamat dengar HTTP gerbang
YABANIN_GATEWAY_ADMIN:9090Endpoint metrik admin gerbang
YABANIN_PROVIDER_ADDRlocalhost:8081Alamat penyedia API huluan
YABANIN_REDIS_ADDRlocalhost:6379Alamat sambungan Redis
YABANIN_PG_URI—DSN PostgreSQL (diperlukan)
YABANIN_LOG_LEVELinfoAras log: debug, info, warn, error
YABANIN_LOGGERD_STREAMevents:queueNama strim Redis
YABANIN_ADMIN_LISTEN:8086Alamat dengar panel pentadbir
YABANIN_ADMIN_DOMAINlocalhostDomain kuki untuk sesi pentadbir
YABANIN_SESSION_KEY—Kunci penandatanganan HMAC (diperlukan untuk admin)
YABANIN_CACHE_HMAC_SECRET—Rahsia untuk menandatangani respons yang di-cache oleh Redis

Keutamaan pemuatan konfigurasi​

  1. Lalai — dikod keras dalam pkg/config/*.go
  2. File konfigurasi YAML — dimuatkan daripada laluan dalam YABANIN_CONFIG (atau config.yaml)
  3. Pemboleh ubah persekitaran — menindih nilai YAML; akhiran _FILE membaca daripada laluan file

Tertib penyelesaian ialah: lalai → gabungan YAML → tindihan pemboleh ubah persekitaran. Untuk rahsia, gunakan varian _FILE untuk menunjuk kepada lekap rahsia Docker.

Nilai persekitaran numerik yang cacat (YABANIN_CIRCUIT_FAILURE_THRESHOLD=abc, …) sentiasa menghasilkan amaran permulaan yang menamakan pemboleh ubah dan mengekalkan lalai terbina dalam. Tetapkan YABANIN_CONFIG_STRICT=1 (disyorkan dalam CI) untuk menukar amaran itu menjadi kegagalan pemuatan. Nilai tempoh yang cacat (YAML atau persekitaran) menggagalkan Validate() semasa permulaan dalam kedua-dua mod; konfigurasi sah yang sedia ada tidak terjejas.

Pemboleh ubah persekitaran boolean menerima tepat 1 atau true (tidak peka huruf besar-kecil) sebagai benar; setiap nilai lain yang tidak kosong (0, false, yes, sampah, tidak dipangkas) ialah palsu — bukan sandaran. Hanya yang tidak ditetapkan/kosong mengekalkan lalai, jadi bagi bendera yang lalainya benar, pemboleh ubah mesti dibiarkan tidak ditetapkan untuk mengekalkannya. Ini ialah kontrak senyap: penghuraian boolean tidak pernah memberi amaran dan YABANIN_CONFIG_STRICT tidak terpakai kepadanya.