Skip to main content

本機手動測試工具

gh-pages 分支提供了一套小型 Python 工具，讓工程師可以在本機手動操作 Vylux，而不需要把這些 helper 放進主應用分支。

工具放在：

tools/manual/

這套工具的定位是本機與可信任工程環境用的輔助工具，不是 production SDK。

先決條件​

  • Python 3.11+
  • 工具會自動安裝 cryptography，用於 AES-GCM source token
  • 若要操作 RustFS object，需安裝 boto3
  • 準備好可用的 .env，必要時再加 .env.local

先從 repo root 以 editable mode 安裝這個工具：

pip install -e tools/manual

安裝 RustFS 相關依賴：

pip install -e 'tools/manual[rustfs]'
如果 pip 和 python 沒有指向同一個環境

在大多數 conda 和 virtualenv 工作流裡，pip 和 python 會屬於同一個目前啟用的環境。若你的環境不是這樣，請把 pip ... 改成 python -m pip ...。

環境變數載入順序​

工具會依序載入：

  1. .env
  2. .env.local（覆蓋 .env）
  3. 同名 process environment variables（優先級最高）

這和 Vylux 本機開發時的常見習慣一致：

  • .env 通常放 container-to-container 位址，例如 postgres、redis、otel-collector
  • .env.local 通常放 host-to-container 覆蓋值，例如 localhost:5434、localhost:6381、localhost:9002

快速開始​

在 gh-pages 分支根目錄執行：

pip install -e tools/manual
vylux-manual --help

如果你偏好 module 形式，也可以使用：

python -m vylux_manual --help

建議使用方式如下：

  1. 先在 repo root 準備好 Vylux 所需的 .env 或 .env.local。
  2. 用 editable mode 安裝一次工具。
  3. 執行 vylux-manual --help 查看所有可用指令。
  4. 依你想驗證的流程，逐一執行單一指令，例如上傳檔案、送出工作、查詢狀態，或產生簽名 URL。

本頁以 vylux-manual 這個安裝後產生的命令作為主要入口。

安裝完成後，只要 shell 使用的是同一個 Python 環境，就可以直接執行 vylux-manual。repo root 主要影響的是安裝命令，以及工具會讀取的 .env 檔案位置。

支援的指令​

目前支援：

  • 上傳檔案到 source 或 media bucket
  • 列出 source 或 media bucket 中的 object
  • 用 head 查物件 metadata
  • 從 source 或 media bucket 刪除 object
  • 建立 audio job
  • 建立 video transcode job
  • 建立 video full job
  • 查詢 job status
  • retry failed job
  • 依 content hash 刪除衍生媒體
  • 產生已簽名的 /img、/original、/thumb URL
  • 設定 IMAGE_SOURCE_KEY 時產生可重用的 AES-GCM source token
  • 產生 /api/key/{id} 的 URL 與 Bearer token

常見流程​

上傳來源檔案​

vylux-manual upload source uploads/demo.flac /path/to/demo.flac
vylux-manual upload source uploads/demo.mp4 /path/to/demo.mp4

建立加密 audio HLS 工作​

vylux-manual create-audio a0b1c2d3 uploads/demo.flac --encrypt --waveform

建立加密 video transcode 工作​

vylux-manual create-video-transcode deadbeef uploads/demo.mp4 --encrypt

查詢 job 狀態​

vylux-manual job-status <job-id>

依 hash 刪除衍生媒體​

vylux-manual delete-media deadbeef

建議流程​

多數手動測試可以依照這個順序進行：

  1. 把來源檔案上傳到 source bucket。
  2. 送出你要觀察的媒體處理工作。
  3. 用 job-status 持續查詢直到處理完成。
  4. 處理完成後，再產生播放或交付所需的簽名 URL。

這樣能讓這套工具維持在一次性驗證與理解流程的用途，而不是演變成自動化系統。

修改工具程式後​

如果你修改了 tools/manual/src/vylux_manual 底下的 Python 程式，通常不需要重新編譯或重新安裝。因為套件是以 editable mode 安裝，vylux-manual 本來就直接指向你的工作樹。

多數情況下，流程就是：

vylux-manual --help

儲存修改後，直接重新執行你要測試的命令即可。

只有在你修改了 pyproject.toml 的 packaging metadata、加入新依賴，或更動 console script 定義時，才需要重新執行安裝命令。

卸載工具​

要從目前的 Python 環境移除這個工具，可以執行：

pip uninstall vylux-manual

如果你的 pip 和 python 在 shell 中不是同一套環境，則改用 interpreter-specific 的寫法：

python -m pip uninstall vylux-manual

卸載後，vylux-manual 會從該環境中消失。若命令仍然存在，通常表示你的 PATH 上還有另一個 Python 環境也安裝了它。

簽名與播放輔助​

這套工具也能產生你的應用平常會對外提供的那些 route。

已簽名圖片 URL​

vylux-manual image-url uploads/sample.png webp --options w320_h180

.env 或 .env.local 有 IMAGE_SOURCE_KEY 時，此命令會自動加密 source key；未設定時維持明文 URL。

分開生成並保存 token：

vylux-manual source-token uploads/sample.png
vylux-manual image-url uploads/sample.png webp --options w320_h180 --token '<saved-token>'

重現固定測試向量：

vylux-manual source-token static/forum/recommend-cover.png \
	--nonce 000102030405060708090a0b

--nonce 只供測試向量使用；一般操作請省略，讓工具生成安全的隨機 nonce。

已簽名原檔 URL​

vylux-manual original-url uploads/sample.png --token '<saved-token>'

已簽名縮圖 URL​

vylux-manual thumb-url videos/mo/movie-2026-04-01/cover.jpg

Key endpoint URL 與 Bearer token​

vylux-manual key-url <key-id> <content-hash> --ttl 3600

安全提醒​

  • 不要把 API_KEY、HMAC_SECRET、IMAGE_SOURCE_KEY、KEY_TOKEN_SECRET 暴露到瀏覽器
  • 請把這套工具視為可信任的本機 helper，而不是公開 client
  • 若你會分享 shell history 或截圖，記得其中可能會帶到敏感值

相關頁面​