Chuyển tới nội dung chính

Triển khai

Hướng dẫn triển khai lên một VPS bằng Docker Compose. Nội dung được chuyển từ DEPLOYMENT.md (tiếng Anh, nay chỉ còn trỏ tới đây), đã đối chiếu với docker-compose.prod.yml và Dockerfile. Stack compose production (thứ tự khởi động, tự phục hồi, seed, scripts/deploy.sh, scripts/backup-mongo.sh) đã chạy thử trên Docker cục bộ. Chưa xác minh trên VPS thật: chứng chỉ TLS, workflow đẩy image và mức RAM dưới tải.

Hai cách chạy​

Phát triểnProduction (VPS)
File composedocker-compose.ymldocker-compose.prod.yml
File môi trường.env.env.production
Backendnpm run dev trên máyImage production kéo từ Docker Hub (build ở CI), không phải root, có healthcheck
MongoDB và RedisGắn vào 127.0.0.1Mạng Docker riêng, không publish, Redis có mật khẩu
HTTPSKhôngCaddy trong compose, tự cấp chứng chỉ Let's Encrypt
Swaggerhttp://localhost:8081/apiTắt (đặt SWAGGER_ENABLED=true để mở)

Chạy local: quick-start.

Kiến trúc triển khai tham chiếu​

Cấu hình mẫu trong DEPLOYMENT.md: Ubuntu 22.04 trở lên, 2 vCPU, 4 GB RAM, Docker Engine kèm Compose plugin. Sơ đồ: container-diagram.

Các bước​

Hướng dẫn từng bước cho VPS nhỏ (1.5GB RAM) kèm FE trên Vercel: vps-production-guide. Các mục dưới đây là tham chiếu.

1. Chuẩn bị máy chủ​

  • Tường lửa chỉ mở SSH, 80, 443 (ví dụ ufw).
  • Cài Docker Engine kèm Compose plugin. Caddy chạy trong compose nên không cần nginx hay certbot.
  • Lưu ý: cổng do Docker publish bỏ qua ufw. Vì vậy compose production chỉ publish 80 và 443 (Caddy); backend, MongoDB, Redis không publish cổng nào. Không đổi điều này.

2. Cấu hình môi trường​

git clone <repo-url> /opt/job-portal-be && cd /opt/job-portal-be
cp .env.example .env.production
chmod 600 .env.production

Đặt tối thiểu (giá trị thật tự sinh bằng openssl rand -hex ..., không lưu vào git):

NODE_ENV=production
PORT=8081
FE_URL=https://example.com
CORS_ORIGINS=https://example.com,https://www.example.com
TRUST_PROXY=1
MONGO_INITDB_ROOT_PASSWORD=<chuỗi hex ngẫu nhiên>
REDIS_PASSWORD=<chuỗi hex ngẫu nhiên>
JWT_ACCESS_TOKEN_SECRET=<chuỗi hex ngẫu nhiên>
JWT_REFRESH_TOKEN_SECRET=<chuỗi hex ngẫu nhiên>
OTP_SECRET=<chuỗi hex ngẫu nhiên>

kèm các biến SMTP_*, GOOGLE_*, GEMINI_*, GROQ_*, AI_GROQ_*, EMAIL_ADMIN, INIT_PASSWORD. Danh sách đầy đủ: environment-variables.

  • Dùng mật khẩu hex vì MONGO_URL được dựng từ chúng; ký tự @ / : làm hỏng URI.
  • MONGO_URL và REDIS_HOST trong file bị compose ghi đè.
  • Cookie refresh là Secure và SameSite=Strict ở production, nên frontend và API phải phục vụ qua HTTPS và cùng site (ví dụ example.com và api.example.com).

3. Khởi động​

./scripts/deploy.sh # pull image theo IMAGE_TAG rồi up -d --wait
curl -s https://<API_DOMAIN>/api/v1/health/ready

Cần thêm DOCKERHUB_USER, IMAGE_NAME, IMAGE_TAG, API_DOMAIN vào .env.production (xem .env.example).

4. Dữ liệu ban đầu​

npm run seed tạo kỹ năng, nguồn tin và tài khoản quản trị EMAIL_ADMIN. Công ty, tin, CV và các tài khoản mẫu @seed.local chỉ được tạo khi NODE_ENV là development hoặc test; mọi giá trị khác, kể cả không đặt, đều chỉ tạo admin (seed.service.ts). Ở chế độ này INIT_PASSWORD phải dài ít nhất 12 ký tự. Đổi mật khẩu admin sau lần đăng nhập đầu.

5. Reverse proxy và TLS​

Caddy chạy trong compose, cấu hình ở Caddyfile, tự cấp và gia hạn chứng chỉ Let's Encrypt cho API_DOMAIN:

Thiết lậpLý do
request_body max_size 10MBỨng dụng giới hạn upload 5 MB
TRUST_PROXY=1 trong .env.productionCaddy gửi X-Forwarded-For; thiếu thì rate limit và phiên dùng chung IP của proxy
WebSocketCaddy chuyển tiếp mặc định; Socket.IO ở /notifications cần
flush_interval -1Stream chat SSE không bị gom đệm

DNS của API_DOMAIN phải trỏ về VPS và cổng 80, 443 mở trước khi khởi động Caddy. Chưa kiểm chứng với DNS và chứng chỉ thật.

6. Cập nhật phiên bản​

Quy trình đầy đủ (gắn tag image, kiểm tra readiness, điều kiện rollback): rollback. Lệnh tối thiểu khi chưa dùng IMAGE_TAG:

# sửa IMAGE_TAG trong .env.production rồi:
./scripts/deploy.sh

SIGTERM từ docker stop kích hoạt shutdown hook của Nest nên hàng đợi và kết nối database đóng gọn (app.enableShutdownHooks() trong main.ts). Quá trình này có thời gian ngừng ngắn vì chỉ có một container, và các token trong CACHE_MANAGER (đặt lại mật khẩu, hủy xóa tài khoản) mất khi khởi động lại (data-flow).

Nâng cấp Phase 1 (chạy một lần)​

Sao lưu MongoDB và hai volume uploads, cv_storage trước (xem backup-and-recovery).

  1. Kéo image mới (build sẵn ở CI), chưa khởi động lại backend. Chạy dedupe và tạo unique index bằng image mới:

    docker compose -f docker-compose.prod.yml --env-file .env.production pull backend
    docker compose -f docker-compose.prod.yml --env-file .env.production run --rm backend \
    node dist/databases/migrations/application-unique-index.js

    Đơn trùng bị soft-delete (giữ đơn mới nhất) và có deletedBy.email = "system:dedupe-migration". Chạy bước này trước khi code mới khởi động để autoIndex không build index trên dữ liệu còn trùng. Chạy lại an toàn.

  2. Khởi động backend mới: docker compose -f docker-compose.prod.yml --env-file .env.production up -d backend.

  3. Dời file CV cũ sang volume private:

    docker compose -f docker-compose.prod.yml --env-file .env.production exec backend \
    node dist/databases/migrations/move-cv-files-to-private-storage.js

    Exit code 1 nghĩa là có file trùng tên khác nội dung; file đó vẫn nằm ở public/images/... và cần xử lý tay. Từ bước 2 đến bước 3, CV cũ chưa mở được (404).

  4. Deploy frontend (nút "Xem CV" gọi GET /resumes/:id/file).

7. Sao lưu​

Xem backup-and-recovery.

Rollback​

Xem Deploy và rollback: image gắn tag do CI đẩy lên Docker Hub, chọn bằng IMAGE_TAG; rollback bằng cách đặt lại tag cũ rồi chạy ./scripts/deploy.sh.

Known Limitation​

  • Không có CD, không có staging; mọi bước là tay.
  • Một container, không có nhân bản; cần xử lý cron, Socket.IO, cache và file trước khi chạy nhiều instance (scalability).