配置（oakapp.toml）

每个应用目录下都必须有一个 oakapp.toml 文件，其中包含应用的静态元数据和构建步骤。元数据包括应用的标识符和版本。构建步骤是在容器中执行以构建或运行应用的命令。示例 oakapp.toml 文件：

Toml

1# (必需) 应用标识符
2identifier = "com.luxonis.python_demo"
3# (必需) 应用入口点
4entrypoint = ["bash", "-c", "python3 /app/main.py"]
5
6# (可选) 准备容器命令
7# 这里是您可以在运行时安装所有依赖的地方
8prepare_container = [
9    { type = "COPY", source = "requirements.txt", target = "requirements.txt" },
10    { type = "RUN", command = "apt-get update" },
11    { type = "RUN", command = "apt-get install -y python3-pip" },
12    { type = "RUN", command = "pip3 install -r /app/requirements.txt --break-system-packages" },
13]
14
15# (可选) 准备构建依赖
16# 这里是您可以在构建时安装所有依赖的地方
17prepare_build_container = [
18    # 示例: npm, gcc, ...
19]
20
21# (可选) 所有应用程序文件复制到容器后的附加命令
22build_steps = []

配置字段

应用元数据

identifier - 应用名称，采用 Java 风格的格式（以点号分隔；例如 com.my_company.my_app）
- com.luxonis 命名空间保留用于官方应用
- com.example 命名空间不推荐用于生产应用
app_version - 应用版本，格式为 major.minor.patch（例如 1.0.0）

应用构建与运行时配置

entrypoint - 字符串数组（argv 格式的命令）
cwd -（可选，默认为 /）容器的当前工作目录
shell -（可选，默认为 ["/bin/bash", "-c"]）用于执行 build_steps、entrypoint 以及 prepare_container 和 prepare_build_container 部分中的 RUN 命令的 shell
app_dir_name（可选/高级，默认为 app）- 容器内部用于存放应用文件的目录；仅当你已经将此目录名用于其他用途时才使用

Shell 格式与可执行格式

与 Docker 类似，所有命令既可以指定为可执行格式（字符串数组），也可以指定为 shell 格式（单个字符串）。对于 entrypoint，我们强烈建议使用可执行格式。

应用层

与 Docker 类似，应用由多个层构成：

基础镜像层（在 base_image 部分指定）
运行时层（在 prepare_container 部分构建）
构建层（在 prepare_build_container 部分构建；构建后该层与运行时层分离）
应用层（应用目录中的所有文件以及 build_steps 在此执行）

注意

用 Docker 术语来说，每一层对应一个 Dockerfile 中的 RUN 指令。

这既能实现高效缓存，又能避免常见问题。

除了应用层外，还有两个并行的附加层：

静态前端层（如果在 static_frontend 部分指定）
DepthAI 模型缓存层（如果在 depthai_models 部分指定）

如果其中任何一层发生变化，后续所有层都会被重建。并行层之间没有相互依赖关系，因此彼此独立重建。

基础镜像

默认基础镜像是 debian/bookworm-slim，从 registry-1.docker.io 拉取。完整的 base_image 配置如下：

Toml

1[base_image]
2api_url = "https://registry-1.docker.io" # Optional: Service https address
3service = "registry.docker.io" # Optional: Name of Image Registry Service
4image_name = "library/debian"
5image_tag = "bookworm-slim"
6
7oauth_url = "https://auth.docker.io/token" # Optional: address to oauth 2.0 token for this service
8auth_type = "repository" # Optional: scope type
9auth_name = "library/debian" # Optional: name of resource

建议

对于 DepthAI OAK 应用，我们推荐使用我们的基础镜像，其中包含了你可能需要的多数依赖。

使用自定义基础镜像

如果你已经在使用 Docker 进行开发，可以通过将 base_image 指向你自己的镜像，在 OAK 应用中复用之前的工作。当你希望先以熟悉的 Docker 工作流程对操作系统包、运行时或共享依赖进行迭代，然后再通过 oakapp.toml 打包最终应用时，这种方法非常有用。如果你正在开发一个可复用的基础环境，并希望在多个应用之间共享它，这也是一种很好的选择。使用自定义基础镜像来搭建稳定、共享的环境，同时使用 prepare_container 和 prepare_build_container 来处理应用特定的运行时和构建步骤。要使用不同的镜像作为基础层，在 oakapp.toml 中按如下方式定义：

Toml

1[base_image]
2image_name = "myorg/my-base"
3image_tag = "latest"

默认情况下，镜像从 Docker Hub 拉取，但你也可以通过 api_url 字段将 base_image 指向其他仓库。

Docker Hub 未验证的拉取

oak-agent 当前从 Docker Hub 进行未验证的拉取。在多次拉取或从共享网络进行构建后，Docker Hub 可能会因为匿名拉取速率限制而拒绝请求。为避免这种情况，请参阅自建容器仓库。如果发生该情况，构建可能会失败，并显示类似如下的错误：

1oakctl command failed:
2   0: Received an error RPC response: Failed to build application container:
3      Image download failed: OCI registry client received an error:
4      APIError(ErrorList { errors: [Error { code: "TOOMANYREQUESTS", message:
5      "You have reached your unauthenticated pull rate limit.
6      https://www.docker.com/increase-rate-limit", detail: Null }] })

自托管容器注册表

为了避免 Docker Hub 的速率限制，你可以在开发期间自托管一个容器注册表，并将 base_image.api_url 指向它。运行一个可从设备访问的注册表：

Command Line

1docker run --rm -d -p 5000:5000 --name registry registry:2

构建并将镜像推送到本地注册表：

1echo "FROM ubuntu:26.04" > ./Dockerfile
2docker buildx build --platform linux/arm64 -t myapp-base:latest --load .
3docker tag myapp-base:latest localhost:5000/myapp-base:latest
4docker push localhost:5000/myapp-base:latest

在 oakapp 中使用基础镜像。在 oakapp.toml 中添加 [base_image] 部分，如下所示：

Toml

1[base_image]
2api_url = "http://<self-hosted-registry-ip>:5000" # Service http address visible from the device
3image_name = "myapp-base"
4image_tag = "latest"

请注意，应用程序是在设备上构建的，因此注册表必须可从设备访问。base_image.api_url 必须指向设备网络可访问的地址。要使上传的镜像在 OAK4 设备上正常工作，它必须以 linux/arm64 镜像的形式上传。

运行时和构建层

prepare_container 和 prepare_build_container 都是在容器中执行的命令数组，用于准备相应的层。唯一的区别是构建层在运行时不存在。可用的命令类型有：

RUN - 在容器中运行命令

Toml

1prepare_container = [
2    { type = "RUN", command = "apt-get update" },
3    { type = "RUN", command = "apt-get install -y python3-pip" },
4]

COPY - 从应用的目录复制文件到容器中，早于应用层的复制。这对于复制依赖文件（如 requirements.txt）很有用。此处无需复制实际的应用程序文件，因为稍后在应用层中会复制它们。
- source - 源文件的路径，相对于主机上的应用目录
- target - 容器内应用目录的路径（如果指定了 app_dir_name，则相对于它）

Toml

1prepare_container = [
2    { type = "COPY", source = "requirements.txt", target = "requirements.txt" },
3]

应用层

首先，来自应用目录的所有文件都被复制到容器中（如果指定了 app_dir_name，则复制到该目录）。然后，按顺序执行 build_steps 中的命令。

build_steps - 构建应用程序或其他准备命令的步骤（字符串数组）

Toml

1build_steps = [
2    "g++ -o /app/my_app /app/main.cpp",
3    "chmod +x /app/my_app",
4]

你可以通过在应用目录中添加 .oakappignore 文件来忽略复制到容器的文件。语法类似于 .gitignore。示例：

Plain Text

1# Ignore all .log files
2*.log
3# Ingore node_modules/ directory
4node_modules/

挂载

挂载允许你将运行应用的设备上的目录或设备链接到应用的容器中。你不能通过这种方式挂载主机上的目录。必需的挂载必须在构建时和运行时都存在。

required_mounts, required_devices - 必需的挂载 - 如果在容器启动时不存在，应用将因错误而停止

语法为 source[:target[:options]]；默认值：

source=target
options="rbind,rw"
所有挂载路径必须是绝对路径。对于 required_mounts、required_devices、optional_mounts、optional_devices 和 additional_mounts（source/target），相对路径会被拒绝。

示例：

Toml

1required_mounts = [
2    "/data/my-storage:/app/storage:rw,rbind",
3]

optional_mounts, optional_devices - 如果在容器启动时不存在，这些挂载将被忽略
additional_mounts ( source , target , type , options , required ) 对象数组，示例如下：

Toml

1additional_mounts = [
2    { source = "/run/user/1000/pulse", target = "/run/user/1000/pulse", type = "none", options = [
3        "rbind",
4        "rw",
5    ], required = true },
6    { source = "/home/root/.config/pulse/cookie", target = "/root/.config/pulse/cookie", type = "none", options = [
7        "bind",
8        "ro",
9    ], required = true },
10]

additional_build_mounts - 与 additional_mounts 相同，但仅用于构建时；这些挂载在运行时不存在
allowed_devices - 应用被允许在容器内访问的设备列表

Toml

1allowed_devices = [{ allow = true, access = "rwm" }]

静态前端

静态前端层允许你构建并提供与你的应用一起使用的静态 Web 前端。请参见 GitHub 上的示例。

static_frontend
- dist_path - 构建后的前端文件路径（相对于主机上的应用目录）
  - build（可选）- 前端的构建配置
    - source_path - 前端源文件的路径
    - steps - 构建前端的命令数组

Toml

1[static_frontend]
2dist_path = "./frontend/dist" # 构建的前端文件的路径
3
4[static_frontend.build]
5source_path = "./frontend" # 前端源文件的路径
6steps = ["cd /app/frontend/src && npm install && npm run build"]

assign_frontend_port - 如果设置为 true，则会为容器内的 OAKAPP_STATIC_FRONTEND_PORT 环境变量分配一个可用端口；即使未指定 static_frontend，也可以使用此选项。

Toml

1assign_frontend_port = true

static_frontend_dir_name（可选/高级；默认值为 static_frontend）- 容器内挂载静态前端文件的目录（将存储在 OAKAPP_STATIC_FRONTEND_PATH 环境变量中）；仅当您已经将此目录名称用于其他用途时才使用。

DepthAI 模型缓存

此部分允许您指定一个包含 *.yaml 格式的 DepthAI 模型的文件夹，该文件夹将在构建期间缓存在容器内。这样，您可以创建离线工作的应用程序，而无需在运行时下载模型。

depthai_models
- yaml_path - 指向 *.yaml 格式的 DepthAI 模型文件夹的路径
- use_only_cache - 如果设置为 true，则仅使用缓存的模型，不会在运行时下载新模型（设置 DEPTHAI_ZOO_INTERNET_CHECK 环境变量）

Toml

1depthai_models = { yaml_path = "./backend/src/depthai_models" }

depthai_models_dir_name（可选/高级；默认值为 depthai_models）- 容器内挂载 DepthAI 模型的目录；仅当您已经将此目录名称用于其他用途时才使用。

环境变量和构建参数

环境变量仅在运行时设置。

Toml

1[env]
2MY_ENV_VAR = "some_value"
3ANOTHER_ENV_VAR = "another_value"

构建参数仅在构建时设置，在运行时不可用。

Toml

1[arg]
2MY_BUILD_ARG = "some_build_value"
3ANOTHER_BUILD_ARG = "another_build_value"

环境变量和构建参数的优先级均低于用户在命令行中设置的变量（oakctl app run --env MY_ENV_VAR=value）。

本页目录

配置（oakapp.toml）

配置字段

应用元数据

应用构建与运行时配置

应用层

基础镜像

使用自定义基础镜像

自托管容器注册表

运行时和构建层

应用层

挂载

静态前端

DepthAI 模型缓存

环境变量和构建参数