App 配置#

每个 app（以前称为 add-on）都存储在一个文件夹中。文件结构如下：

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

#App 脚本

与每个 Docker 容器一样，你需要一个脚本在容器启动时运行。用户可能会运行许多 app，因此如果你做的是简单的事情，建议使用 Bash 脚本。

我们所有的镜像还安装了 bashio。它包含一组常用操作，可以在 app 中使用以减少 app 之间的代码重复，从而使 app 更容易开发和维护。

在开发你的脚本时：

• /data 是用于持久化存储的 volume。
• /data/options.json 包含用户配置。你可以使用 Bashio 来解析这些数据。

CONFIG_PATH=/data/options.json

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

因此如果你的 options 包含

{ "target": "beer" }

那么在 bash 文件的环境中将会有一个包含 beer 的变量 TARGET。

#App Dockerfile

大多数 app（以前称为 add-on）都基于最新的 Alpine Linux 镜像。如果需要运行在不同的时区，请添加 tzdata。tzdata 已经添加到我们的 base 镜像中。

FROM ghcr.io/home-assistant/base:latest

# 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" ]

如果你没有使用 Home Assistant GitHub builder actions（请参见 Publishing your app），请确保 Dockerfile 也包含一组 labels，其中包括：

LABEL \
  io.hass.version="VERSION" \
  io.hass.type="app" \
  io.hass.arch="aarch64|amd64"

#构建参数

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

#App 配置

app（以前称为 add-on）的配置存储在 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: ghcr.io/my-org/my-app

#必填配置选项

#可选配置选项

#选项 / Schema

options 字典包含所有可用选项及其默认值。将默认值设置为 null 或在 schema 字典中定义数据类型，即可使某个选项成为必填项。这样，在 app（以前称为 add-on）启动之前需要用户提供该选项。支持嵌套数组和字典，最大深度为二。

要使某个选项真正可选（没有默认值），需要使用 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)
• bool
• int / int(min,) / int(,max) / int(min,max)
• float / float(min,) / float(,max) / float(min,max)
• email
• url
• password
• port
• match(REGEX)
• list(val1|val2|...)
• device / device(filter)：设备过滤器可以使用以下格式：subsystem=TYPE，即 subsystem=tty 用于串口设备。

#App 翻译

app（以前称为 add-on）可以为 UI 中使用的配置选项提供翻译文件。

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

{language_code} 使用有效的语言代码，如 en，完整列表请参见此处，en.yaml 将是一个有效的文件名。

此文件支持 2 个主要 key：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 下的 key（此例中为 ssl）需要与你的 schema 配置中的一个 key 相匹配（在 config.yaml 中）。

#端口描述翻译

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

此处在 network 下的 key（此例中为 80/TCP）需要与你的 ports 配置中的一个 key 相匹配（在 config.yaml 中）。

#App 高级选项

有时 app 开发者可能希望允许用户配置提供自己的文件，这些文件随后将直接提供给内部服务作为其配置的一部分。一些示例包括：

1. 内部服务需要配置项的列表，且每项的 schema 很复杂，但服务没有提供 UI 进行设置，更简单的做法是将用户指向其文档并请求一个符合该 schema 的文件。
2. 内部服务需要一个二进制文件或作为其配置一部分的外部配置文件。
3. 内部服务支持配置变更时的实时重新加载，你希望为其部分或全部配置支持此功能，方法是要求用户提供一个符合其 schema 的文件进行实时重新加载。

在这些情况下，你应该在你的 app 配置文件的 map 中添加 addon_config。然后你应该指导用户将该文件放入 /addon_configs/{REPO}_<your addon's slug> 文件夹中。如果 app 在本地安装，{REPO} 将为 local。如果 app 从 GitHub 仓库安装，{REPO} 是从 GitHub 仓库 URL 生成的哈希标识符（例如：https://github.com/xy/my_hassio_addons）。 此文件夹在 app 的 docker 容器运行时将挂载在 /config 下。你应该在 app 的 schema 中提供一个选项来收集从该文件夹开始的相对文件路径，或者依赖固定的文件名并将其包含在文档中。

addon_config 的另一种用途可能是你的 app 想要提供基于文件的输出，或让用户访问内部文件以进行调试。一些示例包括：

1. 内部服务将日志记录到文件，你希望允许用户访问该日志文件
2. 内部服务使用数据库，你希望允许用户访问该数据库以进行调试
3. 内部服务生成一些文件，这些文件打算在其自身配置中使用，你希望允许用户访问它们

在这些情况下，你应该在 map 中添加 addon_config:rw，这样你的 app 就可以向该文件夹写入以及从中读取。然后你应该在 app 运行时将这些文件写出到 /config，以便用户可以看到和访问它们。