FAQ

用戶

如何重置管理員密碼？

管理員密碼可以通過執行 reset-admin-password 指令在 immich-server 上重置。

如何查看 Immich 中所有用戶的列表？

您可以通過在 Immich-server 上執行 list-users 指令來查看所有用戶的列表。

---

移動應用

移動應用上的雲圖示有什麼區別？

圖示	描述
	資產僅在伺服器上可用，並由其他設備（例如 Web 客戶端）上傳，或是從該設備中上傳後刪除。
	資產僅本地可用，尚未備份。
	資產已從該設備上傳並備份至伺服器，原始檔案仍保存在設備中。

更新後無法登入應用程式。我該怎麼辦？

確認移動應用和伺服器正在運行相同的版本（主要和次要版本）。

注释

應用商店更新有時會延遲，因為商店（Google Play Store 和 Apple App Store）需要先批准更新，這可能會花費一些時間。

如果您仍然無法登入應用，可嘗試以下操作：

• 檢查移動日誌。
• 確保登入憑證正確，通過網頁應用程式登入測試。

為什麼在移出應用時前台備份會停止？前台備份應該自動轉移到背景備份嗎？

前台備份和背景備份是兩種不同的機制。它們之間沒有互相通訊或交互。

前台備份由用戶的操作控制，而背景備份由設備的操作系統控制。當應用被移到背景時，背景任務的調度被委派給設備的操作系統調度器。它決定背景任務何時執行以及持續多長時間。

行為因設備製造商和操作系統而異，但大多與省電政策有關。

為什麼 iOS 上的背景備份無法正常工作？

在 iOS（iPhone 和 iPad）上，操作系統根據多個因素決定某應用是否可以啟動背景任務，其中大部分 Immich 應用無法控制。為提高背景任務執行的可能性，請遵循以下步驟：

• 在系統設置中啟用 Immich 的後台應用刷新功能： 設置 > 通用 > 後台應用刷新。
• 在不需要時禁用 低電量模式，因為這會阻止應用程式在背景運行。
• 禁用不需要背景任務的應用程式的後台應用刷新。這樣可以減少 Immich 的任務調度競爭。
• 更頻繁地使用 Immich 應用。

為何移動應用的某些功能在使用自簽名證書、基本身份驗證、自訂標頭或雙向 TLS 時無法正常工作？

這些網絡功能屬於實驗性質。它們通常無法正常使用影片播放、資產上載或下載及其他功能。 許多限制已記錄於 #15230。 替代這些實驗功能，我們建議使用 URL 切換功能、VPN 或為您的域名申請 免費可信賴的 SSL 證書。

目前我們未主動研發這些功能，也無法提供支援，但歡迎改善此功能的貢獻。 請與我們的開發團隊討論大型 PR，以確保您不會浪費時間。

為什麼移動應用還沒有更新？

應用商店可能需要幾天時間來批准應用的新版本。如果您著急，安卓 APK 文件可以從 GitHub 的發布頁面下載。

---

資產

Immich 是否會更改檔案？

不，Immich 不會修改原始檔案。 所有已編輯的元數據保存於 .xmp 附屬檔案和數據庫中。 然而，當在 Immich 的 UI 中清空回收站時，Immich 會刪除此已被移至垃圾桶的原始檔案。

為什麼我的檔案名稱在文件管理器中顯示為隨機字符串？

當存儲模板功能被關閉（默認設置）時，Immich 將檔案名稱保存為隨機字符串（也叫做隨機 UUID），以避免重複檔名。 若要恢復原始檔案名稱，您必須啟用存儲模板後運行存儲模板遷移作業。 在啟用之前，建議詳細了解 存儲模板。

我可以添加我現有的照片庫嗎？

可以，通過 外部庫。

在選擇新的 存儲模板 後，現有檔案會如何處理？

模板更改僅適用于 新的 資產。若需將模板重新應用至先前上傳的資產，可執行存儲遷移作業，此功能可在 作業 頁面找到。

為什麼只有照片而不是影片被上傳到 Immich？

這通常發生於使用反向代理部署 Immich 時。 請確保您的反向代理 配置允許大請求。 此外，請檢查反向代理的磁碟空間。 某些代理可能會將請求緩存至磁碟後再傳遞，若磁碟空間不足，請求可能失敗。

如果您使用 Cloudflare Tunnel，請注意他們設置檔案大小上限為 100 MB，且無法更改。 有時候，大小超過此限制的檔案可能運行良好，甚至可達到 1 GB。然而官方限制仍為 100 MB。 若遇到問題，我們建議切換至不同的網絡部署。

為什麼某些照片存錯日期於文件系統中？

某些場景可能導致此情況。解決方法是重新運行存儲遷移作業。 該作業僅在資產首次上傳後自動運行一次。如果元數據提取最初失敗，作業被清空或取消等情況，作業可能未自動運行。

我如何隱藏時間軸上的照片？

您可以 歸檔 它們。

我如何備份 Immich 的數據？

請參考 備份和還原。

Immich 支援讀取現有的人臉標記元數據嗎？

是的，它會從導入的資產元數據創建新的人臉和人物。詳情請參閱 功能需求 #4348 和 PR #6455。

Immich 支援過濾 NSFW 圖片嗎？

目前不支援。GitHub 上有一個 開放功能需求。

為什麼有這麼多縮略圖生成作業？

每個資產都有三個縮略圖作業：

• 模糊的（thumbhash）
• 預覽（Webp）
• 縮略圖（Jpeg）

另外，還有針對人物（人臉）縮略圖的額外作業。

為什麼 Whatsapp 的檔案不顯示正確的日期？

Whatsapp 發送的檔案沒有元數據保存於檔案中。因此，Immich 無法知道檔案的原始日期，當檔案從 Whatsapp 上傳時，只能按到達設備的順序。請參見 #9116。

如果一項資產存在於多個帳戶中會怎麼處理？

對於資產是否必須跨用戶唯一性沒有要求。如果多個用戶上載相同圖像，它會被處理為一個獨立資產，並相應執行作業和生成縮略圖。

為什麼 HDR 影片在 Immich 播放器中顯得暗淡，但下載後看起來正常？

Immich 使用的播放器存在已知的 HDR 色彩顯示問題。我們正在試驗一個提供更佳 HDR 色彩配置檔的播放器，以便進一步改進。

為什麼 Immich 將我的影片轉碼為較低品質？

Immich 始終保留您的原始檔案。除此之外，生成轉碼版本以提高兼容性和性能。

我如何刪除轉碼的影片而不刪除原始檔案？

資產的轉碼版本可以通過設置轉碼策略使其不必要並為該資產啟動一次轉碼作業來刪除。這可以通過在資產查看器選項中單個資產使用 刷新編碼影片 按鈕，或通過在管理頁面為所有資產運行轉碼作業完成。

要更新轉碼策略，請導航到管理 > 影片轉碼設置 > 轉碼策略，並從下拉列表中選擇策略。該策略將決定現有轉碼是否會在轉碼作業中被刪除或覆寫。如果根據該策略應進行影片轉碼，現有轉碼將被覆寫。否則，它會被刪除。

注释

例如，如果您有現有轉碼且策略為「影像解析度高於正常或格式不符合需求」，並切換到更窄的策略：「不符合需求格式」。如果某資產僅因其解析度而進行轉碼，當運行轉碼作業時，現有轉碼將被刪除。因為解析度不再屬於轉碼策略的一部分，該轉碼成為不必要。同樣地，若您將策略設為「不轉碼任何影片」，並為所有資產運行轉碼作業，這將刪除所有的現有轉碼，因為它們已不必要。

備份過程中是否可以壓縮圖片？

不可以。我們的設計原則是始終保持原始資產不被修改。

如何在 Docker 中掛載 CIFS/Samba 卷？

如果您無法或不希望在主機上掛載 Samba（例如在 Windows 環境中），您可以在 Docker 中掛載該卷。 以下是在 docker-compose.yml 中的範例。

更改您的用戶名、密碼、本地 IP 和共享名稱，請參考以下這一行 - originals:/usr/src/app/originals， 這與創建的卷 originals 一節相關。您可以隨意命名，並根據需要將其映射到 Docker 容器中。 例如，您可以將 originals: 更改為 Photos:，並將 - originals:/usr/src/app/originals 更改為 Photos:/usr/src/app/photos。

...
services:
  immich-server:
...
    volumes:
      # 不要編輯下一行。如果您想更改系統上的媒體存儲位置，請編輯 .env 文件中的 UPLOAD_LOCATION 值
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
+     - originals:/usr/src/app/originals
...
volumes:
  model-cache:
+ originals:
+   driver_opts:
+     type: cifs
+     o: 'iocharset=utf8,username=USERNAMEHERE,password=PASSWORDHERE,rw' # 如果需要只讀，請更改為 `ro`
+     device: '//localipaddress/sharename'

---

相簿

匯入資源到 Immich 時，可以保留我現有的相簿結構嗎？

可以，借助 Immich CLI 並使用 --album 標誌。

可以在相簿內重新排序照片嗎？

目前還不行。如需該功能更新的通知，請關注 GitHub 討論。

---

外部庫

在保留現有相簿結構的同時，可以添加外部庫嗎？

我們尚未實施從外部庫創建相簿的官方機制，但社群提供了一些 解決方案。

外部庫中的重複項會發生什麼情況？

重複檢查僅適用於上傳庫，並使用文件哈希。此外，重複檢查不是全域的，而是針對_每個庫_。因此，可能會出現同一文件在時間線中出現兩次的情況，這在外部庫中特別容易發生。

為什麼我對文件的編輯無法儲存於只讀外部庫中？

在讀寫外部庫（預設）中，圖像可正常編輯。 在只讀庫中（docker-compose.yml 中的 :ro），Immich 無法創建 .xmp 輔助文件來儲存已編輯的文件元數據。 因此，無法編輯只讀外部庫中文件的元數據（如時間戳、位置、描述、星級評分等）。

外部庫中的文件刪除操作如何處理？

當垃圾桶被清空時，Immich 將嘗試刪除已被移除的原始文件。 在讀寫外部庫（預設）中，Immich 將刪除原始文件。 在只讀庫中（docker-compose.yml 的 :ro），文件仍可在 UI 中被移到垃圾桶。 然而，當垃圾桶被清空時，這些文件將重新出現在主時間線中，因為 Immich 無法刪除原始文件。

---

機器學習

智能搜尋功能如何運作？

Immich 使用 CLIP 模型。機器學習模型將每張圖像轉換為 "嵌入"，本質上是一串數字，語意上編碼圖像中包含的內容。當您進行搜尋時，輸入的文字也會被轉換成相應的嵌入，並與圖像的嵌入進行比較以找到相似的圖像。因此，並不會生成可檢視的 "標籤"、"標籤名" 或 "描述"。有關 CLIP 及其功能的更多資訊，請查閱這裡。

臉部識別功能如何運作？

詳情請參考臉部識別功能說明。

我如何停用機器學習？

信息

停用機器學習會導致搜尋功能和“探索”頁面的體驗不佳，因為它們依賴於機器學習才能正常運作。

可通過管理 > 設定 > 機器學習設定停用機器學習，無論是全部停用還是按模型類型停用。例如，您可以選擇停用 CLIP 智能搜尋，但保留臉部識別啟用。這意味著機器學習服務只會處理啟用的任務。

然而，停用所有任務不會自動停用機器學習服務本身。在這種情況下，您可以註釋掉 docker-compose.yml 中的 immich-machine-learning 部分以防止它啟動。

出現模型損壞或下載失敗的錯誤，我該怎麼辦？

您可以刪除模型緩存卷，該卷保存了下載的模型。這將為服務提供一個乾淨的環境重新下載模型。如果模型完全無法下載，您可以從 Hugging Face 手動下載並放置到緩存文件夾中。

我可以用自訂的 CLIP 模型嗎？

不，目前不支援。只兼容 Hugging Face 頁面中列出的模型。如果您認為應該添加某個未列出的模型，可以提出功能請求。

我想用英文以外的語言進行搜尋，可以嗎？

您可以切換到多語言 CLIP 模型。請參閱這裡了解具體操作。

Immich 支援影片中的臉部識別嗎？

Immich 的機器學習功能作用於生成的縮略圖。如果臉部出現在影片的縮略圖中，它將被臉部識別功能檢測到。 未來可能會實現掃描整個影片以檢測臉部的功能。

Immich 支援動物識別嗎？

不支援。

提示

您可以在一定程度上使用智能搜尋來實現。例如，如果您有一隻金毛和吉娃娃，可輸入這些關鍵字進行搜索並查看結果。

我檢測到大量不是真正 "臉部" 的結果，該怎麼辦？

您可以將 MIN DETECTION SCORE 提高到 0.8 來減少錯誤檢測到的縮略圖。將該分數設置得太高（高於 0.9）可能會過濾掉太多真正的臉部，具體取決於使用的庫。如果您只想隱藏特定的臉部，可以在管理面板中調整 'MIN FACES DETECTED' 設定， 以提高算法對該人物的 "主要臉部" 的最低檢測分數，減少選到錯誤縮略圖的可能性。

immich_model-cache 卷佔用了很多空間，可能出了什麼問題？

如果您安裝了多個模型但不打算使用其中一些，則可以考慮刪除 immich_model-cache 中的舊模型。為此，您可以掛載模型緩存並刪除不需要的模型。

步驟

docker run -it --rm -v immich_model-cache:/mnt-models alpine sh
cd /mnt-models
ls clip/ facial-recognition/
# rm -r clip/ABC facial-recognition/DEF # 刪除未使用的模型

---

性能

為何 Immich 在低內存系統（例如樹莓派）上運行緩慢？

Immich 選擇性地使用轉碼和機器學習來實現多個功能。然而，在樹莓派上運行可能過於繁重。您可以採取措施減少，或者將 Immich 的機器學習容器託管於性能更強的系統，或者全部停用機器學習。

我可以減少 CPU 和記憶體的使用率嗎？

首次備份是最密集的，因為需要執行的任務數量較多。最耗 CPU 的是轉碼和機器學習任務（例如智能搜尋、臉部檢測），其次是縮略圖生成。以下是降低 CPU 使用率的一些方法：

• 將這些任務的任務併發度降到 1。
• 在 設定 > 轉碼設定 > 執行緒 下，將執行緒數設置為較低的值，例如 1 或 2。
• 在 設定 > 機器學習設定 > 臉部識別 > 模型名稱 下，您可以將臉部識別模型更改為 buffalo_s 而非 buffalo_l。前者是更小更快速的模型，但效果略差。
  • 如需讓新增圖像的臉部識別正常運行，您必須對所有圖像重新運行臉部檢測任務。
• 在容器層級上，您可以設置資源限制來進一步降低使用率。
  • 建議僅在採取這裡的一些措施之後，應用這些限制以獲得最佳性能。
• 如果這些更改仍不夠，請參見上述內容獲取如何停用機器學習的說明。

我可以限制 CPU 和記憶體使用嗎？

默認情況下，容器沒有資源限制，可以使用主機上的 CPU 資源，這由內核調度程序決定。要限制此行為，您可以在 docker-compose.yml 文件的相關容器配置區塊中添加以下內容。

docker-compose.yml

deploy:
  resources:
    limits:
      # CPU 執行緒數量
      cpus: '1.00'
      # 記憶體大小（GB）
      memory: '1G'

更多詳細信息，您可以查看原始的 Docker 文檔或使用這個指南。

請注意，內存限制通過終止容器運作，因此如果設置過低可能導致運行不穩定。

如何提升機器學習速度？

注释

此建議提升吞吐量，而非延遲。也就是說，它能讓智能搜尋任務處理得更快，但搜尋本身速度不會因此增加。

您可以通過增加機器學習任務（智能搜尋、臉部檢測）的併發度來提高吞吐量。併發度越高，主機將能並行處理更多資源。您可以通過導航到 管理 > 設定 > 任務設定 並根據需要增加併發度。

危险

在一般的機器上，2 或 3 個同時併發工作可能已經達到 CPU 的極限。存儲速度和延遲很快會成為限制因素，尤其是在使用 HDD 的情況下。

使用 GPU 可以更舒適地提高併發性，但在大多數情況下仍應不超過 16。

避免誇大工作併發性，因為您可能正在嚴重超載服務器。

我的伺服器顯示 Server Status Offline | Version Unknown。我該怎麼辦？

您需要在反向代理上啟用 WebSockets。

---

Docker

如何查看 Immich 日誌？

Immich 組件通常使用 Docker 部署。要查看已部署 Docker 容器的日誌，您可以使用 Docker CLI，特別是 docker logs 命令。有關示例，請參閱 Docker 幫助。

如何減少 Redis 的日誌詳細程度？

要減少 Redis 的日誌，您可以在 docker-compose.yml 文件的 redis: 部分新增以下行：

command: redis-server --loglevel warning

如何以非 root 用戶身份運行 Immich？

您可以通過為每個服務在 docker-compose.yml 中設置 user 參數來更改容器中的用戶。 您可能需要為以下內部容器路徑新增掛載點或 Docker 卷：

• immich-machine-learning:/.config
• immich-machine-learning:/.cache
• redis:/data

非 root 用戶/組需要對卷掛載具有讀/寫權限，包括 UPLOAD_LOCATION 和機器學習的 /cache。

Docker Compose 卷

Docker Compose 的頂層卷元素不支持非 root 訪問，上述所有卷必須為本地卷掛載。

為了進一步加固系統，您可以為每個容器新增以下塊。

docker-compose.yml

security_opt:
  # 防止容器啟動後提升權限
  - no-new-privileges:true
cap_drop:
  # 防止訪問原始網絡流量
  - NET_RAW

如何清除 Immich 中的數據？

Immich 的數據有兩種形式：

1. 元數據存儲於 Postgres 數據庫中，位於 DB_DATA_LOCATION 文件夾（之前的 pg_data Docker 卷）。
2. 文件（原件、縮圖、配置文件等），存儲於 UPLOAD_LOCATION 文件夾中，有更多信息。

警告

這將銷毀您的數據庫並重置您的實例，意味著您將從零開始。

移除 Immich（容器和卷）

docker compose down -v

移除容器和卷後，有幾個目錄需要刪除以將 Immich 重置為新裝置。一旦它們被刪除，Immich 可以重新啟動，並將是一次全新安裝。

• DB_DATA_LOCATION 包含數據庫、媒體信息和設置。
• UPLOAD_LOCATION 包含所有上傳到 Immich 的媒體。

Portainer

如果您使用 Portainer，請在 Portainer 中關閉堆棧。進入卷節點，然后移除所有與 Immich 有關的卷，重啟堆棧。

為什麼機器學習服務報告工作器崩潰？

注释

如果錯誤顯示工作器正在退出，這是正常現象。這是一種設計功能，旨在在服務未被使用時減少 RAM 消耗。

這可能是由以下幾個原因引起的。

如果錯誤提到 SIGKILL 或錯誤代碼 137，則很可能是服務運行內存不足。 可以考慮增加服務器的 RAM 或將服務移至具有更多 RAM 的服務器。

如果提到 SIGILL（注意缺少 K）或錯誤代碼 132，則很可能是您的服務器 CPU 與 Immich 不兼容。

數據庫

為什麼會出現數據庫所有權錯誤？

如果您在數據庫啟動時出現類似 FATAL: data directory "/var/lib/postgresql/data" has wrong ownership 的數據庫錯誤，這很可能是由於文件系統問題。 NTFS 和 ex/FAT/32 文件系統不受支持。有關更多詳細信息，請參閱此處。

如何驗證我的數據庫完整性？

從 v1.104.0 開始，新安裝默認啟用數據庫校驗和。您可以通過運行以下命令檢查是否已啟用它們。 結果為 on 表示校驗和已啟用。

檢查是否啟用了校驗和

docker exec -it immich_postgres psql --dbname=postgres --username=<DB_USERNAME> --command="show data_checksums"
 data_checksums
----------------
 on
(1 row)

如果校驗和已啟用，可以使用以下命令檢查數據庫的狀態。正常結果是所有 0s。

檢查數據庫損壞

docker exec -it immich_postgres psql --dbname=postgres --username=<DB_USERNAME> --command="SELECT datname, checksum_failures, checksum_last_failure FROM pg_stat_database WHERE datname IS NOT NULL"
  datname  | checksum_failures | checksum_last_failure
-----------+-------------------+-----------------------
 postgres  |                 0 |
 immich    |                 0 |
 template1 |                 0 |
 template0 |                 0 |
(4 rows)

您還可以掃描 Postgres 數據庫文件結構中的錯誤：

掃描文件結構錯誤

docker exec -it immich_postgres pg_amcheck --username=<DB_USERNAME> --heapallindexed --parent-check --rootdescend --progress --all --install-missing

正常結果將結束如下並返回退出代碼 0：

7470/8832 relations (84%), 730829/734735 pages (99%)
8425/8832 relations (95%), 734367/734735 pages (99%)
8832/8832 relations (100%), 734735/734735 pages (100%)

如果檢測到損壞，您應立即備份然後才能在數據庫中執行其他操作。 為此，您可能需要為數據庫服務器設置 zero_damaged_pages=on 標誌以允許 pg_dumpall 成功。 備份後，建議的下一步是從檢測到損壞之前的健康備份中恢復數據庫。 損壞的數據庫轉儲可以用於手動恢復自上次備份以來所做的任何更改（如果需要）。

可能的損壞原因很多，包括意外關機或卸載、使用 Postgres 數據的網絡共享或存儲介質不佳，例如 SD 卡或故障的 HDD/SSD。