# 設定參考

控制器、Docker Compose、探測器 agent、Web 建置與說明文件建置所使用的完整環境變數參考。

控制器會讀取環境變數，也可以讀取工作目錄或 `server/` 下的 `.env`。Docker Compose 則讀取該專案的 `.env`，並將支援的值傳入容器。

時間長度使用 Go 語法，例如 `250ms`、`5s`、`30m` 或 `168h`。布林值使用 `true` 或 `false`。機密值必須保持穩定、彼此不同，而且不能放進版本控制。

## Compose 部署變數

這些值用來選擇映像檔與主機對外開放方式，不會直接設定控制器。

| 變數                | 預設值                              | 用途                                     |
| ------------------- | ----------------------------------- | ---------------------------------------- |
| `NETSTAMP_IMAGE`    | `yorukot/netstamp`                  | 控制器映像檔儲存庫                       |
| `NETSTAMP_VERSION`  | `latest`                            | 控制器與遷移映像檔的標籤                 |
| `TIMESCALEDB_IMAGE` | `timescale/timescaledb:latest-pg16` | 資料庫映像檔                             |
| `NETSTAMP_PORT`     | `3000`                              | 對外映射至控制器 8080 連接埠的主機連接埠 |

正式環境應固定映像檔版本。Compose volume 的邏輯名稱是 `netstamp-postgres`；Docker 通常會在實際名稱前加上 Compose 專案名稱。

## 控制器核心設定

| 變數                             | 預設值                  | 用途                                                           |
| -------------------------------- | ----------------------- | -------------------------------------------------------------- |
| `APP_ENV`                        | `local`                 | 執行環境；不是 `local` 時會啟用安全工作階段 cookie 行為        |
| `DEMO_MODE`                      | `false`                 | 啟用後端示範模式限制                                           |
| `SERVICE_NAME`                   | `controller`            | 日誌與遙測使用的服務識別名稱                                   |
| `APP_VERSION`                    | `0.1.0`                 | 回報的應用程式版本；Compose 會將 `NETSTAMP_VERSION` 對應到這裡 |
| `API_VERSION`                    | `v1`                    | 掛載在 `/api/<version>` 下的版本路徑                           |
| `LOG_LEVEL`                      | `info`                  | `debug`、`info`、`warn`、`error`、`dpanic`、`panic` 或 `fatal` |
| `LOG_PSEUDONYM_KEY`              | development placeholder | 將敏感日誌識別資訊去識別化時使用的穩定金鑰                     |
| `SYSTEM_SETTINGS_ENCRYPTION_KEY` | development placeholder | 加密系統管理機密設定時使用的穩定金鑰                           |
| `SHUTDOWN_TIMEOUT`               | `10s`                   | 控制器正常關閉的期限                                           |

所有非本機部署都必須更換這兩個開發用預留金鑰。變更設定加密金鑰可能使已儲存的 SMTP 機密值無法解密。

## HTTP 與公開來源網址

| 變數                       | 預設值  | 用途                                                   |
| -------------------------- | ------- | ------------------------------------------------------ |
| `BACKEND_BASE_URL`         | empty   | 回呼、電子郵件與探測器安裝網址使用的公開控制器來源網址 |
| `PUBLIC_WEB_BASE_URL`      | empty   | 使用者連結使用的公開瀏覽器來源網址                     |
| `HTTP_ADDR`                | `:8080` | 控制器監聽位址                                         |
| `WEB_DIR`                  | empty   | 建置後的前端目錄；正式映像檔設為 `/app/web`            |
| `REQUEST_TIMEOUT`          | `10s`   | 請求內容的逾時時間                                     |
| `HTTP_READ_HEADER_TIMEOUT` | `5s`    | 讀取標頭的逾時時間                                     |
| `HTTP_READ_TIMEOUT`        | `15s`   | 讀取請求的逾時時間                                     |
| `HTTP_WRITE_TIMEOUT`       | `15s`   | 寫入回應的逾時時間                                     |
| `HTTP_IDLE_TIMEOUT`        | `60s`   | keep-alive 連線閒置逾時時間                            |
| `HTTP_TRUSTED_PROXIES`     | empty   | 以逗號分隔的 Proxy IP 位址或 CIDR 前綴                 |

來源網址只能包含 `http` 或 `https` 通訊協定與主機名稱。啟用外部驗證時，`BACKEND_BASE_URL` 不可為空。

## 資料庫

| 變數                    | 預設值      | 用途                                     |
| ----------------------- | ----------- | ---------------------------------------- |
| `DATABASE_HOST`         | `localhost` | PostgreSQL 主機；Compose 使用 `postgres` |
| `DATABASE_PORT`         | `5432`      | PostgreSQL 連接埠                        |
| `DATABASE_USER`         | `netstamp`  | 資料庫使用者                             |
| `DATABASE_PASSWORD`     | `netstamp`  | 資料庫密碼                               |
| `DATABASE_NAME`         | `netstamp`  | 資料庫名稱                               |
| `DATABASE_SSLMODE`      | `disable`   | PostgreSQL SSL 模式                      |
| `DB_MAX_CONNS`          | `10`        | 連線池上限                               |
| `DB_MIN_CONNS`          | `0`         | 連線池最少閒置連線數量                   |
| `DB_MAX_CONN_LIFETIME`  | `1h`        | 連線池中連線的最長存活時間               |
| `DB_MAX_CONN_IDLE_TIME` | `30m`       | 連線池中連線的最長閒置時間               |

資料庫連線若會通過不受信任的網路，請啟用 TLS 驗證。標準 Compose 環境會將資料庫流量留在私有網路內。

## 工作階段、密碼與權杖

| 變數                                    | 預設值                  | 用途                                     |
| --------------------------------------- | ----------------------- | ---------------------------------------- |
| `AUTH_SESSION_HASH_KEY`                 | development placeholder | 不透明工作階段權杖使用的 HMAC/雜湊金鑰   |
| `AUTH_API_TOKEN_HASH_KEY`               | development placeholder | 個人 API 權杖使用的 HMAC/雜湊金鑰        |
| `AUTH_SESSION_IDLE_TTL`                 | `24h`                   | 工作階段閒置期限                         |
| `AUTH_SESSION_ABSOLUTE_TTL`             | `168h`                  | 工作階段最長存活時間                     |
| `AUTH_SESSION_TOUCH_INTERVAL`           | `5m`                    | 兩次寫入工作階段活動狀態的最短間隔       |
| `AUTH_SUDO_TTL`                         | `5m`                    | 敏感操作所需的近期驗證有效時間           |
| `AUTH_REGISTRATION_ENABLED`             | `true`                  | 本機帳號註冊政策的環境變數備援值         |
| `AUTH_EXTERNAL_FLOW_TTL`                | `10m`                   | OAuth/OIDC 驗證流程存活時間              |
| `AUTH_PASSWORD_RESET_TOKEN_TTL`         | `30m`                   | 密碼重設連結有效時間                     |
| `AUTH_PASSWORD_RESET_RATE_LIMIT_WINDOW` | `1h`                    | 密碼重設速率限制的時間範圍               |
| `AUTH_PASSWORD_RESET_IP_LIMIT`          | `10`                    | 時間範圍內每個 IP 可發出的請求數         |
| `AUTH_PASSWORD_RESET_EMAIL_LIMIT`       | `3`                     | 時間範圍內每個電子郵件地址可發出的請求數 |
| `AUTH_ARGON2ID_MEMORY_KIB`              | `65536`                 | Argon2id 記憶體成本                      |
| `AUTH_ARGON2ID_ITERATIONS`              | `3`                     | Argon2id 迭代成本                        |
| `AUTH_ARGON2ID_PARALLELISM`             | `4`                     | Argon2id 平行處理數                      |

系統管理介面中儲存的設定可以覆蓋註冊政策。變更雜湊金鑰會使受該金鑰保護的既有憑證失效。

## 通用 OIDC

| 變數                                 | 預設值           | 用途                                 |
| ------------------------------------ | ---------------- | ------------------------------------ |
| `AUTH_OIDC_ENABLED`                  | `false`          | 啟用通用 OIDC                        |
| `AUTH_OIDC_ISSUER_URL`               | empty            | OIDC 簽發者與探索服務來源網址        |
| `AUTH_OIDC_CLIENT_ID`                | empty            | 用戶端 ID                            |
| `AUTH_OIDC_CLIENT_SECRET`            | empty            | 用戶端密鑰                           |
| `AUTH_OIDC_DISPLAY_NAME`             | `Single sign-on` | 登入按鈕標籤                         |
| `AUTH_OIDC_JIT_PROVISIONING_ENABLED` | `false`          | 為身分有效但尚未存在的使用者建立帳號 |

## Google 驗證

| 變數                                   | 預設值   | 用途                                    |
| -------------------------------------- | -------- | --------------------------------------- |
| `AUTH_GOOGLE_ENABLED`                  | `false`  | 啟用 Google OpenID Connect              |
| `AUTH_GOOGLE_CLIENT_ID`                | empty    | Google 用戶端 ID                        |
| `AUTH_GOOGLE_CLIENT_SECRET`            | empty    | Google 用戶端密鑰                       |
| `AUTH_GOOGLE_DISPLAY_NAME`             | `Google` | 登入按鈕標籤                            |
| `AUTH_GOOGLE_JIT_PROVISIONING_ENABLED` | `false`  | 為接受的 Google 身分建立新使用者        |
| `AUTH_GOOGLE_ALLOWED_HOSTED_DOMAINS`   | empty    | 以逗號分隔的 Workspace 託管網域允許清單 |

## GitHub 驗證

| 變數                                   | 預設值   | 用途                                       |
| -------------------------------------- | -------- | ------------------------------------------ |
| `AUTH_GITHUB_ENABLED`                  | `false`  | 啟用 GitHub OAuth                          |
| `AUTH_GITHUB_CLIENT_ID`                | empty    | GitHub OAuth 用戶端 ID                     |
| `AUTH_GITHUB_CLIENT_SECRET`            | empty    | GitHub OAuth 用戶端密鑰                    |
| `AUTH_GITHUB_DISPLAY_NAME`             | `GitHub` | 登入按鈕標籤                               |
| `AUTH_GITHUB_JIT_PROVISIONING_ENABLED` | `false`  | 為接受的 GitHub 身分建立新使用者           |
| `AUTH_GITHUB_ALLOW_SIGNUP`             | `true`   | 允許透過 GitHub OAuth 流程註冊 GitHub 帳號 |

## 指派、警示與通知背景工作

| 變數                                      | 預設值 | 用途                                             |
| ----------------------------------------- | ------ | ------------------------------------------------ |
| `ASSIGNMENT_REFRESH_WORKER_ENABLED`       | `true` | 重試已排入佇列的指派更新工作                     |
| `ASSIGNMENT_REFRESH_WORKER_INTERVAL`      | `5s`   | 指派更新背景工作的輪詢間隔                       |
| `ASSIGNMENT_REFRESH_WORKER_BATCH_SIZE`    | `25`   | 每次更新週期取得的工作數量                       |
| `ASSIGNMENT_REFRESH_WORKER_STALE_TIMEOUT` | `1m`   | 中斷的更新工作可被重新取得前的逾時時間           |
| `ALERT_EVALUATION_ENABLED`                | `true` | 執行指標門檻警示評估                             |
| `NOTIFICATION_WORKER_ENABLED`             | `true` | 傳送已排入佇列的事件通知                         |
| `NOTIFICATION_WORKER_INTERVAL`            | `5s`   | 通知寄件匣的輪詢間隔                             |
| `NOTIFICATION_WORKER_BATCH_SIZE`          | `25`   | 每次週期取得的通知傳送工作數量                   |
| `NOTIFICATION_WORKER_STALE_TIMEOUT`       | `1m`   | 中斷的傳送工作可被重新取得前的逾時時間           |
| `NOTIFICATION_HTTP_TIMEOUT`               | `10s`  | Webhook、Slack、Discord 與 Telegram 的 HTTP 逾時 |

停用背景工作只會暫停處理，不會刪除設定或已排入佇列的工作。

## SMTP

| 變數            | 預設值     | 用途                                                    |
| --------------- | ---------- | ------------------------------------------------------- |
| `SMTP_HOST`     | empty      | SMTP 主機；主機或寄件者為空時，電子郵件功能視為尚未設定 |
| `SMTP_PORT`     | `587`      | SMTP 連接埠                                             |
| `SMTP_USERNAME` | empty      | 選用的 SMTP AUTH 使用者名稱                             |
| `SMTP_PASSWORD` | empty      | 選用的 SMTP AUTH 密碼                                   |
| `SMTP_FROM`     | empty      | 信封寄件者地址                                          |
| `SMTP_TLS_MODE` | `starttls` | `starttls`、`implicit` 或 `none`                        |
| `SMTP_TIMEOUT`  | `10s`      | 連線與寄送逾時時間                                      |

儲存在系統管理介面中的 SMTP 設定會覆蓋這些環境變數備援值。

## Tracing

| 變數                                 | 預設值 | 用途                        |
| ------------------------------------ | ------ | --------------------------- |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | empty  | 接收 OTLP HTTP trace 的端點 |

程式碼儲存庫提供的可觀測性 Compose 環境會將這個值指向 VictoriaTraces。保留空值即可停用匯出。

## 探測器 agent

Systemd 安裝程式會寫入前三個值，其餘都是本機執行參數的覆寫值。

| 變數                                      | 預設值   | 用途                                              |
| ----------------------------------------- | -------- | ------------------------------------------------- |
| `NETSTAMP_PROBE_CONTROLLER_URL`           | required | 控制器來源網址，不含 `/api/v1`                    |
| `NETSTAMP_PROBE_ID`                       | required | 探測器 UUID                                       |
| `NETSTAMP_PROBE_SECRET`                   | required | 探測器執行階段金鑰                                |
| `NETSTAMP_PROBE_HTTP_TIMEOUT`             | `10s`    | 執行階段 API 請求逾時時間                         |
| `NETSTAMP_PROBE_MAX_WORKERS`              | `128`    | 同時執行的背景工作數量上限                        |
| `NETSTAMP_PROBE_RESULT_QUEUE_SIZE`        | `10000`  | 可暫存的結果數量                                  |
| `NETSTAMP_PROBE_RESULT_BATCH_SIZE`        | `100`    | 單次提交的批次上限                                |
| `NETSTAMP_PROBE_RESULT_FLUSH_INTERVAL`    | `5s`     | 提交未滿批次前的最長等待時間                      |
| `NETSTAMP_PROBE_ASSIGNMENT_TTL`           | `10m`    | 本機指派資料的有效期限                            |
| `NETSTAMP_PROBE_SHUTDOWN_TIMEOUT`         | `10s`    | Agent 正常關閉的期限                              |
| `NETSTAMP_PROBE_HEARTBEAT_INTERVAL`       | `30s`    | 心跳訊號間隔                                      |
| `NETSTAMP_PROBE_ASSIGNMENT_POLL_INTERVAL` | `30s`    | 指派輪詢間隔                                      |
| `NETSTAMP_PROBE_INITIAL_BACKOFF`          | `1s`     | 執行階段重試的初始延遲                            |
| `NETSTAMP_PROBE_MAX_BACKOFF`              | `30s`    | 執行階段重試的最長延遲                            |
| `NETSTAMP_PROBE_MAX_ATTEMPTS`             | `5`      | 目前重試週期判定失敗前的嘗試次數                  |
| `NETSTAMP_PROBE_METRICS_ADDR`             | empty    | 選用的 Prometheus 監聽位址，例如 `127.0.0.1:9091` |
| `NETSTAMP_PROBE_PPROF_ADDR`               | empty    | 選用的 pprof 監聽位址，例如 `127.0.0.1:6060`      |
| `NETSTAMP_PROBE_LOG_LEVEL`                | `info`   | `debug`、`info`、`warn` 或 `error`                |

所有數值容量與時間長度都必須大於零。最大退避時間不得小於初始退避時間。

## Web 應用程式建置變數

這些值會編譯進靜態前端。容器啟動後再變更執行環境，不會修改已建置的程式套件。

| 變數                                            | 預設值                  | 用途                      |
| ----------------------------------------------- | ----------------------- | ------------------------- |
| `VITE_NETSTAMP_API_BASE_URL`                    | `/api/v1`               | 瀏覽器 API 基底網址       |
| `VITE_NETSTAMP_API_PROXY_TARGET`                | `http://localhost:8080` | Vite 開發用反向代理目標   |
| `VITE_NETSTAMP_REGISTRATION_ENABLED`            | `true`                  | 後端政策允許時顯示註冊 UI |
| `VITE_NETSTAMP_PROJECT_CREATION_ENABLED`        | `true`                  | 顯示建立專案 UI           |
| `VITE_NETSTAMP_USER_CREDENTIAL_CHANGES_ENABLED` | `true`                  | 顯示憑證管理介面          |
| `VITE_NETSTAMP_DEMO_MODE`                       | `false`                 | 啟用唯讀示範模式          |
| `VITE_NETSTAMP_DEMO_EMAIL`                      | empty                   | 選用的示範帳號電子郵件    |
| `VITE_NETSTAMP_DEMO_PASSWORD`                   | empty                   | 選用的示範帳號密碼        |

分析服務整合都是選用功能：`VITE_NETSTAMP_GA_MEASUREMENT_ID`、`VITE_NETSTAMP_GOOGLE_TAG_ID`、`VITE_NETSTAMP_CLARITY_PROJECT_ID`、`VITE_NETSTAMP_META_PIXEL_ID` 或其 `FACEBOOK` 別名、`VITE_NETSTAMP_POSTHOG_KEY` 與主機、`VITE_NETSTAMP_PLAUSIBLE_DOMAIN` 與指令碼 URL，以及 `VITE_NETSTAMP_UMAMI_WEBSITE_ID` 與指令碼 URL。

`VITE_NETSTAMP_TRACKING_CONSENT_MODE` 接受 `regional`、`always` 或 `never`；`VITE_NETSTAMP_TRACKING_CONSENT_COUNTRIES` 則是區域適用國家清單。

## 說明文件建置變數

| 變數                           | 預設值                     | 用途                           |
| ------------------------------ | -------------------------- | ------------------------------ |
| `PUBLIC_SITE_URL`              | `https://netstamp.dev`     | 說明文件的標準來源網址         |
| `PUBLIC_NETSTAMP_APP_BASE_URL` | `https://app.netstamp.dev` | 說明文件連往產品應用程式的 URL |

說明文件支援相同的選用追蹤服務與同意控制，但前綴使用 `PUBLIC_NETSTAMP_*`，而不是 `VITE_NETSTAMP_*`。