跳轉到

加速器設定參考

本頁列出所有可用的環境變數與設定選項。Spectrum（Core）使用 SPECTRUM_* 前綴；Prisma Pro / Enterprise 使用 PRISMA_* 前綴。

設定層次

設定優先順序（由高至低）：

  1. PHP 程式碼設定（SpectrumConfig 物件）
  2. 環境變數（SPECTRUM_* / PRISMA_*）
  3. 設定檔（nextpdf-spectrum.toml）
  4. 預設值

Spectrum 環境變數（Core 層級）

基本設定

環境變數 類型 預設值 說明
SPECTRUM_ENABLED bool false 啟用 Spectrum 加速器
SPECTRUM_BIN string 自動偵測 Spectrum 二進位檔路徑
SPECTRUM_MODE enum sidecar 部署模式：sidecar | remote
SPECTRUM_VERSION string — 強制指定版本（格式：1.0.0）
SPECTRUM_LOG_LEVEL enum warn 日誌等級：error | warn | info | debug | trace

Sidecar 模式（Mode A）

環境變數 類型 預設值 說明
SPECTRUM_SOCKET string /run/nextpdf/spectrum.sock Unix Domain Socket 路徑
SPECTRUM_WORKERS int CPU 核心數 Worker 執行緒數量
SPECTRUM_MAX_QUEUE_DEPTH int 1000 最大等待佇列深度
SPECTRUM_SOCKET_PERMISSIONS octal 0660 Socket 檔案權限
SPECTRUM_SOCKET_GROUP string www-data Socket 檔案群組

遠端模式（Mode B）

環境變數 類型 預設值 說明
SPECTRUM_ENDPOINT string — Spectrum/Prisma 服務端點 URL
SPECTRUM_TIMEOUT_MS int 5000 請求逾時（毫秒）
SPECTRUM_CONNECT_TIMEOUT_MS int 1000 連線逾時（毫秒）
SPECTRUM_MAX_RETRIES int 2 最大重試次數（幂等操作）
SPECTRUM_RETRY_DELAY_MS int 100 重試間隔（毫秒，指數退避基數）

電路斷路器

環境變數 類型 預設值 說明
SPECTRUM_CB_THRESHOLD int 3 觸發斷路所需連續失敗次數
SPECTRUM_CB_COOLDOWN_SEC int 30 斷路冷卻時間（秒）
SPECTRUM_CB_HALF_OPEN_TIMEOUT_SEC int 5 半開探測請求逾時（秒）

功能開關

環境變數 類型 預設值 說明
SPECTRUM_FONT_SUBSETTING bool true 啟用字型子集化加速
SPECTRUM_IMAGE_COMPRESSION bool true 啟用影像壓縮加速
SPECTRUM_PDF_PARSING bool true 啟用 PDF 解析加速
SPECTRUM_LINEARIZATION bool false 啟用線性化加速（需更多記憶體）

Prisma 環境變數（Pro / Enterprise 層級）

授權

環境變數 類型 預設值 說明
PRISMA_LICENSE_KEY string — 必填。商業授權金鑰
PRISMA_LICENSE_ENDPOINT string https://license.nextpdf.dev 授權驗證端點
PRISMA_LICENSE_CACHE_TTL_SEC int 3600 授權快取 TTL（秒）

批次處理（Pro+）

環境變數 類型 預設值 說明
PRISMA_BATCH_MAX_CONCURRENCY int 16 批次最大並行數
PRISMA_BATCH_QUEUE_SIZE int 5000 批次佇列大小
PRISMA_BATCH_TIMEOUT_MS int 30000 單一批次任務逾時（毫秒）
PRISMA_PRIORITY_QUEUE bool true 啟用優先權佇列

Enterprise 專屬

環境變數 類型 預設值 說明
PRISMA_TENANT_ISOLATION bool false 啟用租戶隔離
PRISMA_HIGH_CONTROL_MODE bool false 啟用 HighControl 模式
PRISMA_CLUSTER_NODES string — 叢集節點清單（逗號分隔 URL）
PRISMA_CLUSTER_STRATEGY enum consistent-hash 路由策略：round-robin | consistent-hash | least-conn
PRISMA_HSM_ENABLED bool false 啟用 HSM PKCS#11 整合
PRISMA_HSM_PKCS11_LIB string — PKCS#11 函式庫路徑（如 /usr/lib/softhsm/libsofthsm2.so）
PRISMA_HSM_SLOT_ID int 0 HSM 槽位 ID
PRISMA_EMBED_BACKEND enum built-in 嵌入後端：built-in | openai | ollama | custom
PRISMA_EMBED_ENDPOINT string — 自訂嵌入 API 端點
PRISMA_EMBED_MODEL string nextpdf-embed-v1 嵌入模型名稱
PRISMA_VECTOR_EXPORT enum — 向量匯出目標：pinecone | qdrant | pgvector

可觀測性

環境變數 類型 預設值 說明
PRISMA_METRICS_ENABLED bool true 啟用 Prometheus 指標端點
PRISMA_METRICS_PORT int 9090 Prometheus 指標端口
PRISMA_OTEL_ENABLED bool false 啟用 OpenTelemetry 追蹤
PRISMA_OTEL_ENDPOINT string — OTLP gRPC 端點（如 http://otel-collector:4317）
PRISMA_OTEL_SERVICE_NAME string nextpdf-prisma OTEL 服務名稱

PHP 設定物件

環境變數的替代方案：透過 SpectrumConfig 在 PHP 程式碼中設定。

<?php

declare(strict_types=1);

use NextPDF\Accelerator\SpectrumConfig;
use NextPDF\Accelerator\SpectrumClient;
use NextPDF\Accelerator\CircuitBreakerConfig;
use NextPDF\Accelerator\RetryConfig;

$config = new SpectrumConfig(
    enabled: true,
    mode: SpectrumConfig::MODE_SIDECAR,
    socket: '/run/nextpdf/spectrum.sock',
    workers: 8,
    features: SpectrumConfig::FEATURE_FONT_SUBSETTING
        | SpectrumConfig::FEATURE_IMAGE_COMPRESSION
        | SpectrumConfig::FEATURE_PDF_PARSING,
    circuitBreaker: new CircuitBreakerConfig(
        threshold: 3,
        cooldownSeconds: 30,
        halfOpenTimeoutSeconds: 5,
    ),
    retry: new RetryConfig(
        maxRetries: 2,
        delayMs: 100,
        backoffMultiplier: 2.0,
    ),
    timeoutMs: 5000,
);

$client = new SpectrumClient(config: $config);

設定檔（nextpdf-spectrum.toml）

# /etc/nextpdf/spectrum.toml
[server]
mode = "sidecar"
socket = "/run/nextpdf/spectrum.sock"
workers = 8
max_queue_depth = 1000
log_level = "info"

[features]
font_subsetting = true
image_compression = true
pdf_parsing = true
linearization = false

[circuit_breaker]
threshold = 3
cooldown_seconds = 30
half_open_timeout_seconds = 5

[retry]
max_retries = 2
delay_ms = 100
backoff_multiplier = 2.0

框架整合設定

Laravel

// config/nextpdf.php
return [
    'accelerator' => [
        'enabled' => env('SPECTRUM_ENABLED', false),
        'mode' => env('SPECTRUM_MODE', 'sidecar'),
        'socket' => env('SPECTRUM_SOCKET', '/run/nextpdf/spectrum.sock'),
        'endpoint' => env('SPECTRUM_ENDPOINT'),
        'timeout_ms' => (int) env('SPECTRUM_TIMEOUT_MS', 5000),
        'circuit_breaker' => [
            'threshold' => (int) env('SPECTRUM_CB_THRESHOLD', 3),
            'cooldown_seconds' => (int) env('SPECTRUM_CB_COOLDOWN_SEC', 30),
        ],
    ],
];

Symfony

# config/integrations/nextpdf.yaml
nextpdf:
  accelerator:
    enabled: '%env(bool:SPECTRUM_ENABLED)%'
    mode: '%env(SPECTRUM_MODE)%'
    socket: '%env(SPECTRUM_SOCKET)%'
    timeout_ms: '%env(int:SPECTRUM_TIMEOUT_MS)%'

參見