بوابة كاربوف

بوابة API موحدة + لوحة تحكم. خلفية Go (Gin + gRPC) + واجهة أمامية Next.js (App Router + shadcn/ui)، مزودة بمسبح الاعتماديات، تحقق البريد الإلكتروني، OAuth2 SSO من Linux.do، حساب الحصص والفوترة، تحقق TOTP ثنائي الخطوة.

✨ الميزات

• بوابة REST موحدة — وضع العملية الأحادية أو نمط الخدمات المتعددة، بوابة gateway → المصادقة/auth، الموسيقى/music، المسبح/pool، الحصص/quota، الفوترة/billing، العامل/worker، يمكن نشر الخلفيات gRPC بشكل مستقل
• تجمع بيانات الاعتماد (مشفر) — تشفير الظرف KEK + DEK، AES-256-GCM مع AAD، اشتقاق المفتاح الرئيسي POOL_KEK_HEX
• تسجيل البريد الإلكتروني + التفعيل — إرسال رمز / رابط تفعيل عبر SMTP، حماية مزدوجة (رمز التحقق + رابط البريد)، في حال عدم تكوين SMTP يتم التحويل التلقائي إلى LogSender
• تسجيل الدخول عبر OAuth2 لطرف ثالث — SSO من Linux.do (PKCE S256 + توقيع state cookie بـ HMAC)، ثلاث حالات قرار (تسجيل الدخول / ربط / إلغاء الربط)، تخزين token مشفر
• الحصص / الفوترة — PlanQuotaMiddleware كحماية في طبقة gateway، تحقق ثانوي داخل الخدمة التجارية حسب الخطة + النطاق
• التحقق بخطوتين TOTP — pquerna/otp + حماية من إعادة الاستخدام عبر Redis
• سجلات التدقيق — JSON منظم، ملفات منفصلة حسب النوع، تدوير يومي
• CSRF + جلسة — تحقق مزدوج عبر cookie 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، لأنه سيتم تضمينه مباشرة في حزمة العميل
• بعد استخدام العكس العكسي (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
   ``
أعد تشغيل البوابة، ستظهر تلقائيًا صفحة تسجيل الدخول / التسجيل "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 ---