Base Image (oakapp-base)

Base image 是一个最小化的 Docker 镜像，它提供了运行复杂 OAK4 Apps 所需的环境。它包含 Python 3.12 和其他必需的库，使开发者能够构建和部署 OAK4 相机上的应用程序。Base image 的关键组件包括：

nginx - 一个代理，用于提供静态文件或处理应用程序前端的请求。它在同一端口上同时暴露 DAI WebSocket 和前端。这很重要，尤其是在通过 IP 地址访问时。编码流仅通过 HTTPS 可用，而通过 IP 访问设备以启用 HTTPS 的唯一方法是使用自签名证书。浏览器每个 IP 地址只允许一个自签名证书，因此 nginx 为前端和 DAI WebSocket 创建了一个反向代理，它们在内部运行于不同的端口，但必须通过单个端口和单个证书公开。
oak_webrtc - 一个用于 WebRTC 通信的工具，用于通过 *.luxonis.app 域提供对应用程序的远程访问。它使用 WebRTC 在应用程序和查看器之间建立连接，从而实现视频和其他数据的实时流式传输。它可以直接在本地网络上连接，并且在网络容量允许的情况下，吞吐量可达 400 Mbps。通过 WebSocket 的通信受限于浏览器性能和网络带宽，但它可以轻松处理 1 Gbps+ 的速度。
python 3.12 - Python 用于应用程序的后端，该后端利用 DAI v3。请注意，DAI 本身已安装在应用程序中；以下是 requirements 文件的一个示例：requirements.txt。

Examples

Default App

您可以在此定义中查看：oakapp.toml。关键部分如下：

Toml

1identifier = "com.example.default"
2entrypoint = ["bash", "-c", "/usr/bin/runsvdir -P /etc/service"]
3app_version = "1.0.0"
4assign_frontend_port = true

identifier - 应用程序的名称，采用类似 Java 的格式（以点作为分隔符）。请注意，标识符在 Hub 中必须是唯一的，因此建议使用您的团队名称作为前缀。
entrypoint - 字符串数组（argv 格式的命令）。这是应用程序启动时执行的命令。在这种情况下，它运行服务管理器（runit 监督器），该管理器负责运行所有默认服务以及使用 base image 的应用程序中的用户定义服务。它首先启动内部的 nginx，该服务处理 HTTPS 和端口暴露。然后运行 ak_webrtc 工具，该工具通过 WebRTC 管理远程访问。最后，它执行 /etc/service/ 文件夹中定义的任何脚本。在我们的例子中，这是文件 /etc/service/backend/run，其中包含 exec python3.12 /app/main.py 以启动应用程序的后端。您可以根据需要为应用程序添加更多服务。
app_version - 应用程序的版本。建议使用语义化版本控制。
assign_frontend_port - 如果为 true，应用程序将被分配一个前端端口，该端口随后由内部 nginx 服务器用于提供前端文件。如果为 false，应用程序将不会获得分配的前端端口，也无法在标准端口上提供任何前端文件。运行在 OAK4 上的代理程序负责端口分配，并且每个应用程序都会分配一个唯一的端口，因此无需在 oakapp.toml 文件中指定端口。

Toml

1prepare_container = [
2    { type = "COPY", source = "./requirements.txt", target = "./requirements.txt" },
3    { type = "RUN", command = "python3.12 -m pip install -r /app/requirements.txt --break-system-packages"}
4]

此部分定义了准备应用程序容器的步骤。它包括将 requirements.txt 文件复制到容器中，并使用 pip 安装所需的 Python 包。这确保了在应用程序启动时所有必需的依赖项都可用。此外，它还保证了在执行 oakctl app run 命令时，依赖项仅安装一次或根据需要安装。

Toml

1build_steps = [
2    "mkdir -p /etc/service/backend",
3    "cp /app/backend-run.sh /etc/service/backend/run",
4    "chmod +x /etc/service/backend/run",
5]

此部分注册了将在应用程序启动时启动的后端服务。它创建了服务的目录，将 backend-run.sh 脚本复制到适当的位置，并设置了必要的权限使其可执行。此脚本负责启动应用程序的后端。您可以根据需要为应用程序添加更多服务。你可以使用任何支持 ARM64 架构的 Docker 镜像（如果你在 OAK4 上运行应用程序）作为应用程序的基础，但建议使用 luxonis/oakapp-base 镜像，因为它专为 OAK4 Apps 设计，并包含所有必需的依赖项和配置。另一个重要的部分是 backend-run.sh 文件（位于 backend-run.sh），其中包含一个简单的命令来启动 Python 后端。它使用 Python 3.12，这是基础镜像的一部分，因此无需再次安装。

Open Vocabulary Object Detection

这是一个更复杂的示例，它使用了所有功能。应用程序定义可在以下位置找到：oakapp.toml。与上一个示例相比，主要区别在于：

Toml

1prepare_build_container = [{type = "RUN", command = "bash -c 'curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash && . \"$HOME/.nvm/nvm.sh\" && nvm install 24'"}]
2build_steps = [
3    "mkdir -p /etc/service/backend",
4    "cp /app/backend-run.sh /etc/service/backend/run",
5    "chmod +x /etc/service/backend/run",
6]
7
8[static_frontend]
9dist_path = "./frontend/dist"
10
11[static_frontend.build]
12source_path = "./frontend"
13steps = ["bash -c 'cd /app/frontend/src && export NODE_OPTIONS=--max-old-space-size=4096 && . $HOME/.nvm/nvm.sh && npm install && npm run build'"]

此示例使用 React.js 构建的自定义前端，而不是 DAI 的一部分且在上一个示例中使用的 Visualizer。它使用 nvm 安装 Node.js 版本 24，然后构建前端应用程序。前端构建在 static_frontend.build 部分执行，其中使用 npm 安装依赖项并构建应用程序。此构建也在设备上执行，因此运行 oakctl app run . 足以构建包括前端在内的整个应用程序。

dist_path - 构建的前端应用程序的路径；这是构建过程完成后构建文件的位置。建议遵循此示例中的结构，一个文件夹用于后端，另一个文件夹用于前端。这不是必需的，但有助于保持结构清晰和有条理。
source_path - 前端应用程序源代码的路径；这是构建过程开始前源代码的位置。
steps - 一个字符串数组，每个字符串代表将在容器中执行以构建前端应用程序的命令。在这种情况下，npm 用于安装依赖项并构建应用程序。NODE_OPTIONS 环境变量设置为增加 Node.js 的内存限制，有助于避免在构建过程中出现内存不足错误。前端使用 React.js 库 @luxonis/depthai-viewer-common，该库提供用于渲染流和注释的高级组件，并通过 WebSocket 进行直接访问以及通过 *.luxonis.app 域进行远程访问来与后端通信。

本页目录

Base Image (oakapp-base)

Examples

Default App

Open Vocabulary Object Detection