101 lines
5.0 KiB
Markdown
101 lines
5.0 KiB
Markdown
# EZBio — Modern URL Shortener & Link in Bio Platform
|
|
|
|
Hệ thống rút gọn liên kết thông minh kết hợp nền tảng Bio Link (Link in Bio) được viết lại toàn diện từ phiên bản PHP sang **Next.js 16 (App Router)**, **TypeScript**, **Tailwind CSS v4**, **Prisma ORM**, hỗ trợ lưu trữ **Cloudflare R2** và tối ưu hóa triển khai trên **Vercel**.
|
|
|
|
---
|
|
|
|
## 🌟 Các Tính Năng Nổi Bật
|
|
|
|
### 1. Phân hệ Rút gọn Liên kết (URL Shortener Core)
|
|
- **Tự động sinh mã ngắn linh hoạt:** Cho phép Admin cấu hình độ dài chuỗi ngẫu nhiên (`default_url_length` từ 3 - 16 ký tự, mặc định 5 hoặc 6).
|
|
- **Tùy chọn nâng cao:** Đặt bí danh tùy chỉnh (Custom Short Code), bảo vệ link bằng mật khẩu băm bcrypt, hẹn giờ hết hạn link (`expires_at`), gắn thẻ phân loại (Tags).
|
|
- **QR Code tự động:** Tạo mã QR chất lượng cao (PNG & SVG) cho mọi liên kết với tùy chọn màu sắc.
|
|
- **Tự động lấy tiêu đề trang:** Cào tự động thẻ `<title>` và OpenGraph metadata của URL đích.
|
|
- **Cơ chế chuyển hướng & Tracking:** Thống kê lượt click, thiết bị (Desktop/Mobile/Tablet), hệ điều hành (OS), trình duyệt, vị trí địa lý (GeoIP) và nguồn giới thiệu (Referrer).
|
|
|
|
### 2. Phân hệ Bio Link & Landing Page Cá Nhân
|
|
- **Đường dẫn cá nhân hóa:** Truy cập qua `/portal/[username]` hoặc Subdomain.
|
|
- **Trình soạn thảo trực quan (Live Phone Preview):** Giao diện chỉnh sửa chia 2 cột với khung điện thoại thông minh mô phỏng cập nhật theo thời gian thực.
|
|
- **Danh thiếp điện tử (vCard):** Tự động sinh file `.vcf` danh bạ để khách lưu vào điện thoại với 1 chạm.
|
|
- **Liên kết Mạng xã hội:** Hỗ trợ Facebook, Twitter/X, Instagram, Threads, TikTok, YouTube, Telegram (mỗi nút đều có tính năng xem mã QR riêng).
|
|
- **Bộ hiệu ứng màu sắc:** 6 bộ Gradient cho tiêu đề, 6 bộ Gradient cho hình nền hoặc tải ảnh nền tùy chỉnh.
|
|
|
|
### 3. Phân hệ Quản trị & Giám sát Lưu trữ Cloudflare R2
|
|
- **Admin Dashboard:** Biểu đồ tăng trưởng, thống kê thiết bị, top 10 quốc gia.
|
|
- **Cloudflare R2 Storage Monitor (Cảnh báo hạn mức Free):**
|
|
- Giám sát trực quan dung lượng đã dùng trên tổng 10 GB miễn phí.
|
|
- Tự động hiển thị cảnh báo vàng khi đạt 80% (8 GB) và cảnh báo đỏ khẩn cấp khi đạt 90% (9 GB).
|
|
- Hỗ trợ cơ chế **Local Storage Fallback** khi chưa cấu hình R2 keys.
|
|
- **Quản lý Người dùng & URLs:** Phân quyền Admin/User, khóa/mở khóa tài khoản, thao tác hàng loạt (Bulk Actions).
|
|
- **Cấu hình Hệ thống:** Cài đặt SEO Meta, SMTP Email, Logo, Favicon và độ dài mã ngắn mặc định.
|
|
|
|
---
|
|
|
|
## 🚀 Hướng Dẫn Cài Đặt & Chạy Cục Bộ (Local Dev)
|
|
|
|
### 1. Cấu hình Biến Môi Trường (`.env`)
|
|
Mở file `.env` và điền chuỗi kết nối PostgreSQL của bạn:
|
|
|
|
```env
|
|
DATABASE_URL="postgresql://username:password@your-db-host:5432/ezbio?sslmode=require"
|
|
AUTH_SECRET="tao-mot-chuoi-bi-mat-ngau-nhien-it-nhat-32-ky-tu"
|
|
NEXT_PUBLIC_APP_URL="http://localhost:3000"
|
|
```
|
|
|
|
*(Nếu chưa cấu hình Cloudflare R2, hệ thống sẽ tự động dùng Local Storage lưu tại `public/uploads`).*
|
|
|
|
### 2. Đồng bộ CSDL & Tạo Dữ Liệu Khởi Tạo (Seed)
|
|
Chạy lệnh sau để tạo các bảng trong PostgreSQL:
|
|
|
|
```bash
|
|
# Đẩy schema lên database
|
|
npx prisma db push
|
|
|
|
# Tạo tài khoản Admin, Demo và dữ liệu cấu hình mẫu
|
|
npm run seed
|
|
```
|
|
|
|
> **Tài khoản mặc định sau khi seed:**
|
|
> - **Admin:** `[email protected]` / `password123`
|
|
> - **Demo User:** `[email protected]` / `password123`
|
|
|
|
### 3. Khởi chạy máy chủ phát triển
|
|
```bash
|
|
npm run dev
|
|
```
|
|
Truy cập: `http://localhost:3000`
|
|
|
|
---
|
|
|
|
## ☁️ Cấu hình Cloudflare R2 Storage (Khi triển khai)
|
|
|
|
Thêm các khóa sau vào `.env` hoặc phần **Environment Variables** trên Vercel:
|
|
|
|
```env
|
|
STORAGE_DRIVER="cloudflare_r2"
|
|
CLOUDFLARE_R2_ACCOUNT_ID="your-account-id"
|
|
CLOUDFLARE_R2_ACCESS_KEY_ID="your-access-key-id"
|
|
CLOUDFLARE_R2_SECRET_ACCESS_KEY="your-secret-access-key"
|
|
CLOUDFLARE_R2_BUCKET_NAME="ezbio-bucket"
|
|
CLOUDFLARE_R2_PUBLIC_URL="https://pub-your-bucket.r2.dev"
|
|
CLOUDFLARE_R2_FREE_LIMIT_MB="10240"
|
|
CLOUDFLARE_R2_WARNING_PERCENT="80"
|
|
```
|
|
|
|
---
|
|
|
|
## 🚢 Triển khai lên Vercel & GitHub
|
|
|
|
1. Khởi tạo Git và đẩy mã nguồn lên GitHub:
|
|
```bash
|
|
git init
|
|
git add .
|
|
git commit -m "feat: complete EZBio Next.js rewrite"
|
|
git branch -M main
|
|
git remote add origin https://github.com/your-username/ezbio.git
|
|
git push -u origin main
|
|
```
|
|
2. Đăng nhập vào [Vercel](https://vercel.com), chọn **Add New Project** và liên kết với kho lưu trữ GitHub của bạn.
|
|
3. Trong mục **Environment Variables** trên Vercel, dán các biến từ file `.env`.
|
|
4. Nhấn **Deploy**. Vercel sẽ tự động build và cấp phát tên miền trực tuyến cho bạn!
|