Deploy

Deploy Trọn Gói Next.js App & MySQL Lên AWS EC2 (Auto-Deploy + Mở Port DB Local)

Cập nhật 22/06/2026

Bài viết này hướng dẫn chi tiết các bước triển khai hệ thống Personal Developer Knowledge Base App lên nền tảng AWS EC2, thiết lập cơ chế tự động triển khai (Auto-deploy) với GitHub Actions khi đẩy mã nguồn vào nhánh master, mở cổng cơ sở dữ liệu MySQL để kết nối chỉnh sửa dữ liệu trực tiếp từ máy local, và cấu hình tên miền thông qua Caddy Server.

1. Cấu hình ban đầu trên AWS Console

Trước khi thao tác với dòng lệnh, bạn cần chuẩn bị môi trường bên ngoài thông qua giao diện web của AWS:

  1. Khởi tạo một phiên bản EC2 Instance. Khuyến nghị sử dụng hệ điều hành Ubuntu Server từ phiên bản 22.04 LTS trở lên. Cấu hình phần cứng tối thiểu nên là t3.small để tránh hiện tượng tràn bộ nhớ (Out of Memory) trong quá trình biên dịch Docker.

  2. Truy cập vào mục Security thuộc giao diện quản lý Instance, chọn Security Group, nhấp vào Edit Inbound Rules và tiến hành mở các cổng sau đây:

    • Cổng SSH (Port 22): Chọn cấu hình My IP để bảo mật.

    • Cổng HTTP (Port 80) và HTTPS (Port 443): Chọn cấu hình Anywhere-IPv4 (0.0.0.0/0) để tiếp nhận lưu lượng mạng công cộng.

    • Cổng MySQL/Aurora (Port 3306): Chọn cấu hình Anywhere-IPv4 hoặc My IP để thiết lập kết nối dữ liệu từ xa từ máy tính cá nhân.

2. Thiết lập môi trường trên máy chủ EC2

Thực hiện kết nối SSH vào máy chủ thông qua tệp Key Pair định dạng .pem (sử dụng lệnh ssh -i key.pem ubuntu@<IP_EC2>) và chạy tuần tự các nhóm lệnh dưới đây:

Cập nhật hệ thống và cài đặt các gói phụ trợ

Code
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git ufw

Cài đặt nền tảng Docker chính thức

Code
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker ubuntu

Cấu hình tường lửa nội bộ UFW

Code
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3306/tcp
sudo ufw --force enable

Áp dụng phân quyền Docker

Gõ lệnh sau đây để ngắt kết nối phiên làm việc SSH hiện tại:

exit

Thực hiện kết nối SSH lại vào máy chủ để cấu hình nhóm người dùng Docker chính thức có hiệu lực, giúp bạn có thể thực thi các lệnh Docker mà không cần tiền tố sudo.

3. Cấu hình GitHub Personal Access Token và tiến hành sao chép mã nguồn

Do cơ chế xác thực mặc định của GitHub không hỗ trợ nhập mật khẩu tài khoản trực tiếp dạng văn bản thông thường trên terminal, bạn cần sử dụng mã Token đại diện.

Các bước khởi tạo Personal Access Token (PAT) trên giao diện GitHub

  1. Đăng nhập vào tài khoản GitHub, nhấp vào ảnh đại diện ở góc trên cùng bên phải và chọn mục Settings.

  2. Di chuyển xuống danh mục dưới cùng ở thanh trình đơn bên trái, nhấp chọn Developer settings.

  3. Chọn Personal access tokens, sau đó nhấp vào mục Tokens (classic).

  4. Chọn Generate new token, tiếp tục chọn Generate new token (classic).

  5. Cấu hình các thông số cho mã Token:

    • Mục Note: Nhập tên gợi nhớ (Ví dụ: ec2-deploy-token).

    • Mục Expiration: Chọn thời hạn hiệu lực theo nhu cầu (90 ngày hoặc Không hết hạn).

    • Mục Select scopes: Tích chọn vào ô thuộc tính repo để cấp quyền sao chép các kho lưu trữ mã nguồn riêng tư.

  6. Nhấp chọn Generate token và tiến hành sao chép chuỗi mã hóa vừa được hiển thị (Chuỗi ký tự bắt đầu bằng cụm ghp_xxxxxxxxxxxx). Lưu ý lưu trữ chuỗi này cẩn thận vì hệ thống chỉ hiển thị một lần duy nhất.

Tiến hành sao chép mã nguồn về máy chủ

Quay lại cửa sổ dòng lệnh của máy chủ EC2, thực hiện lệnh sao chép bằng cách nhúng trực tiếp mã Token vào đường dẫn URL để bỏ qua bước xác thực thủ công:

git clone https://ngoctri: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@github.com/NguyenTri-2207/Personal-Developer-Knowledge-Base-App.git

4. Khởi tạo tệp cấu hình môi trường (.env)

Di chuyển vào thư mục dự án vừa được tải về hệ thống:

cd ~/Personal-Developer-Knowledge-Base-App/

Lưu ý quan trọng: Tệp tin cấu hình .env bắt buộc phải nằm bên trong thư mục chứa tệp docker-compose.yml của dự án để Docker Compose có thể nhận diện cấu hình chính xác, không được khởi tạo ngoài thư mục gốc của người dùng.

Khởi tạo và biên tập nội dung tệp .env:

nano .env

Tiến hành sao chép cấu hình môi trường thực tế vào nội dung tệp tin:

Đoạn mã

Code
# -----------------------------------------------------------------------------
# PDK DATABASE CONFIGURATION (LOCAL / PRODUCTION OVERRIDE)
# -----------------------------------------------------------------------------
PDK_MYSQL_ROOT_PASSWORD=my_super_secret_root_pass_123
PDK_MYSQL_DATABASE=pdk_knowledge_base
PDK_MYSQL_USER=pdk_kb_user
PDK_MYSQL_PASSWORD=my_kb_user_password_456

# Chuỗi kết nối cơ sở dữ liệu sử dụng nội bộ hệ thống hoặc từ xa
DATABASE_URL=mysql://pdk_kb_user:my_kb_user_password_456@localhost:3306/pdk_knowledge_base

PROJECT_NAME=projects/640443097330
PROJECT_NUMBER=640443097330

# Mã khóa API cho các dịch vụ AI tích hợp
GEMINI_API_KEY=AQ.Ab8RN6I1HxNvsu038rU98wxD2dxX-kfGRtzvt7Nmmz5pcHlumw
AI_MODEL=gemini-2.5-flash
DEEPSEEK_API_KEY=sk-eb2eca22762f4a63adb096997c514a14
DEEPSEEK_MODEL=deepseek-chat

Nhấn tổ hợp phím Ctrl + O, sau đó nhấn Enter để thực hiện lưu tệp tin, nhấn Ctrl + X để thoát khỏi trình soạn thảo văn bản nano. Tiến hành thiết lập phân quyền bảo mật hạn chế cho tệp cấu hình:

chmod 600 .env

5. Thiết lập quy trình triển khai tự động (CI/CD) với GitHub Actions

Mục đích cấu hình phần này nhằm giúp hệ thống tự động biên dịch lại mã nguồn mỗi khi có thao tác đẩy mã (push) vào nhánh chính master mà không cần quản trị viên can thiệp thủ công bằng dòng lệnh.

Tạo tệp tin Workflow tại môi trường máy local

Tại thư mục gốc của mã nguồn dưới máy tính cá nhân của bạn, tiến hành khởi tạo cấu trúc thư mục và tệp .github/workflows/deploy.yml với nội dung chi tiết sau:

Code
name: Deploy to AWS EC2

on:
  push:
    branches:
      - master # Kích hoạt quy trình khi có mã nguồn mới đẩy vào nhánh master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Deploy via SSH to EC2
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ubuntu
          key: ${{ secrets.EC2_SSH_KEY }}
          script: |
            cd ~/Personal-Developer-Knowledge-Base-App
            git checkout master
            git pull origin master
            docker compose --profile full up -d --build
            docker image prune -f

Cấu hình các biến môi trường ẩn (Secrets) trên kho lưu trữ GitHub

Truy cập vào giao diện web dự án của bạn trên GitHub, lần lượt chọn Settings, chọn mục Secrets and variables tại menu trái, nhấp chọn Actions. Chọn tiếp New repository secret để khởi tạo hai biến bảo mật sau:

  • Biến EC2_HOST: Nhập địa chỉ IP Public hoặc Elastic IP tĩnh của máy chủ EC2 (13.229.37.157).

  • Biến EC2_SSH_KEY: Mở tệp tin khóa bảo mật .pem trên máy tính của bạn, sao chép toàn bộ nội dung văn bản bên trong và dán trực tiếp vào đây.

6. Khởi chạy hệ thống lần đầu tiên bằng tay

Tại thư mục làm việc của dự án trên máy chủ EC2, tiến hành thực thi câu lệnh Docker Compose để hệ thống tải về các gói ảnh nền tảng (base images) và khởi tạo cấu trúc cơ sở dữ liệu ban đầu:

docker compose --profile full up -d --build

Lưu ý: Sau khi các tiến trình container báo trạng thái hoạt động ổn định, bạn có thể sử dụng các công cụ quản trị giao diện trực quan như MySQL Workbench kết nối từ xa trực tiếp qua tài khoản quản trị cao nhất root và mật khẩu PDK_MYSQL_ROOT_PASSWORD để nạp các tệp dữ liệu sao lưu định dạng .sql từ máy cá nhân lên thẳng máy chủ đám mây.

7. Cài đặt Caddy Server và cấu hình tên miền con (Subdomain)

Ứng dụng Caddy Server hoạt động như một máy chủ chuyển tiếp cuộc gọi (reverse proxy), tiếp nhận lưu lượng mạng từ cổng tiêu chuẩn công cộng 80/443 để điều hướng nội bộ vào cổng 3000 của ứng dụng Next.js, đồng thời tự động quản lý chứng chỉ bảo mật SSL HTTPS.

Thực hiện cài đặt Caddy Server lên hệ điều hành máy chủ

Code
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

Cấu hình tệp tin điều hướng Caddyfile

Mở tệp tin cấu hình hệ thống của Caddy:

sudo nano /etc/caddy/Caddyfile

Tiến hành dọn sạch toàn bộ các khối lệnh cấu hình mặc định sẵn có, thay thế bằng nội dung điều hướng cho tên miền con của bạn:

Đoạn mã

Code
pdk.siucode.com {
    reverse_proxy localhost:3000
}

Nhấn tổ hợp phím Ctrl + O, nhấn Enter để ghi nhớ dữ liệu tệp tin và nhấn Ctrl + X để đóng trình soạn thảo.

Áp dụng cấu hình và làm mới dịch vụ

Thực thi câu lệnh làm mới dịch vụ để hệ thống Caddy cập nhật tệp tin cấu hình mới và tự động tiến hành xác thực chứng chỉ mã hóa dữ liệu bảo mật SSL khóa xanh với tổ chức Let's Encrypt:

sudo systemctl reload caddy

8. Kết luận quy trình vận hành

Sau khi hoàn thành chuỗi thiết lập trên, bạn sẽ đạt được các kết quả vận hành sau:

  • Hệ thống ứng dụng chính thức hoạt động an toàn và ổn định thông qua địa chỉ tên miền mã hóa bảo mật: https://pdk.siucode.com.

  • Quy trình phân phối mã nguồn tự động được hoàn thiện trọn vẹn. Trong các phiên làm việc tiếp theo, bạn chỉ cần thực hiện thay đổi mã nguồn dưới máy tính cá nhân, chạy lệnh đẩy mã lên kho lưu trữ trực tuyến (git push origin master), máy chủ GitHub Actions sẽ tự động thực thi các công đoạn đóng gói, kết nối từ xa và cập nhật phiên bản mới lên máy chủ AWS EC2 một cách khép kín.