配置 (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命令的 shellapp_dir_name- (可选/高级,默认为app)容器内复制应用程序文件的目录;仅当您已将此目录名称用于其他用途时才使用stop_grace_period- (可选,默认为10s)在任何app stop操作期间用作宽限期的时间长度;oak-agent首先尝试通过发送SIGTERM来停止应用程序,只有在宽限期过后,如果应用程序仍在运行,才会发出SIGKILLrestart_policy- (可选,默认为never)控制oak-agent在应用程序进程退出后是否重新启动应用程序
Shell 形式与可执行形式
与 Docker 类似,所有命令都可以用可执行形式(字符串数组)或 shell 形式(单个字符串)指定。对于
entrypoint,我们强烈建议使用可执行形式。终止信号处理
与大多数容器运行时类似,在应用程序容器内运行的进程负责正确处理
SIGTERM。自动应用程序重启
restart_policy 在应用程序进程退出时自动恢复应用程序。Toml
1restart_policy = "on-failure:3"| 值 | 行为 |
|---|---|
never | 不会自动重新启动应用程序。这是默认值。 |
always | 每次退出后重新启动应用程序,包括成功退出。 |
on-failure | 在不成功退出后重新启动应用程序,没有重试限制。 |
on-failure:<count> | 在不成功退出后最多重新启动应用程序 <count> 次。 |
应用程序层
- 基础镜像层(在
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
1base_image = "debian:bookworm-slim" # 默认
2base_image = "luxonis/oakapp-base:1.2.5"建议
对于 DepthAI OAK 应用程序,我们建议使用我们的 基础镜像,其中包含您可能需要的大部分依赖项。
使用自定义基础镜像
base_image 指向您自己的镜像来在 OAK 应用程序中重用该工作。当您希望首先在熟悉的 Docker 工作流中迭代操作系统包、运行时或共享依赖项,然后使用 oakapp.toml 打包最终应用程序时,这很有用。当您正在开发可重用的基础环境并希望在多个应用程序之间共享时,这也可以很好地适用。使用自定义基础镜像进行稳定的共享环境设置,并使用 prepare_container 和 prepare_build_container 进行应用程序特定的运行时和构建步骤。要使用不同的镜像作为基础层,请在 oakapp.toml 中定义它,如下所示:Toml
1base_image = "your-org/your-image:tag"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 未经身份验证的拉取
oak-agent 默认从镜像注册表进行未经身份验证的拉取。在重复拉取或从共享网络构建时,Docker Hub 等注册表可能会因为其匿名拉取速率限制而拒绝请求。如果发生这种情况,构建可能会失败并出现类似以下内容的错误:Sh
1oakctl 命令失败:
2 0: 收到错误 RPC 响应:无法构建应用程序容器:
3 镜像下载失败:OCI 注册表客户端收到错误:
4 APIError(ErrorList { errors: [Error { code: "TOOMANYREQUESTS", message:
5 "您已达到未经身份验证的拉取速率限制。
6 https://www.docker.com/increase-rate-limit", detail: Null }] })oakctl registry login 或参阅 自托管容器注册表。自托管容器注册表
base_image.api_url 指向它。运行一个可从设备访问的注册表:Command Line
1docker run --rm -d -p 5000:5000 --name registry registry:2Sh
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:latestoakapp.toml 中添加 base_image 字段,如下所示:Toml
1base_image = "http://registry-ip:5000/your-image:tag"运行时和构建层
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" }]静态前端
static_frontenddist_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 = truestatic_frontend_dir_name(可选/高级;默认为static_frontend)- 容器内挂载静态前端文件的目录(将存储在OAKAPP_STATIC_FRONTEND_PATH环境变量中);仅当您已将此目录名称用于其他用途时才使用
DepthAI 模型缓存
*.yaml 格式的 DepthAI 模型的文件夹,这些模型将在构建时缓存到容器中。这样,您可以创建离线工作的应用程序,而无需在运行时下载模型。depthai_modelsyaml_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)。