Video demo : Link Video Demo

🚀 Hướng dẫn Deploy Hệ thống CellVisualization

Tài liệu này hướng dẫn chi tiết cách triển khai hệ thống CellVisualization (Laravel + React + AI Python Backend) từ một máy chủ mới tinh (Fresh Install).

🟢 PHẦN A: SETUP TRÊN WINDOWS SERVER

Phần này dành cho việc triển khai trên Windows (Localhost hoặc Windows VPS) sử dụng XAMPP.

1. Chuẩn bị Môi trường (Prerequisites)

1.1. Cài đặt XAMPP (Web Server & Database)

• Tải xuống XAMPP cho Windows (Chọn phiên bản PHP 8.2 hoặc 8.3).
• Cài đặt và khởi động Apache và MySQL từ XAMPP Control Panel.

1.2. Cài đặt Công cụ phụ trợ

• Composer: Tải Composer-Setup.exe và cài đặt.
• Node.js: Tải Node.js LTS (v20 hoặc v22) và cài đặt.
• Miniconda (Quản lý Python): Tải Miniconda3 Windows 64-bit và cài đặt. (Lưu ý: Trong quá trình cài, tick chọn "Add Miniconda3 to my PATH environment variable" nếu muốn dùng tiện lợi trong CMD, hoặc dùng Anaconda Prompt sau này).

2. Thiết lập Web App (Laravel)

1. Mở Terminal (PowerShell hoặc CMD): Di chuyển đến thư mục htdocs của XAMPP.

   cd C:\xampp\htdocs

2. Tải mã nguồn:

   git clone https://github.com/garnalam/Cell-Visualize.git
   cd Cell-Visualize

3. Cài đặt thư viện:

   composer install
   npm install
   npm run build

4. Cấu hình Database:

   • Copy file môi trường:

     copy .env.example .env

   • Mở file .env và chỉnh sửa:

     DB_CONNECTION=mysql
     DB_HOST=127.0.0.1
     DB_PORT=3306
     DB_DATABASE=cell_visualization
     DB_USERNAME=root
     DB_PASSWORD=

5. Mở trình duyệt vào http://localhost/phpmyadmin, tạo database mới tên là cell_visualization.

6. Hoàn tất Laravel:

   php artisan key:generate
   php artisan storage:link
   php artisan migrate

3. Thiết lập AI Backend

3.1. Tạo môi trường Python

Mở Anaconda Prompt (hoặc CMD nếu đã add path) và chạy:

# 1. Tạo môi trường 'lab' với Python 3.12
conda create -n lab python=3.12 -y

# 2. Kích hoạt môi trường
conda activate lab

# 3. Di chuyển vào thư mục AI Core
cd C:\xampp\htdocs\Cell-Visualize\ai_core

# 4. Cài đặt các thư viện cần thiết
pip install -r requirements.txt

3.2. Cấu hình Model nnU-Net (BẮT BUỘC)

Đây là bước quan trọng nhất để tính năng Segment hoạt động.

1. Tìm thư mục cài đặt: Tại cửa sổ Anaconda Prompt đang active lab, gõ:

   python -c "import nnunetv2; print(nnunetv2.__path__[0])"

   (Kết quả ví dụ: C:\Users\Admin\miniconda3\envs\lab\Lib\site-packages\nnunetv2).

2. Chép dữ liệu Model:

   • Tải 4 thư mục dữ liệu từ Google Drive.
   • Copy đè (Overwrite) 4 thư mục này vào đường dẫn tìm được ở bước 1.

3.3. Cấu hình file .env cho AI Server

Trong file ai_core/.env với nội dung (sửa đường dẫn cho đúng thực tế máy bạn):

APP_ENV=local
PORT=8001
LARAVEL_STORAGE_PATH=C:\xampp\htdocs\Cell-Visualize\storage\app\public

# Đường dẫn python.exe của môi trường 'lab'
NNUNET_PYTHON_EXE=C:\Users\Admin\miniconda3\envs\lab\python.exe

# Đường dẫn thư viện nnunetv2 (nơi vừa copy model vào)
NNUNET_BASE_PATH=C:\Users\Admin\miniconda3\envs\lab\Lib\site-packages\nnunetv2

MODEL_CLS_NAME=darkcovidnet_3class_state.pth

4. Chạy Hệ thống (Windows)

Bạn cần mở 2 cửa sổ Terminal riêng biệt:

Terminal 1 (Laravel):

cd C:\xampp\htdocs\Cell-Visualize
php artisan serve

(Web chạy tại: http://127.0.0.1:8000)

Terminal 2 (AI Server):

conda activate lab
cd C:\xampp\htdocs\Cell-Visualize\ai_core
python api_server.py

(API chạy tại: http://127.0.0.1:8001)

---

🔵 PHẦN B: SETUP TRÊN LINUX SERVER (UBUNTU 22.04/24.04)

Phần này hướng dẫn setup trên VPS Linux mới tinh (Fresh Install) dùng Nginx/Apache và Systemd.

1. Cập nhật hệ thống & Cài đặt gói cơ bản

Đăng nhập SSH vào server và chạy:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl unzip zip software-properties-common

2. Thiết lập Môi trường Web (LAMP Stack)

2.1. Cài đặt PHP 8.3, Apache & MySQL

# Thêm repo PHP mới nhất
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

# Cài đặt PHP 8.3 và các extension cần thiết
sudo apt install -y php8.3 php8.3-cli php8.3-common php8.3-mysql php8.3-zip php8.3-gd php8.3-mbstring php8.3-curl php8.3-xml php8.3-bcmath

# Cài đặt Apache2
sudo apt install -y apache2 libapache2-mod-php8.3

# Cài đặt MySQL
sudo apt install -y mysql-server

2.2. Cài đặt Composer & Node.js

# Cài Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Cài Node.js 20 (LTS)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

2.3. Cài đặt Miniconda (Quản lý Python)

mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm -rf ~/miniconda3/miniconda.sh
~/miniconda3/bin/conda init bash
source ~/.bashrc

3. Triển khai Mã nguồn (Project Setup)

3.1. Clone Code & Install Dependencies

Giả sử cài đặt vào /var/www/html/CellVisualization.

cd /var/www/html
sudo git clone https://github.com/garnalam/Cell-Visualize.git
sudo chown -R $USER:$USER CellVisualization
cd CellVisualization

# Cài thư viện
composer install --optimize-autoloader --no-dev
npm install
npm run build

3.2. Cấu hình Database

# Đăng nhập MySQL
sudo mysql

Chạy lệnh SQL:

CREATE DATABASE cell_visualization;
CREATE USER 'cell_user'@'localhost' IDENTIFIED BY 'YourStrongPassword123!';
GRANT ALL PRIVILEGES ON cell_visualization.* TO 'cell_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Cập nhật file .env:

cp .env.example .env
nano .env

Sửa DB_DATABASE, DB_USERNAME, DB_PASSWORD theo thông tin trên.

Hoàn tất setup Laravel:

php artisan key:generate
php artisan migrate --force
php artisan storage:link

3.3. Phân quyền (Rất quan trọng trên Linux)

# Cấp quyền cho Apache user (www-data) ghi vào storage
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

4. Thiết lập AI Environment (Linux)

4.1. Tạo môi trường Conda

conda create -n lab python=3.12 -y
conda activate lab

# Di chuyển vào ai_core
cd /var/www/html/CellVisualization/ai_core

# Cài thư viện (Linux server thường ko có màn hình, cài opencv-python-headless nếu cần)
pip install -r requirements.txt
# Fix lỗi thiếu libGL nếu có:
sudo apt install libgl1

4.2. Cấu hình nnU-Net

Tìm đường dẫn thư viện:

python -c "import nnunetv2; print(nnunetv2.__path__[0])"
# Ví dụ output: /home/ubuntu/miniconda3/envs/lab/lib/python3.12/site-packages/nnunetv2

Upload và Copy Model: Dùng SFTP (FileZilla/WinSCP) để upload 4 thư mục model (nnUNet_raw...) lên server, sau đó copy đè vào đường dẫn trên.

4.3. Tạo file .env cho AI Server

nano /var/www/html/CellVisualization/ai_core/.env

Nội dung:

APP_ENV=production
PORT=8001
LARAVEL_STORAGE_PATH=/var/www/html/CellVisualization/storage/app/public

# Sửa 2 dòng dưới theo đường dẫn thật trên server của bạn (dùng lệnh `which python` trong env lab để xem)
NNUNET_PYTHON_EXE=/home/ubuntu/miniconda3/envs/lab/bin/python
NNUNET_BASE_PATH=/home/ubuntu/miniconda3/envs/lab/lib/python3.12/site-packages/nnunetv2

MODEL_CLS_NAME=darkcovidnet_3class_state.pth

5. Chạy Tự động (Production Service)

Trên Linux, chúng ta không chạy thủ công mà dùng Systemd để AI Server tự chạy lại khi khởi động máy.

5.1. Tạo Service file

sudo nano /etc/systemd/system/cell-ai.service

Dán nội dung sau (Sửa User và đường dẫn cho đúng):

[Unit]
Description=Cell AI Python Server
After=network.target

[Service]
# User chạy lệnh (nên là user sở hữu code hoặc www-data, nhưng conda env thường nằm ở user thường)
User=ubuntu
Group=www-data
WorkingDirectory=/var/www/html/CellVisualization/ai_core
# Đường dẫn tuyệt đối đến python trong env 'lab'
ExecStart=/home/ubuntu/miniconda3/envs/lab/bin/python api_server.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

5.2. Kích hoạt Service

sudo systemctl daemon-reload
sudo systemctl enable cell-ai
sudo systemctl start cell-ai

# Kiểm tra trạng thái
sudo systemctl status cell-ai

5.3. Cấu hình Apache VirtualHost (Để chạy Web Laravel)

sudo nano /etc/apache2/sites-available/cell-viz.conf

Nội dung:

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/html/CellVisualization/public

    <Directory /var/www/html/CellVisualization/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Kích hoạt:

sudo a2ensite cell-viz.conf
sudo a2enmod rewrite
sudo systemctl restart apache2

Hoàn tất!

• Web truy cập tại: http://your-server-ip
• AI API chạy ngầm tại: http://127.0.0.1:8001