कार्पोव गेटवे

एकीकृत API गेटवे + कंसोल। Go बैकएंड (Gin + gRPC) + Next.js फ्रंटएंड (App Router + shadcn/ui), इसमें क्रेडेंशियल पूल, ईमेल सत्यापन, Linux.do OAuth2 SSO, कोटा बिलिंग, TOTP दो चरणीय सत्यापन शामिल है।

✨ विशेषताएँ

• 統一 REST गेटवे — एकल प्रक्रिया या बहु सेवा मोड, gateway → auth/music/pool/quota/billing/worker gRPC बैकएंड स्वतंत्र रूप से डिप्लॉय हो सकते हैं
• क्रेडेंशियल पूल (encrypted) — KEK + DEK लिफाफा एन्क्रिप्शन, AES-256-GCM with AAD, POOL_KEK_HEX मास्टर कुंजी डेरिवेशन
• ईमेल रजिस्ट्रेशन + एक्टिवेशन — SMTP कोड भेजना / एक्टिवेशन लिंक, डबल सुरक्षा (वेरिफिकेशन कोड + ईमेल लिंक), SMTP न हो तो ऑटो LogSender में डिमोट
• OAuth2 थर्ड-पार्टी लॉगिन — Linux.do SSO (PKCE S256 + HMAC साइन स्टेट कुकी), लॉगिन / बाइंड / अनबाइंड तीन स्थिति निर्णय, टोकन एन्क्रिप्ट होकर स्टोर
• कोटा / बिलिंग — PlanQuotaMiddleware गेटवे लेयर पर, बिजनेस सर्विस में योजना + स्कोप के अनुसार द्वितीय सत्यापन
• TOTP टू-स्टेप — pquerna/otp + Redis रिप्ले प्रोटेक्शन
• ऑडिट लॉग — संरचित JSON, टाइप के अनुसार फाइल में, रोजाना रोटेशन
• CSRF + सत्र — sid httpOnly कुकी + X-CSRF-Token हेडर दोहरी सत्यापन
• shadcn/ui कंसोल — Next.js 16 App Router + Radix + Tailwind v4

🏗 रिपॉजिटरी संरचना

karpov-gateway/
├── gateway/             # Go 后端 (Gin + gRPC)
│   ├── cmd/             # 各 service 入口 (gateway/auth/music/pool/...)
│   ├── internal/        # 业务实现 (private)
│   ├── api/             # protobuf 定义
│   ├── migrations/      # PostgreSQL schema
│   ├── go.mod           # Go 模块 (go 1.24+)
│   └── Dockerfile
├── web/                 # Next.js 16 前端控制台
│   ├── src/             # App Router pages + components
│   ├── middleware.ts    # CSRF / session / CSP nonce
│   ├── package.json     # pnpm workspace
│   └── Dockerfile
├── deploy/
│   ├── compose/         # 本地开发 (PG + Redis + pgAdmin)
│   └── compose-prod/    # 生产单机 (gateway + web + PG + Redis 全栈)
└── .github/workflows/   # GitHub Actions CI (lint / test / build / govulncheck / gosec)

🚀 त्वरित प्रारंभ

1. पूर्व आवश्यकताएँ

| उपकरण | संस्करण | | ---------- | ------- | | Go | 1.24+ | | Node.js | 20.11+ | | pnpm | 9+ | | Docker | 24+ | | PostgreSQL | 14+ | | Redis | 7+ |

2. निर्भरता प्रारंभ करें (Postgres + Redis + pgAdmin)

cd deploy/compose
cp .env.example .env       # 改强密码！
docker compose up -d

3. Gateway बैकएंड प्रारंभ करें

cd gateway
cp .env.example .env       # 与 deploy/compose/.env 的 PG/Redis 密码保持一致
go mod download
go run ./cmd/qqmusic-gateway
默认 :8080 (HTTP) + :9000 (gRPC)
首次启动会在 stderr 打印一个 superadmin 账号 + 临时密码

4. वेब कंसोल प्रारंभ करें

cd web
cp .env.example .env.local
pnpm install
pnpm dev
http://localhost:3000

🐳 उत्पादन परिनियोजन (Docker Compose सिंगल मशीन)

cd deploy/compose-prod
cp .env.example .env
编辑 .env：填入真域名 / 强密码 / SMTP 凭据 / OAuth client
nano .env
生成 KEK
openssl rand -hex 32     # → 写到 POOL_KEK_HEX=
docker compose up -d --build
docker compose logs -f gateway

ध्यान देने योग्य बातें:

• NEXT_PUBLIC_APP_URL बदलने के बाद अनिवार्य रूप से docker compose build --no-cache web चलाएँ, क्योंकि यह client bundle में inline हो जाएगा
• रिवर्स प्रॉक्सी (Nginx/Caddy) के बाद अनिवार्य रूप से TRUST_PROXY=true चालू करें, अन्यथा X-Forwarded-Proto काम नहीं करेगा
• KEK बदलते ही पुराने क्रेडेंशियल पूल / पुराने OAuth टोकन पूरी तरह अपठनीय हो जाएंगे

🔐 OAuth2 (Linux.do) एकीकरण

• https://connect.linux.do पर ऐप्लिकेशन के लिए आवेदन करें
• callback पता भरें: https://your-domain/v1/auth/oauth/linuxdo/callback
• प्राप्त client_id / client_secret को .env में लिखें:

   OAUTH_LINUXDO_ENABLED=true
   OAUTH_LINUXDO_CLIENT_ID=...
   OAUTH_LINUXDO_CLIENT_SECRET=...
   OAUTH_LINUXDO_MIN_TRUST_LEVEL=1
   OAUTH_PUBLIC_BASE=https://your-domain
   OAUTH_FRONTEND_BASE=https://your-domain
   ``
gateway को पुनः प्रारंभ करें, लॉगिन पृष्ठ / पंजीकरण पृष्ठ पर "Linux.do एक-क्लिक लॉगिन" अपने आप दिखाई देगा
🧪 परीक्षण / Lint

• golangci-lint run + gofmt -l . सभी हरे
• go test -race ./... सभी हरे
• वेब में बदलाव पर pnpm lint && pnpm typecheck चलाएं
• कृपया .env / data/.kek` या कोई भी असली पासवर्ड वाली फाइल सबमिट न करें

🔒 सुरक्षा

अगर कोई सुरक्षा समस्या मिले तो सीधे मेंटेनर से संपर्क करें, पब्लिक issue न खोलें।

MiChongs द्वारा ❤️ से निर्मित

--- Tranlated By Open Ai Tx | Last indexed: 2026-06-08 ---