設定

環境變數

用法

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

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

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

變數

警告:

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

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

Key	預設值	Type	說明
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。
DATABASE_STATEMENT_TIMEOUT	N/A	string	（v1.36.0+）PostgreSQL statement_timeout，單位為毫秒。請使用數字字串（如 5000）設定，或用 DISABLE_TIMEOUT 省略啟動參數（建議用於 PgBouncer / RDS Proxy）。若未設定或無效，預設為 60000 ms。
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。請同時提供 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	Type	說明
oidc.cookieKeys	string[]	簽署 Cookie 金鑰 的字串陣列。
oidc.privateKeys	string[]	用於 OIDC JWT 簽署 的私鑰內容字串陣列。

支援的私鑰類型

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