Immich 重設管理員密碼：被 OIDC 鎖住也能救

Immich 重設管理員密碼前，先分清你是哪一種鎖死

Immich 管理員密碼登入不了，官方支援的做法只有一條：進到正在執行的 immich_server 容器，用它內建的 immich-admin 指令重設。真正卡住人的通常不是指令本身，而是一開始沒分清楚自己遇到的是哪一種鎖死。

密碼遺失和身分提供者鎖死是兩件不同的事，修法也不一樣。OIDC 是 OpenID Connect（一種用第三方身分提供者做單一登入的協定），Immich 的後台把這一區寫成 OAuth 設定，兩個詞在這裡指同一件事。用下面兩句話對一下你的登入頁：

• 登入頁還看得到 email 和密碼兩個欄位，你輸入之後被拒絕：這是密碼問題，直接往重設密碼那一節走。
• 登入頁只剩一顆用第三方帳號登入的按鈕，或者一打開就被轉去身分提供者：本機密碼登入被關掉了，先重新打開它，重設密碼才有意義。

第二種狀況還有一個更淺的可能。後台的 auto launch 開著時，Immich 會在你一進登入頁就把你丟去身分提供者，所以你根本沒機會看到密碼表單。官方文件寫得很清楚，這時可以直接開 /auth/login?autoLaunch=0，登入頁就會停在原地不轉走。如果密碼表單在那裡出現了，你的本機密碼登入其實還活著，問題只是看不到而已。

這篇對應哪個 Immich 版本

本文的指令對照 Immich v3.2.2（2026 年 9 月 15 日發布）的官方文件。這件事要講明白，因為管理 CLI 的子指令名稱在版本之間搬過家，網路上舊文章抄來的指令名在新版會找不到。所以不要相信任何教學（包含這一篇）寫的名字，要相信你那台機器自己印出來的清單：

docker exec -it immich_server immich-admin version
docker exec -it immich_server immich-admin help

help 會把這個映像檔實際支援的子指令列出來。你要用的名字就在那份清單裡。如果清單裡沒有本文提到的某個子指令，是你的版本比較舊或比較新，不是指令打錯。還沒有裝起來、想從零開始的話，先看 用 Docker Compose 自架 Immich 取代 Google 相簿，這篇假設你的 compose 環境已經在跑。

怎麼進到 immich_server 容器裡

這一步最常見的錯誤是服務名和容器名搞混。官方 compose 檔裡，服務名是 immich-server（連字號），container_name 是 immich_server（底線）。docker compose 認服務名，docker 認容器名，兩者不能互換。

cd /path/to/immich     # 放 docker-compose.yml 和 .env 的那個目錄
docker compose ps
docker compose exec immich-server /bin/bash

docker compose exec 一定要在有 compose 檔的目錄裡執行，因為它是先讀檔案才知道 immich-server 是誰。如果你忘了路徑在哪，用容器名走另一條，跟目錄無關：

docker exec -it immich_server /bin/bash

注意旗標不要抄錯。-it 是 docker exec 的旗標，docker compose exec 本身就會配好 TTY（終端機介面），-i 不在它的旗標清單裡，加了它會直接拒絕執行，而錯誤訊息講的是旗標不認識，跟 Immich 沒有關係。兩種寫法的差異、以及互動式 shell 為什麼需要 TTY，整理在 docker compose exec 開互動 shell 裡。

docker compose ps 是這一步的檢查點。immich-server 的狀態要是執行中；如果它顯示重啟中或已退出，exec 不會成功，因為沒有活著的行程可以進去。那種情況跳到下面「immich_server 根本起不來」那一節。

用 immich-admin reset-admin-password 重設密碼

進到容器裡之後，先確認你要改的是哪個帳號，再執行重設：

immich-admin list-users
immich-admin reset-admin-password

也可以不進 shell，一行直接跑完：

docker compose exec immich-server immich-admin reset-admin-password

這是一支互動式指令，它會在你的終端機裡問你問題，然後把結果印在同一個地方。所以有三件事要做到。第一，不要加 -d，不要丟到背景執行，因為背景行程沒有你的終端機可以問話，你會以為它沒反應。第二，逐行把容器印出來的每一句讀完再按 Enter，它問的內容（包含要不要讓現有的登入工作階段失效）在不同版本的字句不一樣，照你眼前看到的那一版回答。第三，指令印出來的新憑證或重設連結只會出現這一次，先貼進密碼管理器，再關掉視窗。

如果終端機完全沒有任何提示出現，容器那邊八成正在噴錯。另開一個視窗看它自己的紀錄：

docker compose logs --tail=100 immich-server

改完之後回瀏覽器用新密碼登入。還是被拒絕的話，最可能的原因是你改到了別的帳號：immich-admin list-users 印出來的清單會告訴你哪一個帳號才是管理員，一台機器上有兩個管理員帳號的情況比想像中常見。

OIDC 把本機密碼登入關掉時怎麼救

Immich 的系統設定允許管理員關掉整台機器的帳號密碼登入。官方文件對這件事的警告很直接：如果 OAuth 登入同時也不能用，那就沒有任何人能用任何方式登入。所以這種鎖死是設定造成的，不是密碼錯，你重設一百次密碼也進不去，因為伺服器根本不收密碼這種登入方式。

好消息是同一支 CLI 就能把它打開，而且完全不需要有人先登入：

immich-admin enable-password-login
immich-admin reset-admin-password

immich-admin 是直接連資料庫改設定的，不經過網頁登入那一層，所以它在你被鎖在門外的時候照樣有效。這也是官方文件自己指定的救援路徑。

身分提供者已經壞掉、或者憑證過期而你暫時修不好的話，順手把它停掉，登入頁就不會再一直想轉走：

immich-admin disable-oauth-login

另一種狀況是你的 OIDC 登入其實成功了，但進去發現什麼都不能改，因為那個透過 SSO 建立的帳號不是管理員。這時把它升級：

immich-admin grant-admin

它會問你要升級哪個 email，對應的就是 list-users 裡的那個地址。revoke-admin 是反向操作，事情處理完之後可以把臨時開的權限收回去。

如果 immich_server 根本起不來

exec 的前提是容器活著。docker compose ps 顯示重啟中或已退出時，先解決啟動問題，因為 CLI 需要一個跑得起來的映像檔，也需要連得上的資料庫。

docker compose logs --tail=100 immich-server
docker compose logs --tail=50 database

最常見的是三類原因，紀錄裡都看得到。一是資料庫連不上，通常是 .env 裡的 DB_PASSWORD 被改過，但 DB_DATA_LOCATION 底下的資料目錄還是用舊密碼初始化的，Postgres 那邊會記錄認證失敗。二是記憶體不夠，容器被系統的 OOM killer 殺掉並反覆重啟，機器上同時跑機器學習容器時特別容易發生，需要多少記憶體可以對照 Immich 的記憶體與儲存空間需求。三是升級升到一半，映像檔版本和資料庫結構不一致。

改完 .env 或 compose 檔之後要用 docker compose up -d，不要只用 docker compose restart。restart 是把同一個容器停掉再開，設定檔的變更不會被讀進去，你會看到一模一樣的錯誤而懷疑自己改錯地方；差別整理在 restart 和重新建立容器的差別。

最後手段：從 Postgres 容器下手

只有在伺服器容器怎麼都起不來、immich-admin 完全沒辦法執行的時候才走這一條。直接動資料庫沒有任何防護，一個少寫 WHERE 的 UPDATE 會改到整張表，psql 不會再問你一次。官方文件對這件事的立場就是：能不動就不要動，要動之前先有一份當下的備份。

所以第一個指令是備份，不是查詢。官方的備份寫法是：

docker exec -t immich_postgres pg_dump --clean --if-exists --dbname=<DB_DATABASE_NAME> --username=<DB_USERNAME> | gzip > "/path/to/backup/dump.sql.gz"

兩個佔位符從你的 .env 抄：DB_DATABASE_NAME 預設是 immich，DB_USERNAME 預設是 postgres。要注意這份 dump 只有資料庫，照片檔案在別的地方，完整的一套（含還原時那個「必須是全新安裝」的前提）看 Immich 的備份與還原流程，檔案實際落在哪個目錄則看 Immich 用 Docker 跑時照片存在哪裡。

備份完成才進資料庫，而且先只讀不寫：

docker exec -it immich_postgres psql --dbname=immich --username=postgres

\dt
SELECT * FROM "user";
SELECT "key", "value" FROM "system_metadata" WHERE "key" = 'system-config';

這裡的雙引號不是裝飾。現在的版本表名是單數的 user，而 user 是 Postgres 的保留字，沒有雙引號包起來查詢就會失敗。欄位名像 isAdmin 是駝峰式大小寫，不加雙引號時 Postgres 會把它折成全小寫而找不到欄位。舊版安裝的表名可能是複數的 users，所以先用 \dt 看清楚你這台到底是哪一個，再照抄名字。

user 這張表要看四件事，它們解釋了大部分「密碼明明對卻進不去」的情況。isAdmin 為真的是哪一列，那才是你要救的帳號。deletedAt 有值代表帳號被軟刪除，登入自然會被拒。oauthId 有值代表這個帳號綁了身分提供者。password 是 NULL 代表這個帳號從來沒有本機密碼，它是透過 SSO 建立的，這種帳號要先有密碼才能用密碼登入。

不要自己算一個雜湊值塞進 password 欄位。那個欄位存的是密碼雜湊（hash），格式和參數必須和伺服器驗證時用的完全一致，猜錯的結果是登入一直被拒，而你以為密碼已經改好了，於是往錯的方向查下去。密碼一律交給 immich-admin reset-admin-password。

system_metadata 裡那一列 system-config 存的是你在後台改過的設定，密碼登入的開關就在裡面。先把查詢印出來的 JSON 完整存成一個檔案，這是你的還原點。接著只把 passwordLogin 底下的 enabled 改回真，再寫回去：

UPDATE "system_metadata" SET "value" = '<你改好的 JSON>' WHERE "key" = 'system-config';

把整列刪掉也能讓 Immich 回到預設值，但代價是你在後台調過的每一項設定（儲存範本、機器學習、併發數）全部一起回到預設，所以那是更後面的選項，不是更快的選項。改完之後重啟伺服器容器讓它重新讀取設定：

docker compose restart immich-server
docker compose logs --tail=50 immich-server

紀錄裡沒有新的錯誤、登入頁重新長出密碼欄位，就回去跑 immich-admin reset-admin-password，剩下的交給支援的路徑處理。

之後不要再被鎖在門外

這次的麻煩幾乎都可以用設定階段的幾個決定避免掉。

• 管理員帳號用一個你真的收得到信的 email，不要 admin@localhost 這類寫死的假地址。
• 密碼存進密碼管理器，不要存在那台 VPS 上的檔案裡，因為你被鎖在外面的時候常常也進不去那台機器的桌面。
• 導入 SSO 之後仍然保留本機密碼登入。身分提供者會過期、會改設定、會自己壞掉，留一條本機路徑就不會變成鎖死。
• 開第二個管理員帳號並用 immich-admin grant-admin 給權限，鑰匙不要只有一份。
• 資料庫備份要排程，而且至少演練過一次還原。備份沒有還原過，等於還不知道它能不能用。

FAQ

immich-admin reset-admin-password 會動到我的照片嗎？

不會。它改的是資料庫裡那個帳號的密碼，照片檔案放在 UPLOAD_LOCATION 指到的目錄，這支指令不碰那裡。它可能影響的是現有的登入工作階段：指令會問你要不要讓已經登入的裝置全部失效，回答要的話，手機 App 需要重新登入一次。

我設了 OIDC，登入頁沒有密碼欄位，要怎麼進去？

先開 /auth/login?autoLaunch=0。如果密碼表單出現了，代表密碼登入還開著，只是被自動轉址蓋住。表單還是不出現的話，密碼登入已經在系統設定裡被關掉，在 immich_server 容器裡執行 immich-admin enable-password-login 打開它，再執行 immich-admin reset-admin-password。這支 CLI 直接連資料庫，不需要有人先登入就能生效。

docker compose exec 說找不到服務，或說容器沒在執行，怎麼辦？

找不到服務通常是目錄不對或名字不對。docker compose exec 必須在放 docker-compose.yml 的目錄裡執行，而且它認的是服務名 immich-server（連字號），不是容器名 immich_server（底線）。用容器名要改成 docker exec -it immich_server /bin/bash。如果訊息是容器沒在執行，那就不是指令的問題：用 docker compose ps 看狀態，再用 docker compose logs --tail=100 immich-server 看它為什麼起不來，修好之後才有東西可以 exec。

可以直接在 Postgres 裡改 password 欄位嗎？

技術上可以，實務上不要。那個欄位存的是密碼雜湊，格式和參數要和伺服器驗證的方式完全一致，手寫的值對不上就會一直登入失敗，而你會誤以為密碼已經換好而查錯方向。資料庫只用來做兩件事：查清楚哪個帳號是管理員（SELECT * FROM "user";），以及在伺服器完全起不來時把密碼登入的開關打開。密碼本身交給 immich-admin reset-admin-password，動手之前先做一份 pg_dump 備份。