// File: docs/deployment-setup-guide.md // Change Log // - 2026-05-22: แก้ไข IP Address ของเซิร์ฟเวอร์ AI จาก 192.168.10.100 เป็น 192.168.10.8 เพื่อให้ตรงกับสภาพแวดล้อมจริง # คู่มือการตั้งค่าและการ Deploy ระบบ (Deployment Setup Guide) > **Project:** NAP-DMS (LCBP3) > **Version:** 1.9.5 > **Last Updated:** 2026-05-21 > **Stack:** NestJS + Next.js + MariaDB + Redis + Elasticsearch + Qdrant > **Target Platform:** QNAP TS-473A (Container Station) + ASUSTOR AS5403T (Gitea Runner) --- ## 🏗️ 1. สถาปัตยกรรมระบบการ Deploy (Deployment Architecture) ระบบ DMS แยกการทำงานออกเป็นเซิร์ฟเวอร์หลัก 2 เครื่องเพื่อความปลอดภัยและประสิทธิภาพสูงสุด (Server Role Separation): - **QNAP Server (TS-473A) - `192.168.10.8` (VLAN 10):** เป็นเซิร์ฟเวอร์หลักที่รันฐานข้อมูล, Cache, Search Engine และรัน Application Containers (Frontend + Backend) รวมถึง Git Server (Gitea) และ Nginx Proxy Manager (NPM) - **ASUSTOR Server (AS5403T) - `192.168.10.9` (VLAN 10):** เป็นเซิร์ฟเวอร์สำหรับรัน CI/CD Gitea Runner (`act_runner`) เพื่อแยกโหลดการ Build โค้ดออกจากโปรดักชันเซิร์ฟเวอร์ ``` [ ASUSTOR Runner ] (192.168.10.9) │ │ SSH (Via Private Key) ▼ [ QNAP TS-473A ] (192.168.10.8) ├── Git Pull & Build (BuildKit) └── Restart Stack (docker compose --force-recreate) ``` --- ## 🔐 2. การตั้งค่า SSH Key Authentication (Persistent SSH Setup) เนื่องจาก QNAP จะรีเซ็ต Directory `/` ไปเป็น RAM หลังการ Reboot ทำให้เกิดปัญหา SSH Key หาย เราจำเป็นต้องตั้งค่าให้เป็น Persistent SSH: ### 2.1 บน ASUSTOR (Gitea Runner) สร้าง SSH Key Pair และเก็บไว้ในโฟลเดอร์ถาวร: - **Private Key:** `/etc/config/ssh/gitea-runner` - **Public Key:** `/etc/config/ssh/gitea-runner.pub` ### 2.2 บน QNAP (Target Server) 1. นำเนื้อหา Public Key ไปเพิ่มในไฟล์ `authorized_keys`: ```bash mkdir -p /etc/config/ssh # เพิ่ม public key ลงไป (ต้องอยู่ภายในบรรทัดเดียว ห้ามเว้นวรรคผิดพลาด) nano /etc/config/ssh/authorized_keys ``` 2. แก้ไขไฟล์คอนฟิก SSH ของ QNAP (สำคัญมาก: ต้องแก้ไฟล์ที่ **`/etc/config/ssh/sshd_config`** เท่านั้น ไม่ใช่ `/etc/ssh/sshd_config`): ```ini # ตั้งค่า AuthorizedKeysFile ชี้ไปที่ absolute path ของโฟลเดอร์คอนฟิกถาวร AuthorizedKeysFile /etc/config/ssh/authorized_keys ``` *หมายเหตุ: ห้ามใช้ relative path เช่น `.ssh/authorized_keys` เด็ดขาด เพราะระบบจะไปหาที่ `/share/homes/admin/.ssh/` แทนที่จะเป็น `/root/.ssh/`* 3. Reload QNAP SSH daemon (เนื่องจาก QNAP ไม่มี `pgrep` และ `systemctl` ให้ใช้คำสั่งนี้): ```bash kill -HUP $(ps | grep "/usr/sbin/sshd -f /etc/config" | grep -v grep | awk '{print $1}') ``` --- ## 📁 3. การเตรียมโครงสร้างโฟลเดอร์บน QNAP ล็อกอินเข้า QNAP ผ่าน SSH และรันคำสั่งเตรียม Directory โครงสร้างพื้นฐาน: ```bash # 1. โฟลเดอร์หลักสำหรับ App Source และ Build Script mkdir -p /share/np-dms/app/source # Clone repository (ครั้งแรกครั้งเดียว) cd /share/np-dms/app/source git clone https://git.np-dms.work/np-dms/lcbp3.git # 2. โฟลเดอร์สำหรับเก็บไฟล์อัปโหลดและ Logs mkdir -p /share/np-dms/data/uploads/temp mkdir -p /share/np-dms/data/uploads/permanent mkdir -p /share/np-dms/data/logs/backend # 3. ตั้งค่าสิทธิ์โฟลเดอร์ (UID 1001 คือ NestJS User ภายใน Container) chown -R 1001:1001 /share/np-dms/data/uploads chown -R 1001:1001 /share/np-dms/data/logs/backend chmod -R 750 /share/np-dms/data/uploads # 4. โฟลเดอร์สำหรับ persistent volumes ของ DB/Services อื่นๆ mkdir -p /volume1/lcbp3/volumes/mariadb-data mkdir -p /volume1/lcbp3/volumes/redis-data mkdir -p /volume1/lcbp3/volumes/elastic-data ``` --- ## 📝 4. การจัดการ Environment Variables (`.env`) สร้างไฟล์ `.env` ที่ **`/share/np-dms/app/.env`** บน QNAP โดยตรง ⚠️ *กฎความปลอดภัย (Tier 1): ห้าม Commit ไฟล์นี้ขึ้น Git หรือเก็บในโฟลเดอร์ Source Code เด็ดขาด!* ```dotenv # File: /share/np-dms/app/.env # Application Configuration NODE_ENV=production APP_NAME=LCBP3-DMS NEXT_PUBLIC_API_URL=https://backend.np-dms.work/api AUTH_URL=https://lcbp3.np-dms.work # Database (MariaDB native UUID v7 - ADR-019) DB_HOST=mariadb DB_PORT=3306 DB_USERNAME=lcbp3_user DB_PASSWORD= DB_DATABASE=lcbp3_dms DB_POOL_SIZE=20 # Redis Cache & BullMQ (ADR-008) REDIS_HOST=cache REDIS_PORT=6379 REDIS_PASSWORD= REDIS_DB=0 # Security Credentials (Tier 1) JWT_SECRET=<สร้างด้วย openssl rand -base64 32> AUTH_SECRET=<สร้างด้วย openssl rand -base64 32> # File Upload Security (Tier 1) UPLOAD_PATH=/app/uploads MAX_FILE_SIZE=52428800 # 50MB ALLOWED_FILE_TYPES=.pdf,.doc,.docx,.xls,.xlsx,.dwg,.zip # ClamAV Antivirus CLAMAV_HOST=lcbp3-clamav CLAMAV_PORT=3310 # AI Services Boundary (ADR-023/ADR-023A - Isolation on Admin Desktop) OLLAMA_URL=http://192.168.10.8:11434 AI_HOST_URL=http://192.168.10.8:11434 AI_QDRANT_URL=http://192.168.10.8:6333 ``` --- ## 🔄 5. การตั้งค่า CI/CD Gitea Actions ใน Gitea Web UI ไปที่ repository → **Settings** → **Actions** → **Secrets** เพื่อเพิ่มตัวแปรลับ (Secrets) ที่ใช้เชื่อมต่อ SSH ไปยัง QNAP: | Secret Name | Value | คำอธิบาย | | :--- | :--- | :--- | | `HOST` | `192.168.10.8` | IP Address ของ QNAP (VLAN 10) | | `PORT` | `22` | พอร์ต SSH (Default: 22) | | `USERNAME` | `admin` | สิทธิ์แอดมินในการควบคุม Container ของ QNAP | | `SSH_KEY` | `-----BEGIN OPENSSH PRIVATE KEY-----...` | เนื้อหาในไฟล์คีย์ส่วนตัวจาก ASUSTOR (`/etc/config/ssh/gitea-runner`) | --- ## 🚀 6. ขั้นตอนการ Deploy ### 6.1 การ Deploy อัตโนมัติ (Automated CI/CD) เมื่อมีการ Push โค้ดไปยังกิ่ง `main` ระบบ Gitea Actions จะรับงานไปรันบน ASUSTOR Runner: 1. เชื่อมต่อ SSH ไปยัง QNAP (สิทธิ์ `admin` ผ่าน SSH Key) 2. สั่ง `git pull` ดึงโค้ดล่าสุดลงโฟลเดอร์ `/share/np-dms/app/source/lcbp3` 3. เรียกใช้สคริปต์ `@/scripts/deploy.sh` ของโครงการเพื่อทำการ build และ deploy ### 6.2 การ Deploy ด้วยตนเอง (Manual Deploy) หากพบปัญหาเรื่องเน็ตเวิร์ก หรือต้องการรัน Deploy เองตรงจาก QNAP: ```bash # 1. SSH เข้า QNAP ssh admin@192.168.10.8 # 2. ไปที่โฟลเดอร์ Repository และ pull โค้ดล่าสุด cd /share/np-dms/app/source/lcbp3 git pull origin main # 3. รันสคริปต์ Deploy bash scripts/deploy.sh ``` ### รายละเอียดการทำงานของ `deploy.sh`: - **Build Step (BuildKit):** รันคำสั่ง Build Image ในแบบขนานกัน (Parallel) เพื่อลดเวลาก่อสร้าง: ```bash docker build -f backend/Dockerfile -t lcbp3-backend:latest . & docker build -f frontend/Dockerfile -t lcbp3-frontend:latest . & ``` - **Recreate Container:** ใช้ `--force-recreate` ควบคู่กับ Environment file โปรดักชัน: ```bash docker compose --env-file /share/np-dms/app/.env -f specs/04-Infrastructure-OPS/04-00-docker-compose/QNAP/app/docker-compose-app.yml up -d --force-recreate ``` - **Health Check:** ตรวจสอบความถูกต้องของการสตาร์ตระบบ (Timeout 60 วินาที) ก่อนรายงานผลความสำเร็จ --- ## 🆘 7. การกู้คืนระบบและการแก้ปัญหา (Rollback & Troubleshooting) ### 7.1 การ Rollback ระบบ หากหลังจาก Deploy พบว่าระบบทำงานบกพร่อง (Critical Bug): 1. **ผ่าน Gitea UI:** ไปที่แท็บ **Actions** → เลือกกิ่งที่มีเสถียรภาพตัวล่าสุด (Stable Commit) → กดปุ่ม **Re-run Jobs** 2. **รันคำสั่งตรงบน QNAP (SSH):** ```bash cd /share/np-dms/app/source/lcbp3 # ตรวจหาแฮชคอมมิตก่อนหน้าที่มีความเสถียร git log --oneline -10 # ย้อนกลับโค้ด git checkout # รันสร้างและดีพลอยใหม่ด้วยโค้ดเดิม bash scripts/deploy.sh ``` ### 7.2 ปัญหาตู้คอนเทนเนอร์ค้าง (Container Removal Timeout) หากตอน Deploy มีอาการค้างที่กระบวนการลบตู้อันเดิม: ```bash # Force stop และลบตู้อันที่ค้าง docker kill backend frontend 2>/dev/null || true docker rm -f backend frontend 2>/dev/null || true # ทำความสะอาด Cache และ Prune ของตกค้าง docker system prune -f --volumes # รีสตาร์ตตู้ Stack ทั้งหมดใหม่อีกครั้ง bash scripts/deploy.sh ``` --- // Change Log: // - 2026-05-21: จัดทำเอกสารคู่มือขั้นตอนการเซ็ตอัปการ Deploy สำหรับทีมปฏิบัติการและผู้พัฒนา (v1.9.5)