加入應用程式入口網站項目

應用程式入口網站（Application Portal）項目會給你的 App 一個像 https://<nas>/myapp/ 的網址。使用者開啟它、登入 DSM 後，就會直接進入你的 App 視窗。你在 dsm-package.yaml 宣告這個項目，安裝精靈會詢問別名，再由管理員啟用。

只有帶 executor 的 App 能有這個項目：capabilities.rootOps 或 capabilities.delegate（見能力）。DSM 在解除安裝時會移除別名，但網頁伺服器重新載入前仍會繼續提供，而只有 root 能讓它重新載入。executor 會在解除安裝時處理。無升權 App 任何階段都不使用 root，所以不能宣告 portal。

加入能力

synopkgland add portal

App 必須已宣告 root-ops 或 delegate，或在同一次呼叫加入，例如 synopkgland add delegate,portal；否則指令會以 STANDALONE_PORTAL_REQUIRES_EXECUTOR 失敗。此指令會把 portal: {} 寫入 dsm-package.yaml。如果你的 os_min_ver 低於 7.1-42661，會把它提高到該值並印出此變更。如果 portal 已經存在，指令會回報「unchanged」。你也可以同時加入其他能力，例如 synopkgland add portal,files。

你也可以自己寫這個欄位：

os_min_ver: 7.1-42661
portal:
  # 選填；預設值是套件名稱轉成的 slug
  alias: myapp

欄位	規則
`portal`	`{}` 或 `{alias: <alias>}`。不可有其他鍵。
`alias`	1 到 64 個字元：小寫英文字母、數字與連字號。不可以連字號開頭或結尾，也不可是保留別名。
預設別名	小寫的套件名稱。若它是保留別名或不是有效別名，則為 `app-` 加 12 個十六進位字元。
`os_min_ver`	`7.1-42661` 或更高
Executor	`capabilities.rootOps` 或 `capabilities.delegate`

保留別名：dsfile、indexdb、mobile、oauth、scripts、sharing、ssdp、synosdsjslib、synohdpack、webapi、webman、calendar、chatplus、contacts、drive、file、photo、sso、synologymeet。

portal 值不正確時，check 與 build 會以 STANDALONE_PORTAL_INVALID 失敗；os_min_ver 太低時是 STANDALONE_PORTAL_MIN_DSM；App 沒有 executor 時是 STANDALONE_PORTAL_REQUIRES_EXECUTOR。inspect 會把帶 portal 但沒有 executor 的 SPK 回報為 PORTAL_REQUIRES_EXECUTOR。

安裝者與管理員要做什麼

步驟	誰	會發生什麼
安裝	安裝的人	DSM 7.2 以上的安裝精靈有「別名」欄位，預設填入預設別名。違反別名規則的值會讓安裝中止。DSM 7.1 由 executor 註冊，沒有別名精靈步驟。
啟用	管理員	開啟你的 App，在「應用程式入口」面板套用別名。另一種方式是在控制台的「登入入口網站」>「應用程式」操作。
開啟	任何有權限的使用者	開啟 `https://<nas>/<alias>/` 並登入 DSM。
解除安裝	Executor	DSM 移除別名後，executor 會重新載入 DSM 網頁伺服器，網址立即無法開啟。

安裝者填寫的答案只是建議的別名。在管理員套用別名之前，這個項目都是關閉的。管理員也可以用「停用」把它關掉。

DSM 7.2 以上透過 SPK resource 註冊 portal 項目；DSM 7.1 由已核准的 executor 註冊。manifest 的最低 DSM 版本低於 7.2 時，CLI 建置 Go 與 bridge runtime 都會帶入 executor portal mode。不論安裝於 DSM 7.1 或 7.4，管理員都能在 App 設定中對 Go App，以及以 Rust、Python、Node 撰寫的 bridge App 使用「啟用入口／移除入口」。此模式下 bridge runtime 提供固定的 portal.register 與 portal.unregister route；最低版本為 DSM 7.2 以上的 App 則由 DSM resource 管理。這些操作需要宣告 portal 能力並核准 executor；取得工作階段 token 不會啟用入口。

從入口頁移除自己的入口時，App 會先要求確認，因為目前頁面將無法繼續使用。移除後依畫面指引操作：選擇「開啟 DSM 桌面」，從桌面開啟 App，再前往「設定 → 應用程式入口 → 啟用入口」。請先閱讀這些步驟再離開移除結果畫面。

直接開啟 portal 視窗

在登入 DSM 的同一 NAS 主機名稱開啟已啟用的別名。桌面 SynoToken 可用時，共用視窗 wrapper 會直接使用；缺少時，會在呼叫後端與 DSM WebAPI 前，透過相對於 portal prefix 的同源 GET webman/login.cgi?enable_syno_token=yes 取得目前工作階段的 token。並行呼叫共用這次請求，token 只保留在記憶體。請求期限為五秒，會拒絕 redirect、不合法的回應與 token。

瀏覽器仍須有有效的 DSM 工作階段。API 與 executor 請求需要 cookie 及 SynoToken，原生 authenticate.cgi 驗證會保留瀏覽器原始用戶端位址；取得 token 不會略過這些檢查。取得失敗時仍走既有工作階段錯誤處理；請以同一主機名稱重新登入 DSM，再開啟 App。

DSM Application Portal banner 顯示這個 App 的名稱時，AppShell 會隱藏重複的品牌區；DSM 帳號選單可見時，也會隱藏預設帳號區。自訂 sidebar-footer 會保留；banner 隱藏、缺少或無法辨識時，仍顯示 shell 自己的控制項。

使用方式

portal 有宣告時，預設的 Vue UI 會顯示「應用程式入口」面板。在 plain UI 中，請自行掛載面板：

ctx.portal.mountPanel(document.getElementById('portal'))

只有當 dsm-package.yaml 宣告了 portal，才有 ctx.portal。

呼叫	結果
`status()`	`{state, alias?, url?, canManage, controlPanel, defaultAlias}`。`state` 為 `active`、`inactive` 或 `unavailable`。
`apply(alias)`	設定別名並回傳新狀態。僅限管理員。
`disable()`	關閉項目並回傳新狀態。僅限管理員。
`openControlPanel()`	開啟控制台的「登入入口網站」>「應用程式」。
`mountPanel(element)`	繪製現成的面板，含連結、別名表單與錯誤文字。

管理員透過 DSM 讀取與變更別名。其他使用者透過後端方法 portal.status 讀取，所有已登入的使用者都能呼叫。非管理員在項目啟用時會看到連結，未啟用時會看到請管理員設定的提示。

限制

限制	值
最低 DSM 版本	7.1-42661
可宣告的 App	有 `rootOps` 或 `delegate` 的 App
別名長度	1 到 64 個字元
每個 App 的項目數	1
誰能套用或關閉	DSM 管理員
面板語言	en、zh-TW、zh-CN、ja、ko、de、fr、es、it

疑難排解

錯誤碼	原因	解法
`portal_alias_invalid`	別名是空的、太長、含其他字元，或以連字號開頭或結尾。	使用 1 到 64 個小寫英文字母、數字或連字號。
`portal_alias_reserved`	別名在保留清單中。	改用其他別名。
`portal_alias_in_use`	另一個 App 已使用這個別名。	改用其他別名。
`admin_required`	非管理員嘗試套用或關閉別名。	請管理員處理。
`portal_unavailable`	DSM 未接受這項變更。	再試一次，或改用控制台的「登入入口網站」>「應用程式」。
`STANDALONE_PORTAL_INVALID`	`portal` 不是 `{}` 或 `{alias}`，或別名無效。	修正 manifest。
`STANDALONE_PORTAL_MIN_DSM`	`os_min_ver` 低於 `7.1-42661`。	提高 `os_min_ver`，或執行 `synopkgland add portal`。
`STANDALONE_PORTAL_REQUIRES_EXECUTOR`	App 沒有 `rootOps` 也沒有 `delegate`。	加入 `root-ops` 或 `delegate`，或移除 `portal`，改由管理員在 DSM 設定反向代理。
解除安裝後網址仍能開啟	executor 的清理失敗；系統日誌項目 `synopkgland-executor` 會說明原因。	管理員在控制台 >「登入入口網站」>「應用程式」儲存任一別名（會重新載入網頁伺服器），或重新啟動 NAS。

DSM 可能回報別名無效（4100）、保留（4102）或已被使用（4103）。面板會把它們顯示為 portal_alias_invalid、portal_alias_reserved 與 portal_alias_in_use。完整清單請見錯誤碼。

容器 App 沒有 executor，不能宣告入口項目；integration.web.portal 會以 CONTRACT_PORTAL_REQUIRES_EXECUTOR 失敗。請見容器 App。