打包 Docker 应用

Docker 应用打包主要包含以下步骤：

• 准备应用镜像（构建并导出为 tar 文件）
• 使用开发者工具 ugcli 创建 Docker 应用项目
• 编写应用配置文件 project.yaml
• 编写 docker-compose.yaml 并配置 compose 变量
• 将应用镜像拷贝到应用项目对应架构的 images 目录下
• 制作应用图标并拷贝到应用项目的 rootfs_common 目录下
• 使用开发者工具 ugcli 打包应用

下面将介绍如何从零开始打包一个 Docker 应用并生成 UPK 安装包，包括项目结构、配置说明与 compose 设置。

准备应用镜像

Docker 应用是以 Docker 镜像 为载体，你需要先完成镜像的构建与导出。

构建镜像

使用 Dockerfile 在本地或 CI 中构建镜像，并确保镜像可在目标架构（如 amd64、arm64）上运行。示例：

FROM alpine:3.18
RUN apk add --no-cache your-runtime
COPY . /app
WORKDIR /app
ENTRYPOINT ["/app/entrypoint.sh"]

构建并打标签，例如：

docker build -t docker.io/mycompany/myapp:0.1.0 .

导出为 tar

使用 docker save 导出镜像生成 tar 文件， 示例：

# 导出当前架构镜像为 tar（可按需对 amd64/arm64 各导出一份）
docker save -o myapp-0.1.0.tar docker.io/mycompany/myapp:0.1.0

最终你需要为每个支持的架构准备至少一个镜像 tar 文件，并在后续步骤中放入项目目录 rootfs_<arch>/images/ 下。

应用镜像 tar 文件规范

• 应用有使用的镜像都需要导出为独立的 tar 文件。
• 每个镜像 tar 文件只能有一个 tag，且与 docker-compose 中配置使用的一致。
• 应用如果同时支持 amd64 和 arm64 架构，需要分别导出两个架构的 tar 文件。

创建应用项目

运行 ugcli create com.mycompany.docker.myapp 创建应用项目。在交互中选择 「是否为 Docker 应用」 为是，完成创建后会在当前目录下生成项目目录，结构如下：

com.mycompany.docker.myapp
├── project.yaml              # 应用配置文件
├── rootfs_amd64              # amd64 架构
│   └── images                # 放置该架构的镜像 tar 文件
├── rootfs_arm64              # arm64 架构
│   └── images                # 放置该架构的镜像 tar 文件
└── rootfs_common             # 各架构共用
    ├── icon.png              # 应用图标
    └── docker-compose.yaml   # Compose 编排文件（见下节）

目录规范

• rootfs_common 下 仅允许 icon.png 和 docker-compose.yaml 文件。
• 各架构目录下 仅允许 images/ 且其中只放 .tar 镜像文件。

编写应用配置文件

修改项目根目录下的 project.yaml，配置应用基本信息及 Docker 应用相关必填配置项。Docker 应用与原生应用的主要区别如下：

• 必需设置 is_docker_app: true
• 必需设置 depend_docker_version，依赖 Docker 套件
• 通过 parameters 定义安装时可配置项，这些配置项会作为 compose 中的变量使用

示例：

spec_version: "2.1"
app_id: com.mycompany.docker.myapp
version: 0.1.0
support_arch:
  - amd64
  - arm64
is_docker_app: true
only_admin: true
port: 29090
open_type: tab
tag_types:
  - utility
depend_fw_version: 1.13.0.0000
depend_docker_version: 1.7.0.0000
parameters:
  - key: PATH
    type: path
    multi: true
    required: true
    i18n:
      en-US:
        name: Resource Access Paths
        description: Multiple paths can be configured
      zh-CN:
        name: 资源访问路径
        description: 可配置多个路径
  - key: ACCOUNT
    type: string
    i18n:
      en-US:
        name: Login Account
        description: 6-8 characters
      zh-CN:
        name: 登录账号
        description: 长度6-8位
i18n:
  en-US:
    name: My Docker APP
    description: My Docker APP Desc
    author: My Company
    official: https://myapp.example.com
    help: https://myapp.example.com/help
    publisher: My Company
    publisher_link: https://mycompany.example.com
  zh-CN:
    name: 我的Docker应用
    description: 我的Docker应用描述
    author: 演示应用开发者
    official: https://myapp.example.com.cn
    help: https://myapp.example.com.cn/help
    publisher: 演示应用发布者
    publisher_link: https://mycompany.example.com.cn

parameters 配置项

parameters 是一个数组，每个元素对应一个配置项，用于声明安装/配置应用时可输入的变量。 Compose 中引用的变量名（${VAR}）需要与配置项的 key 一致。

配置项字段说明：

字段	类型	必填	说明
key	string	是	配置项标识（变量名），建议使用大写加下划线，例如 ACCOUNT、LOG_LEVEL。
type	string	是	配置项类型，可选：string、path、number、password。
multi	bool	否	是否支持多个值。
required	bool	否	是否必填。
changeable	bool	否	安装完成后是否允许修改。
max_length	int	否	输入最大长度，0 表示不限制。
min_length	int	否	输入最小长度，0 表示不限制。
max_values_count	int	否	最多可配置值数量，仅当 multi: true 时生效。
verify_regexp	string	否	输入值校验正则表达式，为空表示不校验。
i18n	map	是	多语言展示信息，key 为语言代码（如 en-US、zh-CN），value 为配置项名称与描述。

i18n.<lang> 字段如下：

字段	类型	必填	说明
name	string	是	配置项名称（界面展示名）。
description	string	是	配置项说明（填写规范、格式约束、示例等）。

配置项类型说明：

type 值	含义	典型场景	示例值	备注
string	普通字符串	账号、开关标识、日志级别等文本参数	admin、INFO	可结合 min_length / max_length / verify_regexp 做格式约束。
path	路径类型字符串	挂载到容器内的目录或文件路径	/mnt/user/data	需要多路径时可配合 multi: true 使用。
number	数字类型输入	端口、重试次数、阈值等数值参数	8080、3	用户配置时会限制只能输入数字。
password	敏感字符串	密码、令牌、密钥等敏感信息	MySecret123	用于需要隐藏展示的输入项。

• multi 建议主要用于 type: path 场景（如多个挂载路径）。
• 其他类型通常使用单值（multi: false），避免与实际变量使用方式不一致。

编写 Docker Compose 文件

Docker 应用在 rootfs_common 下放置 docker-compose.yaml（标准 Docker Compose 格式）。

文件位置与格式

• 路径：rootfs_common/docker-compose.yaml
• 格式：标准 Docker Compose（如 Compose Spec v2/v3），使用 变量语法 ${VAR} 引用在 parameters 声明的配置项，变量名 VAR 与配置项的 key 一致。

变量来源

1. 内置变量（无需在 project.yaml 的 parameters 中声明，由 Docker 套件在安装时注入）：

   • TZ：时区，例如 Asia/Shanghai

2. 安装参数变量：与 project.yaml 中 parameters 的 key 一一对应（区分大小写）。用户在安装/配置应用时填写的值会替换到 compose 中。

   • 若某变量在 compose 中被使用，则应在 parameters 中定义对应 key。
   • 建议变量命名使用大写加下划线（如 ACCOUNT、LOG_LEVEL），便于与普通字符串区分。

示例（project.yaml 与 compose 对应关系）：

# project.yaml
parameters:
  - key: PATH
    type: path
    multi: true
    required: true
  - key: ACCOUNT
    type: string
    required: true
  - key: LOG_LEVEL
    type: string
    required: false

在 compose 中引用变量

在 docker-compose.yaml 中可直接引用上述变量，例如：

services:
  app:
    image: docker.io/mycompany/myapp:0.1.0
    volumes:
      - ./config:/opt/myapp
      - ${PATH}
    network_mode: bridge
    ports:
      - 29090:9090
    environment:
      - UMASK=022
      - TZ=${TZ}
      - ACCOUNT=${ACCOUNT}
      - LOG_LEVEL=${LOG_LEVEL}
    restart: always

• 镜像：image 需与放入 rootfs_<arch>/images/ 的 tar 中镜像包含的 tag 一致，且不能使用 latest。
• 多值参数：parameters 中 type: path 且 multi: true 时，在 compose 中会按多值处理（如挂载多路径）；其他类型在模板中为单值。

安全与规范建议

• 不可使用 privileged、cap_add、 host pid/ipc，避免使用 host 网络，打包时将会检测并进行告警提示。
• 仅使用已在 parameters 中声明的 key 或内置变量（如 TZ），避免未定义变量导致打包时校验失败。

拷贝应用镜像与图标

• 镜像：将各架构的镜像 tar 文件放入对应目录：
  • amd64：rootfs_amd64/images/ 下，例如 rootfs_amd64/images/myapp-0.1.0.tar
  • arm64：rootfs_arm64/images/ 下，例如 rootfs_arm64/images/myapp-0.1.0-arm64.tar
• 图标：制作 256×256 PNG 图标（参考通用图标规范），替换 rootfs_common/icon.png。（开发阶段可暂用默认图标。）

打包应用

在应用项目根目录下执行：

ugcli pack --build 1

• --build 为构建号，与 project.yaml 中的 version 一起组成最终版本号（如 0.1.0 使用构建号 1 则最终版本号为 0.1.0.1）。
• 可指定 --arch amd64 或 --arch arm64 仅打某一架构，默认按 support_arch 生成。

生成的 UPK 文件位于 build_dir/，命名格式：{amd64|arm64}_{appid}_{version}.upk。