Hướng Dẫn Cài Đặt Và Sử Dụng Immich Trên Ubuntu Bằng Docker Compose

Cài đặt và sử dụng Immich trên Ubuntu là giải pháp tự host kho lưu trữ ảnh và video cá nhân hiệu quả nhất hiện nay để thay thế Google Photos và iCloud mà không tốn phí duy trì hàng tháng. Bài viết này từ InterData sẽ hướng dẫn bạn từng bước thiết lập Immich bằng Docker Compose, tối ưu mô hình Machine Learning, mở port an toàn và cấu hình ứng dụng di động tự động sao lưu nền liên tục.

1. Immich Là Gì? Vì Sao Nên Tự Host Thay Thế Google Photos?

Immich là phần mềm máy chủ mã nguồn mở tự host (self-hosted) chuyên dùng để quản lý, sao lưu và lập chỉ mục hình ảnh, video với tốc độ xử lý cao. Được phát triển nhằm thay thế trực tiếp các dịch vụ lưu trữ đám mây độc quyền, Immich cung cấp ứng dụng di động hỗ trợ đồng bộ tự động, cơ chế nhận diện khuôn mặt và tìm kiếm ngữ nghĩa thông minh ngay trên máy chủ của bạn.

Khi các nền tảng đám mây lớn áp dụng mức phí thuê bao định kỳ cho dung lượng vượt mức 15GB, nhu cầu chuyển đổi sang giải pháp lưu trữ Cloud Storage tự quản lý ngày càng phổ biến. Immich nổi lên như một lựa chọn dẫn đầu nhờ các đặc điểm kỹ thuật cụ thể:

• Giao diện tương đồng: Giao diện Web và Mobile (iOS/Android) được thiết kế hiện đại, hỗ trợ dòng thời gian (timeline), xem album, bản đồ định vị (Map View) và quản lý người dùng độc lập.
• Ứng dụng Trí tuệ Nhân tạo On-premise: Tích hợp sẵn mô hình CLIP để tìm kiếm hình ảnh bằng văn bản tự nhiên (ví dụ: “chó chạy trên cỏ”, “hóa đơn”, “hoàng hôn”) và mô hình Facial Recognition để gom nhóm khuôn mặt tự động mà không gửi dữ liệu ra máy chủ bên ngoài.
• Hỗ trợ định dạng gốc: Xử lý mượt mà ảnh RAW của máy ảnh chuyên nghiệp, Live Photos từ iOS, Motion Photos từ Android và video định dạng 4K HDR/HEVC với khả năng chuyển mã phần cứng (Hardware Transcoding).
• Quyền sở hữu dữ liệu 100%: Toàn bộ tệp tin media nằm trực tiếp trong hệ thống tệp cục bộ theo cấu trúc thư mục rõ ràng, không bị mã hóa hay đóng gói vào cơ sở dữ liệu đóng.

2. Yêu Cầu Phần Cứng Để Vận Hành Immich Trên Máy Chủ Ubuntu

Khác với các ứng dụng lưu trữ tĩnh đơn giản, Immich vận hành đồng thời các tiến trình trích xuất thumbnail, encode video và suy luận vector Machine Learning. Việc triển khai trên hệ điều hành Ubuntu Server (phiên bản 22.04 LTS hoặc 24.04 LTS) yêu cầu cấu hình phần cứng đáp ứng các thông số sau:

Nếu bạn tự host trên máy tính cá nhân hoặc bo mạch Raspberry Pi, rủi ro mất điện đột ngột có thể làm hỏng cơ sở dữ liệu PostgreSQL. Hơn nữa, việc không có địa chỉ IP tĩnh khiến việc sao lưu dữ liệu di động ngoài mạng nội bộ gặp khó khăn. Do đó, phương án triển khai trên máy chủ ảo VPS Ubuntu đặt tại các trung tâm dữ liệu tiêu chuẩn mang lại đường truyền mạng liên tục và tốc độ đọc ghi I/O cao cho thư viện ảnh.

3. Quy Trình 5 Bước Cài Đặt Immich Trên Ubuntu Bằng Docker Compose

Phương pháp cài đặt chuẩn hóa và dễ nâng cấp nhất hiện nay là sử dụng Docker Compose V2. Quy trình bao gồm 5 bước thực hiện trực tiếp trên giao diện dòng lệnh (CLI):

Bước 1: Cập nhật hệ thống và cài đặt Docker Engine + Docker Compose Plugin

Trước tiên, kết nối SSH vào máy chủ Ubuntu và thực hiện cập nhật toàn bộ các gói phần mềm hiện có. Nếu máy chủ chưa có Docker, hãy tham khảo cài đặt Docker Compose V2 trên Ubuntu để hoàn thiện môi trường nền tảng.

# Cập nhật danh sách gói hệ thống
sudo apt update && sudo apt upgrade -y

# Cài đặt các gói phụ thuộc cần thiết
sudo apt install -y curl wget apt-transport-https ca-certificates gnupg lsb-release

# Cài đặt Docker và Docker Compose Plugin chính thức
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Kiểm tra phiên bản Docker Compose V2
docker compose version

Bước 2: Tạo thư mục lưu trữ cấu hình Immich

Tạo một thư mục riêng biệt chuyên dùng để chứa các file định nghĩa container và biến môi trường:

mkdir -p ./immich-app
cd ./immich-app

Bước 3: Tải tệp tin cấu hình chuẩn từ kho lưu trữ Immich

Sử dụng wget để tải tệp định nghĩa container docker-compose.yml và tệp mẫu biến môi trường example.env chính thức:

wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

Bước 4: Cấu hình tệp biến môi trường .env

Mở tệp tin .env bằng trình biên tập nano để chỉ định đường dẫn lưu trữ dữ liệu và thông tin xác thực cơ sở dữ liệu:

nano .env

Bạn cần điều chỉnh 3 thông số then chốt sau:

• UPLOAD_LOCATION: Đường dẫn tuyệt đối trên máy chủ Ubuntu nơi lưu trữ toàn bộ ảnh, video và thumbnail (Ví dụ: /mnt/storage/immich-photos hoặc /var/immich/upload).
• DB_PASSWORD: Chuỗi mật khẩu ngẫu nhiên có độ phức tạp cao dành cho PostgreSQL.
• IMMICH_VERSION: Giữ nguyên giá trị release để luôn tải phiên bản ổn định nhất.

# Ví dụ nội dung tệp .env chuẩn
UPLOAD_LOCATION=/var/immich/upload
IMMICH_VERSION=release
DB_PASSWORD=MatKhauBaoMatPostgres_2026!
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Sau khi chỉnh sửa xong, nhấn Ctrl + O, nhấn Enter để lưu lại và nhấn Ctrl + X để thoát nano. Đảm bảo cấp quyền cho thư mục upload đã khai báo:

sudo mkdir -p /var/immich/upload
sudo chown -R $USER:$USER /var/immich/upload

Bước 5: Khởi chạy cụm container và xác thực trạng thái

Khởi động toàn bộ dịch vụ Immich (bao gồm immich-server, immich-machine-learning, immich_redis, immich_postgres) ở chế độ chạy nền (detached mode):

docker compose up -d

Kiểm tra xem tất cả các container đã ở trạng thái Up (healthy) hay chưa:

docker compose ps

Nếu cần theo dõi nhật ký hoạt động để xử lý sự cố khởi tạo cơ sở dữ liệu ban đầu, sử dụng lệnh:

docker compose logs -f

4. Hướng Dẫn Cấu Hình Và Sử Dụng Immich Lần Đầu

Sau khi cụm container hoạt động ổn định, hãy tiến hành thiết lập tài khoản quản trị và kết nối ứng dụng theo các bước sau:

1/ Khởi tạo tài khoản Admin: Mở trình duyệt web và truy cập địa chỉ http://<IP-Máy-Chủ>:2283. Nhấp chọn Getting Started, nhập địa chỉ email, họ tên và mật khẩu cho tài khoản quản trị viên cao nhất.

Nếu ở bước này mà bạn không thể truy cập địa chỉ http://<IP-Máy-Chủ>:2283, thì nguyên nhân có thể là do chưa mở port hoặc browser cố nâng HTTP request thành HTTPS do cấu hình Helmet mặc định sử dụng upgrade-insecure-requests (theo tài liệu của Immich).

Nếu gặp tình trạng không thể truy cập địa chỉ http://<IP-Máy-Chủ>:2283, hãy tiếp tục đọc phần hướng dẫn mở port và thiết lập HTTPS bên dưới.

2/ Cấu hình App trên điện thoại di động:

• Tải ứng dụng Immich chính thức trên Apple App Store hoặc Google Play Store.
• Mở ứng dụng, tại mục Server Endpoint URL, điền địa chỉ máy chủ (Ví dụ: http://103.xxx.xxx.xxx:2283/api hoặc domain HTTPS).
• Đăng nhập bằng tài khoản Admin đã tạo hoặc tài khoản người dùng thành viên.

3/ Kích hoạt tính năng Backup tự động:

• Vào tab Backup trong ứng dụng điện thoại.
• Cấp quyền truy cập Full Photos Access để ứng dụng đọc được thư viện hình ảnh và video.
• Chọn các album cần đồng bộ (Camera, Screenshots, WhatsApp…) và gạt bật Background Backup để thiết bị tự đồng bộ khi có kết nối Wi-Fi hoặc dữ liệu di động.

5. Tối Ưu Machine Learning Và Bảo Mật Bằng Nginx Reverse Proxy

5.1. Thiết lập Swap Memory chống sập container Machine Learning

Khi tải lên hàng nghìn bức ảnh cùng lúc, container immich-machine-learning sẽ kích hoạt các mô hình trích xuất khuôn mặt và vector CLIP. Quá trình này tiêu tốn lượng RAM đột biến, dễ dẫn đến lỗi Out-Of-Memory (OOM Killer) làm sập hệ thống. Việc cấu hình Swap Memory trên Linux là giải pháp quan trọng để tạo vùng đệm an toàn:

# Tạo file swap dung lượng 4GB
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Duy trì file swap sau khi khởi động lại máy chủ
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

5.2. Mở cổng mạng bằng tường lửa UFW

Để bảo vệ máy chủ khỏi các cuộc quét cổng trái phép, bạn nên thiết lập tường lửa UFW, chỉ mở các cổng dịch vụ cần thiết gồm SSH (22), HTTP (80), HTTPS (443) và cổng mặc định của Immich (2283):

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 2283/tcp
sudo ufw enable

5.3. Cấu hình Nginx Reverse Proxy kết hợp chứng chỉ SSL Let’s Encrypt

Việc truy cập trực tiếp qua giao thức HTTP (cổng 2283) không đảm bảo an toàn cho dữ liệu nhạy cảm khi đồng bộ ngoài mạng công cộng. Bạn nên sử dụng Nginx làm reverse proxy kết hợp chứng chỉ bảo mật HTTPS. Để xem nguyên lý chi tiết, bạn có thể tham khảo thêm hướng dẫn cấu hình Nginx Reverse Proxy và cài chứng chỉ SSL Let’s Encrypt.

Cài đặt Nginx và Certbot:

sudo apt install -y nginx certbot python3-certbot-nginx

Tạo tệp cấu hình virtual host cho Immich tại /etc/nginx/sites-available/immich.conf.

Mở tệp bằng lệnh sudo nano /etc/nginx/sites-available/immich.conf và dán đoạn cấu hình sau vào. Thay thế “photos.yourdomain.com” bằng tên miền của bạn hoặc nếu muốn dùng localhost thì có thể giữ nguyên.

server {
    server_name photos.yourdomain.com;

    # Cho phép tải lên tệp video lớn (không giới hạn kích thước)
    client_max_body_size 50000M;

    location / {
        proxy_pass http://127.0.0.1:2283;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Hỗ trợ kết nối Websocket cho tính năng đồng bộ thời gian thực
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Thời gian chờ truyền tải tệp tin dung lượng lớn
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
        send_timeout 600s;
    }
}

Sau đó,

Ctrl + O → Enter: lưu file.

Ctrl + X: thoát.

Kích hoạt cấu hình và cấp chứng chỉ SSL miễn phí:

sudo ln -s /etc/nginx/sites-available/immich.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d photos.yourdomain.com

6. Hướng Dẫn Sao Lưu Dữ Liệu Và Cập Nhật Immich Định Kỳ

6.1. Quy trình sao lưu (Backup) cơ sở dữ liệu PostgreSQL và thư mục ảnh

Để đảm bảo an toàn tuyệt đối, hệ thống backup Immich cần thực hiện 2 phần độc lập: bản sao lưu cơ sở dữ liệu (chứa metadata, khuôn mặt, album) và thư mục tệp tin ảnh gốc (đã cấu hình tại UPLOAD_LOCATION).

# Chuyển vào thư mục chứa docker-compose.yml của Immich
cd ~/immich-app

# Xuất toàn bộ cơ sở dữ liệu Postgres ra file .sql
docker compose exec -t immich_postgres pg_dumpall -c -U postgres > immich_db_backup_$(date +%F).sql

# Nén thư mục ảnh gốc (hoặc đồng bộ qua rsync/Rclone sang máy chủ lưu trữ thứ hai)
sudo rsync -avz --progress /var/immich/upload /backup/immich-media/

6.2. Quy trình cập nhật (Update) Immich lên phiên bản mới nhất

Đội ngũ phát triển Immich phát hành bản cập nhật thường xuyên. Trước khi nâng cấp, hãy đọc qua Release Notes trên GitHub để kiểm tra các thay đổi cấu trúc có thể gây xung đột (Breaking Changes), sau đó chạy các lệnh sau:

cd ~/immich-app

# Kéo container images mới nhất về máy
docker compose pull

# Dừng và khởi động lại cụm container với image mới
docker compose up -d

# Xóa bỏ các images cũ không còn sử dụng để giải phóng dung lượng đĩa
docker image prune -f

7. Câu Hỏi Thường Gặp Về Cài Đặt Và Sử Dụng Immich Trên Ubuntu (FAQ)

Lưu ý: Hướng dẫn kỹ thuật trên được xây dựng dựa trên tài liệu chuẩn của Immich và thử nghiệm thực tế trên hệ điều hành Ubuntu Server. Cấu hình biến môi trường và tài nguyên máy chủ có thể thay đổi tùy thuộc vào quy mô dữ liệu media thực tế của bạn.