加速器驗證機制¶

NextPDF 加速器引擎採用分層驗證架構，各層級提供對應的安全機制。Sidecar 模式（Mode A）透過作業系統層級的 Socket 權限實現存取控制；Remote 模式（Mode B）則提供完整的 HTTP 驗證機制。

安全模型概覽¶

flowchart TD
    subgraph ModeA["Mode A — Sidecar（OS 層級）"]
        SOCK["Unix Socket 權限\n(chmod 660, group: www-data)"]
        PROC["程序身份驗證\n(UID / GID 比對)"]
    end

    subgraph ModeB["Mode B — Remote（HTTP 層級）"]
        BEARER["Bearer Token\n(Spectrum Core)"]
        JWT_HS["JWT HS256\n(Prisma Pro)"]
        JWT_RS["JWT RS256 / ES256\n(Prisma Pro+)"]
        MTLS["mTLS 雙向驗證\n(Prisma Enterprise)"]
    end

    subgraph Enterprise["Enterprise HighControl"]
        HC["HighControl 模式\n租戶隔離 + 審計"]
        TENANT["tenant_id 斷言\n(JWT claims)"]
    end

    BEARER --> JWT_HS --> JWT_RS --> MTLS --> HC
    HC --> TENANT

Mode A — Sidecar 安全設定¶

Sidecar 模式依賴作業系統的 Socket 檔案權限，無需 HTTP 層級的 Token 驗證。

# 建立專用群組
sudo groupadd nextpdf-accel
sudo usermod -aG nextpdf-accel www-data

# 設定 Socket 目錄權限
sudo mkdir -p /run/nextpdf
sudo chown root:nextpdf-accel /run/nextpdf
sudo chmod 2750 /run/nextpdf  # SGID bit 確保新建 Socket 繼承群組

# 啟動 Spectrum（以正確 GID 執行）
nextpdf-spectrum serve \
    --socket /run/nextpdf/spectrum.sock \
    --socket-group nextpdf-accel \
    --socket-permissions 0660

安全注意：確保只有受信任的 PHP 程序使用者屬於 nextpdf-accel 群組。勿將此群組設定給不受信任的應用程式。

Bearer Token（Spectrum Core，Remote 模式）¶

Bearer Token 是最簡單的 HTTP 驗證機制，適合同一可信任網路內的服務間通訊。

設定¶

# 產生隨機 Token
SPECTRUM_TOKEN=$(openssl rand -hex 32)

# Spectrum 服務端設定
nextpdf-spectrum serve \
    --auth-token "${SPECTRUM_TOKEN}" \
    --port 8080

# PHP 端環境變數
SPECTRUM_ENDPOINT=http://spectrum.internal:8080
SPECTRUM_AUTH_TOKEN=your-secret-token

PHP 設定¶

use NextPDF\Accelerator\SpectrumConfig;
use NextPDF\Accelerator\Auth\BearerToken;

$config = new SpectrumConfig(
    endpoint: 'http://spectrum.internal:8080',
    auth: new BearerToken(token: $_ENV['SPECTRUM_AUTH_TOKEN']),
);

JWT HS256（Prisma Pro，預設）¶

JWT（JSON Web Token）提供更強的安全保證，支援 Claims 驗證（過期時間、發行者、受眾）。

Token 結構¶

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "iss": "nextpdf-php-client",
  "sub": "app-identifier",
  "aud": "nextpdf-prisma",
  "iat": 1740000000,
  "exp": 1740003600,
  "jti": "550e8400-e29b-41d4-a716-446655440000"
}

PHP 端 JWT 鑄造¶

SpectrumClient 會自動鑄造短效 JWT（預設有效期 1 小時），無需手動管理：

use NextPDF\Accelerator\SpectrumConfig;
use NextPDF\Accelerator\Auth\JwtHmac;

$config = new SpectrumConfig(
    endpoint: 'https://prisma.internal:8080',
    auth: new JwtHmac(
        secret: $_ENV['PRISMA_JWT_SECRET'],
        issuer: 'my-php-app',
        subject: 'app-identifier',
        audience: 'nextpdf-prisma',
        ttlSeconds: 3600,
    ),
);

Prisma 服務端設定¶

# /etc/nextpdf/prisma.toml
[auth]
mode = "jwt_hmac"
jwt_secret = "${PRISMA_JWT_SECRET}"
jwt_audience = "nextpdf-prisma"
jwt_issuer_allowlist = ["my-php-app", "my-worker-app"]
jwt_max_ttl_seconds = 3600

JWT RS256 / ES256（Prisma Pro+）¶

非對稱加密的 JWT 適合多個 PHP 應用程式共享單一 Prisma 服務，且無需在各應用程式之間共享對稱密鑰。

產生金鑰對（ES256 推薦）¶

# 產生 ECDSA P-256 私鑰
openssl ecparam -name prime256v1 -genkey -noout -out prisma-signing.key

# 導出公鑰（提供給 Prisma 服務）
openssl ec -in prisma-signing.key -pubout -out prisma-signing.pub

# 轉換為 PHP 可讀格式（PEM）
cat prisma-signing.key

PHP 設定¶

use NextPDF\Accelerator\Auth\JwtAsymmetric;

$config = new SpectrumConfig(
    endpoint: 'https://prisma.internal:8080',
    auth: new JwtAsymmetric(
        algorithm: JwtAsymmetric::ALG_ES256,
        privateKeyPath: '/secrets/prisma-signing.key',
        keyId: 'key-2026-03',  // 用於金鑰輪換識別
        issuer: 'my-php-app',
        audience: 'nextpdf-prisma',
    ),
);

Prisma 服務端設定（JWKS）¶

[auth]
mode = "jwt_asymmetric"
jwks_uri = "https://my-php-app/.well-known/jwks.json"
# 或直接提供公鑰檔案清單
public_keys = [
    "/etc/nextpdf/keys/prisma-signing.pub"
]

mTLS 雙向憑證驗證（Prisma Enterprise）¶

mTLS（Mutual TLS）要求客戶端與服務端雙方都提供 X.509 憑證，提供最高等級的傳輸層安全性。

憑證需求¶

角色	憑證類型	建議有效期
Prisma 服務（Server）	由內部 CA 簽發的 TLS 憑證	1 年
PHP 客戶端（Client）	由相同 CA 簽發的客戶端憑證	90 天
憑證頒發機構（CA）	根 CA 或中繼 CA	5 年

建立內部 CA（示範用途）¶

# 1. 建立根 CA
openssl req -x509 -newkey rsa:4096 -days 1825 \
    -keyout ca.key -out ca.crt \
    -subj "/CN=NextPDF Internal CA/O=My Company"

# 2. 建立 Prisma 服務憑證
openssl req -newkey rsa:2048 -keyout prisma-server.key \
    -out prisma-server.csr \
    -subj "/CN=prisma.internal/O=My Company"
openssl x509 -req -days 365 -CA ca.crt -CAkey ca.key \
    -in prisma-server.csr -out prisma-server.crt

# 3. 建立 PHP 客戶端憑證
openssl req -newkey rsa:2048 -keyout php-client.key \
    -out php-client.csr \
    -subj "/CN=php-app-01/O=My Company"
openssl x509 -req -days 90 -CA ca.crt -CAkey ca.key \
    -in php-client.csr -out php-client.crt

PHP 設定¶

use NextPDF\Accelerator\Auth\MutualTls;

$config = new SpectrumConfig(
    endpoint: 'https://prisma.internal:8443',
    auth: new MutualTls(
        clientCert: '/secrets/php-client.crt',
        clientKey: '/secrets/php-client.key',
        caCert: '/secrets/ca.crt',
        verifyPeer: true,
    ),
);

Prisma Enterprise 服務端設定¶

[tls]
enabled = true
cert = "/etc/nextpdf/tls/prisma-server.crt"
key = "/etc/nextpdf/tls/prisma-server.key"
ca = "/etc/nextpdf/tls/ca.crt"
client_auth = "require"  # 強制要求客戶端憑證
min_version = "1.3"      # 最低 TLS 1.3

HighControl 模式（Enterprise 多租戶）¶

HighControl 模式在 JWT Claims 層級強制執行租戶隔離，確保每個租戶的資料完全隔離。

JWT 擴充 Claims¶

{
  "iss": "saas-platform",
  "sub": "tenant-abc123",
  "aud": "nextpdf-prisma",
  "iat": 1740000000,
  "exp": 1740003600,
  "jti": "unique-request-id",
  "tenant_id": "tenant-abc123",
  "plan": "enterprise",
  "data_region": "eu-west-1",
  "permissions": ["pdf:read", "pdf:write", "rag:embed"]
}

PHP 設定¶

use NextPDF\Accelerator\Auth\HighControlJwt;

$config = new SpectrumConfig(
    endpoint: 'https://prisma.enterprise:8443',
    auth: new HighControlJwt(
        algorithm: HighControlJwt::ALG_ES256,
        privateKeyPath: '/secrets/signing.key',
        tenantId: $currentTenant->getId(),
        dataRegion: 'eu-west-1',
        permissions: ['pdf:read', 'pdf:write'],
    ),
);

資料隔離保證¶

隔離層級	機制	說明
網路	mTLS	傳輸加密與身份驗證
請求	JWT `tenant_id`	每個請求攜帶租戶斷言
處理	獨立 Worker 池	租戶間的工作程序隔離
儲存	路徑前綴隔離	暫存檔案以 `tenant_id` 分隔
審計	完整請求日誌	所有操作均記錄 `tenant_id`

參見¶

設定參考 — 完整環境變數清單
API 參考 — HTTP 端點與認證標頭格式
SaaS 基礎設施 — 驗證 — 平台層級的 API 驗證慣例

Commercial License

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

Contact Sales