封裝格式

套件定義

一份包含所有可用欄位的完整容器套件定義：

image:
  url: nginx:1.26-alpine
description: Lightweight high-performance web server and reverse proxy
supplies: ["http"]
command: ["optional", "command", "override"]
environment:
  NGINX_HOST: "@hostname@"
network:
  external:
    "@port@": "80"
  internal:
    "5432": "5432"
  domains:
    - "@hostname@"
volumes:
  html:
    mountpoint: /usr/share/nginx/html
    quota: 2gb
    uid: 1000
    gid: 1000
  data:
    mountpoint: /data
    archive: seed-data.tar.gz
questions:
  hostname:
    query: "What hostname should nginx serve?"
    type: hostname
  port:
    query: "What external port should nginx listen on?"
    type: port
    default: "8080"
archives:
  - image: nginx:latest
    directory: /usr/share/nginx/html
    volume: html
git_sources:
  - url: "https://github.com/example/config.git"
    branch: main
    volume: data
templates:
  config:
    volume: data
    path: config.yaml
    content: |
      host: {{ .Responses.hostname }}
      port: {{ .Responses.port }}
      version: {{ .Package.Version }}
notes:
  URL:
    value: "http://@hostname@:@port@"
    type: url
  Support:
    value: "+1 (555) 123-4567"
    type: phone

image 欄位也接受簡寫的字串形式：image: nginx:1.26-alpine。

image 欄位

image 欄位指出要執行的容器映像檔。它接受兩種寫法：

# 物件寫法
image:
  url: nginx:1.26-alpine
  type: oci                # 選用，預設為 "oci"

# 簡寫字串寫法
image: nginx:1.26-alpine

簡短的映像檔名稱會在編譯期間自動正規化：

type 唯一有效的值是 oci（預設值）。映像檔 URL 只能包含 英數字、@、.、_、:、 / 與 -——shell 特殊字元會被拒絕。

網路設定

連接埠值在範本替換之後必須是 1 到 65535 之間的整數。 用不到的話，請整個省略 external、internal 或 domains——不要寫成空的對應或清單。

連接埠項目的鍵可以是數字連接埠字串 （"2222": "22"），也可以是符合 ^[a-zA-Z][a-zA-Z0-9_]*$ 的語意名稱（http: "3000"）。 替連接埠命名之後，上層套件就能依角色參照它（@dep_KEY_port_http@）而不必寫號碼； 而對特殊名稱 http 而言，這也表示讓該連接埠加入下面介紹的共用 HTTP 入口。

HTTP 入口（名為 http 的連接埠）

Town OS 執行著一個共用的 :443 入口， 它為每個套件終結 TLS，並反向代理到該套件的純 HTTP 容器連接埠。 套件只要把某個 internal 連接埠命名為 http，就加入了這個入口：

network:
  internal:
    http: "3000"      # 容器的純 HTTP 連接埠

這麼做之後：

• 服務可透過 https://<PACKAGE_DNS>/ 連上—— 網址中不帶連接埠。沒有主機連接埠需要選；也不要再把 HTTP 連接埠 對應到 external 之下。
• 入口會為 <PACKAGE_DNS>（例如 gitea.default.home）提供一張本地受信任的終端憑證 （由內建的 Rolodex CA 簽發），而且 Rolodex 會在 _443 上發布 DANE TLSA 記錄，讓支援 DANE 的用戶端可以釘選該憑證。
• 由於入口占用了 :443，應用程式產生的任何網址都必須是 不帶連接埠的 HTTPS。請據此設定應用程式的對外網址（例如 gitea 的 GITEA__server__ROOT_URL: "https://@PACKAGE_DNS@/"）， 並讓應用程式在容器內繼續以純 HTTP 監聽。

非 HTTP 的通訊協定（SSH、資料庫等）不可使用 http 這個名稱——它們不是 HTTP，入口無法為其終結 TLS。 請改用數字對應原樣轉送：

network:
  internal:
    http: "3000"          # 由 :443 入口承接，終結 TLS
    "@sshport@": "22"     # 純 TCP 轉送，絕不包上 TLS

面向網際網路的名稱（domains）

預設情況下，入口只服務本地受信任的 <PACKAGE_DNS> 名稱。 若還想以公開受信任的憑證把服務開放到公開網際網路，請把真正的 FQDN 列在 network.domains 之下，並把該名稱的公開 DNS 指向這台主機。 入口會為列出的每個網域取得 ACME（Let’s Encrypt）憑證：

network:
  internal:
    http: "3000"
  domains:
    - git.example.com

封存檔

archives 欄位會在安裝時把容器映像檔中的檔案擷取到磁碟區裡：

archives:
  - image: nginx:latest
    directory: /usr/share/nginx/html
    volume: html

若目標磁碟區在安裝或調節時是空的，Podman 會拉取映像檔、建立一個暫時容器， 並把指定的目錄複製進該磁碟區。

問答

問答定義了套件安裝期間顯示的互動式提示。使用者的回答會取代定義中各處的 @name@ 範本標記。

questions:
  port:
    query: "What external port should nginx listen on?"
    type: port
    default: "8080"

問題型別

布林問題

boolean 問題會顯示為核取方塊而非文字欄位，其答案會以字面字串 true 或 false 替換進去。由於沒勾選同樣是一個真實的答案， 帶 default: "true" 的問題也可以被使用者關掉——明確的 false 會勝過預設值。

environment:
  REGISTRATION_OPEN: "@open@"
  METRICS_ENABLED: "@metrics@"
questions:
  open:
    query: "Allow open registration?"
    type: boolean          # 未作答 -> "false"
  metrics:
    query: "Enable metrics?"
    type: boolean
    default: "true"        # 未作答 -> "true"

檔案範本看到的也是正規化之後的值，因此 {{ .Responses.metrics }} 會算繪成 true 或 false，並且可以用 {{ if eq .Responses.metrics "true" }} 判斷。

選填問題

除非宣告了 optional: true，否則每個問題都必須給出非空的回答。 少了它，那些應用程式確實可以不要的設定——SMTP 轉送、API 金鑰——就沒有誠實的表達方式： 作者只好編一個佔位的預設值，然後祈禱操作者會把它改掉。

environment:
  SMTP_HOST: "@smtp_host@"
  SMTP_PORT: "@smtp_port@"
questions:
  smtp_host:
    query: "SMTP server hostname"
    optional: true
  smtp_port:
    query: "SMTP server port"
    type: port
    optional: true
    default: "587"

留白時，選填問題會在它的 @marker@ 處替換成空字串， 因此應用程式看到的是一個空的變數，而不是某個沒人挑過的值。它絕不會被自動產生： 留白的選填 secret 會保持空白，而不會變成一串隨機字串， 讓應用程式老老實實拿去嘗試驗證。

optional 可以和 type 搭配——已作答的選填連接埠仍會依連接埠驗證， 而留白的則會被編譯掉、什麼都不留。它對 boolean 沒有意義， 因為核取方塊總會落在它的兩個值之一。

OAuth 問題

有些應用程式需要一份只有其廠商才能核發的憑證來設定——Plex 帳號權杖、GitHub 個人權杖—— 而慣常的取得方式是在終端機裡跑個指令稿，再把印出來的東西貼過去。oauth 問題 改為從安裝對話框執行那套流程：操作者按下連線，在瀏覽器分頁中核准， 回傳的權杖就成為答案。

這裡沒有供應商登錄表。問題自帶一個 oauth 區塊， 寫明供應商自己的各個網址，因此任何具備裝置式流程的廠商，都不必改動 Town OS 就能支援。

environment:
  PLEX_TOKEN: "@plextoken@"
questions:
  plextoken:
    query: "Plex account"
    type: oauth
    oauth:
      start:
        method: POST
        url: "https://plex.tv/api/v2/pins?strong=true"
        headers:
          X-Plex-Client-Identifier: "{{client_id}}"
      extract:
        id: id
        code: code
      approve: "https://app.plex.tv/auth#?clientID={{client_id}}&code={{code}}"
      poll:
        url: "https://plex.tv/api/v2/pins/{{id}}"
        headers:
          X-Plex-Client-Identifier: "{{client_id}}"
      token: authToken
      interval: 2s
      timeout: 10m

網址、標頭與表單值中的 {{...}} 佔位符， 會依 extract 所命名的內容解析，另外還有 {{client_id}}——這是 Town OS 為每次流程產生、 並在每一步都送出的隨機識別碼，Plex 正是把它的 pin 綁在這上面。

權杖是一份憑證，因此也就按憑證對待：在套件資訊面板中會被遮罩，可以複製但絕不列印。 它像其他回答一樣會被快取，因此重新安裝或升級時會直接重用，不必再把操作者送回供應商那邊。

由於呼叫這些網址的是系統控制器而非瀏覽器，它們必須是 https， 而且不能解析到回送、私有、連結本機或 CGNAT 位址。這項檢查會在實際建立連線時執行， 每一次重新導向也會再檢查一次，因此套件無法藉由某個流程，讓控制器伸手進主機自己的網路。

註記

註記（notes）提供安裝後顯示的鍵值資訊。

notes:
  URL:
    value: "http://localhost:@port@"
    type: url
  Info:
    value: "Default admin credentials are admin/admin"

相依關係

套件可以宣告對其他套件的相依關係。相依套件會共用上層套件的 podman 網路， 讓同一相依樹中的容器能透過 podman 內建的 DNS，直接以容器名稱通訊。

dependencies:
  db:
    package: postgres
    responses:
      password: "@dbpass@"
      user: "mattermost"
      database: "mattermost"
      port: "5432"

上層套件在執行階段會為每個相依套件取得對應的環境變數： TOWNOS_DEP_{KEY}_HOST（容器名稱）與 TOWNOS_DEP_{KEY}_PORT_{port}（容器側連接埠號）。 上層套件也可以在自己的環境變數值中使用 @dep_KEY_host@ 與 @dep_KEY_port_N@ 範本變數（見範本系統）。

範例：一個對 PostgreSQL 宣告了 db 相依關係的 Mattermost 套件， 可以在它的資料來源網址中參照資料庫主機：

environment:
  MM_SQLSETTINGS_DATASOURCE: "postgres://mattermost:@dbpass@@@dep_db_host@:@dep_db_port_5432@/mattermost?sslmode=disable"

虛擬機器執行環境

套件可以執行虛擬機器而非容器，只要指定 vm 欄位來取代 image：

vm:
  image: "https://example.com/my-vm.qcow2"
  memory: 2gb
  cpus: 2
description: A virtual machine package

vm 欄位與 image 及 proton 互斥。 虛擬機器映像檔不會像容器映像檔那樣被正規化。

編譯

編譯會把套件定義與使用者的回答，轉換成一份完全解析、可直接執行的設定。 編譯管線包含下列步驟：

• 依各問題所宣告的型別驗證全部回答
• 套用型別專屬的驗證（連接埠範圍、主機名稱樣式、位元組剖析等）
• 把所有 @variable@ 範本標記替換成解析後的值
• 把容器映像檔網址正規化為完整限定的參照
• 產出一份可供安裝、已解析的套件

對虛擬機器套件而言，記憶體字串（例如 2gb）會被剖析成位元組數， 並套用 CPU 的預設值。各欄位的驗證錯誤會一併蒐集後一起回傳， 因此使用者可以一次改完，而不必一個一個碰壁。

安裝流程

安裝一個套件會走過一連串既定的步驟。 整個流程涵蓋從檔案準備到服務啟動的一切：

• 從套件庫中的套件檔案到已安裝目錄建立硬連結
• 保存回答（版本專屬的以及 last 副本）
• 建立磁碟區，套用配額與選用的 UID/GID 擁有權
• 從封存檔與 git 來源填入磁碟區（僅限容器執行環境）
• 套用範本（把檔案算繪進磁碟區）
• 產生 systemd unit（容器用 Podman，虛擬機器用 QEMU）
• 建立網路狀態檔
• 啟動服務
• 成功後清除 last 回答

有兩個選用旗標可控制磁碟區的行為：

• reuse_volumes——重用同一套件先前已解除安裝版本的磁碟區
• import_from_version——從指定的舊版本匯入磁碟區

安裝預覽

在真正開始安裝之前，你可以先預覽會建立哪些東西。 安裝預覽端點（POST /packages/install-preview）會回傳一份預定安裝的摘要， 而且不做任何變更：

• 將會建立的磁碟區
• 將會對應的連接埠
• 升級資訊（若是從舊版本升級）
• 執行環境型別（容器或虛擬機器）
• 該套件是否有需要回答的問題
• 虛擬機器套件的虛擬機器設定細節（映像檔、記憶體、CPU 數）

匯入套件庫

建立好套件庫之後，可以透過網頁介面或直接調整檔案系統設定， 把它加進你的 Town OS 執行個體。

透過介面

登入 Town OS 儀表板，前往 套件，選擇 套件庫 分頁，按下 新增套件庫。填入名稱、 git 網址與選用的憑證。按 重新整理 可立即拉取套件中繼資料。

透過檔案系統

編輯 btrfs 套件資料目錄中的 repositories.json。這個檔案是一個 由物件組成的 JSON 陣列：

[
  {"name": "default", "url": "https://github.com/town-os/default-packages"},
  {"name": "my-packages", "url": "https://github.com/myuser/my-packages"}
]

順序是有意義的——當套件名稱衝突時，排在後面的會覆蓋前面的。 私人套件庫請把憑證嵌在網址中。變更需要重新啟動服務，或在介面上按 重新整理 才會生效。

風格指引

• 省略空的對應（environment: 、internal: 、volumes: ）——乾脆整個不寫。
• 接受自由文字的問題請省略 type——不要寫一個沒有值的 type:。
• 寫上 description，簡短說明這個套件是什麼。
• 當套件提供的是眾所周知的服務時，寫上帶有相應能力標籤的 supplies。
• 寫上 notes，包含連線網址以及任何重要的安裝後資訊。
• 用 @variable@ 範本，讓使用者在安裝時自訂連接埠、主機名稱與憑證。
• 需要 Go 範本邏輯的設定檔請使用 templates——它們只會寫入一次，並保留使用者的修改。