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