Tài liệu

Tài liệu này dành cho quản trị viên tự lưu trữ Wanmory trên NAS, máy chủ gia đình hoặc máy tính cá nhân, bao gồm cài đặt, cấu hình, triển khai dịch vụ AI, sử dụng hằng ngày, cài đặt hệ thống và vận hành. Chi tiết kiến trúc và thuật toán xem tại Kiến trúc.

Wanmory là thư viện ảnh riêng tư có AI, mã nguồn mở và tự lưu trữ. Hệ thống gồm bốn container: backend Go (server), dịch vụ suy luận AI bằng Python (ml), cơ sở dữ liệu PostgreSQL + pgvector (postgres), và mdns phụ trách phát tên miền nội bộ. Mọi ảnh, siêu dữ liệu, vector và hàng đợi tác vụ đều lưu cục bộ, không phụ thuộc dịch vụ đám mây nào.

• Quản lý ảnh: dòng thời gian theo tháng, album và album thông minh, dọn ảnh liên tiếp và ảnh giống nhau, bản đồ dấu chân, trình chiếu.
• Khả năng AI: phát hiện và gom nhóm khuôn mặt, tìm kiếm bằng ngôn ngữ tự nhiên (Chinese-CLIP), nhận dạng chữ (PP-OCR), chấm điểm thẩm mỹ (AI chọn lọc).
• Nhiều thành viên: tài khoản riêng, quyền xóa theo người tải lên, lịch sử đăng nhập.

Cách 1: script cài đặt (khuyến nghị)

Trên máy 64 bit đã cài Docker, chạy:

curl -fsSL https://wanmory.com/install.sh | bash

Script lần lượt làm những việc sau:

• Kiểm tra môi trường: kiến trúc CPU (amd64 / arm64) và không gian người dùng 64 bit, Docker và Docker Compose v2 có dùng được không, bộ nhớ và dung lượng ổ đĩa còn trống.
• Cấu hình tương tác: thư mục cài đặt (mặc định ~/wanmory), cổng truy cập (mặc định 8080, tự kiểm tra có bị chiếm không), tên miền nội bộ (mặc định wanmory.local), mật khẩu cơ sở dữ liệu (mặc định tạo ngẫu nhiên) và nơi lưu cơ sở dữ liệu (mặc định là volume Docker pgdata, cũng có thể chỉ định thư mục trên ổ đĩa cục bộ), múi giờ (gõ tên thành phố hoặc vùng để tìm, ví dụ shanghai, tokyo, 北京; nhiều kết quả thì chọn theo số).
• Nơi lưu trữ: thư mục dữ liệu (ảnh thu nhỏ, ảnh xem trước và ảnh tải lên, mặc định ./data), thư mục mô hình AI (mặc định ./models).
• Lời nhắc và kết quả của script bằng tiếng Anh để hiển thị đúng trên mọi loại terminal của NAS.
• Thư mục ảnh có sẵn: thêm lần lượt nhiều thư mục, mỗi thư mục chọn riêng gắn chỉ đọc (khuyến nghị) hoặc đọc ghi.
• Tạo .env (quyền 600); nếu có nhập thư mục ảnh thì tạo thêm docker-compose.override.yml, Docker Compose sẽ tự gộp tệp này.
• Tải docker-compose.yml chính thức (GitHub không vào được thì tự chuyển sang Gitee), kiểm tra cấu hình rồi kéo image và khởi động, chờ dịch vụ sẵn sàng thì in ra địa chỉ truy cập.

# Ví dụ: cài không tương tác vào /opt/wanmory, dùng cổng 9000 và gắn thư mục ảnh trên NAS
curl -fsSL https://wanmory.com/install.sh | WANMORY_PORT=9000 WANMORY_PHOTOS=/volume1/photo,/volume2/family bash -s -- -y --dir /opt/wanmory

Cách 2: cài thủ công

1. 1
   Tạo thư mục triển khai và lấy tệp Compose

   Tạo một thư mục chứa tệp Compose, dữ liệu và mô hình, rồi tải docker-compose.yml chính thức:

   bashSao chép

   mkdir -p ~/wanmory && cd ~/wanmory
   curl -fsSLO https://raw.githubusercontent.com/i-dj/wanmory/main/docker/docker-compose.yml

2. 2
   (Tùy chọn) Viết .env

   Tạo .env trong cùng thư mục để ghi đè giá trị mặc định. Môi trường chạy thật nhất định phải đổi mật khẩu cơ sở dữ liệu:

   .envSao chép

   WANMORY_DB_PASSWORD=hay-thay-bang-chuoi-ngau-nhien
   WANMORY_PORT=8080
   WANMORY_TZ=Asia/Ho_Chi_Minh
   WANMORY_VERSION=latest

3. 3
   Khởi động dịch vụ

   Lần khởi động đầu sẽ kéo image và tự chạy di chuyển cơ sở dữ liệu:

   bashSao chép

   docker compose up -d
   docker compose ps        # kiểm tra cả bốn dịch vụ đều running / healthy

4. 4
   Truy cập và khởi tạo

   Mở http://wanmory.local:8080 (hoặc http://<IP máy chủ>:8080) trên trình duyệt, tạo tài khoản quản trị viên theo hướng dẫn, rồi tải mô hình trong «Cài đặt hệ thống → AI». Tải mô hình xong, ảnh có sẵn sẽ tự vào hàng đợi xử lý AI.

Tệp Compose chính thức định nghĩa bốn dịch vụ: cơ sở dữ liệu postgres, backend server, phát tên miền nội bộ mdns và dịch vụ AI tích hợp ml. Tác dụng của từng mục cấu hình được ghi chú ngay trong tệp:

# Tệp Compose chính thức của Wanmory: chạy docker compose up -d trong thư mục chứa tệp này
# Biến dạng ${VAR:-mặc định} được đọc từ .env cùng thư mục, chưa đặt thì dùng giá trị mặc định
services:
  # ── Cơ sở dữ liệu: PostgreSQL 17 + pgvector ──────────────────────
  # Lưu siêu dữ liệu ảnh, mọi người, album, cài đặt, hàng đợi tác vụ và vector (chỉ mục HNSW)
  # Không mở cổng, chỉ truy cập được trong mạng nội bộ của Compose
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: wanmory
      POSTGRES_PASSWORD: ${WANMORY_DB_PASSWORD:-wanmory}   # môi trường chạy thật nhất định phải đổi trong .env
      POSTGRES_DB: wanmory
    volumes:
      - ${WANMORY_DB_DIR:-pgdata}:/var/lib/postgresql/data  # mặc định là volume có tên pgdata; đặt WANMORY_DB_DIR thì lưu vào thư mục đó. Cần đưa vào sao lưu
    healthcheck:                             # server chờ bước kiểm tra này, cơ sở dữ liệu sẵn sàng mới khởi động
      test: ["CMD", "pg_isready", "-U", "wanmory", "-d", "wanmory"]
      interval: 5s
      timeout: 3s
      retries: 20
    restart: unless-stopped
  # ── Backend: chương trình Go có nhúng ứng dụng web ───────────────
  # Phụ trách API, tải lên (tus), điều phối tác vụ, ảnh thu nhỏ, phân quyền; khởi động là tự di chuyển cơ sở dữ liệu
  server:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    environment:
      DATABASE_URL: postgres://wanmory:${WANMORY_DB_PASSWORD:-wanmory}@postgres:5432/wanmory
      WANMORY_ML_URL: http://ml:3003         # địa chỉ dịch vụ AI tích hợp; dịch vụ AI từ xa cấu hình trong «Cài đặt AI» trên web
      TZ: ${WANMORY_TZ:-Asia/Shanghai}       # múi giờ dùng khi EXIF thiếu múi giờ
      WANMORY_MDNS: "off"                    # container này ở mạng bridge không nhận được multicast, việc phát tên miền giao cho dịch vụ mdns bên dưới
      WANMORY_HTTP_PUBLIC_PORT: ${WANMORY_PORT:-8080}   # cổng hiển thị trên web, giữ khớp với ánh xạ cổng
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # giá trị ban đầu của tên miền nội bộ, đổi trong cài đặt web thì lấy theo cài đặt
    ports:
      - "${WANMORY_PORT:-8080}:8080"         # cổng máy chủ:cổng container
    volumes:
      - ${WANMORY_DATA_DIR:-./data}:/data    # upload/ chứa ảnh gốc tải lên, thumbs/ chứa ảnh thu nhỏ và ảnh xem trước 1440px
      # Thư mục ảnh có sẵn gắn vào thư mục con dưới /photos, gắn được nhiều; :ro là chỉ đọc, quét mỗi 15 phút
      # - /mnt/nas/photos:/photos/nas:ro
      # - /media/usb/may-anh:/photos/usb:ro
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
  # ── Phát tên miền nội bộ (mDNS) ──────────────────────────────────
  # Cùng image với server, chỉ chạy lệnh con mdns, phát wanmory.local (đổi được trên web)
  mdns:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    command: ["mdns"]
    network_mode: host                       # bắt buộc dùng mạng của máy chủ mới gửi nhận được multicast trong mạng nội bộ
    environment:
      WANMORY_URL: http://127.0.0.1:${WANMORY_PORT:-8080}   # định kỳ hỏi server tên miền hiện tại
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # chưa hỏi được thì phát tạm tên miền này
    depends_on:
      - server
    restart: unless-stopped
  # ── Dịch vụ AI tích hợp: FastAPI + ONNX Runtime, chỉ dùng CPU ────
  # Không trạng thái, chỉ nhận ảnh xem trước từ server rồi trả về khuôn mặt, vector, chữ; không mở cổng
  ml:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-ml:${WANMORY_VERSION:-latest}
    volumes:
      - ${WANMORY_MODELS_DIR:-./models}:/models  # lưu bền tệp mô hình, tạo lại container không phải tải lại
    environment:
      WANMORY_MODEL_DIR: /models
      WANMORY_AUTO_DOWNLOAD: "0"             # không tự tải, quản trị viên xác nhận giấy phép và dung lượng trên web rồi mới tải
    restart: unless-stopped
volumes:
  pgdata:

.env (biến của Compose)

Các biến dưới đây được docker-compose.yml sử dụng, ghi vào .env cùng thư mục là có hiệu lực:

Container server (tùy chọn)

DATABASE_URL, WANMORY_ML_URL, WANMORY_MDNS, WANMORY_HTTP_PUBLIC_PORT đã được cấu hình và ghi chú công dụng trong tệp Compose. Các biến dưới đây không có trong tệp mặc định, cần thì thêm vào environment của server:

Ảnh có sẵn trên NAS hay ổ cứng di động không cần tải lên. Gắn thư mục vào thư mục con dưới /photos trong container, hệ thống quét mỗi 15 phút, nhập tại chỗ các tệp mới (không sao chép, không di chuyển), rồi đọc siêu dữ liệu, tạo ảnh thu nhỏ và xử lý AI giống như ảnh tải lên.

  server:
    volumes:
      - ./data:/data
      - /mnt/nas/photos:/photos/nas:ro       # :ro gắn chỉ đọc
      - /media/usb/may-anh:/photos/usb:ro
      - /home/toi/Pictures:/photos/pictures   # gắn đọc ghi

Sửa xong thì chạy docker compose up -d, container khởi động lại khoảng 20 giây sau sẽ bắt đầu quét lần đầu.

• Khuyến nghị gắn chỉ đọc (:ro): hệ thống không ghi gì vào các thư mục này; xóa ảnh trong ứng dụng chỉ chuyển vào «Đã xóa gần đây», xóa vĩnh viễn cũng không xóa tệp gốc, và về sau không quét nhập lại nữa. Thư mục gắn đọc ghi thì xóa vĩnh viễn sẽ xóa luôn tệp gốc.
• Tệp có nội dung giống hệt nhau chỉ nhập một bản (so trùng theo checksum SHA-1), kể cả tệp đã tải lên trước đó và tệp trùng giữa nhiều thư mục.
• Tự động bỏ qua thư mục ẩn và thư mục hệ thống của NAS (.xxx, @eaDir, #recycle…).
• Ảnh nhập từ thư mục ảnh không thuộc thành viên nào, chỉ quản trị viên mới xóa được.

Dịch vụ mdns chạy ở chế độ mạng host, phát tên miền truy cập trong mạng nội bộ (mặc định wanmory.local). macOS, iOS, iPadOS và Windows 10 trở lên không cần cấu hình router vẫn vào được qua http://wanmory.local:8080. Tên miền đổi được trong «Cài đặt hệ thống → Tên miền truy cập» và phải kết thúc bằng .local.

Tải lên trên web dùng giao thức tải tiếp tus (/api/uploads/), mỗi phần 16 MB. Khi đặt sau reverse proxy cần nới giới hạn kích thước mỗi yêu cầu và tắt bộ đệm yêu cầu. Ví dụ Nginx:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}
location /api/uploads/ {
    proxy_pass http://127.0.0.1:8080;
    client_max_body_size 0;          # không giới hạn kích thước yêu cầu (tối thiểu 20m)
    proxy_request_buffering off;     # chuyển tiếp dạng luồng, không ghi đệm ra đĩa ở phía proxy
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Dịch vụ AI là dịch vụ HTTP không trạng thái: nhận ảnh xem trước 1440 pixel từ backend, trả về khuôn mặt, vector và kết quả nhận dạng chữ, không truy cập cơ sở dữ liệu, cũng không lưu tệp. Backend hỗ trợ hai cách chạy, chuyển trong «Cài đặt hệ thống → AI → Cách chạy AI»:

Khi dịch vụ AI không dùng được, tác vụ AI vẫn nằm trong hàng đợi và tạm ngừng nhận, không tốn lượt thử lại; dịch vụ hồi phục thì tự xử lý tiếp. Các chức năng như duyệt ảnh, tải lên không bị ảnh hưởng.

Cách 1: chạy trực tiếp trên Mac hoặc máy có GPU (khuyến nghị)

Chạy trực tiếp sẽ dùng được tăng tốc phần cứng: trên chip Apple, mô hình khuôn mặt dùng CoreML, Chinese-CLIP dùng MPS; trên card NVIDIA, Chinese-CLIP dùng CUDA và chạy ở nửa độ chính xác (khoảng 1,9 GB VRAM / bộ nhớ). Cần cài uv trước.

git clone https://github.com/i-dj/wanmory.git
cd wanmory/ml
uv sync --extra torch                 # cài phụ thuộc bản PyTorch (tăng tốc tìm kiếm ngữ nghĩa bằng GPU)
# Tạo token truy cập, backend và dịch vụ AI dùng cùng một giá trị
export WANMORY_ML_TOKEN=$(openssl rand -hex 24)
echo $WANMORY_ML_TOKEN
WANMORY_FACE_MODEL_PRELOAD=1 uv run --extra torch python -m wanmory_ml
# Mặc định lắng nghe 0.0.0.0:3003, đổi bằng WANMORY_ML_HOST / WANMORY_ML_PORT

Cách 2: chạy image Docker trên một máy khác

Dành cho máy x86 mạnh hơn nhưng không có GPU dùng được, image chỉ dùng CPU:

docker run -d --name wanmory-ml --restart unless-stopped \
  -p 3003:3003 \
  -e WANMORY_ML_TOKEN=<token-truy-cap> \
  -v $PWD/models:/models \
  ghcr.io/i-dj/wanmory-ml:latest

Bật dịch vụ từ xa ở backend

1. 1
   Mở cài đặt AI

   Đăng nhập quản trị viên, vào «Cài đặt hệ thống → AI → Cách chạy AI», chọn «Dịch vụ từ xa».

2. 2
   Điền địa chỉ và token

   Địa chỉ có dạng http://192.168.1.20:3003, token điền giá trị tạo ở bước trên. Trước khi lưu sẽ kiểm tra kết nối và hiển thị độ trễ cùng phiên bản dịch vụ.

3. 3
   Xác nhận mức và mô hình

   Kết nối thành công, nếu đang để mức «Tự động» thì sẽ đề xuất lại theo phần cứng máy từ xa; tải mô hình cần dùng trong «Mức mô hình».

Mức quyết định bộ mô hình dùng cho khuôn mặt và tìm kiếm ngữ nghĩa. Khi chọn «Tự động», hệ thống đề xuất theo phần cứng máy chạy dịch vụ AI: có GPU dùng được thì chọn «Độ chính xác cao»; chỉ CPU và bộ nhớ dưới 6 GB thì chọn «Nhẹ», còn lại chọn «Cân bằng».

• Nhận dạng chữ dùng PP-OCRv6 (RapidOCR), mô hình cài kèm phụ thuộc, không cần tải riêng.
• Sau khi đổi mức, toàn bộ ảnh được phát hiện lại khuôn mặt và tính lại vector ngữ nghĩa theo mô hình mới; trong lúc đó tìm kiếm vẫn dùng vector cũ, những người đã đặt tên được giữ nguyên.
• Mô hình được tải vào thư mục ./models đã gắn, có thể xóa mô hình không còn dùng để giải phóng dung lượng (mô hình đang dùng thì không xóa được).
• Mô hình khuôn mặt InsightFace chỉ dùng cho mục đích phi thương mại, trước khi thương mại hóa cần thay thế hoặc xin cấp phép.

1. 1
   Tạo quản trị viên

   Lần truy cập đầu, hệ thống thấy chưa có tài khoản nào sẽ hướng dẫn tạo quản trị viên. Quản trị viên có thể thêm thành viên và sửa cài đặt hệ thống.

2. 2
   Tải mô hình

   Vào «Cài đặt hệ thống → AI», xác nhận mức mô hình rồi tải về. Trước khi mô hình sẵn sàng, tác vụ AI sẽ xếp hàng chờ.

3. 3
   Nhập ảnh

   Tải lên qua web, hoặc làm theo Gắn thư mục ảnh có sẵn để nối ảnh trên NAS.

4. 4
   Thêm thành viên

   Trong «Cài đặt hệ thống → Thành viên», tạo tài khoản cho người khác và chọn vai trò «Thành viên» hoặc «Quản trị viên».

• Tải lên trên web hỗ trợ ảnh, video, HEIC, RAW (như DNG)…, chọn được nhiều tệp; tải theo từng phần qua giao thức tus, mất mạng hay tải lại trang vẫn tải tiếp được.
• Tệp tải lên được lưu theo năm tháng trong thư mục tải lên (mặc định data/upload), thư mục đổi được trong «Cài đặt hệ thống → Thư mục tải lên», chỉ áp dụng cho tệp tải lên mới.
• Sau khi nhập sẽ lần lượt: đọc siêu dữ liệu (ExifTool) → tạo ảnh thu nhỏ và ảnh xem trước 1440 pixel (libvips / FFmpeg) → vector ngữ nghĩa, khuôn mặt, nhận dạng chữ (dịch vụ AI) → tra ngược địa điểm.
• Biểu tượng tác vụ nền ở đầu thanh bên hiển thị tiến độ và thời gian còn lại ước tính của «Nhập ảnh» và «AI nhận diện ảnh» theo số lượng ảnh.

Thông tin về người (tên, quan hệ gộp) dùng chung cho mọi thành viên; số ảnh, ảnh đại diện và trang của từng người được tính theo những ảnh mà mỗi thành viên nhìn thấy, ảnh đã ẩn chỉ chính chủ thấy.

• Thành viên: khi thêm thành viên thì đặt tên, mật khẩu ban đầu (ít nhất 4 ký tự) và vai trò; có thể đặt lại mật khẩu hoặc xóa thành viên.
• Lịch sử đăng nhập: ghi lại thời gian, thiết bị và IP của mỗi lần đăng nhập, vị trí ước tính ngoại tuyến theo IP (ip2region), lưu nửa năm gần nhất. Chỉ quản trị viên xem được.
• Trong «Tài khoản của tôi», mỗi thành viên có thể đổi mật khẩu, ảnh đại diện và xem các thiết bị đang đăng nhập.

Đầu thẻ hiển thị trạng thái AI theo thời gian thực (đang chạy được hay lý do tạm dừng), sửa xong có hiệu lực ngay, không cần khởi động lại.

«Cài đặt hệ thống → Cập nhật hệ thống» hiển thị phiên bản hiện tại của backend và dịch vụ AI, và báo khi có phiên bản mới. Khi cập nhật, chạy trong thư mục chứa docker-compose.yml:

docker compose pull && docker compose up -d

Di chuyển cơ sở dữ liệu tự chạy khi server khởi động. Nếu đã cố định phiên bản bằng WANMORY_VERSION thì sửa thẻ trong .env trước.

Dữ liệu cần sao lưu gồm ba phần:

# Xuất cơ sở dữ liệu
docker compose exec -T postgres pg_dump -U wanmory -Fc wanmory > wanmory-$(date +%F).dump
# Khôi phục vào bản triển khai mới (chạy docker compose up -d postgres trước)
docker compose exec -T postgres pg_restore -U wanmory -d wanmory --clean < wanmory-2026-11-10.dump

Thành viên quên mật khẩu thì quản trị viên đặt lại trong «Cài đặt hệ thống → Thành viên». Chính quản trị viên quên mật khẩu thì chạy trên máy chạy ứng dụng, trong thư mục chứa docker-compose.yml:

docker compose exec server wanmory reset-password            # liệt kê tài khoản rồi chọn
docker compose exec server wanmory reset-password <tên>       # chỉ định thẳng tài khoản

• Lệnh sẽ liệt kê mọi tài khoản (tên, vai trò, thời gian tạo, lần đăng nhập gần nhất), chọn theo số thứ tự rồi nhập mật khẩu mới hai lần.
• Sau khi đặt lại, tài khoản đó bị đăng xuất trên mọi thiết bị, ảnh và album không bị ảnh hưởng.
• Thao tác này chỉ làm được trên máy chủ, trên web không có lối vào. Không dùng Docker thì chạy wanmory reset-password kèm các biến môi trường lúc chạy như DATABASE_URL.

Xem nhật ký từng dịch vụ: docker compose logs -f server, docker compose logs -f ml. Vẫn không giải quyết được thì hãy phản hồi ở trang Báo lỗi, kèm số phiên bản và nhật ký liên quan.

Chạy script gỡ cài đặt trên máy chạy Wanmory:

curl -fsSL https://wanmory.com/uninstall.sh | bash

Script đọc .env trong thư mục cài đặt trước, liệt kê container, cơ sở dữ liệu, thư mục dữ liệu, mô hình AI cùng dung lượng chiếm dụng, và các thư mục ảnh đã gắn; sau đó dừng và xóa container cùng mạng, rồi hỏi từng mục có xóa không (mặc định đều giữ lại):

• Các thư mục ảnh có sẵn đã gắn (NAS, ổ cứng di động) không bao giờ bị xóa.
• Khi chọn xóa cơ sở dữ liệu hoặc thư mục dữ liệu, cần gõ DELETE để xác nhận lần nữa.
• Chỉ xóa container mà giữ dữ liệu thì chạy lại install.sh trong thư mục cũ là khôi phục toàn bộ; nếu xóa .env mà giữ cơ sở dữ liệu thì hãy ghi lại WANMORY_DB_PASSWORD trong đó trước.