交付

你建置未簽章的 SPK，不安裝就先檢查，再用 deploy 或手動安裝裝到 NAS，並用 status 讀取狀態。CLI 不會簽章、發佈或提交套件。

設定

建置

synopkgland check
synopkgland build --arch x86_64

build 會寫出 dist/<package>-<version>-<build>-<arch>.spk，例如 dist/MyApp-0.1.0-0001-x86_64.spk。省略 --arch 時，會建置 arches 內的所有架構。--out-dir 可更改資料夾。-o 指定單一檔名，且需搭配單一 --arch。

專案	架構	輸出
native-go、binary	x86_64、aarch64、armv7	每個架構一個 SPK。該架構必須在 arches 內。init -t native-go 不會把 armv7 放進 arches；要建置或部署到 armv7 NAS 前請自行加入。
compose	x86_64、aarch64	一個名為 <package>.spk 的 SPK。使用 Web gateway 時，每個架構一個 SPK：<package>-x86_64.spk 與 <package>-aarch64.spk。

第一次建置前，請在 frontend/ 執行 npm install 安裝 Vue 介面的相依套件。請見快速開始。

檢查

synopkgland inspect dist/MyApp-0.1.0-0001-x86_64.spk

inspect 讀取 SPK，不會安裝。第一個區段檢查 DSM 7 套件格式，每個錯誤與警告都附 SPK 規則碼。synopkgland 建置的 SPK 另有第二個區段檢查建置合約，回報套件與版本、平台、SPK 是否已簽章、能力以及哪些需要管理員核准、檔案，以及解除安裝後要檢視哪些目錄。任一區段發現錯誤時會失敗；只有警告不會失敗。

inspect 也能檢查其他工具建置的 SPK，這時只執行 DSM 格式區段。請見封裝指令碼與直譯式語言。

部署

synopkgland deploy --dry-run --arch x86_64
synopkgland deploy --host my-nas

--dry-run 只輸出計畫，絕不連線。deploy --host 會為單一架構建置一個 SPK、安裝，並印出狀態。--host 為必填（HOST_REQUIRED）。

--host 可接 synoagentcli profile 名稱、profile 的主機名稱或 URL，或單純的主機名稱。CLI 依下列順序尋找憑證：

順序	來源
1	~/.synoagentcli/setting.json 中的 profile，且它含有 URL、使用者名稱與密碼。
2	只有 URL 的 profile：使用 DSM_PASSWORD 與 DSM_USERNAME（預設 admin）。
3	沒有 profile：使用 DSM_URL 與 DSM_PASSWORD，以及 DSM_USERNAME（預設 admin）。單純的 --host 值會變成 http://<host>:5000。

CLI 會讀取目前資料夾或上層資料夾中的 .env 檔，且不會覆蓋已設定的變數。請不要把 .env 放進版本控制。NAS_CREDENTIALS_MISSING 表示這些來源都沒有提供密碼。

省略 --arch 時，deploy 會從 NAS 讀取 CPU 廠商：

CPU 廠商	架構
Intel、AMD	x86_64
Realtek、Rockchip	aarch64
Annapurna	armv7
其他	以 DEPLOY_ARCH_UNDETERMINED 失敗。請傳入 --arch。

native-go 與 binary 專案不接受 Compose 選項 --share、--run-as 與 --param（CLI_OPTION_INVALID），也不接受 --dev（DEVELOPMENT_INSTANCE_UNSUPPORTED）。

讀取狀態與記錄

synopkgland status --host my-nas
synopkgland logs --host my-nas

status 會印出安裝狀態、DSM 狀態（或 NOT_INSTALLED）、Open URL，以及每項已宣告能力的狀態：ready、needs-admin-approval、unsupported 或 blocked。請見能力。加上 --json 會得到 {ok, command, data}；錯誤則是 {ok: false, code, message, hint}。

logs 會逐行印出套件中心對該套件的狀態，接著印出套件名稱與就緒狀態。它不是 App 記錄。它會執行 synoagentcli，因此即使你使用 DSM_* 變數，也必須安裝該工具。套件未安裝時會回傳 NOT_INSTALLED。logs 沒有 --json。

既有原生產品可用 deploy 建置並安裝 NAS 架構的 SPK，並用 status 回報安裝狀態。logs 不適用於它。

使用

版本與升級

欄位	規則
version	以點分隔的數字，最多四段，例如 0.1.0 或 1.2.3.4。
build	1 到 9999 的整數。

套件版本是 <version>-<build>，build 補成四位數，例如 0.1.0-0001。套件中心會顯示它，SPK 檔名也包含它。

deploy 會比較你的版本與已安裝的版本。當 version 較高，或 version 相同且 build 高於已安裝的 build 時才會安裝。相同的 version 搭配相同或較低的 build，會以 DEPLOY_VERSION_INVALID 失敗。較低的 version 會以 DEPLOY_VERSION_INVALID 失敗，訊息為 “Refusing downgrade”。交給別人的每個 SPK 都請提高 build，功能版本則提高 version。

Compose 專案的 deploy 會替你選擇下一個 build 編號。升級會保留 App 資料，請見資料與移除。若套件使用 delegate 或 root-ops，升級會暫停 executor，並只在已核准的 pins 仍相符時才恢復；否則需要管理員重新核准。請見能力。

把 SPK 交給別人

1. 傳送符合 NAS CPU 的 .spk。inspect 會列出 SPK 內的平台。
2. 在 NAS 上的套件中心選擇「手動安裝」並選取檔案。
3. 此 SPK 未簽章，安裝前 DSM 可能會顯示警告。只在你信任檔案來源時繼續。
4. 若使用 delegate 或 root-ops，由 DSM 管理員開啟 App 並核准一次。

CLI 沒有任何指令能提交到 Package Source 或其他目錄。使用者可以在套件中心加入 https://packages.synopkgland.com/，安裝已上架的套件。

限制

限制	值
簽章	SPK 一律未簽章。
deploy	每次執行一個架構。
最低 DSM 版本	dsm-package.yaml 的 os_min_ver。native-go 與 binary 預設 7.1-42661，compose 預設 7.2.1-69057。init 與 build 的 --min-dsm 接受 7.0、7.1、7.2、7.2.1，或完整的 7.x-build 值。
Compose 建置工具	Web gateway 建置需要 Go 1.21 或更新版本，並固定以 Go 1.26.9 建置（GATEWAY_GO_MISSING）。
既有原生產品	只支援 build、check 與 inspect。其 build 範圍為 1 到 2147483647。

疑難排解

症狀或錯誤碼	原因	解法
STANDALONE_UI_BUILD_FAILED	介面建置失敗，或相依套件尚未安裝。	在 frontend/ 執行 npm install，再重新 build。
STANDALONE_GO_MISSING	路徑中找不到 go。	安裝 Go 1.25 或更新版本。
STANDALONE_ARCH_NOT_DECLARED	--arch 指定的架構不在 arches 內。	把它加到 dsm-package.yaml 的 arches。
HOST_REQUIRED	deploy、status 或 logs 沒有 --host。	傳入 --host，或使用 deploy --dry-run。
NAS_CREDENTIALS_MISSING	沒有 profile，也沒有 DSM_URL 與 DSM_PASSWORD。	建立 synoagentcli profile，或設定這些變數。
DEPLOY_ARCH_UNDETERMINED	無法辨識 NAS 的 CPU 廠商。	傳入 --arch x86_64、aarch64 或 armv7。
DEPLOY_VERSION_INVALID	version 與已安裝的相同，且 build 沒有更高。	提高 build 或 version。
DEPLOY_VERSION_INVALID，訊息為 “Refusing downgrade”	version 低於已安裝的版本。	把 version 提高到超過已安裝的版本。
logs 回傳 NOT_INSTALLED	該 NAS 上尚未安裝此套件。	先執行 deploy。
delegate 或 root-ops 為 blocked	status 無法把已安裝的版本對應到已建置的 SPK。	在此專案建置已安裝的版本（dist/<package>-<version>-<arch>.spk），再重新執行 status。

其他錯誤碼請到錯誤碼查詢。

相關連結

• 快速開始
• 能力
• 資料與移除
• CLI
• 平台