打包格式

软件包定义

一份包含全部可用字段的完整容器软件包定义：

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>/ 访问—— URL 中不带端口。没有宿主机端口需要选；也不要再把 HTTP 端口 映射到 external 下。
• 入口会为 <PACKAGE_DNS>（例如 gitea.default.home）提供一张本地受信任的叶证书 （由内置的 Rolodex CA 签发），并且 Rolodex 会在 _443 上发布 DANE TLSA 记录，让支持 DANE 的客户端可以固定该证书。
• 由于入口占用了 :443，应用生成的任何 URL 都必须是 不带端口的 HTTPS。请据此设置应用的对外 URL（例如 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 块， 写明服务商自己的各个 URL，因此任何具备设备式流程的厂商都无需改动 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

URL、请求头和表单值中的 {{...}} 占位符， 会依据 extract 所命名的内容来解析，另外还有 {{client_id}}——这是 Town OS 为每次流程生成、 并在每一步都发送的随机标识符，Plex 正是把它的 pin 绑定在这上面。

令牌是一份凭据，因此也按凭据对待：在软件包信息面板中被掩码，可复制但绝不打印。 它像其他回答一样被缓存，因此重装或升级时会直接复用，而不必让操作者再跑一趟服务商那边。

由于调用这些 URL 的是系统控制器而不是浏览器，它们必须是 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 软件包， 可以在它的数据源 URL 中引用数据库主机：

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@ 模板标记替换为解析后的取值
• 把容器镜像 URL 归一化为完全限定的引用
• 产出一份可供安装的、已解析的软件包

对于虚拟机软件包，内存字符串（例如 2gb）会被解析为字节数， CPU 的默认值也会被套用。各字段的校验错误会一并收集后统一返回， 因此用户可以一次改完，而不必逐个碰壁。

安装流程

安装一个软件包会走完一套既定的步骤序列。 整个过程涵盖从文件准备到服务启动的一切：

• 从仓库中的软件包文件到已安装目录建立硬链接
• 持久化回答（版本专属的以及 last 副本）
• 创建卷，套用配额和可选的 UID/GID 归属
• 从归档和 git 来源填充卷（仅限容器运行时）
• 套用模板（把文件渲染进卷中）
• 生成 systemd 单元（容器基于 Podman，虚拟机基于 QEMU）
• 创建网络状态文件
• 启动服务
• 成功后清除 last 回答

有两个可选标志用于控制卷的行为：

• reuse_volumes——复用同一软件包先前已卸载版本的卷
• import_from_version——从指定的旧版本导入卷

安装预览

在真正开始安装之前，你可以先预览会创建些什么。 安装预览端点（POST /packages/install-preview）会返回一份计划中的安装摘要， 且不做任何改动：

• 将会创建的卷
• 将会映射的端口
• 升级信息（若是从旧版本升级）
• 运行时类型（容器或虚拟机）
• 该软件包是否有需要回答的提问
• 虚拟机软件包的虚拟机配置详情（镜像、内存、CPU 数）

导入仓库

创建好软件包仓库之后，可以通过网页界面或直接修改文件系统配置， 把它添加到你的 Town OS 实例中。

通过界面

登录 Town OS 仪表盘，进入 软件包，选择 仓库 标签页，点击 添加仓库。填入名称、 git URL 和可选的凭据。点击 刷新 可以立即拉取软件包元数据。

通过文件系统

编辑 btrfs 软件包数据目录中的 repositories.json。该文件是一个 由对象组成的 JSON 数组：

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

顺序是有意义的——当软件包重名时，靠后的条目会覆盖靠前的。 私有仓库请把凭据嵌入 URL 中。改动需要重启服务，或在界面上点 刷新 才会生效。

风格指引

• 省略空映射（environment: 、internal: 、volumes: ）——干脆整个不写。
• 接受自由文本的提问请省略 type——不要写一个没有取值的 type:。
• 写上 description，简短说明这个软件包是什么。
• 当软件包提供的是众所周知的服务时，写上带有相应能力标签的 supplies。
• 写上 notes，包含连接 URL 以及任何重要的安装后信息。
• 用 @variable@ 模板，让用户在安装时自定义端口、主机名和凭据。
• 需要 Go 模板逻辑的配置文件请使用 templates——它们只写入一次，并会保留用户的修改。