所有環境變數與命令行參數的完整說明
命令行參數優先於環境變數。所有配置項都支援環境變數和命令行參數兩種方式設定。
基本伺服器配置，包括工具啟用和授權設定。
| 環境變數 | 命令行參數 | 說明 | 預設值 |
|---|---|---|---|
ASPOSE_TOOLS
|
--word/--excel/--pdf/--ppt/--ocr/--email/--barcode/--all
|
啟用的工具類型。可用值：all（全部）、word、excel、powerpoint/ppt、pdf、ocr、email、barcode。多個工具用逗號分隔。 |
all |
ASPOSE_LICENSE_PATH
|
--license path
|
License 檔案路徑。可以是絕對路徑、相對路徑或僅檔案名稱。若未指定，將自動搜尋常見的 License 檔案名稱。 | - |
MCP 傳輸模式配置。
| 環境變數 | 命令行參數 | 說明 | 預設值 |
|---|---|---|---|
ASPOSE_TRANSPORT
|
--stdio/--http/--ws/--websocket
|
傳輸模式。可用值：stdio（標準輸入輸出）、http（HTTP SSE）、ws/websocket（WebSocket）。 |
stdio |
ASPOSE_PORT
|
--port N
|
HTTP/WebSocket 模式的監聽埠號。有效範圍：1-65535。無效值將重設為預設值。 | 3000 |
ASPOSE_HOST
|
--host addr
|
HTTP/WebSocket 模式的監聽位址。可用值：localhost、0.0.0.0、* 或特定 IP 位址。無效值將重設為預設值。 |
localhost |
文件 Session 管理配置。啟用 Session 後可使用 document_session 工具進行多步驟編輯操作。
| 環境變數 | 命令行參數 | 說明 | 預設值 |
|---|---|---|---|
ASPOSE_SESSION_ENABLED
|
--session-enabled/--session-disabled
|
是否啟用 Session 管理功能。 | false |
ASPOSE_SESSION_MAX
|
--session-max N
|
最大同時 Session 數量。最小值：1。 | 10 |
ASPOSE_SESSION_TIMEOUT
|
--session-timeout N
|
Session 閒置超時時間（分鐘）。0 表示永不超時。 | 30 |
ASPOSE_SESSION_MAX_FILE_SIZE_MB
|
--session-max-file-size N
|
Session 模式下的最大檔案大小（MB）。最小值：1。 | 100 |
ASPOSE_SESSION_TEMP_DIR
|
--session-temp-dir path
|
Session 暫存檔案目錄。 | 系統臨時目錄 |
ASPOSE_SESSION_TEMP_RETENTION_HOURS
|
--session-temp-retention-hours N
|
暫存檔保留時間（小時）。超過此時間的檔案將被清理。最小值：1。 | 24 |
ASPOSE_SESSION_ON_DISCONNECT
|
--session-on-disconnect behavior
|
客戶端斷線時的處理方式。可用值：AutoSave（自動儲存）、Discard（丟棄）、SaveToTemp（存到暫存）、PromptOnReconnect（重連時提示）。 |
SaveToTemp |
ASPOSE_SESSION_ISOLATION
|
--session-isolation mode
|
Session 隔離模式。none：無隔離，所有用戶可存取所有 session；group：群組級隔離，同群組內用戶可相互存取 session。 |
group |
ASPOSE_SESSION_AUTO_SAVE_INTERVAL
|
--session-auto-save N
|
自動暫存間隔（分鐘）。大於 0 時，系統會定期將有變更的 Session 暫存到臨時目錄。0 表示停用。 | 0 |
ASPOSE_SESSION_GROUP_ID
|
- | Stdio 模式下的群組識別符。用於 Session 隔離。 | - |
ASPOSE_SESSION_USER_ID
|
- | Stdio 模式下的用戶識別符。用於 Session 隔離。 | - |
HTTP/WebSocket 模式的 Origin 標頭驗證，用於防止 DNS 重綁定攻擊。
| 環境變數 | 命令行參數 | 說明 | 預設值 |
|---|---|---|---|
ASPOSE_ORIGIN_VALIDATION
|
--no-origin-validation
|
是否啟用 Origin 標頭驗證。環境變數設為 false 或使用命令行參數停用。 |
true |
ASPOSE_ALLOW_LOCALHOST
|
--no-localhost
|
是否允許 localhost 來源。適用於開發環境。 | true |
ASPOSE_ALLOW_MISSING_ORIGIN
|
--require-origin
|
是否允許無 Origin 標頭的請求（如 curl、Postman、伺服器對伺服器請求）。 | true |
ASPOSE_ALLOWED_ORIGINS
|
--allowed-origins origins
|
允許的來源域名清單，逗號分隔。例如：https://app1.com,https://app2.com。 |
- |
健康檢查端點 /health 和 /ready 自動排除 Origin 驗證。
API Key 認證配置。支援本地驗證、閘道模式、Introspection 端點和自訂驗證端點。
| 環境變數 | 命令行參數 | 說明 | 預設值 |
|---|---|---|---|
ASPOSE_AUTH_APIKEY_ENABLED
|
--auth-apikey-enabled/--auth-apikey-disabled
|
是否啟用 API Key 認證。 | false |
ASPOSE_AUTH_APIKEY_MODE
|
--auth-apikey-mode mode
|
驗證模式。可用值：local（本地驗證）、gateway（信任閘道）、introspection（遠端 Introspection）、custom（自訂端點）。 |
local |
ASPOSE_AUTH_APIKEY_KEYS
|
--auth-apikey-keys keys
|
API Key 列表（Local 模式必填）。格式：key1:group1,key2:group2。 |
- |
ASPOSE_AUTH_APIKEY_HEADER
|
--auth-apikey-header name
|
API Key 的 HTTP Header 名稱。 | X-API-Key |
ASPOSE_AUTH_APIKEY_GROUP_HEADER
|
--auth-apikey-group-header name
|
群組識別符的 HTTP Header 名稱（Gateway 模式使用）。 | X-Group-Id |
ASPOSE_AUTH_APIKEY_INTROSPECTION_URL
|
--auth-apikey-introspection-url url
|
Introspection 端點 URL（Introspection 模式必填）。 | - |
ASPOSE_AUTH_APIKEY_INTROSPECTION_AUTH
|
--auth-apikey-introspection-auth value
|
Introspection 請求的 Authorization Header 值。 | - |
ASPOSE_AUTH_APIKEY_INTROSPECTION_FIELD
|
--auth-apikey-introspection-field name
|
Introspection 請求中 API Key 的欄位名稱。 | key |
ASPOSE_AUTH_APIKEY_CUSTOM_URL
|
--auth-apikey-custom-url url
|
自訂驗證端點 URL（Custom 模式必填）。 | - |
ASPOSE_AUTH_APIKEY_TIMEOUT
|
--auth-apikey-timeout N
|
外部驗證請求超時時間（秒）。有效範圍：1-300。 | 5 |
ASPOSE_AUTH_APIKEY_CACHE_ENABLED
|
--auth-apikey-cache-enabled/--auth-apikey-cache-disabled
|
是否啟用認證結果快取。 | true |
ASPOSE_AUTH_APIKEY_CACHE_TTL
|
--auth-apikey-cache-ttl N
|
快取存活時間（秒）。 | 300 |
ASPOSE_AUTH_APIKEY_CACHE_MAX_SIZE
|
--auth-apikey-cache-max-size N
|
快取最大項目數。 | 10000 |
{"active": true, "group_id": "..."}
JWT 認證配置。支援本地驗證（HMAC/RSA/ECDSA）、閘道模式、OAuth Introspection 和自訂驗證端點。
| 環境變數 | 命令行參數 | 說明 | 預設值 |
|---|---|---|---|
ASPOSE_AUTH_JWT_ENABLED
|
--auth-jwt-enabled/--auth-jwt-disabled
|
是否啟用 JWT 認證。 | false |
ASPOSE_AUTH_JWT_MODE
|
--auth-jwt-mode mode
|
驗證模式。可用值：local（本地驗證）、gateway（信任閘道）、introspection（OAuth Introspection）、custom（自訂端點）。 |
local |
ASPOSE_AUTH_JWT_SECRET
|
--auth-jwt-secret value
|
HMAC 對稱密鑰（Local 模式，與 PUBLIC_KEY_PATH 二選一）。 | - |
ASPOSE_AUTH_JWT_PUBLIC_KEY_PATH
|
--auth-jwt-public-key-path path
|
RSA/ECDSA 公鑰檔案路徑（Local 模式，與 SECRET 二選一）。 | - |
ASPOSE_AUTH_JWT_ISSUER
|
--auth-jwt-issuer value
|
JWT 發行者（iss claim 驗證）。 | - |
ASPOSE_AUTH_JWT_AUDIENCE
|
--auth-jwt-audience value
|
JWT 受眾（aud claim 驗證）。 | - |
ASPOSE_AUTH_JWT_GROUP_CLAIM
|
--auth-jwt-group-claim name
|
群組識別符的 Claim 名稱（如 tenant_id, team_id, org_id）。 | tenant_id |
ASPOSE_AUTH_JWT_USER_CLAIM
|
--auth-jwt-user-claim name
|
用戶識別符的 Claim 名稱。 | sub |
ASPOSE_AUTH_JWT_GROUP_HEADER
|
--auth-jwt-group-header name
|
群組識別符的 HTTP Header 名稱（Gateway 模式使用）。 | X-Group-Id |
ASPOSE_AUTH_JWT_USER_HEADER
|
--auth-jwt-user-header name
|
用戶識別符的 HTTP Header 名稱（Gateway 模式使用）。 | X-User-Id |
ASPOSE_AUTH_JWT_INTROSPECTION_URL
|
--auth-jwt-introspection-url url
|
OAuth Introspection 端點 URL（Introspection 模式必填）。 | - |
ASPOSE_AUTH_JWT_CLIENT_ID
|
--auth-jwt-client-id value
|
OAuth Client ID（Introspection 模式使用）。 | - |
ASPOSE_AUTH_JWT_CLIENT_SECRET
|
--auth-jwt-client-secret value
|
OAuth Client Secret（Introspection 模式使用）。 | - |
ASPOSE_AUTH_JWT_CUSTOM_URL
|
--auth-jwt-custom-url url
|
自訂驗證端點 URL（Custom 模式必填）。 | - |
ASPOSE_AUTH_JWT_TIMEOUT
|
--auth-jwt-timeout N
|
外部驗證請求超時時間（秒）。有效範圍：1-300。 | 5 |
ASPOSE_AUTH_JWT_CACHE_ENABLED
|
--auth-jwt-cache-enabled/--auth-jwt-cache-disabled
|
是否啟用認證結果快取。 | true |
ASPOSE_AUTH_JWT_CACHE_TTL
|
--auth-jwt-cache-ttl N
|
快取存活時間（秒）。 | 300 |
ASPOSE_AUTH_JWT_CACHE_MAX_SIZE
|
--auth-jwt-cache-max-size N
|
快取最大項目數。 | 10000 |
若同時啟用 API Key 和 JWT 認證，請求必須依序通過兩者驗證才算成功。
日誌、Webhook 和 Metrics 配置。
| 環境變數 | 命令行參數 | 說明 | 預設值 |
|---|---|---|---|
ASPOSE_LOG_ENABLED
|
--log-enabled/--log-disabled
|
是否啟用結構化日誌。 | true |
ASPOSE_LOG_TARGETS
|
--log-targets targets
|
日誌輸出目標，逗號分隔。可用值：Console、EventLog（僅 Windows）。 |
Console |
ASPOSE_WEBHOOK_ENABLED
|
--webhook-enabled/--webhook-disabled
|
是否啟用 Webhook 通知。設定 WEBHOOK_URL 時會自動啟用。 | false |
ASPOSE_WEBHOOK_URL
|
--webhook-url url
|
Webhook 接收端點 URL。 | - |
ASPOSE_WEBHOOK_AUTH_HEADER
|
--webhook-auth-header value
|
Webhook 請求的 Authorization Header 值。 | - |
ASPOSE_WEBHOOK_TIMEOUT
|
--webhook-timeout N
|
Webhook 請求超時時間（秒）。有效範圍：1-300。 | 5 |
ASPOSE_METRICS_ENABLED
|
--metrics-enabled/--metrics-disabled
|
是否啟用 Prometheus Metrics 端點。 | false |
ASPOSE_METRICS_PATH
|
--metrics-path path
|
Metrics 端點路徑。 | /metrics |
擴充功能系統配置。擴充功能系統需要同時啟用 Session 功能。
這些設定適用於整個擴充功能系統，無法由個別擴展覆寫。
| 環境變數 | 命令行參數 | 說明 | 預設值 |
|---|---|---|---|
ASPOSE_EXTENSION_ENABLED
|
--extension-enabled/--extension-disabled
|
是否啟用擴充功能系統。需要同時啟用 Session。 | false |
ASPOSE_EXTENSION_CONFIG
|
--extension-config path
|
擴展配置檔案路徑（extensions.json）。 | - |
ASPOSE_EXTENSION_TEMP_DIR
|
--extension-temp-dir path
|
快照檔案暫存目錄。 | 系統臨時目錄 |
ASPOSE_EXTENSION_TRANSPORT_MODE
|
--extension-transport-mode mode
|
預設傳輸模式。可用值：stdin（標準輸入）、mmap（記憶體映射）、file（臨時檔案）。 |
stdin |
ASPOSE_EXTENSION_HEALTH_INTERVAL
|
--extension-health-interval N
|
健康檢查間隔（秒）。有效範圍：1-3600。 | 30 |
ASPOSE_EXTENSION_MAX_RESTARTS
|
--extension-max-restarts N
|
擴展崩潰時的最大重啟次數。有效範圍：0-100。 | 3 |
ASPOSE_EXTENSION_RESTART_COOLDOWN
|
- | 重啟嘗試之間的冷卻時間（秒）。 | 5 |
ASPOSE_EXTENSION_GRACEFUL_SHUTDOWN_TIMEOUT
|
--extension-graceful-shutdown-timeout N
|
優雅關閉超時時間（秒）。 | 5 |
ASPOSE_EXTENSION_MAX_SNAPSHOT_SIZE
|
--extension-max-snapshot-size N
|
最大快照大小（位元組）。超過此大小的快照將被拒絕。有效範圍：1MB-1GB。 | 104857600 (100MB) |
ASPOSE_EXTENSION_MIN_FREE_DISK_SPACE
|
--extension-min-free-disk-space N
|
寫入快照前所需的最小可用磁碟空間（位元組）。 | 524288000 (500MB) |
這些設定定義了預設值和允許範圍，個別擴展可在 extensions.json 中覆寫（需在 Floor-Ceiling 範圍內）。
| 環境變數 | 命令行參數 | 說明 | 預設值 |
|---|---|---|---|
ASPOSE_EXTENSION_FRAME_INTERVAL_DEFAULT
|
--extension-frame-interval N
|
快照傳輸間隔預設值（毫秒）。 | 100 |
ASPOSE_EXTENSION_FRAME_INTERVAL_FLOOR
|
--extension-frame-interval-floor N
|
快照傳輸間隔下限（毫秒）。 | 10 |
ASPOSE_EXTENSION_FRAME_INTERVAL_CEILING
|
--extension-frame-interval-ceiling N
|
快照傳輸間隔上限（毫秒）。 | 5000 |
ASPOSE_EXTENSION_SNAPSHOT_TTL_DEFAULT
|
--extension-snapshot-ttl N
|
未確認快照的 TTL 預設值（秒）。 | 30 |
ASPOSE_EXTENSION_SNAPSHOT_TTL_FLOOR
|
--extension-snapshot-ttl-floor N
|
未確認快照的 TTL 下限（秒）。 | 5 |
ASPOSE_EXTENSION_SNAPSHOT_TTL_CEILING
|
--extension-snapshot-ttl-ceiling N
|
未確認快照的 TTL 上限（秒）。 | 300 |
ASPOSE_EXTENSION_MAX_MISSED_HEARTBEATS_DEFAULT
|
--extension-max-missed-heartbeats N
|
最大連續心跳失敗次數預設值。 | 3 |
ASPOSE_EXTENSION_MAX_MISSED_HEARTBEATS_FLOOR
|
--extension-max-missed-heartbeats-floor N
|
最大連續心跳失敗次數下限。 | 1 |
ASPOSE_EXTENSION_MAX_MISSED_HEARTBEATS_CEILING
|
--extension-max-missed-heartbeats-ceiling N
|
最大連續心跳失敗次數上限。 | 20 |
ASPOSE_EXTENSION_DEBOUNCE_DELAY_DEFAULT
|
--extension-debounce-delay N
|
Session 修改事件防抖延遲預設值（毫秒）。 | 100 |
ASPOSE_EXTENSION_DEBOUNCE_DELAY_FLOOR
|
--extension-debounce-delay-floor N
|
Session 修改事件防抖延遲下限（毫秒）。 | 0 |
ASPOSE_EXTENSION_DEBOUNCE_DELAY_CEILING
|
--extension-debounce-delay-ceiling N
|
Session 修改事件防抖延遲上限（毫秒）。 | 1000 |
ASPOSE_EXTENSION_IDLE_TIMEOUT_DEFAULT
|
--extension-idle-timeout N
|
閒置超時預設值（分鐘）。0 表示永不卸載。 | 30 |
ASPOSE_EXTENSION_IDLE_TIMEOUT_FLOOR
|
--extension-idle-timeout-floor N
|
閒置超時下限（分鐘）。 | 1 |
ASPOSE_EXTENSION_IDLE_TIMEOUT_CEILING
|
--extension-idle-timeout-ceiling N
|
閒置超時上限（分鐘）。 | 1440 (24小時) |
ASPOSE_EXTENSION_IDLE_TIMEOUT_SPECIAL_ALLOWED
|
--extension-idle-timeout-special-allowed/--extension-idle-timeout-special-disallowed
|
是否允許擴展使用特殊值 0（永不卸載）。 | true |
擴充功能開發詳情請參考 擴充功能開發指南。