配置 (oakapp.toml)
配置 (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） - 应用文件复制到容器内的目录；仅当您已将此目录名称用于其他用途时才使用
Shell 形式 vs 可执行形式
与 Docker 类似，所有命令都可以指定为可执行形式（字符串数组）或 Shell 形式（单个字符串）。对于
entrypoint，我们强烈建议使用可执行形式。应用层
- 基础镜像层（在
base_image部分指定） - 运行时层（在
prepare_container部分构建） - 构建层（在
prepare_build_container部分构建；此层在构建后与运行时层断开连接） - 应用层（在此处执行应用目录中的所有文件并执行
build_steps）
注意
在 Docker 术语中，这些层中的每一层都对应于 Dockerfile 中的一个
RUN 指令。这允许高效缓 存，同时避免常见陷阱。- 静态前端层（如果在
static_frontend部分指定） - DepthAI 模型缓存层（如果在
depthai_models部分指定）
基础镜像
debian/bookworm-slim，请参见下面的示例：Toml
1[base_image]
2api_url = "https://registry-1.docker.io" # 服务 https 地址
3service = "registry.docker.io" # 镜像注册表服务名称
4oauth_url = "https://auth.docker.io/token" # 此服务的 oauth 2.0 令牌地址
5auth_type = "repository" # 范围类型
6auth_name = "library/debian" # 资源名称
7
8image_name = "library/debian"
9image_tag = "bookworm-slim"建议
对于 DepthAI OAK 应用，我们推荐我们的 基础镜像，其中包含了您可能需要的大部分依赖项。
oakapp.toml 中定义此镜像：Toml
1[base_image]
2image_name = "library/debian"
3image_tag = "bookworm-slim"- 它必须是基于 Debian 12 的镜像
- 它必须支持 ARM 架构
- 它必须与 Docker 的 Manifest V2 兼容
oakapp.toml 中配置 [base_image] 设置，如下所示：Toml
1[base_image]
2 api_url = "http://localhost:5000" # 从设备可见的服务 http 地址
3 image_name = "my-base"
4 image_tag = "local"Command Line
1docker run -d -p 5000:5000 --name zot ghcr.io/project-zot/zot-linux-amd64:latest
2
3# 仅用于使用不安全注册表的本地测试
4regctl registry set --tls=disabled localhost:5000
5docker buildx create --use --driver docker-container --driver-opt network=host
6
7# 创建一个简单的基础镜像
8echo "FROM debian:bookworm-slim" > ./Dockerfile
9
10# 设置本地注册表的 IP 地址（如果不在 localhost 上运行）
11docker buildx build -f ./Dockerfile --platform=linux/arm64 -t 127.0.0.1:5000/my-base:local --push .base_image.api_url 必须指向设备网络可访问的地址。运行时和构建层
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）- 模型挂载在容器内的目录；仅当您已将此目录名称用于其他用途时使用。
环境变量和构建参数
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）。