此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 配置字段
  • 应用程序元数据
  • 应用程序构建和运行时配置
  • 自动应用程序重启
  • 应用程序层
  • 挂载
  • 静态前端
  • DepthAI 模型缓存
  • 环境变量和构建参数
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

配置 (oakapp.toml)

最后更新
在每个应用程序的目录中,必须有一个 oakapp.toml 文件,其中包含静态应用程序的元数据和构建步骤。 元数据包括应用程序的标识符和版本。构建步骤是在容器中执行的用于构建或运行应用程序的命令。 oakapp.toml 文件示例:
Toml
1# (Required) App Identifier
2identifier = "com.luxonis.python_demo"
3# (Required) App Entrypoint
4entrypoint = ["bash", "-c", "python3 /app/main.py"]
5
6# (Optional) Prepare container commands
7# Here is the place where you can install all the dependencies that are needed at run-time
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# (Optional) Prepare build dependencies
16# Here is the place where you can install all the dependencies that are needed at build-time
17prepare_build_container = [
18    # Example: npm, gcc, ...
19]
20
21# (Optional) Additional commands after all the app files are copied to the container
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"])用于在 prepare_container 和 prepare_build_container 部分执行 build_steps、entrypoint 和 RUN 命令的 shell
  • app_dir_name - (可选/高级,默认为 app)容器内复制应用程序文件的目录;仅当您已将此目录名称用于其他用途时才使用
  • stop_grace_period - (可选,默认为 10s)在任何 app stop 操作期间用作宽限期的时间长度;oak-agent 首先尝试通过发送 SIGTERM 来停止应用程序,只有在宽限期过后,如果应用程序仍在运行,才会发出 SIGKILL
  • restart_policy - (可选,默认为 never)控制 oak-agent 在应用程序进程退出后是否重新启动应用程序

自动应用程序重启

使用 restart_policy 在应用程序进程退出时自动恢复应用程序。
Toml
1restart_policy = "on-failure:3"
值行为
never不会自动重新启动应用程序。这是默认值。
always每次退出后重新启动应用程序,包括成功退出。
on-failure在不成功退出后重新启动应用程序,没有重试限制。
on-failure:<count>在不成功退出后最多重新启动应用程序 <count> 次。

应用程序层

与 Docker 类似,应用程序分多层构建:
  1. 基础镜像层(在 base_image 部分指定)
  2. 运行时层(在 prepare_container 部分构建)
  3. 构建层(在 prepare_build_container 部分构建;此层在构建后与运行时层断开连接)
  4. 应用程序层(应用程序目录中的所有文件和 build_steps 在此处执行)
除了应用程序层,还有两个额外的并行层:
  • 静态前端层(如果在 static_frontend 部分指定)
  • DepthAI 模型缓存层(如果在 depthai_models 部分指定)
如果这些层中的任何一个发生更改,所有后续层都将重新构建。并行层彼此独立地重新构建,因为它们没有相互依赖关系。

基础镜像

默认基础镜像是 debian/bookworm-slim,从 registry-1.docker.io 拉取。 可以通过指定 base_image 字段来更改,支持多种格式:
Toml
1base_image = "debian:bookworm-slim" # 默认
2base_image = "luxonis/oakapp-base:1.2.5"

使用自定义基础镜像

如果您已经使用 Docker 进行开发,可以通过将 base_image 指向您自己的镜像来在 OAK 应用程序中重用该工作。当您希望首先在熟悉的 Docker 工作流中迭代操作系统包、运行时或共享依赖项,然后使用 oakapp.toml 打包最终应用程序时,这很有用。当您正在开发可重用的基础环境并希望在多个应用程序之间共享时,这也可以很好地适用。使用自定义基础镜像进行稳定的共享环境设置,并使用 prepare_container 和 prepare_build_container 进行应用程序特定的运行时和构建步骤。要使用不同的镜像作为基础层,请在 oakapp.toml 中定义它,如下所示:
Toml
1base_image = "your-org/your-image:tag"
默认情况下,镜像从 Docker Hub 拉取,但您也可以将 base_image 指向不同的注册表:
Toml
1base_image = "ghcr.io/your-org/your-image:tag"
如果您想使用私有仓库中的基础镜像,可以在 oakctl 中进行身份验证:
Sh
1oakctl registry login <registry_url>
凭据安全地存储在系统密钥环中,并且永远不会离开运行 oakctl registry login 的机器。 执行镜像拉取时,注册表使用存储的凭据生成一个短期身份验证令牌,然后该令牌是传输到设备的唯一身份验证信息。一旦不再需要身份验证,可以使用以下命令清除凭据:
Sh
1oakctl registry logout <registry_url>

自托管容器注册表

为了避免 Docker Hub 速率限制,您可以自托管容器注册表并在开发期间将 base_image.api_url 指向它。运行一个可从设备访问的注册表:
Command Line
1docker run --rm -d -p 5000:5000 --name registry registry:2
构建镜像并将其推送到本地注册表:
Sh
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
1base_image = "http://registry-ip:5000/your-image:tag"
请记住,应用程序是在设备上构建的,因此注册表必须可从设备访问。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# 忽略所有 .log 文件
2*.log
3# 忽略 node_modules/ 目录
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)。