設定

環境變數

用法

Logto 依照以下順序處理環境變數：

• 系統環境變數
• 專案根目錄下的 .env 檔案，格式遵循 dotenv

因此，系統環境變數會覆蓋 .env 中的值。

變數

警告:

如果你在專案根目錄下透過 npm start 執行 Logto，NODE_ENV 會永遠是 production。

在預設值中，protocol 會根據你的 HTTPS 設定為 http 或 https。

Key	預設值	類型	說明
NODE_ENV	undefined	'production' | 'test' | undefined	Logto 執行時所處的環境類型。
PORT	3001	number	Logto 監聽的本地埠號。
ADMIN_PORT	3002	number	Logto 管理主控台監聽的本地埠號。
ADMIN_DISABLE_LOCALHOST	N/A	string | boolean | number	設為 1 或 true 可停用管理主控台的埠號。若未設定 ADMIN_ENDPOINT，將完全停用管理主控台。
DB_URL	N/A	string	Logto 資料庫的 Postgres DSN。
HTTPS_CERT_PATH	undefined	string | undefined	詳情請參閱 啟用 HTTPS。
HTTPS_KEY_PATH	undefined	string | undefined	同上。
TRUST_PROXY_HEADER	false	boolean	同上。
ENDPOINT	'protocol://localhost:$PORT'	string	你可以指定自訂網域的 URL 以進行線上測試或正式環境。這也會影響 OIDC 簽發者識別碼 (issuer identifier) 的值。
ADMIN_ENDPOINT	'protocol://localhost:$ADMIN_PORT'	string	你可以為正式環境指定自訂網域的 URL（例如：ADMIN_ENDPOINT=https://admin.domain.com）。這也會影響管理主控台重新導向 URI 的值。
CASE_SENSITIVE_USERNAME	true	boolean	指定使用者名稱是否區分大小寫。修改此值時請小心；變更不會自動調整現有資料庫資料，需手動管理。
SECRET_VAULT_KEK	undefined	string	用於加密 Secret Vault 中資料加密金鑰（DEK, Data Encryption Keys）的金鑰加密金鑰（KEK, Key Encryption Key）。Secret Vault 正常運作必須設定此值。必須為 base64 編碼字串。建議使用 AES-256（32 bytes）。範例：crypto.randomBytes(32).toString('base64')

啟用 HTTPS

使用 Node

Node 原生支援 HTTPS。提供 BOTH（兩者） HTTPS_CERT_PATH 與 HTTPS_KEY_PATH 即可透過 Node 啟用 HTTPS。

HTTPS_CERT_PATH 指向你的 HTTPS 憑證路徑，HTTPS_KEY_PATH 則指向你的 HTTPS 金鑰路徑。

使用 HTTPS 代理伺服器

另一種常見做法是在 Node 前方設置 HTTPS 代理伺服器（例如 Nginx）。

此時，建議將 TRUST_PROXY_HEADER 設為 true，表示信任代理伺服器的標頭欄位。Logto 會將此值傳遞給 Koa 應用程式設定。

何時需要設定此欄位，請參閱 信任 TLS 卸載代理伺服器。

資料庫設定

管理過多環境變數既沒效率又不夠彈性，因此我們將大多數一般設定存放於資料庫表格 logto_configs。

此表格為簡單的鍵值儲存，key 可列舉如下：

Key	類型	說明
oidc.cookieKeys	string[]	簽署 cookie 金鑰 的字串陣列。
oidc.privateKeys	string[]	用於 OIDC JWT 簽署 的私鑰內容字串陣列。

支援的私鑰類型

• EC（P-256、secp256k1、P-384 與 P-521 曲線）
• RSA
• OKP（Ed25519、Ed448、X25519、X448 子類型）