Skip to main content

Vylux

Vylux 是一個獨立運行的媒體處理服務，將圖片即時轉換與非同步媒體處理拆成可單獨部署的基礎能力。它不承載你的業務模型，只負責接收來源物件、驗證資訊與處理參數，輸出可快取、可追蹤、可播放的媒體資產。

目前的核心能力包括：

  • 即時圖片轉換：/img 依 URL 參數即時 resize、轉檔與快取
  • 原檔與縮圖代理：/original、/thumb
  • 以 domain-specific route 建立非同步工作：/api/audio/jobs 與 /api/video/jobs
  • 第一級音訊輸出：audio-only HLS、MP3、FLAC 與 waveform
  • HLS CMAF：AV1 + H.264 ladder、fMP4 segment、Shaka Packager 打包
  • 加密播放：CBCS / SAMPLE-AES、/api/key/{id} Bearer token 金鑰發放
  • 維運能力：PostgreSQL job state、Redis queue、Prometheus metrics、OpenTelemetry tracing
先選符合你當前工作的閱讀路徑

很多誤解其實不是 API 規則錯，而是還沒先決定部署形態或 trust boundary 就開始讀細節頁。先選下面最符合你當前任務的閱讀路徑，會快很多。

服務形態​

all​

  • 同時啟動 HTTP server 與 worker
  • 適合本機開發、staging 與較小型的單節點部署

server​

  • 只啟動 HTTP server、圖片投遞、播放路由與主要 metrics surface
  • 適合搭配獨立 worker，一起達成較乾淨的擴展與故障隔離

worker​

  • 只處理 queue 任務與 worker metrics listener
  • 適合讓 FFmpeg、libvips、packager 這類工作與 HTTP 流量分開擴展

這個設計讓同一個映像可同時用於 Docker Compose、單機部署，以及 K8s 下的 server/worker 拆分。

目前已驗證的能力​

  • /img 即時圖片縮放、格式轉換與快取
  • video:preview 動態預覽，支援 webp 與 gif
  • audio:transcode 對應的 audio-only HLS、MP3、FLAC、waveform 輸出
  • video:transcode 產出 HLS CMAF
  • AV1 + H.264 雙 codec ladder
  • portrait / non-16:9 影片的實際解析度輸出
  • raw-key CBCS / SAMPLE-AES 加密串流
  • /api/key/{id} Bearer token 金鑰發放
  • PostgreSQL job state、Redis queue、Prometheus metrics、OpenTelemetry tracing

建議閱讀路徑​

First run​

  1. 先讀 快速開始
  2. 接著讀 設定 與 部署
  3. 等服務可達後，再看 可觀測性

Application integration​

  1. 先讀 整合導覽
  2. 接著讀 工作 API 與 圖片與媒體投遞 API
  3. 若你需要串流或加密播放，再讀 播放 API 與 加密串流

Operations​

  1. 先讀 部署
  2. 接著讀 設定
  3. probe、metrics 與排障則看 系統端點 與 可觀測性

文件範圍​

目前這個 docs site 聚焦於：

  • 服務結構與核心資料流
  • 媒體處理 pipeline
  • HTTP endpoints、授權方式與 curl 範例
  • 部署、設定、觀測與測試

文件原則​

  • 以目前程式碼與測試行為為準
  • 以部署與接入可操作性為優先，而不是抽象設計描述
  • 會吸收 repo 根目錄與本機輔助資料中已驗證、但不適合長期保留在正式發行包內的操作知識