HaoNgo232/paas-k3s

آخر نشاط مصدر مسجل: ١١ فبراير ٢٠٢٦ في ١٦:٠٠

آخر تحديث لفهرس SkillsMP: ٢٩ أكتوبر ٢٠٢٦ في ١٨:٣٠

skills مجمعة: ٢١

نجوم GitHub: ٠
تفرعات GitHub: ٠

التثبيت بمساعدة مساعد ذكي

انسخ هذا الطلب إلى المساعد الذكي الذي تستخدمه.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/HaoNgo232/paas-k3s.

ملف README للمستودع

مصدر ملف README للمستودع: README.md

قراءة الملف الأصلي

عرض ملف README كاملًا

# Hệ thống Quản trị Các Ứng dụng Web với Kiến trúc Microservices (PaaS K3s Platform) > [!WARNING] > **LƯU Ý:** > - **Tên đề tài chính thức (Luận văn Tốt nghiệp B2110964):** *"Hệ thống quản trị các ứng dụng web với kiến trúc Microservices"*. > - **Bản chất hiện thực kỹ thuật:** Đây là nguyên mẫu **Nền tảng PaaS tự lưu trữ (Self-hosted Mini-PaaS Platform)** trên K3s, giúp tự động hóa quy trình đóng gói (Cloud Native Buildpacks/Docker) và điều khiển triển khai các ứng dụng web/microservices. > - **Phạm vi sử dụng:** Hệ thống phục vụ khảo sát học thuật và kiểm chứng giải pháp thử nghiệm. Hệ thống **KHÔNG PHẢI** là sản phẩm thương mại (SaaS) và **CHƯA ĐƯỢC HARDEN/TESTING ĐẦY ĐỦ** cho môi trường sản xuất (production). --- ## 1. Bối cảnh & Mục tiêu Nghiên cứu Trong thực tiễn phát triển ứng dụng, việc vận hành container bằng Docker Engine đơn lẻ bộc lộ hạn chế về cân bằng tải, phân bổ tài nguyên đa node và quản lý tự động. Trong khi đó, các cụm Kubernetes tiêu chuẩn thường có độ phức tạp cao. Dự án **Hệ thống quản trị các ứng dụng web với kiến trúc Microservices (PaaS K3s Platform)** được triển khai nhằm giải quyết các bài toán: - **Khảo sát giải pháp Mini-PaaS tự dựng (Self-hosted PaaS):** Cung cấp trải nghiệm triển khai ứng dụng từ mã nguồn/Docker image tương tự Heroku hay Render nhưng chạy trên hạ tầng K3s (Lightweight Kubernetes). - **Kiến trúc quản lý Out-of-Cluster Control Plane:** Xây dựng Backend API (NestJS) nằm bên ngoài cụm K3s, điều khiển tài nguyên cụm thông qua Kubernetes API client và Ansible automation. - **Đóng gói mã nguồn không cần Dockerfile:** Tích hợp Cloud Native Buildpacks (kpack) để tự động phát hiện ngôn ngữ (Node.js, Java, Python...) và biên dịch thành OCI Container Image. - **Tự động điều phối dự án mẫu (Scaffold DAG):** Định hình các bộ dự án Fullstack Blueprint (Next.js + Express API + Database) và điều phối thứ tự triển khai theo Đồ thị hướng không chu trình (DAG) bằng BullMQ Flow. --- ## 2. Phạm vi & Giới hạn Thử nghiệm - **Phạm vi đã hoàn thiện & kiểm chứng:** - **Triển khai 3 phương thức:** Triển khai từ Docker Image có sẵn, từ mã nguồn GitHub (kpack buildpacks), và khởi tạo dự án mẫu Fullstack Scaffold. - **Quản lý Space & Project:** Cô lập tài nguyên dựa trên K8s Namespace và áp dụng `ResourceQuota` (CPU, RAM limits, Pod limits). - **Hạ tầng phụ trợ (Admin Panel):** Tự động cài đặt Local Registry (NodePort 30500), Redis (NodePort 30379), Metrics Server, Kpack Build System và Prometheus (HelmChart CRD native K3s). - **Tự động hóa Node (Ansible):** Thực thi Ansible Playbook qua SSH để khởi tạo Master node và join Worker node vào cụm K3s. - **Giám sát thời gian thực:** Stream log container stdout/stderr và build log qua **SSE**; theo dõi tiến trình node join/bootstrap qua **WebSocket**. - **Các giới hạn hiện tại:** - **Backend đơn lẻ (Single Control Plane):** Backend API, Frontend và Postgres/Redis chính chạy trên máy Host ngoài cụm K3s dưới dạng tiến trình đơn lẻ, chưa hỗ trợ High Availability (HA) hay Auto-scaling cho Control Plane. - **Chưa hỗ trợ PHP / Laravel:** Do ClusterStack của kpack hiện tại đang dùng bản Base Image (thiếu các extension như libonig, libxml2, php-fpm). Việc chuyển sang Stack Image bản Full để hỗ trợ PHP là hướng phát triển mở rộng. - **Lưu trữ dữ liệu (Storage):** Sử dụng Local Path Provisioner mặc định của K3s (lưu PersistentVolume trực tiếp trên đĩa của node chạy Pod, chưa có cơ chế replication dữ liệu đa node). - **Tính năng Rollback:** Đã thiết kế trường trạng thái `ROLLED_BACK` và cơ chế dọn dẹp dở dang (cleanup) khi gặp lỗi K8s manifest, nhưng chưa xây dựng giao diện/logic tự động rollback về phiên bản deployment cũ. - **GitHub Webhook:** Đã cài đặt endpoint tiếp nhận webhook `POST /github/webhooks/push` trong mã nguồn backend nhưng chưa qua kiểm thử kịch bản thực địa tự động redeploy. --- ## 3. Bản đồ Chức năng Kỹ thuật (Feature Matrix) | Nhóm chức năng | Trạng thái Hiện thực | Chi tiết Kỹ thuật | |----------------|----------------------|-------------------| | **Quản lý Space & Project** | Hoàn thành | Phân quyền Space theo Namespace K8s, giới hạn ResourceQuota theo Tier. | | **Triển khai từ Docker Image** | Hoàn thành | Khởi tạo K8s Deployment, ClusterIP Service và Ingress (nip.io domain). | | **Triển khai từ GitHub Repo** | Hoàn thành (kpack) | Tự động phát hiện ngôn ngữ, build image via Buildpacks (Timeout: Node.js/Python 10m, Java 20m). | | **Scaffold Project (Blueprint)** | Hoàn thành (DAG) | Điều phối BullMQ Flow 3 tầng: Cấp phát DB (`scaffold-db`) -> API (`scaffold-app`) -> Frontend (`web`). | | **Quản lý Cluster K3s** | Hoàn thành (Ansible) | Khởi tạo Master Node, Join Worker Node qua SSH Ansible Playbooks. | | **Cài đặt Hạ tầng Phụ trợ** | Hoàn thành | Cài đặt Local Registry, Redis, Metrics Server, Kpack và Prometheus (via HelmChart CRD). | | **Theo dõi Thời gian thực** | Hoàn thành | Stream log Pod & Build log qua SSE; Stream tiến trình Ansible qua WebSocket. | --- ## 4. Kiến trúc Mạng & Phân bổ Môi trường Thử nghiệm ```mermaid flowchart TD subgraph Host["Máy Host (192.168.56.13 - Quản trị Nền tảng)"] FE["Next.js Frontend (Port 3000)"] BE["NestJS Backend API (Port 3001)"] DB[("PostgreSQL 16 (Port 5432)")] RD[("Redis 7.2 (Port 6379)")] end subgraph Cluster["Cụm K3s (VirtualBox Host-only Network 192.168.56.0/24)"] subgraph MasterVM["VM1: Master Node (192.168.56.10 - 2 vCPU, 4GB RAM)"] K3S_CP["K3s Control Plane / API Server (Port 6443)"] TRAEFIK["Traefik Ingress (Port 80/443)"] REGISTRY["Local Registry (NodePort 30500)"] KPACK["Kpack Build Engine"] end subgraph WorkerVM["VM2: Worker Node (192.168.56.11 - 2 vCPU, 2GB RAM)"] K3S_AGENT["K3s Agent & containerd"] PODS["User Application Pods"] end end BE -->|K8s API Client :6443| K3S_CP BE -->|Ansible SSH :22| MasterVM BE -->|Ansible SSH :22| WorkerVM FE -->|HTTP / SSE / WS| BE ``` --- ## 5. Môi trường Thử nghiệm & Hướng dẫn Tái lập Demo ### Thông số Môi trường Thử nghiệm - **Máy Host (Nền tảng):** Linux Mint / Ubuntu (Intel Core i7, 16GB RAM). Chạy Backend API (NestJS), Frontend (Next.js), PostgreSQL & Redis qua Docker. - **Máy ảo K3s Cluster (VirtualBox Host-Only):** - **VM1 (Master Node):** IP `192.168.56.10` (2 vCPU, 4GB RAM, Debian). - **VM2 (Worker Node):** IP `192.168.56.11` (2 vCPU, 2GB RAM, Debian). - **Phiên bản Phần mềm:** K3s `v1.34.6+k3s1`, Node.js `v22/v20`, NestJS `11`, Next.js `15`, pnpm `10`, Prisma `7`, BullMQ `5`. ### Các bước Tái lập Môi trường Thử nghiệm ```bash # 1. Khởi chạy cơ sở dữ liệu hệ thống (PostgreSQL & Redis) docker compose up -d # 2. Khởi chạy Backend Control Plane cd backend cp .env.example .env pnpm install pnpm prisma migrate dev pnpm run start:dev # 3. Khởi chạy Frontend Management UI cd ../frontend cp .env.example .env.local pnpm install pnpm dev ``` *Truy cập giao diện quản trị tại:* `http://localhost:3000` *Chi tiết cấu hình môi trường xem tại:* [Experimental Setup Guide](openwiki/operations/experimental-setup.md). --- ## 6. Hệ thống Tài liệu Wiki (`openwiki/`) | Khu vực | Trang Tài liệu | Nội dung Chính | |---------|----------------|----------------| | **Kiến trúc** | [Architecture Overview](openwiki/architecture/overview.md) | Kiến trúc phân tầng backend, mô hình mạng 3 máy, rationale out-of-cluster | | **Mô hình Dữ liệu** | [Domain Concepts](openwiki/domain/concepts.md) | Định nghĩa thực thể (Space, Project, Service, Deployment), K8s mapping | | **Luồng Triển khai** | [Deployment Workflow](openwiki/workflows/deployment.md) | Vòng đời deployment 3 nguồn, kpack timeout, xử lý cleanup & rollback | | **Hệ thống Blueprint** | [Scaffold Workflow](openwiki/workflows/scaffold.md) | Template Registry (`manifest.json`, Handlebars overlays), BullMQ DAG Flow | | **Tích hợp K3s** | [Kubernetes Integration](openwiki/integrations/kubernetes.md) | Client v1 Type-guards, Ansible playbooks, cài đặt 5 thành phần hạ tầng | | **Tham chiếu API** | [API Endpoints](openwiki/api/endpoints.md) | REST API, SSE streaming endpoints và Socket.IO tracking gateway | | **Môi trường Lab** | [Experimental Setup](openwiki/operations/experimental-setup.md) | Thiết lập máy Host + VM Master/Worker, thông số phiên bản phần mềm | | **Thử nghiệm & Test** | [Testing Overview](openwiki/testing/overview.md) | Unit test Jest/Vitest, kịch bản thử nghiệm load balance & multi-node | --- ## 7. Hướng Phát triển Tiếp theo (Future Work) - Đóng gói Backend Control Plane và triển khai High Availability (HA) trực tiếp lên K3s. - Nâng cấp kpack ClusterStack sang bản Full để hỗ trợ **PHP** cùng các framework như Laravel / WordPress. - Hoàn thiện giao diện và logic tự động **Rollback** về phiên bản deployment lịch sử. - Kiểm thử kịch bản thực địa đầy đủ cho **GitHub Webhook Auto-Redeploy**. - Nâng cấp giải pháp lưu trữ dữ liệu phân tán (như Rook/Ceph hoặc Longhorn) thay thế cho Local Path Provisioner.

جارٍ تحميل ملف README للمستودع…

Skills في هذا المستودع

مطوّرو البرمجيات متخصصو إدارة المشاريع مديرو الشبكات وأنظمة الحاسوب المصممون الجرافيكيون

٧ فئات مهنية · 100% مصنفة