synology-app.yaml 參考

synology-app.yaml 與 compose.yaml 放在同一個專案中，專案由 synopkgland init -t compose 建立，並以 synopkgland check 驗證。schema 接受未知的最上層鍵，但只有下列欄位會生效。以任務為主的說明請見容器 App。

欄位

欄位	型別	必填	預設值	說明
schema	integer	是	無	必須是 1。
package	string	是	無	套件識別名稱。最多 32 個字元（CONTRACT_PACKAGE_TOO_LONG）；超過 28 個字元會得到 PACKAGE_IDENTITY_TOO_LONG，因為 deploy --dev 會加上 .dev。
version	string	是	無	套件版本。沒有 -<數字> 後綴時會自動補上 -0001。
displayname	string	是	無	套件中心顯示的名稱。
description	string	是	無	套件說明。
maintainer	string	是	無	維護者名稱。
os_min_ver	string	是	無	最低 DSM 版本，例如 "7.2.1-69057"。容器 App 的下限是 7.2.1-69057。
adminprotocol	string	否	無	套件 Web 入口的協定。經由 gateway 的 app 不會使用。
adminport	integer	否	無	Web 介面的主機連接埠。必須剛好等於一個已發佈的 TCP 主機連接埠。headless app 請省略。
adminurl	string	否	無	附加在 Web 入口後面的路徑。
install	map	否	無	安裝精靈設定，以名稱為鍵。
install.<name>.type	string	是	無	string、boolean、secret、shared_folder、dsm_user、homes、posix_all_shares 其中之一。
install.<name>.default	string, boolean	否	無	預設值。homes 與 posix_all_shares 不允許。
install.<name>.generate	boolean	否	無	安裝時產生一個值。
integration	map	否	無	app 如何與 DSM 整合。只允許 web。
integration.web	map	否	無	Web 入口設定。需要 adminport。
integration.web.launch	string	否	dsm-window	dsm-window（DSM 主選單與桌面項目，點擊開新的瀏覽器分頁）或 new-page（只有套件中心的開啟）。
integration.web.cookies	list of strings	否	無	要透過 Web Station 轉發的 cookie。只有 access: public 時才有意義；gateway 會丟棄所有 cookie。id 與 did 一律不轉發。
integration.web.access	string	否	dsm-users	dsm-users、dsm-admins、dsm-groups 或 public。
integration.web.groups	list of strings	只有 dsm-groups 時	無	DSM 群組名稱（至少一個）。
integration.web.portal	map	否	無	不可使用。Compose App 沒有 executor；check 會以 CONTRACT_PORTAL_REQUIRES_EXECUTOR 失敗。可改由管理員在 DSM 設定反向代理。
permissions	無	否	無	一律拒絕。
privilege	map	否	無	接受這個區塊只是為了讓錯誤訊息清楚；下列每個旗標一律拒絕。
privilege.privileged	boolean	否	無	一律拒絕（COMPOSE_PRIVILEGED_FORBIDDEN）。
privilege.host_network	boolean	否	無	一律拒絕（COMPOSE_HOST_NETWORK_FORBIDDEN）。
privilege.host_pid	boolean	否	無	一律拒絕（COMPOSE_HOST_PID_FORBIDDEN）。
privilege.host_ipc	boolean	否	無	一律拒絕（COMPOSE_HOST_IPC_FORBIDDEN）。
privilege.devices	boolean	否	無	一律拒絕（COMPOSE_DEVICES_FORBIDDEN）。
privilege.cap_add	boolean	否	無	一律拒絕（COMPOSE_CAP_ADD_FORBIDDEN）。
icon	string	否	SDK 預設圖示	專案內至少 256×256 的正方形 PNG，或含 icon_256.png 的 icon_<size>.png 目錄。用於套件中心與 DSM 視窗（CONTRACT_ICON_INVALID）。
reproducible	object	否	無	build --verify-reproducible 的設定；參閱可重現建置。
reproducible.inputs	string[]	否	無	相對於專案的依賴檔案，以其 SHA-256 組成指紋，例如 compose.yaml。最多 64 個。
reproducible.clean	string[]	否	無	第二次建置前刪除的路徑。可用 {arch}。最多 64 個。
i18n	map	否	無	翻譯。只接受 info（CONTRACT_I18N_INVALID）。
i18n.info	map	否	無	以 zh-TW、zh-CN、ja、ko、de、fr、es 或 it 為 key；英文寫在 displayname 與 description。產生 INFO 的 displayname_<lang> 與 description_<lang>；launch: dsm-window 時也翻譯 DSM 主選單與桌面標籤。
i18n.info.<name>.displayname	string	否	displayname	單行，不含 " 或 \。只要有任何翻譯，頂層 displayname 與 description 也須符合同一規則。
i18n.info.<name>.description	string	否	description	單行，不含 " 或 \。
metadata	map	否	無	套件中心的上架資訊。不允許其他鍵。
metadata.changelog	string, map	否	無	最多 16000 個字元，或最多 32 個語系的 map。
metadata.contact_email	string	否	無	電子郵件地址。
metadata.support_email	string	否	無	電子郵件地址。
metadata.homepage	string	否	無	以 http:// 或 https:// 開頭的 URL。
metadata.source_url	string	否	無	以 http:// 或 https:// 開頭的 URL。
metadata.issues_url	string	否	無	以 http:// 或 https:// 開頭的 URL。
metadata.license	string	否	無	授權名稱。
metadata.maintainer_url	string	否	無	以 http:// 或 https:// 開頭的 URL。
metadata.distributor	string	否	無	發行者名稱。
metadata.distributor_url	string	否	無	以 http:// 或 https:// 開頭的 URL。
metadata.support_url	string	否	無	以 http://、https:// 或 mailto: 開頭的 URL。
metadata.helpurl	string	否	無	以 http:// 或 https:// 開頭的 URL。
metadata.long_description	string, map	否	無	最多 16000 個字元，或最多 32 個語系的 map。
metadata.screenshots	list of strings	否	無	最多 12 個 http:// 或 https:// URL，每個最多 2048 個字元。

字串欄位 package、version、displayname、description、maintainer 與 os_min_ver 不可為空，不可含控制字元，也不可含 ${（CONTRACT_INVALID_STRING）。capabilities 不是容器 App 的欄位（CAPABILITY_UNSUPPORTED）。

安裝設定類型

在 compose.yaml 中以 ${<name>} 引用設定。名稱符合 ^[A-Za-z_][A-Za-z0-9_]*$。

type	精靈欄位	規則
string	文字欄位，不可空白	預設值最多 256 個字元，不可有控制字元，不可有 ${（INSTALL_STRING_TOO_LONG、INSTALL_STRING_INVALID）。
boolean	核取方塊	值是 true 或 false。
shared_folder	共用資料夾選擇器	當作 bind 來源使用。
dsm_user	使用者選擇器	最多一個（CONTRACT_DSM_USER_DUPLICATE）。新增 <name>_UID、<name>_GID 與 <name>_GROUP_1 到 <name>_GROUP_8。建置時會替每個服務設定 user。
posix_all_shares	無	不允許預設值或值。必須當作完整的 bind 來源，不能有後綴。只有 deploy 能填入。
homes	無	check 會警告（CONTRACT_HOMES_UNSUPPORTED）；deploy 會拒絕。不允許路徑或預設值。
secret	無	check 會警告（CONTRACT_SECRET_UNSUPPORTED）；deploy 會拒絕。

Compose 從未引用的 string、boolean、shared_folder、homes 或 posix_all_shares 設定會得到 INSTALL_PARAMETER_UNREFERENCED。宣告了 shared_folder 卻沒有 dsm_user 會得到 DSM_USER_REQUIRED（自己建置時是警告，Community 上架時是錯誤）。

Compose 規則

規則	錯誤碼
不可使用 build:	COMPOSE_BUILD_FORBIDDEN
不可使用 privileged: true	COMPOSE_PRIVILEGED_FORBIDDEN
不可使用 network_mode: host	COMPOSE_HOST_NETWORK_FORBIDDEN
不可使用 pid: host 或 ipc: host	COMPOSE_HOST_PID_FORBIDDEN、COMPOSE_HOST_IPC_FORBIDDEN
不可使用 devices 或 cap_add	COMPOSE_DEVICES_FORBIDDEN、COMPOSE_CAP_ADD_FORBIDDEN
不可掛載 socket（/var/run/docker.sock、Container Manager socket、任何 */docker.sock）	COMPOSE_SOCKET_MOUNT_FORBIDDEN
不可使用主機路徑；專案內的 ./sub 允許	COMPOSE_HOST_BIND_FORBIDDEN
bind 來源：${SYNOPKG_PKGVAR}、${SYNO_APP_SECRETS_DIR}，或 shared_folder、homes、posix_all_shares 設定	COMPOSE_BIND_SOURCE_FORBIDDEN、COMPOSE_BIND_SOURCE_UNDECLARED
${X} 後面的子路徑符合 (/[A-Za-z0-9._-]+)+	COMPOSE_BIND_SUFFIX_INVALID
具名 volume 宣告在最上層 volumes:	COMPOSE_NAMED_VOLUME_UNDECLARED
有 dsm_user 時不設定 user:	COMPOSE_USER_CONFLICTS_DSM_USER
有 shared_folder 時不可使用 user: 0、0:0 或 root	COMPOSE_USER_ROOT_FORBIDDEN
不可使用數字的 user:	COMPOSE_USER_NUMERIC_FORBIDDEN
adminport 的主機連接埠發佈在 127.0.0.0/8 或 ::1	COMPOSE_GATEWAY_PORT_EXPOSED
command 或 entrypoint 清單中不可有純數字字串	COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN
不可使用最上層 secrets: 或 configs:；每個 ${NAME} 都要宣告	COMPOSE_DYNAMIC_ROUTE_UNSUPPORTED
depends_on 指向存在的服務	COMPOSE_SERVICE_NOT_FOUND

未用 digest 固定的 image 會回報為風險，synopkgland images pin 可固定它們。每個錯誤碼的意義請見錯誤碼。