# izz-immich

**Trung tâm Điều khiển Máy chủ Immich — v3.4.0**

[English](README.md) | [Tiếng Việt](README.vi.md)  
[Technical Specification](TECHNICAL-SPECIFICATION.md) | [Đặc tả kỹ thuật](TECHNICAL-SPECIFICATION.vi.md)

`izz-immich` là công cụ quản trị tương tác viết bằng Bash để cài đặt, cập nhật, vận hành, bảo vệ, sao lưu, khôi phục, sửa lỗi và chuyển máy chủ Immich.

Mục tiêu của công cụ là cung cấp giao diện Terminal dễ sử dụng nhưng vẫn giữ các bước kiểm tra an toàn quan trọng ở trạng thái minh bạch. Vì công cụ chạy với quyền root, thiết kế ưu tiên **xác minh, khả năng hoàn tác và dừng an toàn khi trạng thái không rõ ràng (fail-closed)** thay vì tự phỏng đoán.

> **Phiên bản tài liệu:** 3.4.0  
> **Áp dụng cho:** izz-immich v3.4.0  
> **Cập nhật:** 2026-09-30

## Công cụ có thể làm gì?

### 1. Cài đặt Immich tự động

Trình cài đặt có thể cài Docker CE, tạo một hệ thống Immich mới, sinh mật khẩu database, cho phép chọn thư mục/cổng, cấu hình tăng tốc phần cứng, khởi động hệ thống và kiểm tra Immich có thực sự phản hồi hay không.

Cài mới sẽ không ghi đè một thư mục bất kỳ đã có dữ liệu. Nếu phát hiện cấu hình Immich hiện hữu, công cụ có thể tiếp quản hoặc chuyển sang cơ chế cài lại an toàn thay vì ghi đè mù quáng.

### 2. Tự nhận diện và cấu hình GPU

Hỗ trợ:

- **NVIDIA** — CUDA / NVENC
- **Intel** — Quick Sync / OpenVINO
- **AMD** — VAAPI
- **CPU-only** khi không có GPU phù hợp

Cấu hình tăng tốc được đặt trong Compose override do izz-immich quản lý, hạn chế sửa các tùy biến riêng của người dùng trong file Compose gốc. Sau khi thay đổi, cấu hình Compose đã resolve được kiểm tra lại.

### 3. Smart Import từ ổ cứng ngoài

Smart Import có thể phát hiện và mount nhiều loại nguồn dữ liệu:

- APFS
- NTFS
- exFAT
- ext4
- btrfs
- ổ Synology dạng RAID/LVM

Nguồn import được mount chỉ đọc. Khi lớp thiết bị cho phép, izz-immich còn đánh dấu block device ở chế độ read-only để kernel từ chối ghi ngay cả khi filesystem muốn thực hiện recovery.

Phiên import chỉ theo dõi và tháo những mount, MD array và LVM volume group mà chính nó đã tạo; các tài nguyên đã hoạt động từ trước cho workload khác không bị cố ý dừng.

### 4. Immich CLI được xác minh bằng digest

Import sử dụng container `immich-cli` được ghim bằng OCI digest bất biến. Nếu đúng image đã xác minh tồn tại trên máy, công cụ có thể dùng lại mà không phải pull lại từ Internet.

Một image chỉ có tag quen thuộc không được xem là bằng chứng đủ tin cậy. Với máy air-gapped, cách phù hợp là cung cấp đúng manifest digest qua registry/mirror nội bộ hoặc image store có thể giữ identity của manifest.

### 5. Sao lưu tự động

Hệ thống backup lưu:

- database dạng `pg_dumpall` nén,
- thư viện ảnh/video,
- `.env`, Compose gốc và các Compose override đang sử dụng,
- manifest ghi trạng thái từng thành phần.

Các bản backup database/config được tổ chức thành từng set theo thời gian. Thư viện media được đồng bộ tích lũy và không dùng `--delete`, vì vậy việc xóa file trên Immich không lập tức xóa luôn bản sao lưu.

Lịch mặc định chạy lúc **03:17**, tránh khung giờ backup database nội bộ thường gặp của Immich quanh 02:00.

### 6. Restore và Disaster Recovery

Trước khi chạm vào database đang chạy, Restore kiểm tra tính hợp lệ của backup, định dạng dump, cấu hình, bind mount PostgreSQL, mountpoint mong đợi, dung lượng trống và filesystem đích thực tế.

Hỗ trợ hai trường hợp:

- **Restore tại chỗ** khi database hiện tại vẫn tồn tại.
- **Disaster Recovery** khi đường dẫn database/library mới hoặc trống, ví dụ sau khi thay ổ dữ liệu hỏng.

Khi restore tại chỗ, database cũ được giữ làm bản rollback. Nếu khôi phục thất bại, izz-immich cố gắng đưa hệ thống về trạng thái trước restore.

### 7. Bảo mật truy cập qua Tailscale

Security Hub có thể đưa Immich sang mô hình chỉ truy cập qua Tailscale:

- chụp trạng thái UFW hiện tại,
- chặn kết nối vào từ LAN/Internet,
- ép Immich chỉ nghe trên loopback,
- dùng Tailscale Serve để cung cấp HTTPS,
- xác minh socket thật và endpoint HTTPS,
- bật dead-man timer để tự hoàn tác nếu người dùng không xác nhận truy cập được.

Công cụ cũng đồng bộ rule UFW/Docker khi Docker subnet thay đổi.

**Lưu ý:** Các thiết bị ở bên trong cùng tailnet vẫn chịu chính sách của Tailscale. Nếu cần giới hạn theo thiết bị/dịch vụ trong tailnet, hãy dùng Tailscale ACL.

### 8. Cập nhật Immich có kiểm soát

Advanced Mode hiện có workflow **Cập nhật Immich** riêng. Update được tách khỏi Repair/Reinstall để một thao tác bảo trì không thể âm thầm biến thành nâng cấp database.

Trước khi khởi động phiên bản Immich mới hơn, workflow sẽ:

- xác định chính xác phiên bản đang chạy;
- xác định bản stable mới nhất từ upstream;
- yêu cầu Immich đang ở trạng thái khỏe trước khi nâng cấp;
- tạo một backup mới và bắt buộc `db=ok`, `library=ok`, `config=ok`;
- xác minh backup set thuộc đúng phiên bản Immich hiện tại;
- pull chính xác target release trước khi thay đổi `.env`;
- ghi persistent recovery marker;
- pin target version trước lần start đầu tiên có thể chạy database migration;
- verify dịch vụ Immich và actual running version sau nâng cấp.

Nếu target đã được start nhưng verification thất bại, izz-immich chủ động **không auto-downgrade**. Target vẫn được pin và recovery point trước nâng cấp được giữ để dùng với Repair hoặc Backup & Restore.

**Known issue của v3.4.0:** lựa chọn nhập target version thủ công hiện có lỗi biến đầu vào. Hãy dùng lựa chọn **Latest stable** cho tới khi lỗi này được sửa.

### 9. Repair và Reinstall an toàn

Repair kiểm tra Docker, container, Compose, GPU runtime và khả năng truy cập Immich trong khi giữ nguyên exact installed version.

Repair không còn cho phép pull moving tag như `release` khi không thể chứng minh exact version đang cài. Công cụ sẽ pin/dùng lại đúng version hiện hữu hoặc dừng. Nếu một Update chưa được xác minh, Repair tiếp tục giữ Update target và không tự downgrade.

Khi Reinstall, công cụ giữ `.env`, đường dẫn dữ liệu, cổng, Compose tùy biến và—khi xác định được—phiên bản Immich đang dùng. Nếu không xác định được version, Reinstall vẫn cảnh báo rõ trước khi cho phép người dùng chủ động chọn bản mới nhất.

### 10. Chuyển sang máy chủ khác

Migration ghi lại thông tin phần cứng/boot của máy cũ và chính sách restart của từng container.

Trên máy mới, công cụ có thể kiểm tra lại UEFI/BIOS, đối chiếu EFI System Partition khi cần, cấu hình lại GPU nếu phần cứng thay đổi, khôi phục restart policy và xác minh Immich sau khi khởi động.

### 11. Dashboard và Diagnostics

Dashboard hiển thị:

- Docker
- trạng thái Immich
- GPU
- dung lượng các ổ chứa dữ liệu
- tình trạng và tuổi của backup
- Tailscale
- trạng thái bảo mật mạng
- các việc người dùng cần chú ý, bao gồm Update chưa được xác minh

Diagnostics có thể kiểm tra toàn hệ thống và xuất báo cáo hỗ trợ kỹ thuật, đồng thời che thêm các mẫu secret/token phổ biến.

### 12. Chống xung đột giữa các thao tác lớn

Những thao tác có thể thay đổi database hoặc cấu hình dữ liệu dùng chung một operation lock. Ví dụ backup tự động sẽ không bắt đầu đúng lúc Restore hoặc Repair đang thay đổi hệ thống.

State lâu dài được ghi dưới file lock bằng file tạm và atomic rename. Lỗi ghi file, hết dung lượng hoặc I/O lỗi không được phép cố ý thay một state tốt bằng state mới bị cắt dở.

### 13. Ghim dependency quan trọng

Các thành phần bên ngoài chạy ở mức quyền cao được ghim bằng commit hoặc digest bất biến, gồm:

- commit `apfs-fuse`
- OCI digest của `immich-cli`
- digest image kiểm tra NVIDIA
- commit `ufw-docker`

Các pin chỉ thay đổi khi source izz-immich được cập nhật có chủ đích cho phiên bản mới.

## Nền tảng hỗ trợ

**Hỗ trợ thay đổi hệ thống đầy đủ:** Ubuntu 24.04 LTS.

Trên các hệ khác vẫn có `apt`/`dpkg`, izz-immich chuyển sang **Safe Mode**: không cài/gỡ/sửa package, repository hoặc driver hệ thống. Các chức năng có đủ dependency sẵn vẫn có thể hoạt động.

Các hệ không có `apt`/`dpkg` không được hỗ trợ trong phiên bản này.

## Yêu cầu

Để cài mới thông thường:

- Ubuntu 24.04 LTS
- quyền root (`sudo`)
- kết nối Internet để tải Docker/Immich và package cần thiết
- đủ dung lượng cho Immich và database
- nên có ổ lưu trữ riêng cho backup

Tailscale là tùy chọn và chỉ cần cho các workflow truy cập từ xa/bảo mật liên quan Tailscale.

## Bắt đầu nhanh

Sau khi clone hoặc tải repository:

```bash
chmod +x izz-immich.sh
sudo ./izz-immich.sh
```

Khi repository chính thức được đăng tại địa chỉ Source đã nhúng trong công cụ, có thể dùng:

```bash
curl -fsSLO https://raw.githubusercontent.com/dhd-voz/izz-immich/main/izz-immich.sh
chmod +x izz-immich.sh
sudo ./izz-immich.sh
```

Nên đọc script trước khi chạy với quyền root.

## Giao diện Simple và Advanced

Công cụ có hai mức menu:

- **Simple mode** cho các công việc thường dùng.
- **Advanced mode** cho backup/restore, cập nhật Immich có kiểm soát, thay đổi bảo mật mạng, repair, migration và các thao tác có thể ảnh hưởng đáng kể tới máy chủ.

Giao diện hỗ trợ đầy đủ tiếng Việt và tiếng Anh.

## Lưu ý an toàn quan trọng

- izz-immich chạy bằng **root**.
- Công cụ có thể thay đổi firewall, package, driver, Docker, mount, thư mục dữ liệu và schema database Immich trong một Update được người dùng chủ động xác nhận.
- Backup/restore **không phải point-in-time snapshot tuyệt đối**. Database được dump trước rồi mới đồng bộ thư viện media, vì vậy upload/xóa file đồng thời có thể tạo ra một khoảng không nhất quán nhỏ.
- Disaster Recovery chủ động từ chối cấu hình mà ownership PostgreSQL không thể được xác định an toàn, ví dụ explicit non-root user không được hỗ trợ hoặc Docker rootless/user namespace.
- Hoàn tác bảo mật mạng cần snapshot hợp lệ. Công cụ không tự tạo ra một “trạng thái gốc” khi không thể chứng minh trạng thái đó.
- Update Immich bắt buộc tạo một backup mới và đầy đủ trước khi nâng cấp. Sau khi target version đã start, database migration có thể làm downgrade không an toàn; vì vậy izz-immich không tự downgrade.
- **Known issue của v3.4.0:** nhập thủ công exact target version trong Update hiện bị lỗi; hãy dùng **Latest stable** cho tới khi được sửa.
- Hãy sao lưu dữ liệu quan trọng trước các thao tác phá hủy.

Để xem kiến trúc, mô hình an toàn, giả định và failure behavior đầy đủ, đọc [TECHNICAL-SPECIFICATION.vi.md](TECHNICAL-SPECIFICATION.vi.md).

## Các đường dẫn runtime chính

| Mục đích | Đường dẫn mặc định |
|---|---|
| Ứng dụng Immich | `/opt/immich-app` |
| State của izz-immich | `/var/lib/izz-immich` |
| Log chính | `/var/log/izz-immich.log` |
| Điểm mount backup | `/mnt/immich-backup` |
| Điểm mount import | `/mnt/izz-src-*` |
| Trang chủ cục bộ | `/opt/izz-immich/home.html` |

## Giấy phép

MIT License. Xem [LICENSE](LICENSE).

Tác giả: **DHD@VOZ**