資料與移除

升級會保留 App 的資料。解除安裝也會保留，除非使用者在解除安裝精靈中勾選一個核取方塊。你的處理常式寫入同一個資料資料夾，其中所有內容都能撐過升級。

設定

把資料寫到資料資料夾

native-go 後端把資料寫到 /var/packages/<package>/var，DSM 把它存放在儲存空間上的 @appdata/<package>。你放進 SPK 的檔案會在每次升級時被取代，因此任何要保留的內容都請寫到資料資料夾。

位置	內容	升級	勾選解除安裝核取方塊
`@appdata/<package>`	App 資料：你的處理常式寫入的內容。Compose App 則是 `${SYNOPKG_PKGVAR}` 的 bind mount。	保留	內容會被刪除
`@apphome/<package>`	套件的 home 資料夾。Compose App 則包含產生的 secrets。	保留	內容會被刪除
`@appconf/<package>`	儲存的套件設定。僅限原生套件。	保留	內容會被刪除
共用資料夾	安裝時你選取或建立的資料夾內的檔案。	保留	永遠不會刪除
Docker named volume	容器自行管理的狀態。僅限 Compose。	保留	永遠不會刪除
套件帳號與群組	DSM 為套件建立的內部身分。	保留	永遠不會刪除

在版本之間變更資料格式

native-go 專案使用 SDK 套件 github.com/synopackageland/syno-pkg-land-sdk/datamigrate，對資料資料夾套用有編號的 schema 步驟。請把你的步驟加到 backend/internal/app/migrations.go 的 Migrations()：

{
  Version: 1,
  Name:    "example",
  Apply: func(ctx datamigrate.Context) error {
    // Read ctx.DataDir. Write a temporary file, then rename it.
    return nil
  },
},

規則	說明
編號	版本從 1 開始，版本的意義永遠不變。
執行時機	後端在每個請求開始時執行所有待處理的步驟。步驟失敗會讓該請求失敗。
進度	儲存在 `<資料資料夾>/data-version`。
冪等	每個步驟都必須能安全地執行兩次。在版本記錄之前當機，會讓該步驟再執行一次。
失敗	最後一次成功的版本仍保持記錄，下一個請求會從該處繼續。輔助工具本身絕不刪除或改寫資料。
版本	`ctx.OldPkgVer` 是升級前已安裝的套件版本。`ctx.NewPkgVer` 是目前執行的版本。

使用

備份

CLI 不會備份任何東西。解除安裝精靈會說明不會檢查 Hyper Backup，平台也無法確認存在可復原的備份。請把下列項目納入你自己的備份：

納入	時機
`@appdata/<package>`	一律納入。
`@apphome/<package>` 與 `@appconf/<package>`	你的 App 有使用時。
共用資料夾	App 有使用時。
Docker named volume	宣告了它們的 Compose App。

核准與委派不是資料，備份不會還原它們。重新安裝後，管理員需要重新核准，每位使用者也要重新選擇他的目的地。

升級

升級會保留資料資料夾，並執行你的 schema 步驟。安裝精靈會檢查 @appdata/<package> 是否已存在。若已存在，它會告訴管理員此次安裝會沿用該資料，以及如何從空白開始。

解除安裝

解除安裝精靈有一個預設不勾選的核取方塊：「一併刪除上列 App 資料」。精靈會列出它將清空的資料夾，並說明共用資料夾、套件帳號與其他 App 的資料永遠不會被刪除。

選擇	結果
未勾選	資料保留。重新安裝相同的套件名稱會沿用它。
已勾選	清空該套件的 `@appdata` 與 `@apphome`，原生套件另清空 `@appconf`。資料夾本身會保留。若某個資料夾未解析到套件自己的區域內，會略過並顯示訊息。
升級，且已勾選	不會刪除任何東西。

DSM 可能保留空的 @appdata/<package>、@appconf/<package>、@apphome/<package> 與 @appshare/<package> 資料夾、/usr/syno/etc/packages/<package> 連結，以及套件帳號。解除安裝後，管理員可以檢視這些項目、備份想保留的內容，並只移除此套件的殘留。synopkgland inspect 與 status 會印出相同的清單。

應用程式權限與登入入口網站

DSM 會保留已解除安裝 App 在控制台 > 應用程式權限中的規則，之後以相同套件名稱安裝時會再次套用。對宣告 portal 的 App，DSM 會移除別名，但網頁伺服器重新載入前仍會繼續提供該網址。這兩項都只有 root 能清理，所以結果取決於 App 的種類（請見能力）：

種類	應用程式權限規則	登入入口網站網址
Executor App（`delegate` 或 `root-ops`）	解除安裝時由 executor 刪除這個 App 的規則，不論是否勾選資料核取方塊。	DSM 移除別名後，executor 會重新載入網頁伺服器，網址立即停止。
無升權 App	保留。解除安裝精靈會提醒管理員到控制台 > 應用程式權限移除。	無：它不能宣告 `portal`。

executor 會把失敗寫到系統日誌項目 synopkgland-executor，解除安裝照常繼續。解除安裝精靈與 status／inspect 的清理清單只把手動步驟列為這種情況的後備。

管理員核准的意義

只有使用 delegate 或 root-ops 的套件才有核准。請見能力。

事件	核准會怎樣
安裝	在 DSM 管理員於 App 視窗中確認一次密碼之前，`status` 會顯示 `needs-admin-approval`。
停止	executor 暫停。核准、授權與已選的範圍都保留。
升級	executor 先停止，升級後只要已核准的策略仍相符就會恢復。新的 executor 不需要核准：只有當它的 SHA-256 與 Package Center 寫進 root 擁有的 INFO 中的 `synopkgland_executor_sha256` 相符時，root 才會安裝它。否則維持暫停，`status` 顯示 `needs-admin-approval`。已核准的策略不變時，已安裝的 executor 會自行改為釘選新的 executor，不需要新的核准。`install-selected` 範圍會請管理員以密碼確認一次共用資料夾。當你變更 `entry`、delegate 的範圍、目的地、生命週期或操作，或任何 `root/*.sh` 時，需要新的核准。版本號變更、介面變更，或策略相同的新版 SDK 都不需要。
範圍變更、`delegate.disable`、`delegate.enable`	所有委派都會被撤銷，每位使用者要重新選擇目的地。已寫入的檔案會保留。
解除安裝	核准、委派、排程任務 `<package> executor boot`、`<package> executor control` 與 `<package> executor selection`，以及這個 App 的應用程式權限規則都會被移除。重新安裝需要全新的核准。

解除安裝會在背景移除這些任務，並會先檢查它們的名稱、擁有者與腳本。它不會等待任務移除完成，逾時也不會中止解除安裝。被變更或無法驗證的任務會保留，管理員可在控制台 > 任務排程表中檢視。

手動移除殘留

executor App 解除安裝時清理失敗（系統日誌項目 synopkgland-executor 會說明原因），可能留下 root 任務、應用程式權限規則與登入入口網站網址。由管理員手動移除：

殘留	移除方式
`<package> executor control` 與 `<package> executor selection`	控制台 > 任務排程表。
`<package> executor boot`	DSM 拒絕透過 HTTP 刪除（錯誤 119）。以 root 執行 `/usr/syno/bin/synowebapi --exec api=SYNO.Core.EventScheduler method=delete version=1 task_name="<package> executor boot"`。
應用程式權限規則	控制台 > 應用程式權限。
仍能開啟的登入入口網站網址	在控制台 > 登入入口網站 > 應用程式儲存任一別名（會重新載入網頁伺服器），或重新啟動 NAS。

限制

限制	值
解除安裝核取方塊	只刪除套件私有的資料夾：`@appdata`、`@apphome`，原生套件另含 `@appconf`。
共用資料夾、Docker named volume、套件帳號	解除安裝永遠不會刪除。
備份	CLI 與精靈都不會設定，也不會驗證。
Schema 步驟輔助工具	僅限 `native-go`。

疑難排解

症狀	原因	解法
重新安裝後沿用先前的設定	先前的解除安裝保留了資料。	再解除安裝一次並勾選「一併刪除上列 App 資料」，然後安裝。
勾選核取方塊解除安裝後仍留有空資料夾	DSM 會保留資料夾的根目錄。核取方塊只清空其內容。	若不打算重新安裝，請以管理員身分檢視並移除。
升級後出現 `needs-admin-approval`	升級變更了策略，或 INFO 的 executor 錨點缺失或不符。	DSM 管理員在 App 視窗中核准。
排程任務已核准，卻出現 `blocked: executor_status_mismatch`	面板會寫出原因。「the approved executor is not answering (`executor_not_listening`)」：executor 行程不在或已暫停。「the running executor reports other digests than this package pins」：正在執行的 executor 不是這個套件建置時的那一個，例如手動改過的升級。「the executor status request failed」：CGI 無法詢問 executor。	DSM 管理員再按一次「Approve background access」。排程任務已核准時，這會重新啟動 executor，不需要密碼。若是 digest 不同，請重新安裝該 executor 所屬的套件。細節寫在 executor log。
升級後請求失敗	某個 schema 步驟失敗。	修正該步驟。下一個請求會從最後記錄的版本繼續。
解除安裝後，executor App 的應用程式權限規則或登入入口網站網址仍在	executor 的清理失敗。系統日誌項目 `synopkgland-executor` 會說明原因。	到控制台 > 應用程式權限移除規則。在控制台 > 登入入口網站 > 應用程式儲存任一別名，或重新啟動 NAS。