環境變數 — HUAN 讙

所有環境變數在啟動時由 @huan/config 以 zod 驗證。缺少或格式錯誤時 Server 與 Worker 會拒絕啟動，並明確指出是哪一個變數有問題——不會帶著錯誤的設定跑起來，然後在某個奇怪的地方失敗。

完整範例見 repository 根目錄的 .env.example。

共用

變數	預設	說明
`NODE_ENV`	`development`	`development`、`test` 或 `production`
`LOG_LEVEL`	`info`	`fatal` 到 `trace`
`DATABASE_URL`	—	必填。 PostgreSQL 連線字串

變數	預設	說明
`S3_ENDPOINT`	—	必填。 Server 與 Worker 連得到的 RustFS 位址
`S3_PUBLIC_ENDPOINT`	同 `S3_ENDPOINT`	瀏覽器與裝置連得到的位址
`S3_REGION`	`us-east-1`	S3 簽章需要，RustFS 不在意實際值
`S3_BUCKET`	`huan`	儲存桶名稱
`S3_ACCESS_KEY_ID`	—	必填。
`S3_SECRET_ACCESS_KEY`	—	必填。
`S3_FORCE_PATH_STYLE`	`true`	RustFS 需要 path-style 位址

變數	預設	說明
`HOST`	`0.0.0.0`	監聽位址
`PORT`	`4000`	監聽埠
`PUBLIC_URL`	`http://localhost:4000`	對外網址，用於組出配對連結
`CORS_ORIGINS`	`http://localhost:5173`	逗號分隔的允許來源
`SESSION_COOKIE_NAME`	`huan_session`
`SESSION_TTL_HOURS`	`336`（14 天）
`SESSION_COOKIE_SECURE`	production 為 `true`	沒有 TLS 的環境才設為 `false`
`TOTP_ISSUER`	`HUAN`	顯示在驗證器 App 裡的名稱
`LOGIN_RATE_LIMIT_MAX`	`10`	時間窗內允許的失敗次數
`LOGIN_RATE_LIMIT_WINDOW_SECONDS`	`300`
`SIGNED_URL_TTL_SECONDS`	`900`	簽章網址有效時間
`DEVICE_HEARTBEAT_SECONDS`	`60`	下發給裝置的 heartbeat 間隔
`DEVICE_FALLBACK_SYNC_SECONDS`	`300`	下發給裝置的保底同步間隔
`DEVICE_MAX_CONCURRENT_DOWNLOADS`	`3`	裝置同時下載的檔案數
`ADMIN_DIST_DIR`	—	設定後由 Server 靜態提供 Admin

Server 與 Worker 都認得，全部選填。沒有設定 OTEL_EXPORTER_OTLP_ENDPOINT 時 SDK 完全不載入。說明見可觀測性。

變數	預設	說明
`OTEL_EXPORTER_OTLP_ENDPOINT`	—	OTLP/HTTP 收件端的根網址。設定了才啟用
`OTEL_EXPORTER_OTLP_PROTOCOL`	`http/protobuf`
`OTEL_RESOURCE_ATTRIBUTES`	—	建議設 `deployment.environment.name=production`
`OTEL_EXPORTER_OTLP_HEADERS`	—	收件端需要驗證時使用
`OTEL_SDK_DISABLED`	`false`	設為 `true` 暫時關閉
`HUAN_VERSION`	`dev`	映像建置時帶入 commit SHA，成為 trace 上的服務版本

變數	說明
`VITE_API_BASE_URL`	開發時的 API 位址。同源部署時不需要設定。

變數	說明
`DOCS_SITE_ORIGIN`	站台來源，預設 `https://docs.huan.linyao.tw`

只影響 llms.txt 與各頁 Markdown 裡的絕對連結。GitHub Actions 會從 Pages 設定自動帶入，本機不需要設定。