前言：兩個最早的專案，兩種相反的狀態

在完成基礎骨架建構後，接下來將透過實際專案進行驗證。首先挑選的對象是 Jellyfin-QPKG 與 roon-qpkg，這兩個專案在架構演進光譜上剛好處於完全相反的兩端。

roon-qpkg 是薄殼架構最早成形的驗證場域。先前提及的 open-webui-ollama-qpkg 正是從中抽取骨架，隨後的通用範本 qpkg-template 又進一步提煉其核心，因此它與現行標準範本的血緣最近。相對地，Jellyfin-QPKG 源自社群專案 fork，沿用舊式結構，其 package_routines 同時身兼安裝程序與服務控管腳本，容器亦透過 docker compose 啟動，是距離標準範本最遠的既有專案。

兩者在架構上的共同交集，在於媒體伺服器不可迴避的兩大核心需求：硬體轉碼必須將主機上的 GPU 或 iGPU 裝置節點穿透掛載給容器，而裝置探索協定則要求容器直接共享 NAS 的網路堆疊。這兩項硬體與網路特性的配置邏輯，如何妥善收斂至範本的 app_run_<id> 掛鉤之中，正是本文探討的重點。

依既有標準實施架構體檢

以下針對 Jellyfin-QPKG v1.2.1 與 roon-qpkg v1.2.3 進行完整規格盤點：

盤點結果顯示，兩個專案皆尚未導入 digest 雜湊鎖定、生命週期測試與憑據證明（attestation）。Jellyfin-QPKG 存在三項顯著問題：內部名稱直接使用上游裸名、腳本使用 bash 而非跨平台 POSIX sh，以及安裝程序於前景同步下載映像檔。前兩項源自上游專案的歷史包袱，第三項則會在硬體效能受限的 NAS（例如搭載 Celeron N5095 的機型）上導致 App Center 安裝進度停滯數分鐘之久。

roon-qpkg 的待改善項目則聚焦於浮動 tag、改採 SHA256 取代 MD5，以及清理 main 分支上的授權宣告不一致問題。先前盤點表記述 roon-qpkg v1.2.3 在 LICENSE 與 qpkg.cfg 上授權相歧，經精確比對，v1.2.3 tag 當下兩者皆為 MIT；LICENSE 是在後續 commit 才改為 Apache-2.0，而 qpkg.cfg 未同步更新，因此此不一致性目前僅存在於 main 分支，尚未流入正式發行版本，修復目標鎖定於 main 分支即可。

一、硬體轉碼的裝置直通

三種硬體加速途徑與掛載機制

在 QNAP 系統環境中，Jellyfin 的硬體加速轉碼主要涵蓋三種硬體來源。Intel 內建顯示核心依循 QSV 或 VA-API 途徑，AMD 處理器走 VA-API，NVIDIA 獨立顯示卡則仰賴 NVENC 與 NVDEC 架構。前兩者僅需將主機端 /dev/dri 目錄下的裝置節點映射至容器內部；NVIDIA 除了需要裝置節點外，還必須載入對應驅動程式的使用者空間函式庫。

Jellyfin-QPKG v1.2.1 採取的硬體偵測實作如下：

if [ -d "/dev/dri" ] || [ -c "/dev/dri/renderD128" ]; then
    DEVICES_ENTRIES="${DEVICES_ENTRIES}      - \"/dev/dri:/dev/dri\"\n"
fi

NVIDIA_DRV_PATH=$(/sbin/getcfg NVIDIA_GPU_DRV Install_Path -f /etc/config/qpkg.conf)
if [ -c "/dev/nvidia0" ] && [ -n "$NVIDIA_DRV_PATH" ] && [ -d "$NVIDIA_DRV_PATH" ]; then
    DEVICES_ENTRIES="${DEVICES_ENTRIES}      - \"/dev/nvidia0:/dev/nvidia0\"\n      - \"/dev/nvidiactl:/dev/nvidiactl\"\n      - \"/dev/nvidia-uvm:/dev/nvidia-uvm\"\n"
    echo "      - \"${NVIDIA_DRV_PATH}/usr:/usr/local/nvidia:ro\"" >> "$COMPOSE_FILE"
fi

針對 Intel 與 AMD 硬體，該腳本直接將整個 /dev/dri 節點樹傳入容器，交由容器內的 Jellyfin 伺服器自主定位 renderD128。針對 NVIDIA 硬體，腳本主動查詢 QTS 系統中 NVIDIA_GPU_DRV 套件的安裝路徑，將驅動程式的 usr 目錄以唯讀權限掛載至容器內的 /usr/local/nvidia，並透過設定 LD_LIBRARY_PATH 引導容器內建的 ffmpeg 讀取動態函式庫。

這項做法與先前在 open-webui-ollama-qpkg 所採用的架構截然不同。後者直接宣告 --gpus all，完全依賴 Container Station 所註冊的 nvidia runtime 進行自動注入。兩種途徑的核心差異在於驅動程式版本的相依管理：使用 runtime 注入時，容器內看見的函式庫完全與主機系統驅動版本即時連動；而手動掛載方式雖然路徑被靜態寫死於腳本中，若 QTS 的 NVIDIA 驅動套件目錄結構調整即告失效，但它徹底免除了開機順序競爭的問題，不依賴開機當下 Container Station 是否已及時註冊 runtime。

遷移至新範本時將同時保留兩種調度模式，由設定檔內的 NV_MODE 參數（可設為 mount 或 runtime）決定，預設採行穩定度較高的 mount 模式。必須客觀指出的是，Jellyfin-QPKG 截至 v1.2.1 為止，硬體轉碼僅在程式邏輯層面驗證過能否生成對應的 compose 內容，尚未在 QNAP 實體機上透過影片串流實測 QSV 與 NVENC 的執行狀態。後續將規劃在 TS-464 平台測試 Intel UHD Graphics 的 QSV 運算，並在具備獨立顯卡的系統上分別對兩種 NV_MODE 進行轉碼驗證。

收斂至範本的生命週期掛鉤

標準範本的核心層刻意維持純粹，對底層 GPU 拓撲一無所知，所有硬體相關參數皆於應用層的 app_run_<id> 掛鉤內動態組裝。以下為規劃中導入 Jellyfin 的掛鉤實作草案：

# 回傳要加到 docker run 的裝置參數。HW_MODE 為 auto、off 或 on。
hw_args() {
    [ "$HW_MODE" = "off" ] && return 0
    ARGS=""
    if [ -c /dev/dri/renderD128 ]; then
        ARGS="$ARGS --device /dev/dri:/dev/dri"
    fi
    if [ -c /dev/nvidia0 ]; then
        NV=$(/sbin/getcfg NVIDIA_GPU_DRV Install_Path -f /etc/config/qpkg.conf)
        if [ "$NV_MODE" = "runtime" ]; then
            ARGS="$ARGS --gpus all"
        elif [ -n "$NV" ] && [ -d "$NV/usr" ]; then
            ARGS="$ARGS --device /dev/nvidia0 --device /dev/nvidiactl --device /dev/nvidia-uvm"
            ARGS="$ARGS -v $NV/usr:/usr/local/nvidia:ro -e LD_LIBRARY_PATH=/usr/local/nvidia/lib64"
            ARGS="$ARGS -e NVIDIA_VISIBLE_DEVICES=all -e NVIDIA_DRIVER_CAPABILITIES=all"
        fi
    fi
    [ "$HW_MODE" = "on" ] && [ -z "$ARGS" ] && log "HW_MODE=on but no GPU device found" 2
    echo "$ARGS"
}

app_fingerprint_jellyfin() {
    # 偵測結果刻意不進指紋。HW_MODE 與 NV_MODE 是使用者的決定，要進。
    printf '%s\n' "$WEB_PORT" "$NET_MODE" "$HW_MODE" "$NV_MODE" "$MEDIA_PATHS" "$JELLYFIN_EXTRA_ARGS"
}

app_needs_recreate_jellyfin() {
    # 容器停著、現在偵測得到的裝置，容器建立時沒有掛，就重建
    WANT=$(hw_args)
    [ -n "$WANT" ] || return 1
    HAVE=$("$DOCKER" inspect -f '{{range .HostConfig.Devices}}{{.PathOnHost}} {{end}}' \
        "$JELLYFIN_CONTAINER_NAME" 2>/dev/null)
    for DEV in /dev/dri /dev/nvidia0; do
        case "$WANT" in
            *\"--device $DEV\"*) case " $HAVE" in *\" $DEV\"*) ;; *) return 0 ;; esac ;;
        esac
    done
    return 1
}

app_run_fallback_jellyfin() {
    # 裝置掛載失敗時退回純軟體轉碼，而非讓 App 起不來
    echo "$1" | grep -qi "device\|nvidia\|gpu" || return 1
    log "Hardware device passthrough failed, retrying without devices: $1" 2
    HW_MODE=off
    app_run_jellyfin
}

這套架構設計確立了三項關鍵決策：

指紋計算徹底排除動態偵測結果。硬體節點在開機初期往往具備時序不確定性，若將裝置偵測狀態列入指紋計算，開機順序的微小差異便會誘發非必要的容器重建。使用者主動設定的 HW_MODE 與 NV_MODE 代表組態意圖，應寫入指紋；硬體在當下的瞬時可見狀態則屬系統狀態，不得列入指紋。

自我修復機制收斂至 app_needs_recreate 處理。系統僅在容器處於停止狀態時觸發檢查，精確比對當前探測到的硬體節點是否已納入 HostConfig.Devices 參數中，唯有發現遺漏時方執行容器重建，正在執行中的服務不受干擾。在此機制下，--gpus all 宣告因不會留下 HostConfig.Devices 紀錄，無法參與這套自我檢查修復，這亦是採用 runtime 模式的架構代價之一。

硬體調用失敗時退回軟體轉碼。核心模組在 app_run_<id> 遭遇非連接埠衝突的啟動失敗時，會將錯誤內容交由 app_run_fallback 判斷。腳本僅在錯誤訊息明確涉及 device、nvidia 或 gpu 關鍵字時介入降級重試，避免將其他非硬體故障隱匿至降級路徑中。變數宣告 HW_MODE=off 獨立成行執行，以確保在 dash 與 busybox ash 等不同 POSIX Shell 環境下的環境變數作用範圍維持一致。

消除高風險權限配置指引

Jellyfin-QPKG 文件草稿中曾提及「若特定 QTS 版本 /dev/dri 權限受限，可執行 chmod -R 777 /dev/dri」，這項指引在資安架構上必須徹底廢除。

在權限模型的本質上，預設的 jellyfin/jellyfin 映像檔本就以 root 身分執行，容器內行程完全跨越主機端裝置節點的 DAC 存取控制限制，標準安裝流程根本不會引發存取阻礙。若使用者選擇透過 --user 參數降權執行，官方標準處置方案是宣告 --device /dev/dri/renderD128，並搭配 --group-add 附加 host 端 render 群組的 gid。考量 QTS 的 /etc/group 未必預設定義 render 群組名稱，實務上可透過 ls -ln /dev/dri 直接讀取其數值 gid。若因便宜行事而將主機端裝置節點變更為 777 權限，形同將 NAS 內部圖形加速硬體的直接存取權無條件開放給主機上所有本機帳號及未隔離容器，衍生嚴重的特權提升隱患。

二、主機網路的架構抉擇

協定本質決定網路模式

Roon 系統的核心裝置探索機制高度依賴 RAAT 協定下的 LAN 多播（Multicast）與廣播（Broadcast），控制端 App 亦藉由此機制動態定位 Roon Server。在標準 Docker bridge 網路模型中，多播封包無法穿透虛擬網路介面，伺服器即使正常運作亦會處於完全隱形的孤立狀態。因此官方直接將 Host 網路模式列為強制需求，roon-qpkg 在服務腳本中嚴格寫死 --net=host，啟動時強制稽核容器網路屬性，且不允許於設定檔中自訂覆寫。

Jellyfin 的架構特性則明顯不同。官方文件明確建議使用 bridge 網路，透過通訊埠對應開放 8096/tcp 負責網頁與串流，以及 7359/udp 供客戶端實施自動探索；僅在啟用 DLNA 功能時才視需求切換至 Host 網路。由於 DLNA 仰賴固定於 1900/udp 的 SSDP 廣播封包，無法在 bridge 模式下順暢運作。Jellyfin 自 10.9 版起已將 DLNA 移出核心改為選用外掛，這意味著未啟用 DLNA 的純淨安裝環境完全無需承擔 Host 網路的暴露風險。

Jellyfin-QPKG v1.2.1 雖採用 bridge 模式，卻遺漏了 7359/udp 的連接埠對應，導致行動裝置與電視端 App 無法自動搜尋伺服器，迫使使用者必須手動輸入 IP。新版遷移架構將統一提供 NET_MODE 參數，預設維持 bridge 模式，並補足 7359/udp 映射設定。

Host 網路對通用範本帶來的衝擊

通用範本的核心在諸多環節預設容器配置於獨立 bridge 網路中，當切換為 Host 網路模式時，必須妥善因應三項連鎖反應：

通訊埠衝突檢測機制的本質差異。範本核心在啟動容器前會預先稽核 WEB_PORT，在 bridge 模式下所佔用的是主機上的轉發埠，透過變更設定檔的對應數值即可避開衝突；但在 Host 模式下，App 所監聽的通訊埠由應用程式內部決定，Jellyfin 固定鎖定 8096，若遭遇衝突只能修改 Jellyfin 自身設定或停用衝突服務，此情境的除錯提示必須在腳本中明確區隔。

就緒狀態頁的連接埠交接時序。通用範本透過暫存狀態頁容器以 Host 網路暫時綁定 WEB_PORT，待主服務就緒後銷毀釋放。當主應用程式同樣採 Host 模式運作時，雙方監聽同一通訊埠，交接時序絕對不可重疊，核心流程必須採取嚴格的先徹底終止狀態頁、再啟動主服務機制。

隔離虛擬網路的清理流程。範本核心預設為個別 App 建立專屬 docker network，但運作於 Host 網路的容器根本不會加入該網路。這導致配置的 NETWORK_NAME 失去實質意義，核心在執行 remove 階段雖會嘗試清理該空白網路，此舉雖無害，但在流程日誌中應妥善標註。

三、Roon 的常駐操作介面與安全性架構

Roon Server 自身並未內建網頁設定介面，所有音訊邏輯皆透過專屬 App 控制。這使得 roon-qpkg 的狀態頁設計與標準範本產生根本分野：範本的狀態頁在主程式就緒後即結束階段任務，而 roon-qpkg 的狀態頁則作為長期維護入口，點擊 App Center 圖示後便直接進入此管理介面。該介面由獨立容器 roonserver-ui 負責，透過輕量化 busybox httpd 監聽獨立的 18630 連接埠，與 Host 網路上的 Roon 核心互不干擾。

為了讓使用者能在免除 SSH 終端機操作的前提下修改音樂媒體庫、資料庫與備份路徑，系統設計了具備嚴密隔離屏障的收件匣（Inbox）架構。

瀏覽器送出表單請求至狀態頁容器內的 save.cgi。該腳本職責極度受限，僅將容量小於 4 KB 的未加工請求字串寫入內部 /inbox/pending.conf，不進行任何語法解析，亦不具備主機端存取權限。狀態頁程式碼目錄本身以唯讀模式掛載，僅有收件匣目錄開放寫入，縱使 httpd 服務遭遇未授權入侵，攻擊者亦僅能在沙盒目錄內產生單一檔案。

主機端透過 QTS crontab 定期排程，每分鐘指派服務腳本執行 apply-pending 子命令。該命令自主機內部讀取掛載的收件匣內容，執行嚴格的白名單過濾：僅接納三個特定設定鍵值，所有路徑必須嚴格限制於 /share/ 目錄樹下，一律拒絕包含相對路徑語法 ..，並剔除可能破壞 Shell 變數賦值或引發指令注入的特殊字元。同時，腳本強制檢核目標路徑的真實存在性，驗證通過後才更新主機組態檔並自動重啟容器。

這項設計在非信任的網頁介面與高權限的主機環境之間建立起極佳的信任防護邊界。針對 Roon 這類極度依賴密集小型區塊隨機存取的資料庫服務，服務腳本亦整合了儲存介質偵測機制，透過查詢 /sys/block/<dev>/queue/rotational 辨識底層硬體；若偵測為機械式硬碟（HDD），系統將即時發出警示以避免音訊解構與檢索效能劣化。

映像檔鎖定邊界探討

Roon 官方釋出的映像檔本質上僅是一個極簡執行環境與 entrypoint.sh 啟動器，其伺服器二進位核心於容器首次啟動時，才會自遠端動態下載安裝至 /Roon 目錄下，後續並由 Roon 內部排程自主更新。因此，在 QPKG 層級對映像檔實施 digest 鎖定，實際上僅凍結了外部包裝環境，無法鎖定 Roon Server 核心的即時版本。此特性在專案的 NOTICE.md 與技術文件中必須詳實揭露，避免使用者誤認整體系統已達成完全不可變狀態。

四、Jellyfin 儲存掛載策略的安全性收斂

Jellyfin-QPKG v1.2.1 既有的 create_all_mounts_file 模組透過剖析 smb.conf，自動將主機端所有標記為可寫入的共享目錄，全數以讀寫模式（rw）掛載至容器內的 /mnt/<share> 目錄下。

此項上游延續下來的設計雖然消除了初次設定的複雜度，卻在系統安全層面引入極高的結構性風險。媒體伺服器因此取得了全機共享資料夾的無限制寫入權限，涵蓋與影音無關的機敏檔案、個人隱私資料乃至系統備份目標。回顧 Jellyfin 近年的漏洞揭露紀錄，CVE-2026-35033 展現了未經身分驗證即可透過串流端點參數注入任意讀取伺服器內部檔案的漏洞，CVE-2026-35031 則是利用字幕上傳發動目錄穿越並串接遠端程式碼執行，更早的 CVE-2023-30626 亦具備任意檔案寫入能力。

在全面開放讀寫掛載的架構下，任何遠端程式碼執行或寫入型漏洞的損害半徑將直接擴散至整台 NAS 的所有資料集。遷移後的新架構將嚴格落實最小權限原則，改採明確的 MEDIA_PATHS 白名單，預設僅搜尋 Multimedia 與 Video 目錄，並強制以唯讀模式（ro）掛載進容器；容器端僅有自身的 /config 與 /cache 具備寫入權限。

為了確保升級平順，掛載點路徑將嚴格維持 /mnt/<共享名稱> 結構，以避免因絕對路徑異動導致既有媒體庫索引全面失效。若使用者有中繼資料寫入媒體目錄之需求，則可透過設定檔白名單選擇性賦予特定目錄寫入權限。

遷移與升級路徑規劃

內部識別碼更名評估

考量長期架構維護，Jellyfin 套件的內部代號決定由原本上游裸名 jellyfin 遷移至 JellyfinDocker，版號同步推進至 2.0.0。

這項決策主要基於消除潛在命名衝突的必然性。沿用裸名會導致系統與上游原作者套件、或是未來官方若推出同名 QPKG 時產生全域衝突。鑑於目前 GitHub 累積下載基數尚小，在導入安全掛載架構與 digest 鎖定此等破壞性變更之際執行更名，是架構轉型的最佳時機。

更名過程伴隨一項關鍵的資料保存挑戰：舊版套件將設定檔直接存放於自身安裝路徑 .qpkg/jellyfin/config 之下，一旦使用者在 App Center 移除舊版，其使用者帳號、媒體庫索引與觀看歷程將一併遭系統刪除。為此，2.0.0 的安裝流程規劃了自動遷移機制：安裝初期透過系統指令檢測舊版套件安裝路徑，若偵測到既有 config/ 目錄即主動進入備份轉移流程；接著安裝腳本預先終止舊版容器運作以確保資料庫靜態完整，隨後以遞迴方式完整複製資料至新套件所屬目錄，並產生狀態標記避免重複覆寫；新版容器啟動後，維持既有媒體掛載對應結構；最後於系統介面提示管理員確認服務運作無誤後，再行安全卸載舊版套件。

專案遷移待辦項目整理

依循通用範本的標準流程，兩大專案的待辦清單整合如下：

版本控管方面，Jellyfin-QPKG 因包含架構重構、內部名稱調整與安全掛載等需手動介入之重大異動，版本號正式遞增為 2.0.0；roon-qpkg 則聚焦於授權宣告校正與映像檔鎖定，升級過程對使用者維持透明，版本號推進至 1.3.0。

系統觀測與驗證實作

在 NAS 終端機環境下，可透過以下指令檢視 Jellyfin 實際自系統獲取的裝置節點與掛載拓撲：

/share/CACHEDEV1_DATA/.qpkg/container-station/bin/docker inspect jellyfin \
    -f '{{range .HostConfig.Devices}}{{.PathOnHost}} {{end}}'

/share/CACHEDEV1_DATA/.qpkg/container-station/bin/docker inspect jellyfin \
    -f '{{range .Mounts}}{{.Source}} -> {{.Destination}} ({{.Mode}}){{"\n"}}{{end}}'

若硬體具備內建顯示核心，首條指令應正確輸出 /dev/dri 節點路徑。第二條指令則會完整列出當前所有掛載目錄，可用於稽核是否有非媒體目錄遭到過度授權掛載。

若欲確認串流播放時是否確實調用硬體加速，可在播放觸發即時轉碼後，直接自轉碼日誌檢索 ffmpeg 指令參數：

LOG=$(ls -t /share/CACHEDEV1_DATA/.qpkg/jellyfin/config/log/FFmpeg.Transcode-*.log | head -1)

grep -o -- '-init_hw_device [^ ]*\|-hwaccel [^ ]*' "$LOG" | sort -u

當硬體成功參與運算時，輸出將顯示 -hwaccel qsv、-hwaccel vaapi 或 -hwaccel cuda 等旗標，若無任何結果則代表系統退回於 CPU 軟體轉碼。

針對 Roon 服務，則可透過診斷指令檢測網路模式與底層儲存介質型態：

/etc/init.d/roon-server-docker.sh diag

cat /share/CACHEDEV1_DATA/.qpkg/RoonServerDocker/web/status.json

檢視其輸出的 status.json，其中 network_mode 應呈現 host，而 data_media 則會明確標示為 ssd、hdd 或 unknown，協助確認儲存配置是否符合高隨機讀寫效能之需求。

後續發展方向

下一篇將進入第二組實戰案例：changedetection.io 與 Homepage。兩者皆屬於高度依賴設定檔驅動的應用，前者專注於持續監控軟體供應商安全通報、QTS 系統更新公告與映像檔版號異動，後者則作為整合所有 QPKG 運作狀態的單一可視化入口。屆時將進一步探討單一套件管理多重容器時的啟動相依順序，以及設定檔如何在確保使用者可編修的前提下安全遞送至容器內部。