基础镜像 (oakapp-base)

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

nginx - 一个代理服务器，用于提供静态文件或处理应用前端的请求。它在同一端口上同时暴露 DAI WebSocket 和前端。这很重要，尤其是在通过 IP 地址访问时。编码流仅通过 HTTPS 可用，而通过 IP 地址访问设备的唯一方法是使用自签名证书。浏览器每个 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。

示例

默认应用

您可以在此定义中查看：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 监督器），该管理器负责运行所有默认服务以及使用基础镜像的应用中的用户定义服务。它首先启动内部的 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 脚本复制到适当的位置，并设置了必要的权限使其可执行。此脚本负责启动应用程序的后端。您可以根据需要为您的应用添加更多服务。

Toml

1[base_image]
2api_url = "https://registry-1.docker.io"
3service = "registry.docker.io"
4oauth_url = "https://auth.docker.io/token"
5auth_type = "repository"
6auth_name = "luxonis/oakapp-base"
7image_name = "luxonis/oakapp-base"
8image_tag = "1.2.5"

您可以使用任何 Docker 映像（基于 Debian 12，支持 ARM 架构并兼容 Docker 的 Manifest V2）作为应用程序的基础，但建议使用 luxonis/oakapp-base 映像，因为它专为 OAK4 Apps 设计，并包含所有必需的依赖项和配置。另一个重要部分是 backend-run.sh 文件，其中包含一个用于启动 Python 后端的简单命令。它使用 Python 3.12，这是基础映像的一部分，因此无需再次安装。

开放词汇对象检测

这是一个更复杂的示例，使用了所有功能。应用程序定义可在以下位置找到：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 域进行直接访问和 WebRTC 进行远程访问。

本页目录

基础镜像 (oakapp-base)View as Markdown

示例View as Markdown

默认应用

开放词汇对象检测

基础镜像 (oakapp-base)

示例