Karpov Gateway

เกตเวย์ API แบบรวมศูนย์ + คอนโซลควบคุม ระบบหลังบ้าน Go (Gin + gRPC) + ส่วนหน้า Next.js (App Router + shadcn/ui) มาพร้อมกับพูลข้อมูลรับรอง, การยืนยันอีเมล, Linux.do OAuth2 SSO, ระบบคิดค่าบริการตามโควต้า, TOTP ยืนยันตัวตนสองขั้นตอน

✨ คุณสมบัติ

• REST Gateway เดียว — โหมดโปรเซสเดียวหรือหลาย service, gateway → auth/music/pool/quota/billing/worker gRPC backend แยกดีพลอยได้อิสระ
• พูลข้อมูลประจำตัว (encrypted) — KEK + DEK การเข้ารหัสซองจดหมาย, AES-256-GCM พร้อม AAD, POOL_KEK_HEX ต้นทางคีย์หลัก
• สมัครสมาชิกอีเมล + เปิดใช้งาน — SMTP ส่งรหัส/ลิงก์เปิดใช้งาน, ระบบสองชั้น (รหัสยืนยัน + ลิงก์อีเมล), หากไม่ได้ตั้ง SMTP จะลดระดับเป็น LogSender อัตโนมัติ
• OAuth2 ล็อกอินบุคคลที่สาม — Linux.do SSO (PKCE S256 + HMAC เซ็น cookie สถานะ), ตัดสินใจสามสถานะ: ล็อกอิน/ผูกบัญชี/ยกเลิกผูก, token เข้ารหัสบันทึกลงฐานข้อมูล
• โควตา / การคิดเงิน — PlanQuotaMiddleware ที่ชั้น gateway ป้องกัน, ภายใน business service ตรวจซ้ำตาม plan + scope
• TOTP สองขั้นตอน — pquerna/otp + ป้องกันรีเพลย์ด้วย Redis
• บันทึกตรวจสอบ — JSON แบบโครงสร้าง, แยกไฟล์ตาม type, หมุนเวียนรายวัน
• CSRF + เซสชัน — cookie sid httpOnly + header 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 เพราะค่าดังกล่าวจะถูก inline เข้าไปใน client bundle
• หลังจากใช้งาน reverse proxy (Nginx/Caddy) ต้องเปิด TRUST_PROXY=true มิฉะนั้น X-Forwarded-Proto จะไม่ทำงาน
• เมื่อ KEK ถูกเปลี่ยน แหล่งข้อมูลเก่า / token OAuth เก่า จะไม่สามารถอ่านได้

🔐 การเชื่อมต่อ OAuth2 (Linux.do)

• ไปที่ https://connect.linux.do เพื่อสมัครแอปพลิเคชัน
• กรอก callback address เป็น: 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 ./... ต้องผ่านทั้งหมด
• หากแก้ไข Web ให้รัน pnpm lint && pnpm typecheck
• ห้ามส่งไฟล์ .env / data/.kek` หรือไฟล์ที่มีรหัสผ่านจริงใด ๆ

🔒 ความปลอดภัย

หากพบปัญหาด้านความปลอดภัย กรุณาติดต่อ maintainer โดยตรง ห้ามเปิด public issue

สร้างด้วย ❤️ โดย MiChongs

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