Immich CLI 實戰(zhàn)指南認證、上傳與自動化管理自托管照片庫的完整命令參考【免費下載鏈接】immichHigh performance self-hosted photo and video management solution.項目地址: https://gitcode.com/GitHub_Trending/im/immichImmich 除了 Web 端與移動端還提供官方的命令行工具immich/cli用于在終端中向 Immich 服務器批量上傳照片和視頻、檢查服務器版本與統(tǒng)計信息。本文以官方功能文檔 command-line-interface.md 為主體完整覆蓋安裝、認證、upload命令全部選項與環(huán)境變量并結(jié)合 packages/cli 目錄下的源碼深入講解去重、并發(fā)上傳、XMP sidecar 附帶上傳、watch 監(jiān)聽等底層實現(xiàn)細節(jié)幫助你在服務器、NAS 腳本或 CI 環(huán)境中把 CLI 真正用起來。功能定位與適用場景官方文檔將 CLI 的當前能力概括為兩點將照片和視頻上傳到 Immich查看服務器版本信息。文檔同時注明更多功能在規(guī)劃中。如果你的目標是批量導入 Google Photos Takeout 導出的目錄官方文檔建議使用社區(qū)維護的工具 immich-go而 CLI 更適合日常把某個目錄同步/歸檔進 Immich這類場景因為它支持 dry-run、并發(fā)控制、JSON 輸出等面向腳本化的設計。CLI 源碼位于 packages/cli 目錄包名為immich/cli入口命令注冊在 src/index.tspackage.json中bin字段將immich命令映射到構(gòu)建產(chǎn)物見 packages/cli/package.json。環(huán)境要求與安裝要求Node.js 22 及以上packages/cli/package.json 中engines聲明為node 22.0.0Npm。如果系統(tǒng)無法安裝 Node/npm可以使用官方提供的 Docker 版本見下文。通過 NPM 安裝npm i -g immich/cli如果你安裝過舊版legacyCLI需要先卸載npm uninstall -g immich通過 Docker 運行當 npm 不可用時可直接運行官方 CLI 鏡像。docker run命令會直接在容器內(nèi)執(zhí)行immich命令因此可以把upload等參數(shù)直接追加在命令行末尾docker run -it -v $(pwd):/import:ro -e IMMICH_INSTANCE_URLhttps://your-immich-instance/api -e IMMICH_API_KEYyour-api-key ghcr.io/immich-app/immich-cli:latest例如執(zhí)行遞歸上傳docker run -it -v $(pwd):/import:ro -e IMMICH_INSTANCE_URLhttps://your-immich-instance/api -e IMMICH_API_KEYyour-api-key ghcr.io/immich-app/immich-cli:latest upload -a -c 5 --recursive directory/請根據(jù)實際環(huán)境修改IMMICH_INSTANCE_URL和IMMICH_API_KEY兩個環(huán)境變量也可以改用 Docker env file 來存放敏感的 API key。從 packages/cli/Dockerfile 可以確認鏡像的工作目錄被設置為/importWORKDIR /import所以-v $(pwd):/import:ro把宿主機當前目錄以只讀方式掛載進去容器內(nèi)的.即指向待上傳目錄ENTRYPOINT直接執(zhí)行 CLI 的構(gòu)建產(chǎn)物參數(shù)透傳給immich命令。命令總覽Usage運行immich無參數(shù)時輸出的完整幫助如下與官方文檔一致$ immich Usage: immich [options] [command] Command line interface for Immich Options: -V, --version output the version number -d, --config-directory directory Configuration directory where auth.yml will be stored (default: ~/.config/immich/, env: IMMICH_CONFIG_DIR) -u, --url [url] Immich server URL (env: IMMICH_INSTANCE_URL) -k, --key [key] Immich API key (env: IMMICH_API_KEY) -h, --help display help for command Commands: login|login-key url key Login using an API key logout Remove stored credentials server-info Display server information upload [options] [paths...] Upload assets help [command] display help for command對照 src/index.ts 可以看到這四個全局選項-d/-u/-k等都通過 commander 的Option.env()綁定了環(huán)境變量因此所有選項都優(yōu)先取命令行參數(shù)其次回退到同名環(huán)境變量。全局選項環(huán)境變量默認值說明-V, --version——輸出版本號-d, --config-directory dirIMMICH_CONFIG_DIR~/.config/immich/存放auth.yml的憑證目錄-u, --url urlIMMICH_INSTANCE_URL—Immich 服務器 URL以/api結(jié)尾-k, --key keyIMMICH_API_KEY—Immich API key認證機制login / logout 與 auth.yml獲取 API KeyAPI key 在 Web 界面的用戶設置面板中獲取可以為 key 指定權(quán)限以限制其訪問范圍。login 命令# immich login [url] [key] immich login http://192.168.1.216:2283/api HFEJ38DNSDUEGlogin成功后會把憑證寫入配置目錄下的auth.yml文件默認目錄為~/.config/immich/目錄可以用-d選項或環(huán)境變量IMMICH_CONFIG_DIR指定。請妥善保管該文件——用完執(zhí)行l(wèi)ogout或手動刪除它。從 src/commands/auth.ts 的實現(xiàn)可以看到login的完整流程調(diào)用connect(url, key)發(fā)起連接。connect位于 src/utils.ts它還會先請求url/.well-known/immich端點做服務發(fā)現(xiàn)如果服務器返回了 API 端點CLI 會自動把 URL 糾正為端點地址因此即使 URL 寫得略有偏差也能連上通過requirePermissions([Permission.UserRead])校驗當前 key 是否具備UserRead權(quán)限缺失時打印缺失的權(quán)限名并退出process.exit(1)調(diào)用getMyUser()確認身份打印Logged in as email若配置目錄不存在則遞歸創(chuàng)建最后以0o600僅屬主可讀寫的文件權(quán)限寫入auth.yml見 src/utils.ts 的writeAuthFile降低憑證被同機其他用戶讀取的風險。logout 命令immich logout實現(xiàn)為直接刪除auth.yml文件src/commands/auth.ts。認證的回退順序執(zhí)行任何需要認證的命令時src/utils.ts 中的authenticate按以下順序取憑證命令行同時提供-u和-k時直接使用它們不讀 auth 文件否則讀取配置目錄中的auth.yml。若文件不存在則提示No auth file exists. Please login first.并退出。這意味著login并不是每次上傳的強制前置步驟——你完全可以每次都用-u/-k或IMMICH_INSTANCE_URL/IMMICH_API_KEY環(huán)境變量傳入憑證這正是 Docker 用法的工作方式。upload 命令完整選項參考官方文檔中upload子命令的完整幫助輸出Usage: immich upload [paths...] [options] Upload assets Arguments: paths One or more paths to assets to be uploaded Options: -r, --recursive Recursive (default: false, env: IMMICH_RECURSIVE) -i, --ignore pattern Pattern to ignore (env: IMMICH_IGNORE_PATHS) -h, --skip-hash Dont hash files before upload (default: false, env: IMMICH_SKIP_HASH) -H, --include-hidden Include hidden folders (default: false, env: IMMICH_INCLUDE_HIDDEN) -a, --album Automatically create albums based on folder name (default: false, env: IMMICH_AUTO_CREATE_ALBUM) -A, --album-name name Add all assets to specified album (env: IMMICH_ALBUM_NAME) --visibility visibility Set the visibility of uploaded assets (choices: archive, timeline, hidden, locked, env: IMMICH_VISIBILITY) -n, --dry-run Dont perform any actions, just show what will be done (default: false, env: IMMICH_DRY_RUN) -c, --concurrency number Number of assets to upload at the same time (default: 4, env: IMMICH_UPLOAD_CONCURRENCY) -j, --json-output Output detailed information in json format (default: false, env: IMMICH_JSON_OUTPUT) --delete Delete local assets after upload (env: IMMICH_DELETE_ASSETS) --delete-duplicates Delete local assets that are duplicates (already exist on server) (env: IMMICH_DELETE_DUPLICATES) --no-progress Hide progress bars (env: IMMICH_PROGRESS_BAR) --watch Watch for changes and upload automatically (default: false, env: IMMICH_WATCH_CHANGES) --help display help for command官方文檔特別說明以上所有選項同樣可以從環(huán)境變量讀取這對 Docker 場景用--env-file注入配置和 cron 腳本尤其有用。對照 src/index.ts 的注冊代碼還可以補充兩個源碼級約束-A, --album-name與-a, --album互斥.conflicts(album)同時指定會報錯-n, --dry-run與--skip-hash互斥.conflicts(skipHash)——dry-run 依賴哈希檢查來判斷哪些文件將被上傳因此二者不能同時使用--watch會自動隱含progress: false.implies({ progress: false })因為進度條渲染與監(jiān)聽日志輸出會互相干擾。關(guān)于并發(fā)默認值有一個值得注意的細節(jié)文檔的幫助輸出標注default: 4而從 src/index.ts 的當前源碼看默認值是按 CPU 核數(shù)動態(tài)計算的Math.max(1, os.cpus().length - 1)。以你所運行版本的immich upload --help實際輸出為準。選項速查表選項環(huán)境變量默認值作用-r, --recursiveIMMICH_RECURSIVEfalse遞歸掃描子目錄-i, --ignore patternIMMICH_IGNORE_PATHS—忽略匹配 glob 模式的文件可多次指定--skip-hashIMMICH_SKIP_HASHfalse上傳前不計算文件哈希提速用-H, --include-hiddenIMMICH_INCLUDE_HIDDENfalse包含隱藏文件/目錄-a, --albumIMMICH_AUTO_CREATE_ALBUMfalse按所在文件夾名自動創(chuàng)建/歸入相冊-A, --album-name nameIMMICH_ALBUM_NAME—將所有上傳資產(chǎn)加入指定名稱的相冊--visibility vIMMICH_VISIBILITY—上傳資產(chǎn)的可見性archive/timeline/hidden/locked-n, --dry-runIMMICH_DRY_RUNfalse只做檢查不執(zhí)行任何寫操作-c, --concurrency nIMMICH_UPLOAD_CONCURRENCY見上文說明同時上傳的資產(chǎn)數(shù)-j, --json-outputIMMICH_JSON_OUTPUTfalse以 JSON 輸出newFiles、duplicates、newAssets--deleteIMMICH_DELETE_ASSETS—上傳成功后刪除本地文件--delete-duplicatesIMMICH_DELETE_DUPLICATES—刪除服務端已存在的重復文件--no-progressIMMICH_PROGRESS_BAR—隱藏進度條--watchIMMICH_WATCH_CHANGESfalse監(jiān)聽目錄變化并自動上傳Quick Start從零完成一次上傳第一步認證# immich login [url] [key] immich login http://192.168.1.216:2283/api HFEJ38DNSDUEG第二步上傳資產(chǎn)上傳單個文件immich upload file1.jpg file2.jpg默認不掃描子目錄遞歸上傳整個目錄immich upload --recursive directory/不確定會發(fā)生什么時先用--dry-run預演它不會執(zhí)行任何實際操作immich upload --dry-run --recursive directory/第三步按需組合選項跳過哈希檢查--skip-hash默認情況下upload會先對每個文件計算 SHA-1用來避免重復上傳。如果你對文件的唯一性有把握可以傳--skip-hash省掉這一步。注意 Immich 服務端始終會自己做基于哈希的去重所以這純粹是性能層面的取舍——帶寬充足時跳過客戶端哈希可能更快。immich upload --skip-hash --recursive directory/按文件夾自動建相冊--album為每個上傳資產(chǎn)按其所在文件夾名自動創(chuàng)建相冊immich upload --album --recursive directory/上傳到指定相冊--album-name把所有資產(chǎn)加入指定名稱的相冊immich upload --album-name My summer holiday --recursive directory/用 glob 模式排除文件--ignore可以傳多個排除模式。glob 的用法可參考 庫功能文檔immich upload --ignore **/Raw/** --recursive directory/immich upload --ignore **/Raw/** **/*.tif --recursive directory/包含隱藏文件--include-hidden默認跳過隱藏文件如需包含immich upload --include-hidden --recursive directory/設置可見性--visibility把上傳資產(chǎn)設為archive、timeline、hidden或lockedimmich upload --visibility archive --recursive directory/JSON 輸出--json-output輸出包含newFiles、duplicates、newAssets三個鍵的 JSON。由于前面有若干行日志輸出需要去掉輸出的前幾行才能解析。例如列出將被上傳的文件供后續(xù)處理immich upload --dry-run --json-output . | tail -n 6 | jq .newFiles[]深入源碼一次 upload 到底做了什么upload的實現(xiàn)集中在 src/commands/asset.ts主入口upload()asset.ts#L139-L162的流程是認證 → 權(quán)限校驗 → 掃描文件 → 批量上傳。1. 權(quán)限與文件掃描上傳要求 API key 具備AssetUpload權(quán)限asset.ts#L141否則 CLI 會明確提示缺失的權(quán)限名。scan()會先調(diào)用服務端的getSupportedMediaTypes()拿到當前服務器支持的全部圖片/視頻擴展名再用 fast-glob 掃描本地目錄src/utils.ts 的crawl。這解釋了為什么--recursive不加時不會進入子目錄模式只加/*而非/**、--ignore模式會被包裝成**/pattern匹配全路徑、--include-hidden對應 glob 的dot選項。2. 去重客戶端 SHA-1 服務端批量比對checkForDuplicates()asset.ts#L179-L310是--skip-hash所控制的環(huán)節(jié)逐文件流式計算 SHA-1sha1()utils.ts#L211-L219進度條按文件總字節(jié)數(shù)顯示Hashing files/Checking for duplicates兩條進度校驗項每攢滿5000 條就調(diào)用一次服務端checkBulkUpload批量接口按返回的action分為newFilesAccept與duplicates已存在的資產(chǎn)所有任務通過內(nèi)部Queue執(zhí)行失敗自動重試 3 次最終逐條報告失敗文件。--skip-hash時則直接跳過本步把所有文件當作新文件asset.ts#L180-L183這正是文檔所說服務端仍會自己哈希去重的原因。3. 上傳與 XMP sidecaruploadFile()asset.ts#L404-L445通過FormData向POST /assets提交fileCreatedAt/fileModifiedAt取自文件的mtimefileSize、isFavoritefalse、assetData文件流visibility僅在指定--visibility時附加sidecarDatafindSidecar()asset.ts#L447-L457會自動查找同名 XMP sidecar支持兩種命名photo.ext.xmp和photo.xmp。存在則一并上傳無需任何額外選項。上傳結(jié)果按服務端返回狀態(tài)統(tǒng)計新資產(chǎn)計入 success重復狀態(tài)AssetMediaStatus.Duplicate計入 skipped結(jié)束時打印成功/跳過的數(shù)量與字節(jié)數(shù)并逐條列出上傳失敗的文件。4. 相冊、刪除本地文件uploadBatch()asset.ts#L69-L78在上傳完成后依次執(zhí)行updateAlbums()--album時以資產(chǎn)的父目錄名作為相冊名getAlbumName()asset.ts#L595-L597先getAllAlbums取已有相冊只創(chuàng)建缺失的再分批把資產(chǎn)加入對應相冊--album-name則全部歸入該固定名稱的相冊deleteFiles()--delete刪除上傳成功的文件--delete-duplicates刪除被判為重復的文件刪除時會順帶unlink對應的 XMP sidecar。注意 dry-run 模式下只打印Would have deleted N local assets。5. watch 模式目錄監(jiān)聽自動上傳--watch使用 chokidar 監(jiān)聽指定路徑startWatch只處理服務器支持媒體類型擴展名的文件ignore模式同樣生效變更事件先匯入Batcherutils.ts#L225-L282每 100 個文件或每 10 秒UPLOAD_WATCH_BATCH_SIZE/UPLOAD_WATCH_DEBOUNCE_TIME_MSasset.ts#L27-L28觸發(fā)一次批量上傳避免寫入中的文件被反復處理awaitWriteFinish: true初始掃描仍走一次性的scan()注釋說明 watcher 不處理初始掃描然后進入長駐監(jiān)聽CtrlC時干凈關(guān)閉 watcher。這使得--watch非常適合放在后臺長期運行充當目錄 → Immich的輕量同步器。并發(fā)模型Queue 與 fastq哈希、去重校驗、上傳三個階段都使用同一個自研的內(nèi)存隊列封裝 src/queue.ts基于fastq.promise支持concurrency并行度與retry次數(shù)的失敗重試上傳鏈路統(tǒng)一配置為retry: 3。因此-c, --concurrency不僅影響上傳并行度也決定了本地哈希計算與批量比對請求的并發(fā)程度——調(diào)大它主要收益在磁盤讀與網(wǎng)絡并發(fā)調(diào)小則對服務器壓力更溫和。server-info查看服務器版本與統(tǒng)計immich server-info實現(xiàn)見 src/commands/server-info.ts它并發(fā)請求四個接口后輸出Url認證后解析出的服務器地址經(jīng).well-known/immich服務發(fā)現(xiàn)糾正后Version服務器 major.minor.patch 版本Formats服務器支持的圖片/視頻擴展名列表Statistics圖片數(shù)、視頻數(shù)、資產(chǎn)總數(shù)。該命令要求 API key 同時具備ServerAbout、AssetStatistics、UserRead三個權(quán)限創(chuàng)建 key 時若未勾選對應權(quán)限會收到明確的缺失權(quán)限提示。常見問題與使用注意URL 必須以/api結(jié)尾IMMICH_INSTANCE_URL/login的 URL 示例均為https://your-immich-instance/api。連接失敗時logErrorutils.ts#L101-L113會特別提示檢查是否有反向代理或 SSO 門戶代替了 API 應答。憑證安全auth.yml以0o600權(quán)限寫入但仍建議用畢logout或刪除文件Docker 場景優(yōu)先用 env file 而非明文參數(shù)。dry-run 與 skip-hash 不可同用--album與--album-name不可同用源碼中均有顯式?jīng)_突校驗。忽略模式語義--ignore按全路徑匹配內(nèi)部包裝為**/pattern寫法與 庫文檔 中掃描設置的排除模式一致推薦只用于基礎的文件夾級排除。版本差異幫助文本如--skip-hash的短選項、--concurrency的默認值標注可能隨版本變化以你所裝版本的immich upload --help實際輸出為準本文引用的行為以當前倉庫 packages/cli 源碼為準。小結(jié)Immich CLI 用一條login完成認證、一條upload覆蓋絕大多數(shù)批量導入需求全部選項均可用環(huán)境變量驅(qū)動天然適配 Docker 與定時任務。理解其源碼后可得到幾個實用結(jié)論去重是客戶端 SHA-1 服務端批量比對的兩段式設計--skip-hash只省本地計算而服務端去重不受影響--watch通過 100 文件/10 秒的批處理窗口實現(xiàn)低開銷的目錄監(jiān)聽XMP sidecar 會被自動附帶上傳。配合--dry-run與--json-output它也能作為腳本化遷移管道的可靠一環(huán)?！久赓M下載鏈接】immichHigh performance self-hosted photo and video management solution.項目地址: https://gitcode.com/GitHub_Trending/im/immich創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考