🚀 部署指南

Docker、Kubernetes、IIS 部署範例

🐳 Docker 部署

使用 Docker 快速部署 Aspose MCP Server。

docker-compose.yml

version: '3.8'

services:
  aspose-mcp:
    image: ghcr.io/xjustloveux/aspose-mcp-server:latest
    container_name: aspose-mcp-server
    ports:
      - "3000:3000"
    environment:
      # === Transport Settings ===
      - ASPOSE_TRANSPORT=sse              # stdio, sse, ws
      - ASPOSE_PORT=3000
      - ASPOSE_HOST=0.0.0.0

      # === Tools (Required) ===
      - ASPOSE_TOOLS=all                  # all, or comma-separated: word,excel,pdf,ppt

      # === License (Optional) ===
      # - ASPOSE_LICENSE_PATH=/app/license/Aspose.Total.lic

      # === Session Settings (Optional) ===
      # - ASPOSE_SESSION_ENABLED=true       # Enable session management (required for document_session tool)
      # - ASPOSE_SESSION_MAX=10             # Max concurrent sessions (default: 10)
      # - ASPOSE_SESSION_TIMEOUT=30         # Session timeout in minutes (default: 30)
      # - ASPOSE_SESSION_MAX_FILE_SIZE_MB=100  # Max file size in MB (default: 100)
      # - ASPOSE_SESSION_TEMP_DIR=/tmp      # Temp directory (default: system temp)
      # - ASPOSE_SESSION_TEMP_RETENTION_HOURS=24  # Temp file retention in hours (default: 24)
      # - ASPOSE_SESSION_ON_DISCONNECT=SaveToTemp  # Disconnect behavior: SaveToTemp, Discard, KeepInMemory
      # - ASPOSE_SESSION_ISOLATION=user     # Isolation mode: none (no isolation), tenant (tenant-level), user (user-level, default)

      # === API Key Authentication (Optional) ===
      # - ASPOSE_AUTH_APIKEY_ENABLED=true
      # - ASPOSE_AUTH_APIKEY_MODE=local    # local, gateway, introspection, custom
      # - ASPOSE_AUTH_APIKEY_KEYS=key1:tenant1,key2:tenant2
      # - ASPOSE_AUTH_APIKEY_HEADER=X-API-Key
      # - ASPOSE_AUTH_APIKEY_TENANT_HEADER=X-Tenant-Id
      # - ASPOSE_AUTH_APIKEY_INTROSPECTION_URL=https://auth.example.com/introspect
      # - ASPOSE_AUTH_APIKEY_INTROSPECTION_AUTH=Bearer token
      # - ASPOSE_AUTH_APIKEY_CUSTOM_URL=https://auth.example.com/validate
      # - ASPOSE_AUTH_APIKEY_CUSTOM_TIMEOUT=5

      # === JWT Authentication (Optional) ===
      # - ASPOSE_AUTH_JWT_ENABLED=true
      # - ASPOSE_AUTH_JWT_MODE=local       # local, gateway, introspection, custom
      # - ASPOSE_AUTH_JWT_SECRET=your-secret-key
      # - ASPOSE_AUTH_JWT_PUBLIC_KEY_PATH=/app/keys/public.pem
      # - ASPOSE_AUTH_JWT_ISSUER=your-issuer
      # - ASPOSE_AUTH_JWT_AUDIENCE=your-audience
      # - ASPOSE_AUTH_JWT_TENANT_CLAIM=tenant_id
      # - ASPOSE_AUTH_JWT_TENANT_HEADER=X-Tenant-Id
      # - ASPOSE_AUTH_JWT_USER_HEADER=X-User-Id
      # - ASPOSE_AUTH_JWT_INTROSPECTION_URL=https://auth.example.com/introspect
      # - ASPOSE_AUTH_JWT_CLIENT_ID=your-client-id
      # - ASPOSE_AUTH_JWT_CLIENT_SECRET=your-client-secret
      # - ASPOSE_AUTH_JWT_CUSTOM_URL=https://auth.example.com/validate
      # - ASPOSE_AUTH_JWT_CUSTOM_TIMEOUT=5

      # === Logging (Optional) ===
      # - ASPOSE_LOG_ENABLED=true
      # - ASPOSE_LOG_TARGETS=Console       # Console, EventLog (Windows only)

      # === Webhook (Optional) ===
      # - ASPOSE_WEBHOOK_URL=https://your-webhook.example.com/events
      # - ASPOSE_WEBHOOK_AUTH_HEADER=Bearer your-token

      # === Prometheus Metrics (Optional) ===
      # - ASPOSE_METRICS_ENABLED=true
      # - ASPOSE_METRICS_PATH=/metrics

    # === Volumes (Optional) ===
    # volumes:
    #   - ./license:/app/license:ro
    #   - ./documents:/app/documents

    # === Restart Policy (Optional) ===
    # restart: unless-stopped

    # === Health Check (Optional) ===
    # healthcheck:
    #   test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
    #   interval: 30s
    #   timeout: 3s
    #   retries: 3

啟動服務

# 啟動
docker-compose up -d

# 查看日誌
docker-compose logs -f

# 停止
docker-compose down

☸️ Kubernetes 部署

使用 Kubernetes 部署 Aspose MCP Server。複製以下 YAML 並根據需求修改。

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aspose-mcp-server
  labels:
    app: aspose-mcp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aspose-mcp
  template:
    metadata:
      labels:
        app: aspose-mcp
    spec:
      containers:
        - name: aspose-mcp
          image: ghcr.io/xjustloveux/aspose-mcp-server:latest
          ports:
            - containerPort: 3000
          env:
            # === Transport Settings ===
            - name: ASPOSE_TRANSPORT
              value: "sse"                # stdio, sse, ws
            - name: ASPOSE_PORT
              value: "3000"
            - name: ASPOSE_HOST
              value: "0.0.0.0"

            # === Tools (Required) ===
            - name: ASPOSE_TOOLS
              value: "all"                # all, or comma-separated: word,excel,pdf,ppt

            # === License (Optional) ===
            # - name: ASPOSE_LICENSE_PATH
            #   value: "/app/license/Aspose.Total.lic"

            # === Session Settings (Optional) ===
            # - name: ASPOSE_SESSION_ENABLED
            #   value: "true"               # Enable session management (required for document_session tool)
            # - name: ASPOSE_SESSION_MAX
            #   value: "10"                 # Max concurrent sessions (default: 10)
            # - name: ASPOSE_SESSION_TIMEOUT
            #   value: "30"                 # Session timeout in minutes (default: 30)
            # - name: ASPOSE_SESSION_MAX_FILE_SIZE_MB
            #   value: "100"                # Max file size in MB (default: 100)
            # - name: ASPOSE_SESSION_TEMP_DIR
            #   value: "/tmp"               # Temp directory (default: system temp)
            # - name: ASPOSE_SESSION_TEMP_RETENTION_HOURS
            #   value: "24"                 # Temp file retention in hours (default: 24)
            # - name: ASPOSE_SESSION_ON_DISCONNECT
            #   value: "SaveToTemp"         # Disconnect behavior: SaveToTemp, Discard, KeepInMemory
            # - name: ASPOSE_SESSION_ISOLATION
            #   value: "user"               # Isolation mode: none (no isolation), tenant (tenant-level), user (user-level, default)

            # === API Key Authentication (Optional) ===
            # - name: ASPOSE_AUTH_APIKEY_ENABLED
            #   value: "true"
            # - name: ASPOSE_AUTH_APIKEY_MODE
            #   value: "local"            # local, gateway, introspection, custom
            # - name: ASPOSE_AUTH_APIKEY_KEYS
            #   value: "key1:tenant1,key2:tenant2"
            # - name: ASPOSE_AUTH_APIKEY_HEADER
            #   value: "X-API-Key"
            # - name: ASPOSE_AUTH_APIKEY_TENANT_HEADER
            #   value: "X-Tenant-Id"
            # - name: ASPOSE_AUTH_APIKEY_INTROSPECTION_URL
            #   value: "https://auth.example.com/introspect"
            # - name: ASPOSE_AUTH_APIKEY_INTROSPECTION_AUTH
            #   value: "Bearer token"
            # - name: ASPOSE_AUTH_APIKEY_CUSTOM_URL
            #   value: "https://auth.example.com/validate"
            # - name: ASPOSE_AUTH_APIKEY_CUSTOM_TIMEOUT
            #   value: "5"

            # === JWT Authentication (Optional) ===
            # - name: ASPOSE_AUTH_JWT_ENABLED
            #   value: "true"
            # - name: ASPOSE_AUTH_JWT_MODE
            #   value: "local"            # local, gateway, introspection, custom
            # - name: ASPOSE_AUTH_JWT_SECRET
            #   value: "your-secret-key"
            # - name: ASPOSE_AUTH_JWT_PUBLIC_KEY_PATH
            #   value: "/app/keys/public.pem"
            # - name: ASPOSE_AUTH_JWT_ISSUER
            #   value: "your-issuer"
            # - name: ASPOSE_AUTH_JWT_AUDIENCE
            #   value: "your-audience"
            # - name: ASPOSE_AUTH_JWT_TENANT_CLAIM
            #   value: "tenant_id"
            # - name: ASPOSE_AUTH_JWT_TENANT_HEADER
            #   value: "X-Tenant-Id"
            # - name: ASPOSE_AUTH_JWT_USER_HEADER
            #   value: "X-User-Id"
            # - name: ASPOSE_AUTH_JWT_INTROSPECTION_URL
            #   value: "https://auth.example.com/introspect"
            # - name: ASPOSE_AUTH_JWT_CLIENT_ID
            #   value: "your-client-id"
            # - name: ASPOSE_AUTH_JWT_CLIENT_SECRET
            #   value: "your-client-secret"
            # - name: ASPOSE_AUTH_JWT_CUSTOM_URL
            #   value: "https://auth.example.com/validate"
            # - name: ASPOSE_AUTH_JWT_CUSTOM_TIMEOUT
            #   value: "5"

            # === Logging (Optional) ===
            # - name: ASPOSE_LOG_ENABLED
            #   value: "true"
            # - name: ASPOSE_LOG_TARGETS
            #   value: "Console"          # Console, EventLog (Windows only)

            # === Webhook (Optional) ===
            # - name: ASPOSE_WEBHOOK_URL
            #   value: "https://your-webhook.example.com/events"
            # - name: ASPOSE_WEBHOOK_AUTH_HEADER
            #   value: "Bearer your-token"

            # === Prometheus Metrics (Optional) ===
            # - name: ASPOSE_METRICS_ENABLED
            #   value: "true"
            # - name: ASPOSE_METRICS_PATH
            #   value: "/metrics"

          # === Volume Mounts (Optional) ===
          # volumeMounts:
          #   - name: license
          #     mountPath: /app/license
          #     readOnly: true

          # === Resources (Optional) ===
          # resources:
          #   requests:
          #     memory: "256Mi"
          #     cpu: "250m"
          #   limits:
          #     memory: "1Gi"
          #     cpu: "1000m"

          # === Liveness Probe (Optional) ===
          # livenessProbe:
          #   httpGet:
          #     path: /health
          #     port: 3000
          #   initialDelaySeconds: 10
          #   periodSeconds: 30

          # === Readiness Probe (Optional) ===
          # readinessProbe:
          #   httpGet:
          #     path: /ready
          #     port: 3000
          #   initialDelaySeconds: 5
          #   periodSeconds: 10

      # === Volumes (Optional) ===
      # volumes:
      #   - name: license
      #     secret:
      #       secretName: aspose-license
      #       optional: true

常用命令

# 建立 License Secret
kubectl create secret generic aspose-license \
  --from-file=Aspose.Total.lic=/path/to/license

# 部署
kubectl apply -f deployment.yaml

# 暴露服務
kubectl expose deployment aspose-mcp-server --port=80 --target-port=3000

# 查看狀態
kubectl get pods -l app=aspose-mcp

🖥️ IIS 部署

在 Windows Server 的 IIS 上部署 Aspose MCP Server。

前置需求

部署步驟

  1. 從 Release 下載 aspose-mcp-server-iis.zip
  2. 解壓縮到 IIS 站台目錄（例如：C:\inetpub\AsposeMcpServer）
  3. 在 IIS 建立新站台，指向該目錄
  4. 設定 Application Pool 為「No Managed Code」
  5. 放置 License 檔案並修改 web.config 中的路徑

web.config 範例

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*"
             modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>

      <aspNetCore processPath="dotnet"
                  arguments=".\AsposeMcpServer.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="InProcess">
        <environmentVariables>
          <!-- Transport Settings (Required) -->
          <environmentVariable name="ASPOSE_TRANSPORT" value="sse" />
          <environmentVariable name="ASPOSE_PORT" value="3000" />

          <!-- Tools (Required) -->
          <environmentVariable name="ASPOSE_TOOLS" value="all" />

          <!-- License Path (Optional) -->
          <!-- <environmentVariable name="ASPOSE_LICENSE_PATH" value=".\Aspose.Total.lic" /> -->

          <!-- Session Settings (Optional) -->
          <!-- <environmentVariable name="ASPOSE_SESSION_ENABLED" value="true" /> -->
          <!-- <environmentVariable name="ASPOSE_SESSION_MAX" value="10" /> -->
          <!-- <environmentVariable name="ASPOSE_SESSION_TIMEOUT" value="30" /> -->
          <!-- <environmentVariable name="ASPOSE_SESSION_TEMP_RETENTION_HOURS" value="24" /> -->
          <!-- <environmentVariable name="ASPOSE_SESSION_ISOLATION" value="user" /> --> <!-- none, tenant, user (default) -->
        </environmentVariables>
      </aspNetCore>

      <!-- WebSocket Support (Optional, for WebSocket transport mode) -->
      <!-- <webSocket enabled="true" /> -->
    </system.webServer>
  </location>
</configuration>
注意： IIS 部署時，建議啟用 HTTPS 並設定適當的安全標頭。

⚙️ 環境變數

所有部署方式都支援以下環境變數（也可使用對應的命令行參數）：

基本設定

環境變數 命令行參數 說明 預設值
ASPOSE_TRANSPORT --stdio/--sse/--ws/--websocket 傳輸模式 stdio
ASPOSE_PORT --port:N 監聽埠號（1-65535，無效值重設為 3000） 3000
ASPOSE_HOST --host:addr 監聽位址（localhost/0.0.0.0/*/特定IP，無效值重設為 localhost） localhost
ASPOSE_TOOLS --word/--excel/--pdf/--ppt/--all 啟用的工具 all
ASPOSE_LICENSE_PATH --license:path License 檔案路徑 -
🔧 工具過濾機制

MCP 工具列表會根據 ASPOSE_TOOLS 設定動態調整。例如設定 word 時，只會顯示 Word 相關工具，不會出現 Excel、PDF 等其他工具。

Session 設定

環境變數 命令行參數 說明 預設值
ASPOSE_SESSION_ENABLED --session-enabled 啟用 Session 管理 false
ASPOSE_SESSION_MAX --session-max:N 最大 Session 數 10
ASPOSE_SESSION_TIMEOUT --session-timeout:N Session 逾時（分鐘） 30
ASPOSE_SESSION_MAX_FILE_SIZE_MB --session-max-file-size:N 最大檔案大小（MB） 100
ASPOSE_SESSION_TEMP_DIR --session-temp-dir:path 臨時目錄 系統臨時目錄
ASPOSE_SESSION_TEMP_RETENTION_HOURS --session-temp-retention-hours:N 暫存檔保留時間（小時） 24
ASPOSE_SESSION_ON_DISCONNECT --session-on-disconnect:behavior 斷線行為 SaveToTemp
ASPOSE_SESSION_ISOLATION --session-isolation:mode Session 隔離模式（none/tenant/user） user
Session 隔離模式說明：
  • none - 無隔離，所有用戶可存取所有 session（Stdio 模式向後兼容）
  • tenant - 租戶級隔離，同租戶內的用戶可相互存取 session
  • user - 用戶級隔離，用戶只能存取自己的 session（預設）

認證設定

同時啟用多種認證： 若同時啟用 API Key 和 JWT 認證，請求必須依序通過兩者驗證才算成功。 適用於 API Key 識別應用程式、JWT 識別使用者的情境。大多數情況只需啟用其中一種即可。
環境變數 命令行參數 說明 預設值
ASPOSE_AUTH_APIKEY_ENABLED --auth-apikey-enabled 啟用 API Key 認證 false
ASPOSE_AUTH_APIKEY_MODE --auth-apikey-mode:mode API Key 驗證模式 local
ASPOSE_AUTH_APIKEY_KEYS --auth-apikey-keys:keys API Key 列表（key:tenant 格式） -
ASPOSE_AUTH_APIKEY_HEADER --auth-apikey-header:name API Key Header 名稱 X-API-Key
ASPOSE_AUTH_APIKEY_TENANT_HEADER --auth-apikey-tenant-header:name Tenant ID Header（Gateway 模式） X-Tenant-Id
ASPOSE_AUTH_APIKEY_INTROSPECTION_URL --auth-apikey-introspection-url:url Introspection 端點 URL -
ASPOSE_AUTH_APIKEY_INTROSPECTION_AUTH --auth-apikey-introspection-auth:value Introspection 認證 Header -
ASPOSE_AUTH_APIKEY_INTROSPECTION_FIELD --auth-apikey-introspection-field:name Introspection 請求欄位名稱 key
ASPOSE_AUTH_APIKEY_CUSTOM_URL --auth-apikey-custom-url:url Custom 驗證端點 URL -
ASPOSE_AUTH_APIKEY_TIMEOUT --auth-apikey-timeout:N 外部驗證逾時（秒，Introspection/Custom） 5
ASPOSE_AUTH_JWT_ENABLED --auth-jwt-enabled 啟用 JWT 認證 false
ASPOSE_AUTH_JWT_MODE --auth-jwt-mode:mode JWT 驗證模式 local
ASPOSE_AUTH_JWT_SECRET --auth-jwt-secret:value JWT HMAC 密鑰 -
ASPOSE_AUTH_JWT_PUBLIC_KEY_PATH --auth-jwt-public-key-path:path RSA/ECDSA 公鑰檔案路徑 -
ASPOSE_AUTH_JWT_ISSUER --auth-jwt-issuer:value JWT 發行者 -
ASPOSE_AUTH_JWT_AUDIENCE --auth-jwt-audience:value JWT 受眾 -
ASPOSE_AUTH_JWT_TENANT_CLAIM --auth-jwt-tenant-claim:name Tenant ID Claim 名稱 tenant_id
ASPOSE_AUTH_JWT_USER_CLAIM --auth-jwt-user-claim:name User ID Claim 名稱 sub
ASPOSE_AUTH_JWT_TENANT_HEADER --auth-jwt-tenant-header:name Tenant ID Header（Gateway 模式） X-Tenant-Id
ASPOSE_AUTH_JWT_USER_HEADER --auth-jwt-user-header:name User ID Header（Gateway 模式） X-User-Id
ASPOSE_AUTH_JWT_INTROSPECTION_URL --auth-jwt-introspection-url:url OAuth Introspection 端點 URL -
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 Custom 驗證端點 URL -
ASPOSE_AUTH_JWT_TIMEOUT --auth-jwt-timeout:N 外部驗證逾時（秒，Introspection/Custom） 5
Introspection/Custom 端點回應格式：
  • API Key Introspection：{"active": true, "tenant_id": "..."}
  • API Key Custom：{"valid": true, "tenant_id": "..."}
  • JWT Introspection：{"active": true, "tenant_id": "...", "sub": "..."}
  • JWT Custom：{"valid": true, "tenant_id": "...", "user_id": "..."}

追蹤設定

環境變數 命令行參數 說明 預設值
ASPOSE_LOG_ENABLED --log-enabled 啟用日誌 true
ASPOSE_LOG_TARGETS --log-targets:Console,EventLog 日誌目標 Console
ASPOSE_WEBHOOK_URL --webhook-url:url Webhook URL -
ASPOSE_WEBHOOK_AUTH_HEADER --webhook-auth-header:header Webhook 認證標頭值 -
ASPOSE_METRICS_ENABLED --metrics-enabled 啟用 Metrics false
💡 優先順序

命令行參數優先於環境變數。完整參數列表請參考 README。