138 lines
8.3 KiB
Markdown
138 lines
8.3 KiB
Markdown
# Member Center 執行參數
|
||
|
||
所有 .NET configuration key 均可改用環境變數，將 `:` 改為 `__`。例如 `RateLimits:Api:OAuthToken:PermitLimit` 對應 `RateLimits__Api__OAuthToken__PermitLimit`。Production secret 必須由 Secrets Manager / Parameter Store 注入。
|
||
|
||
## 基礎啟動
|
||
|
||
| Key | 預設值 | 說明 |
|
||
|---|---:|---|
|
||
| `ASPNETCORE_ENVIRONMENT` / `DOTNET_ENVIRONMENT` | `Production` | `Development` 才讀 repo root `.env`，並允許開發憑證/本機 DB fallback。 |
|
||
| `ConnectionStrings:Default` | Development: localhost PostgreSQL | API/Web 非 Development 必填。 |
|
||
| `MEMBERCENTER_CONNECTION` | 無 | Installer / design-time DbContext 備用 connection string。 |
|
||
| `PathBase` | 空 | API 子路徑，例如 `/member-center`。 |
|
||
| `AllowedHosts` | Web: `*` | ASP.NET Core host filtering；Production 建議填實際 host。 |
|
||
| `Logging:LogLevel:*` | Default=`Information` | 標準 .NET logging level。 |
|
||
|
||
## Identity
|
||
|
||
| Key | 預設值 | 規則 |
|
||
|---|---:|---|
|
||
| `IdentitySecurity:Password:RequiredLength` | `8` | 不得小於 8。 |
|
||
| `IdentitySecurity:Password:RequireDigit` | `true` | 至少一個數字。 |
|
||
| `IdentitySecurity:Password:RequireLowercase` | `true` | 至少一個小寫字母。 |
|
||
| `IdentitySecurity:Password:RequireUppercase` | `true` | 至少一個大寫字母。 |
|
||
| `IdentitySecurity:Password:RequireNonAlphanumeric` | `false` | 暫不要求特殊字元。 |
|
||
| `IdentitySecurity:Lockout:AllowedForNewUsers` | `true` | 新帳號啟用 lockout。 |
|
||
| `IdentitySecurity:Lockout:MaxFailedAccessAttempts` | `5` | 必須大於 0。 |
|
||
| `IdentitySecurity:Lockout:DefaultLockoutMinutes` | `15` | 必須大於 0。 |
|
||
|
||
API、Web 與 Installer 共用上述規則。
|
||
|
||
## Rate limit
|
||
|
||
每個 prefix 都有 `PermitLimit` 與 `WindowSeconds`，兩者必須大於 0。限制為單 instance 記憶體計數；多 instance Production 仍需 AWS WAF。
|
||
|
||
| Prefix | Permit | 秒 | 適用端點 |
|
||
|---|---:|---:|---|
|
||
| `RateLimits:Web:AuthLogin` | 10 | 300 | Web login |
|
||
| `RateLimits:Web:AuthRegister` | 5 | 900 | Web register |
|
||
| `RateLimits:Web:AuthRecovery` | 5 | 900 | Web forgot/resend |
|
||
| `RateLimits:Web:AuthTokenConsumption` | 10 | 600 | Web reset/verify |
|
||
| `RateLimits:Api:AuthRegister` | 5 | 900 | 保留設定；API register endpoint 目前未開放。 |
|
||
| `RateLimits:Api:AuthRecovery` | 5 | 900 | API forgot/resend |
|
||
| `RateLimits:Api:AuthTokenConsumption` | 10 | 600 | API reset/verify |
|
||
| `RateLimits:Api:NewsletterSubscribe` | 20 | 600 | Newsletter subscribe |
|
||
| `RateLimits:Api:NewsletterUnsubscribeToken` | 10 | 600 | Unsubscribe token issuance |
|
||
| `RateLimits:Api:NewsletterOneClickToken` | 60 | 60 | One-click single/batch |
|
||
| `RateLimits:Api:OAuthToken` | 30 | 60 | `/oauth/token` |
|
||
|
||
## Newsletter / File Access token
|
||
|
||
| Key | 預設值 | 說明 |
|
||
|---|---:|---|
|
||
| `NewsletterTokens:ConfirmTokenLifetimeDays` | `7` | 訂閱確認 token。 |
|
||
| `NewsletterTokens:UnsubscribeTokenLifetimeDays` | `7` | 一般退訂 token。 |
|
||
| `NewsletterTokens:OneClickTokenLifetimeDays` | `7` | One-click token。 |
|
||
| `NewsletterTokens:OneClickBatchSizeLimit` | `1000` | 批次 subscriber id 上限。 |
|
||
| `FileAccessTokens:DefaultLifetimeSeconds` | `300` | Delegated download token 預設時效。 |
|
||
| `FileAccessTokens:MinimumLifetimeSeconds` | `30` | 呼叫端最短可要求時效。 |
|
||
| `FileAccessTokens:MaximumLifetimeSeconds` | `900` | 呼叫端最長可要求時效。 |
|
||
|
||
Newsletter 值皆須大於 0；File Access 必須符合 `0 < minimum <= default <= maximum`。
|
||
|
||
## OAuth / OIDC
|
||
|
||
| Key | 預設值 | 說明 |
|
||
|---|---:|---|
|
||
| `Auth:Issuer` | Development 可空 | Production 必填 HTTPS。 |
|
||
| `Auth:WebLoginUrl` | `/account/login` | Authorize 未登入時的 Web login URL。 |
|
||
| `Auth:AllowedLoginReturnUrlPrefixes` | 空 | 逗號分隔 login allowlist。 |
|
||
| `Auth:AllowInternalHttpTokenEndpoint` | `false` | 允許 VPC 私有 HTTP OAuth endpoint；issuer 仍為 HTTPS。 |
|
||
| `Auth:Resources:MemberCenter:Audience` | `member_center_api` | Member Center audience seed。 |
|
||
| `Auth:Resources:SendEngine:Audience` | `send_engine_api` | Send Engine audience seed。 |
|
||
| `Auth:Resources:FileAccess:Audience` | `file_access_api` | File Access audience seed。 |
|
||
| `Auth:MemberCenterAudience` / `Auth:SendEngineAudience` | 無 | 舊版相容 seed。 |
|
||
|
||
OAuth usage/scope mapping 的正式來源為 DB registry；audience key 只作 seed / 相容來源。
|
||
完整現有 scope catalog 與 usage mapping 請見 `docs/SCOPES.md`。
|
||
Web logout 的外部 `returnUrl` allowlist 由 `usage=web_login` OAuth client 的 `post_logout_redirect_uris` 管理；舊 `Auth:AllowedLogoutReturnUrlPrefixes` 不再使用。
|
||
|
||
## 憑證與 Data Protection
|
||
|
||
| Key | 預設值 | 說明 |
|
||
|---|---:|---|
|
||
| DB `system_flags.certificates:openiddict:signing` | installer 產生 | Production API JWT signing PFX。 |
|
||
| DB `system_flags.certificates:openiddict:encryption` | installer 產生 | Production API OpenIddict encryption PFX。 |
|
||
| DB `system_flags.certificates:data-protection` | installer 產生 | Production API/Web 共用 Data Protection PFX。 |
|
||
| `Auth:Certificates:Signing:Path/Password` | 無 | 選填；覆寫 DB signing PFX。 |
|
||
| `Auth:Certificates:Encryption:Path/Password` | 無 | 選填；覆寫 DB encryption PFX。 |
|
||
| `DataProtection:Certificate:Path/Password` | 無 | 選填；覆寫 DB Data Protection PFX。 |
|
||
| `*:Previous:0:Path/Password` | 無 | 選填；檔案型前代憑證，可增加索引。 |
|
||
| `Certificates:ExpirationWarningDays` | `30` | 到期 warning；有效範圍 1–180。 |
|
||
|
||
## Reverse proxy
|
||
|
||
| Key | 預設值 | 說明 |
|
||
|---|---:|---|
|
||
| `ReverseProxy:TrustForwardedHeaders` | `false` | 設為 `true` 時信任 forwarded headers，不要求 `KnownProxies` / `KnownNetworks`；僅可在 app inbound 已由 Security Group / 私有網路限制為可信 proxy 時使用。 |
|
||
| `ReverseProxy:KnownProxies` | 空 | 逗號分隔可信 proxy IP。 |
|
||
| `ReverseProxy:KnownNetworks` | 空 | 逗號分隔可信 CIDR；禁止 `/0`。 |
|
||
| `ReverseProxy:ForwardLimit` | `1` | Proxy hop；限制 1–5。 |
|
||
|
||
`ReverseProxy:TrustForwardedHeaders=true` 會接受 `X-Forwarded-For`、`X-Forwarded-Proto`、`X-Forwarded-Host`。此模式適合 AWS ALB / managed reverse proxy private IP 會變動，但 app security group 已只允許該 proxy 連入的環境。
|
||
|
||
接受 `X-Forwarded-Host` 是刻意支援 AWS ALB 後方的登入、OAuth callback 與 public URL 產生。Production 必須同時由 ALB / router 覆寫外部 forwarded headers、以 Security Group 阻止繞過 proxy，並將 DB `public_base_url` 設為 canonical HTTPS URL。部署驗證需包含偽造 `Host` / `X-Forwarded-Host` 的 redirect 與 email link 測試。
|
||
|
||
未啟用 `TrustForwardedHeaders` 時，必須設定 `KnownProxies` 或 `KnownNetworks` 才會接受 forwarded headers；allowlist 都為空時完全忽略 forwarded headers。
|
||
|
||
## 外部整合與測試旗標
|
||
|
||
| Key | 預設值 | 說明 |
|
||
|---|---:|---|
|
||
| `Authentication:Google:ClientId/ClientSecret` | 無 | 兩者都有才啟用 Google login。 |
|
||
| `SendEngine:BaseUrl` | 無 | Send Engine base URL。 |
|
||
| `SendEngine:SubscriptionEventsPath` | `/webhooks/subscriptions` | Subscription webhook path。 |
|
||
| `SendEngine:WebhookSecret` | 無 | Webhook HMAC secret。 |
|
||
| `Testing:DisableSubscriptionDryRunNoDb` | `false` | 僅測試使用；Production 必須 false。 |
|
||
|
||
## 後台 DB 設定
|
||
|
||
`/admin/security` 儲存在 `system_flags`：
|
||
|
||
| 設定 | 預設值 / 限制 |
|
||
|---|---|
|
||
| Access token lifetime | 60 分鐘；5–1440。 |
|
||
| Refresh token lifetime | 30 天；1–365。 |
|
||
| Public base URL | 空；Production 應為 HTTPS。 |
|
||
| SMTP relay / port | host 空；port 587。 |
|
||
| SMTP TLS / SSL | TLS=true、SSL=false，不得同時啟用。 |
|
||
| SMTP timeout | 15 秒。 |
|
||
| SMTP username/password | 空；password 加密保存。 |
|
||
| Sender name / email | `Member Center` / 空。 |
|
||
|
||
## TestSite 與 Installer
|
||
|
||
TestSite 使用 `MemberCenter:*`：`ApiBaseUrl`、`WebBaseUrl`、`WebLoginClientId`、`WebLoginRedirectPath`、`WebLogoutRedirectPath`、`WebLoginScopes`、`ServiceClientId`、`ServiceClientSecret`、`ServiceScopes`。Secret 不得寫入 `appsettings.json`。
|
||
|
||
Installer 共通參數：`--connection-string/-c`、`--appsettings`、`--no-prompt`、`--verbose`；另有 `--force`、`--admin-email`、`--admin-password`、`--admin-display-name`、`--target`。完整命令以 `dotnet run --project src/MemberCenter.Installer -- --help` 為準。
|