应用程序配置#

每个应用程序（以前称为加载项，Add-on）都存放在一个文件夹中。文件结构如下所示：

addon_name/
  translations/
    en.yaml
  apparmor.txt
  build.yaml
  CHANGELOG.md
  config.yaml
  DOCS.md
  Dockerfile
  icon.png
  logo.png
  README.md
  run.sh

#应用程序脚本

与每个 Docker 容器一样，您需要一个脚本在容器启动时运行。用户可能会运行许多应用程序，因此如果您正在做简单的事情，建议尝试坚持使用 Bash 脚本。

我们所有的图像也安装了 bashio。它包含一组常用的操作，可用于包含在应用程序中，以减少应用程序之间的代码重复，从而使开发和维护应用程序变得更加容易。

开发脚本时：

• /data 是用于持久存储的卷。
• /data/options.json 包含用户配置。您可以使用 Bashio 来解析此数据。

CONFIG_PATH=/data/options.json

TARGET="$(bashio::config 'target')"

所以如果你的options包含

{ "target": "beer" }

那么之后你的bash文件的环境中就会有一个包含beer的变量TARGET。

#应用程序 Dockerfile

所有应用程序（以前称为加载项，Add-on）都基于最新的 Alpine Linux 镜像。Home Assistant 会根据机器架构自动替换为正确的基础镜像。如果您需要使用不同时区，请添加 tzdata；我们的基础镜像已包含该软件包。

ARG BUILD_FROM
FROM $BUILD_FROM

# Install requirements for app
RUN \
  apk add --no-cache \
    example_alpine_package

# Copy data for app
COPY run.sh /
RUN chmod a+x /run.sh

CMD [ "/run.sh" ]

如果您不在设备上使用本地构建或我们的构建脚本，请确保 Dockerfile 还具有一组标签，其中包括：

LABEL \
  io.hass.version="VERSION" \
  io.hass.type="addon" \
  io.hass.arch="armhf|aarch64|i386|amd64"

可以将您自己的基础映像与build.yaml一起使用，或者如果您不需要自动多架构构建的支持，您也可以使用简单的dockerFROM。您还可以在 Dockerfile 后添加特定架构的后缀，以针对特定架构使用特定的 Dockerfile，即 Dockerfile.amd64。

#构建参数

我们默认支持以下构建参数：

#应用程序配置

应用程序（以前称为附加组件）的配置存储在config.yaml 中。

name: "Hello world"
version: "1.1.0"
slug: folder
description: >-
  "Long description"
arch:
  - amd64
url: "website with more information about the app (e.g., a forum thread for support)"
ports:
  123/tcp: 123
map:
  - type: share
    read_only: False
  - type: ssl
  - type: homeassistant_config
    read_only: False
    path: /custom/config/path
image: repo/{arch}-my-custom-addon

#所需的配置选项

#可选配置选项

#选项/架构

options 字典包含所有可用选项及其默认值。将默认值设为 null，或在 schema 字典中定义数据类型，即可把某个选项设为必填。这样，用户必须在应用程序（以前称为加载项，Add-on）启动前提供该选项。支持嵌套数组和字典，最大深度为 2。

要使选项真正可选（没有默认值），需要使用 schema 字典。将 ? 放在数据类型的末尾，并且不要在 options 字典中定义任何默认值。如果给出任何默认值，则该选项将成为必需值。

message: "custom things"
logins:
  - username: beer
    password: "123456"
  - username: cheep
    password: "654321"
random:
  - haha
  - hihi
link: "http://example.com/"
size: 15
count: 1.2

options=$(bashio::addon.options)
old_key='test'
if bashio::jq.exists "${options}" ".${old_key}"; then
    bashio::log.info "Removing ${old_key}"
    bashio::addon.option "${old_key}"
fi

schema 看起来像options 但描述了我们应该如何验证用户输入。例如：

message: str
logins:
  - username: str
    password: str
random:
  - "match(^\\w*$)"
ssh:
  private_key: str
  public_key: str
link: url
size: "int(5,20)"
count: float
not_need: "str?"

我们支持：

• str / str(min,) / str(,max) / str(min,max)
• @@保护0@@
• int / int(min,) / int(,max) / int(min,max)
• float / float(min,) / float(,max) / float(min,max)
• @@保护0@@
• @@保护0@@
• @@保护0@@
• @@保护0@@
• @@保护0@@
• 列表（val1 | 值2 | ...)
• device / device(filter)：设备过滤器可以采用以下格式：subsystem=TYPE，即串行设备的subsystem=tty。

#应用程序扩展构建

应用程序的其他构建选项存储在build.yaml中。该文件将从我们的构建系统中读取。 仅当您不使用默认图像或需要其他东西时才需要这样做。

build_from:
  armhf: mycustom/base-image:latest
args:
  my_build_arg: xy

我们提供了一组基础镜像，应该可以满足很多需求。如果您不想使用基于 Alpine 的版本或需要特定的图像标签，请随时使用 build_from 选项为您的构建固定此要求。

#应用程序翻译

应用程序（以前称为加载项，Add-on）可以为 UI 中使用的配置选项提供翻译文件。

翻译文件的示例路径：addon/translations/{language_code}.yaml

对于{language_code}，请使用有效的语言代码，例如en，对于full list have a look here，en.yaml 将是有效的文件名。

该文件支持 2 个主键configuration 和network。

#配置翻译

configuration:
  ssl:
    name: Enable SSL
    description: Enable usage of SSL on the webserver inside the app
  ssh:
    name: SSH Options
    description: Configure SSH authentication options
    fields:
      public_key:
        name: Public Key
        description: Client Public Key
      private_key:
        name: Private Key
        description: Client Private Key

在本例中，configuration (ssl) 下的密钥需要与 schema 配置中的密钥（在 config.yaml 中）相匹配。

#端口描述翻译

network:
  80/TCP: The webserver port (Not used for Ingress)

在本例中，network (80/TCP) 下的密钥需要与 ports 配置中的密钥（在 config.yaml 中）相匹配。

#应用程序高级选项

有时，应用程序开发人员可能希望允许用户配置以提供自己的文件，然后将这些文件作为其配置的一部分直接提供给内部服务。一些例子包括：

1. 内部服务需要一个已配置项目的列表，并且每个项目的架构都很复杂，但该服务没有提供用于执行此操作的 UI，更容易将用户指向其文档并请求该架构中的文件。
2. 内部服务需要二进制文件或外部配置的某些文件作为其配置的一部分。
3. 内部服务支持配置更改时的实时重新加载，并且您希望通过询问用户在其架构中提供要实时重新加载的文件来支持其部分或全部配置。

在这种情况下，您应在加载项的配置文件中把 addon_config 添加到 map。然后告知用户将该文件放入 /addon_configs/{REPO}_<your addon's slug> 文件夹中。如果应用程序安装自本地，{REPO} 将是 local；如果应用程序来自 GitHub 仓库，{REPO} 则是根据仓库 URL 生成的哈希标识符（例如：https://github.com/xy/my_hassio_addons）。 该文件夹会在运行时挂载到加载项的 Docker 容器内的 /config。您应在加载项的 schema 中提供一个选项，用来收集相对于该文件夹的文件路径，或者依赖固定文件名并在文档中说明。

addon_config 的另一个用例，是让加载项提供基于文件的输出，或允许用户访问内部文件进行调试。一些例子包括：

1. 内部服务日志记录到一个文件，并且您希望允许用户访问该日志文件
2. 内部服务使用数据库，并且您希望允许用户访问该数据库进行调试
3. 内部服务生成旨在在其自己的配置中使用的文件，并且您也希望允许用户访问它们

在这种情况下，您应将 addon_config:rw 添加到 map，以便加载项可以读写该文件夹。然后，在加载项运行时把这些文件写入 /config，让用户能够查看并访问它们。