درگاه کارپوف

درگاه API یکپارچه + کنسول مدیریت. بک‌اند Go (Gin + gRPC) + فرانت‌اند Next.js (App Router + shadcn/ui)، مجهز به استخر اعتبارنامه، تأیید ایمیل، OAuth2 SSO لینوکس، سهمیه‌بندی و صورتحساب، احراز هویت دومرحله‌ای TOTP.

✨ ویژگی‌ها

• درگاه REST یکپارچه — حالت تک‌فرآیندی یا چند سرویس، gateway → auth/music/pool/quota/billing/worker بک‌اند gRPC با قابلیت استقرار مستقل
• استخر اعتبارنامه (رمزنگاری‌شده) — رمزگذاری پاکت KEK + DEK، AES-256-GCM با AAD، مشتق‌سازی کلید اصلی POOL_KEK_HEX
• ثبت‌نام ایمیلی + فعال‌سازی — ارسال کد/لینک فعال‌سازی از طریق SMTP، دوگانه حفاظتی (کد تأیید + لینک ایمیل)، در صورت عدم پیکربندی SMTP، به طور خودکار به LogSender کاهش می‌یابد
• ورود سوم شخص OAuth2 — SSO لینوکس.do (PKCE S256 + امضای HMAC روی state cookie)، تصمیم سه حالته ورود/اتصال/قطع اتصال، رمزنگاری token و ذخیره در پایگاه داده
• سهمیه/صورتحساب — PlanQuotaMiddleware پوشش‌دهنده در لایه gateway، بررسی ثانویه بر اساس plan + scope در سرویس‌های تجاری
• TOTP دو مرحله‌ای — pquerna/otp + محافظت در برابر تکرار با Redis
• گزارش حسابرسی — JSON ساختاریافته، فایل‌بندی بر اساس type، چرخش روزانه
• CSRF + جلسه — کوکی httpOnly با نام sid + بررسی دوگانه با هدر 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 اجرا شود، چون این مقدار در bundle سمت کلاینت قرار می‌گیرد.
• پس از فعال‌سازی پراکسی معکوس (Nginx/Caddy)، حتماً باید TRUST_PROXY=true فعال شود، وگرنه X-Forwarded-Proto کار نمی‌کند.
• اگر KEK تغییر کند، دیگر نمی‌توان به استخر اعتبارنامه‌های قدیمی / توکن‌های OAuth قدیمی دسترسی داشت.

🔐 اتصال OAuth2 (Linux.do)

• به https://connect.linux.do مراجعه و اپلیکیشن ثبت کنید.
• آدرس بازگشت را این مقدار قرار دهید: 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` یا هر فایلی که شامل رمز عبور واقعی است ارسال نکنید

🔒 امنیت

در صورت کشف مشکل امنیتی مستقیماً با maintainer تماس بگیرید، هرگز public issue باز نکنید.

ساخته شده با ❤️ توسط MiChongs

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