加速器安裝指南¶

本頁說明如何在各種環境中安裝 NextPDF 加速器引擎。請根據您的部署目標選擇對應的安裝方式。

系統需求¶

需求項目	最低版本	建議版本
Linux 核心	5.4	6.1+
glibc（GNU 版本）	2.34	2.38+
musl（Alpine 版本）	1.2.3	1.2.5+
CPU 架構	x86_64 / aarch64	—
記憶體（Sidecar）	256 MB	1 GB+
記憶體（Remote 叢集節點）	2 GB	4 GB+

macOS 支援：僅限開發環境（arm64 Mach-O 二進位），不建議用於生產環境。 Windows 支援：透過 WSL2 或 Docker Desktop，不提供原生 PE32+ 的生產支援。

方法一：Docker 映像（建議）¶

Docker 映像是最簡單且最具可重現性的安裝方式。

Spectrum（Core，LGPL-3.0）¶

# 拉取最新穩定版
docker pull ghcr.io/nextpdf-labs/spectrum:latest

# 以 Sidecar 模式啟動（Unix Socket 掛載至主機）
docker run -d \
    --name nextpdf-spectrum \
    --restart unless-stopped \
    -v /run/nextpdf:/run/nextpdf \
    -e SPECTRUM_MODE=sidecar \
    -e SPECTRUM_WORKERS=4 \
    ghcr.io/nextpdf-labs/spectrum:latest

Prisma Pro（商業授權）¶

# 需先以授權金鑰登入 GHCR
echo "${PRISMA_LICENSE_KEY}" | docker login ghcr.io -u nextpdf-customer --password-stdin

docker pull ghcr.io/nextpdf-labs/prisma-pro:latest

docker run -d \
    --name nextpdf-prisma-pro \
    --restart unless-stopped \
    -p 8080:8080 \
    -e PRISMA_LICENSE_KEY="${PRISMA_LICENSE_KEY}" \
    -e PRISMA_MODE=remote \
    -e PRISMA_WORKERS=8 \
    ghcr.io/nextpdf-labs/prisma-pro:latest

Prisma Enterprise（商業授權）¶

docker pull ghcr.io/nextpdf-labs/prisma-enterprise:latest

docker run -d \
    --name nextpdf-prisma-enterprise \
    --restart unless-stopped \
    -p 8080:8080 \
    -p 9090:9090 \
    -e PRISMA_LICENSE_KEY="${PRISMA_LICENSE_KEY}" \
    -e PRISMA_MODE=remote \
    -e PRISMA_WORKERS=16 \
    -e PRISMA_TENANT_ISOLATION=true \
    ghcr.io/nextpdf-labs/prisma-enterprise:latest

Docker Compose 範例¶

# docker-compose.yml
version: "3.9"

services:
  app:
    image: php:8.5-fpm
    volumes:
      - /run/nextpdf:/run/nextpdf
    environment:
      SPECTRUM_MODE: sidecar
      SPECTRUM_SOCKET: /run/nextpdf/spectrum.sock
    depends_on:
      spectrum:
        condition: service_healthy

  spectrum:
    image: ghcr.io/nextpdf-labs/spectrum:latest
    volumes:
      - /run/nextpdf:/run/nextpdf
    environment:
      SPECTRUM_MODE: sidecar
      SPECTRUM_WORKERS: "4"
    healthcheck:
      test: ["CMD", "nextpdf-spectrum", "health"]
      interval: 10s
      timeout: 5s
      retries: 3

方法二：tarball 安裝（GLIBC 2.34+）¶

適用於無法使用 Docker 的傳統伺服器環境。

Spectrum¶

# 下載最新版本（以 v1.0.0 為例）
SPECTRUM_VERSION="1.0.0"
ARCH="x86_64"  # 或 aarch64

curl -fsSL \
    "https://releases.nextpdf.dev/spectrum/${SPECTRUM_VERSION}/nextpdf-spectrum-${ARCH}-unknown-linux-gnu.tar.gz" \
    -o /tmp/nextpdf-spectrum.tar.gz

# 驗證 SHA-256
curl -fsSL \
    "https://releases.nextpdf.dev/spectrum/${SPECTRUM_VERSION}/nextpdf-spectrum-${ARCH}-unknown-linux-gnu.tar.gz.sha256" \
    -o /tmp/nextpdf-spectrum.tar.gz.sha256

sha256sum --check /tmp/nextpdf-spectrum.tar.gz.sha256

# 解壓縮至系統路徑
sudo tar -xzf /tmp/nextpdf-spectrum.tar.gz -C /usr/local/bin/
sudo chmod +x /usr/local/bin/nextpdf-spectrum

# 驗證安裝
nextpdf-spectrum --version

Prisma Pro / Enterprise¶

# Prisma 下載需要授權金鑰
PRISMA_VERSION="1.0.0"

curl -fsSL \
    -H "Authorization: Bearer ${PRISMA_LICENSE_KEY}" \
    "https://releases.nextpdf.dev/prisma-pro/${PRISMA_VERSION}/nextpdf-prisma-${ARCH}-unknown-linux-gnu.tar.gz" \
    -o /tmp/nextpdf-prisma.tar.gz

sudo tar -xzf /tmp/nextpdf-prisma.tar.gz -C /usr/local/bin/
sudo chmod +x /usr/local/bin/nextpdf-prisma

方法三：musl 靜態連結（Alpine Linux）¶

musl 靜態版本無任何動態函式庫依賴，適用於 Alpine Linux 或需要最小化映像的場景。

# 多階段 Alpine Dockerfile 示範
FROM alpine:3.20 AS spectrum-installer

ARG SPECTRUM_VERSION=1.0.0

RUN apk add --no-cache curl && \
    curl -fsSL \
        "https://releases.nextpdf.dev/spectrum/${SPECTRUM_VERSION}/nextpdf-spectrum-x86_64-unknown-linux-musl.tar.gz" \
        | tar -xz -C /usr/local/bin/ && \
    chmod +x /usr/local/bin/nextpdf-spectrum

FROM php:8.5-fpm-alpine

COPY --from=spectrum-installer /usr/local/bin/nextpdf-spectrum /usr/local/bin/nextpdf-spectrum

ENV SPECTRUM_ENABLED=true \
    SPECTRUM_BIN=/usr/local/bin/nextpdf-spectrum \
    SPECTRUM_MODE=sidecar \
    SPECTRUM_SOCKET=/run/nextpdf/spectrum.sock

# 啟動腳本同時啟動 PHP-FPM 與 Spectrum Sidecar
COPY docker-entrypoint.sh /usr/local/bin/
ENTRYPOINT ["docker-entrypoint.sh"]

#!/bin/sh
# docker-entrypoint.sh
set -e

# 建立 socket 目錄
mkdir -p /run/nextpdf

# 背景啟動 Spectrum
nextpdf-spectrum serve \
    --socket "${SPECTRUM_SOCKET}" \
    --workers "${SPECTRUM_WORKERS:-4}" &

# 等待 Spectrum 就緒
nextpdf-spectrum wait-ready --timeout 10s

# 啟動 PHP-FPM
exec php-fpm

方法四：Kubernetes + Helm¶

前置需求¶

# 添加 NextPDF Helm 儲存庫
helm repo add nextpdf https://charts.nextpdf.dev
helm repo update

# 確認可用版本
helm search repo nextpdf/spectrum
helm search repo nextpdf/prisma-pro
helm search repo nextpdf/prisma-enterprise

安裝 Spectrum（Sidecar 模式注入）¶

Spectrum 在 K8s 中通常透過 Init Container 或 Sidecar Container 注入：

# spectrum-sidecar-values.yaml
spectrum:
  enabled: true
  image:
    repository: ghcr.io/nextpdf-labs/spectrum
    tag: "1.0.0"
  workers: 4
  socket:
    path: /run/nextpdf/spectrum.sock
    volumeMountPath: /run/nextpdf
  resources:
    requests:
      cpu: 500m
      memory: 256Mi
    limits:
      cpu: "2"
      memory: 1Gi

安裝 Prisma Enterprise（獨立部署）¶

# 建立授權 Secret
kubectl create secret generic prisma-license \
    --from-literal=key="${PRISMA_LICENSE_KEY}" \
    -n nextpdf-system

# 安裝 Helm Chart
helm install nextpdf-prisma nextpdf/prisma-enterprise \
    --namespace nextpdf-system \
    --create-namespace \
    --values prisma-enterprise-values.yaml \
    --set license.existingSecret=prisma-license

# prisma-enterprise-values.yaml
replicaCount: 3

image:
  repository: ghcr.io/nextpdf-labs/prisma-enterprise
  tag: "1.0.0"

service:
  type: ClusterIP
  port: 8080

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
  hosts:
    - host: prisma.internal.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: prisma-tls
      hosts:
        - prisma.internal.example.com

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

prisma:
  workers: 8
  tenantIsolation: true
  highControlMode: true

monitoring:
  prometheus:
    enabled: true
    port: 9090

安裝後驗證¶

# Spectrum / Prisma 健康檢查
curl http://localhost:8080/health
# 預期回應：{"status":"ok","version":"1.0.0","mode":"remote"}

# 執行內建冒煙測試
nextpdf-spectrum test --endpoint http://localhost:8080

# PHP 端驗證
composer exec nextpdf:accelerator:check

升級策略¶

# 藍綠升級（Zero-downtime）
# 1. 部署新版本至獨立端口
nextpdf-spectrum serve --port 8081 --version-check

# 2. 等待新版本健康
curl http://localhost:8081/health

# 3. 切換 PHP 設定指向新端口
# 4. 等待所有進行中請求完成
# 5. 停止舊版本

參見¶

架構說明 — Mode A vs Mode B 詳細比較
設定參考 — 所有環境變數與設定項目
驗證機制 — 授權金鑰與 JWT 設定

Commercial License

This feature requires a commercial license. Contact our team for pricing and deployment support.

Contact Sales