Docker 容器部署

目标平台： RK3576 | NPU 算力： 6 TOPS | 文档版本： V1.0
适用板型： C-3576BQ 核心板 + M4-R2 底板
最后更新： 2026-10-23

1. 概述

1.1 功能简介

Docker 是一个开源的应用容器引擎，允许开发者将应用程序及其依赖打包到一个轻量级、可移植的容器中，然后发布到任何流行的 Linux 机器上。在 RK3576 平台上，Docker 支持 ARM64（aarch64）架构，可以运行官方 ARM64 镜像（如 python、nginx、redis 等），并支持容器运行时 containerd 和 runc。

RK3576 运行 Linux 6.1 内核，Docker 依赖内核提供的 cgroups、namespace、netfilter、overlayfs 等功能。通过正确的内核配置和 Docker 安装，可以在 RK3576 上实现完整的容器化部署，包括 NPU 推理容器、摄像头处理容器、GPIO 控制容器等硬件透传场景。

核心特性：

特性	说明
容器引擎	Docker CE 24.x+，支持 ARM64 架构
容器运行时	containerd 1.7+ / runc / crun
存储驱动	overlay2
网络模式	bridge、host、macvlan、overlay、none
硬件透传	--device /dev/*、--privileged 特权模式
NPU 支持	容器内挂载 /dev/rknpu0、/usr/lib/librknnrt.so
摄像头支持	容器内挂载 /dev/video、/dev/media
GPIO 支持	容器内挂载 /sys/class/gpio
多架构构建	Docker Buildx 支持 multi-arch 镜像
多容器编排	Docker Compose 支持

1.2 应用场景

AI 推理服务：在容器内运行 RKNN 模型推理，配合 NPU 硬件加速实现边缘 AI 部署
摄像头监控：容器化部署视频采集与分析应用，支持多路摄像头接入
微服务架构：将 Web 服务、数据库、消息队列等组件容器化部署
开发环境隔离：使用 Docker 容器隔离开发环境，避免依赖冲突
CI/CD 流水线：在容器中构建、测试 RK3576 SDK 固件
工业控制：容器化部署 GPIO 控制、传感器数据采集应用
边缘计算网关：多容器协同运行，实现协议转换、数据预处理、云端上报

1.3 工作原理

RK3576 Docker 容器架构：

┌─────────────────────────────────────────────────────┐
│                  容器应用层                           │
│   NPU 推理容器 · 摄像头容器 · Web 服务容器            │
├─────────────────────────────────────────────────────┤
│                  Docker 引擎层                       │
│   Docker CLI · Docker Daemon · containerd · runc     │
├─────────────────────────────────────────────────────┤
│                  容器运行时层                         │
│   namespace 隔离 · cgroups 资源限制 · overlay2 存储   │
├─────────────────────────────────────────────────────┤
│                  Linux 内核层（6.1）                  │
│   cgroups v1/v2 · netfilter · iptables · bridge      │
├─────────────────────────────────────────────────────┤
│                  硬件层（RK3576）                     │
│   NPU · Camera · GPIO · Mali-G52 MC3 · 网络 · 存储   │
└─────────────────────────────────────────────────────┘

容器运行时组件关系：

Docker CLI ──> Docker Daemon (dockerd)
                    │
                    ├──> containerd ──> runc ──> 容器进程
                    │         │
                    │         └──> shim (containerd-shim-runc-v2)
                    │
                    └──> BuildKit（镜像构建引擎）

阶段	组件	功能
镜像构建	BuildKit / Dockerfile	定义容器运行环境，安装依赖，配置应用
镜像拉取	docker pull	从 Docker Hub 或私有仓库拉取 ARM64 镜像
容器创建	docker run	创建容器实例，配置网络、存储卷、设备映射
容器运行	containerd/runc	执行容器进程，隔离命名空间，限制资源
硬件访问	--device/--privileged	将宿主机设备透传到容器内部
数据持久化	volume / bind mount	将宿主机目录映射到容器，实现数据持久化

2. 硬件准备

2.1 硬件清单

序号	物料名称	型号/规格	数量	用途
1	核心板 + 底板	C-3576BQ 核心板 + ShimetaPi M4-R2 底板	1	主开发板
2	调试串口	USB to TTL 3.3V 转换器	1	串口调试，波特率 1500000
3	M.2 SSD（可选）	M.2 接口 NVMe 固态硬盘	1	Docker 镜像和数据存储
4	电源适配器	5V/2A（Type-C 或 6pin，空载最小 1000mA）	1	主板供电
5	摄像头模块（可选）	MIPI CSI 摄像头	1	容器内摄像头透传实验
6	网线	标准 RJ45	1	网络和 SSH 连接

2.2 硬件确认

接入调试串口后，启动开发板，通过串口终端确认硬件信息：

# 确认系统架构
uname -m
# 输出：aarch64

# 确认内核版本
uname -r
# 输出：6.1.x-rockchip

# 确认 CPU 信息
cat /proc/cpuinfo | grep "model name"
# 输出：ARMv8 Processor rev 1 (v8l)

# 确认内存大小
free -h

# 确认存储空间
df -h /

3. 软件准备

3.1 内核配置

Docker 运行需要内核开启 cgroups、namespace、netfilter、overlayfs 等功能的支持。RK3576 Linux 6.1 SDK 提供了通用的 Docker 内核配置（具体配置命令与内核裁剪配置以实际发布的 RK3576 SDK 为准）。

# 在 SDK 编译目录中，应用 Docker 内核配置
cd <以实际发布的 RK3576 SDK 为准>
make ARCH=arm64 rockchip_linux_defconfig rockchip_linux_docker.config

# 编译内核（编译目标以实际 SDK 为准）
make ARCH=arm64 <实际内核编译目标> -j$(nproc)

Rockchip 提供的 Docker 内核配置已包含以下必要功能：

内核模块	配置项	说明
cgroups	CONFIG_CGROUPS=y	资源限制和隔离
namespaces	CONFIG_NAMESPACES=y	容器命名空间隔离
overlayfs	CONFIG_OVERLAY_FS=y	容器文件系统
netfilter	CONFIG_NETFILTER=y	网络过滤
bridge	CONFIG_BRIDGE=y	Docker 网络桥接
veth	CONFIG_VETH=y	虚拟以太网设备
macvlan	CONFIG_MACVLAN=y	MAC 地址虚拟化
seccomp	CONFIG_SECCOMP=y	系统调用过滤（安全）

使用 Docker 官方检查脚本验证内核配置：

wget https://raw.githubusercontent.com/moby/moby/master/contrib/check-config.sh
bash check-config.sh

3.2 cgroup 配置

RK3576 Linux 6.1 系统默认使用 cgroups v1。确认 cgroup 已挂载：

# 检查 cgroup 挂载情况
mount | grep cgroup

# 确认 cgroup 子系统
ls /sys/fs/cgroup/
# 预期输出：blkio  cpu  cpuacct  cpu,cpuacct  cpuset  devices  freezer  memory  net_cls  net_prio  pids  systemd

如果 cgroup 未正确挂载，可在内核启动参数中添加：

cgroup_enable=memory cgroup_enable=cpuset

3.3 Docker CE 安装（Ubuntu 22.04）

RK3576 Ubuntu 22.04 系统推荐使用 Docker 官方仓库安装：

# 更新软件包索引
sudo apt-get update

# 安装依赖
sudo apt-get install -y ca-certificates curl gnupg

# 添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 添加 Docker 官方仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker CE
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 启动并设置开机自启
sudo systemctl enable --now docker

# 验证安装
sudo docker --version
# 输出：Docker version 24.x.x, build xxxxxxx

sudo docker run --rm hello-world

3.4 containerd 安装与配置

containerd 是 Docker 默认的容器运行时，也可独立使用：

# 安装 containerd
sudo apt-get install -y containerd

# 生成默认配置
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

# 启用 SystemdCgroup（推荐）
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml

# 配置国内镜像加速
sudo sed -i 's|sandbox_image = "registry.k8s.io/pause:.*|sandbox_image = "registry.aliyuncs.com/google_containers/pause:3.9"|' /etc/containerd/config.toml

# 重启 containerd
sudo systemctl restart containerd
sudo systemctl enable containerd

runc 与 crun 对比：

特性	runc	crun
默认容器运行时	是（Docker/K8s 默认）	否，可手动切换
编程语言	Go	C
启动速度	较快	更快（约快 50%）
内存占用	较高	较低
cgroup v2 支持	支持	原生支持
适用场景	通用场景	资源受限的嵌入式设备

在 RK3576 上如追求更轻量的运行时，可安装 crun 并配置 Docker 使用：

sudo apt-get install -y crun
# 编辑 /etc/docker/daemon.json 添加：
# "default-runtime": "crun",
# "runtimes": {"crun": {"path": "/usr/bin/crun"}}
sudo systemctl restart docker

3.5 Docker 镜像加速

配置 Docker 使用国内镜像加速：

sudo mkdir -p /etc/docker

sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn/",
    "https://mirror.ccs.tencentyun.com/"
  ],
  "storage-driver": "overlay2",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

4. 操作步骤

4.1 Docker 基础操作

镜像操作：

# 拉取 ARM64 镜像
docker pull python:3.10-slim
docker pull nginx:latest
docker pull redis:7-alpine

# 查看本地镜像
docker image ls

# 删除镜像
docker rmi <imageID>

容器操作：

# 运行交互式容器
docker run -it --rm python:3.10-slim /bin/bash

# 运行后台容器
docker run -d --name my-nginx -p 8080:80 nginx:latest

# 查看运行中的容器
docker container ls

# 查看所有容器（包括已停止的）
docker container ls -a

# 停止/启动容器
docker stop <containerID>
docker start <containerID>

# 进入运行中的容器
docker exec -it <containerID> /bin/bash

# 查看容器日志
docker logs -f <containerID>

# 删除容器
docker rm <containerID>

4.2 Volume 卷管理

Docker 提供三种数据挂载方式：volume（命名卷）、bind mount（绑定挂载）和 tmpfs。

# 创建命名卷
docker volume create my-data

# 查看卷列表
docker volume ls

# 使用命名卷运行容器
docker run -d --name my-redis -v my-data:/data redis:7-alpine

# 绑定挂载宿主机目录
docker run -d -v /home/user/app:/app -v /home/user/models:/models \
  python:3.10-slim python3 /app/main.py

# tmpfs 挂载（内存存储，重启丢失）
docker run -d --tmpfs /tmp:rw,size=100m ubuntu:22.04

# 查看卷详情
docker volume inspect my-data

# 删除未使用的卷
docker volume prune

RK3576 推荐挂载策略：

数据类型	挂载方式	示例路径	说明
NPU 模型文件	bind mount	-v /home/user/models:/models	模型文件持久保存
推理数据	named volume	-v inference-data:/data	数据库等结构化数据
日志文件	bind mount	-v /var/log/app:/app/logs	宿主机统一收集
临时缓存	tmpfs	--tmpfs /tmp:size=200m	高速临时存储

4.3 Docker 网络管理

Docker 提供多种网络驱动，适用于 RK3576 不同场景：

# 查看网络列表
docker network ls

# 创建自定义桥接网络
docker network create --driver bridge \
  --subnet=172.20.0.0/16 \
  --gateway=172.20.0.1 \
  rk3576-net

# 创建 macvlan 网络（容器直接获取物理网络 IP）
docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  -o parent=eth0 \
  macvlan-net

# 创建 overlay 网络（跨主机通信，用于多板集群）
docker network create -d overlay --attachable overlay-net

# 将容器连接到自定义网络
docker run -d --name nginx --network rk3576-net -p 80:80 nginx:latest

# 查看容器网络详情
docker inspect --format='{{json .NetworkSettings.Networks}}' nginx

# 容器间通过服务名通信
docker exec -it nginx curl http://app-server:8080

网络模式对比：

网络模式	隔离性	性能	适用场景
bridge	高	中等	默认推荐，多容器隔离
host	无	最高	高性能网络应用
macvlan	高	高	容器需要独立 MAC 地址
none	最高	N/A	完全隔离的计算容器
overlay	高	中等	跨主机容器通信

4.4 Docker Buildx 多架构构建

Docker Buildx 支持在 RK3576 上构建多架构镜像，也可交叉编译 amd64 镜像：

# 安装 buildx 插件（已在 3.3 节安装）
docker buildx version

# 创建多架构构建器
docker buildx create --name multiarch --driver docker-container --use

# 查看构建器
docker buildx inspect --bootstrap

# 构建 ARM64 镜像（默认）
docker buildx build -t my-app:arm64 --platform linux/arm64 .

# 同时构建 ARM64 + AMD64 镜像
docker buildx build -t my-app:latest \
  --platform linux/arm64,linux/amd64 \
  --push .

# 构建并加载到本地（仅支持当前架构）
docker buildx build -t my-app:latest --load .

多架构 Dockerfile 示例：

FROM --platform=$BUILDPLATFORM ubuntu:22.04

ARG TARGETARCH
ARG BUILDARCH

RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 python3-pip \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY requirements.txt .
RUN pip3 install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python3", "main.py"]

4.5 NPU 推理容器部署

在容器内使用 RK3576 NPU 进行 AI 推理，需要将 NPU 设备和运行时库透传到容器中（RK3576 集成单核 NPU，对应设备节点为 /dev/rknpu0，具体节点以实际 SDK 为准）：

# 查看 NPU 设备
ls /dev/rknpu*
# 输出：/dev/rknpu0

# 以特权模式运行 NPU 容器
docker run -it --privileged \
  --device /dev/rknpu0:/dev/rknpu0 \
  -v /usr/lib/librknnrt.so:/usr/lib/librknnrt.so \
  -v /path/to/models:/models \
  python:3.10-slim /bin/bash

NPU 推理 Dockerfile：

FROM python:3.10-slim

RUN apt-get update && apt-get install -y \
    libgomp1 \
    && rm -rf /var/lib/apt/lists/*

RUN pip3 install rknn-lite numpy

COPY app.py /app/app.py
COPY models/ /app/models/

WORKDIR /app
CMD ["python3", "app.py"]

NPU 推理应用示例（app.py）：

#!/usr/bin/env python3
"""RK3576 NPU 容器内推理示例"""

import numpy as np
from rknnlite.api import RKNNLite

def main():
    rknn = RKNNLite()
    ret = rknn.load_rknn('./models/model.rknn')
    if ret != 0:
        print('加载模型失败')
        return

    ret = rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0)
    if ret != 0:
        print('初始化运行时失败')
        return

    input_data = np.random.randint(0, 255, (1, 224, 224, 3), dtype=np.uint8)
    outputs = rknn.inference(inputs=[input_data])
    print(f"推理输出形状: {outputs[0].shape}")
    rknn.release()

if __name__ == '__main__':
    main()

4.6 资源限制配置

通过 cgroups 对容器进行 CPU 和内存限制：

# 限制容器 CPU 和内存
docker run -d \
  --name limited-app \
  --cpus="2" \
  --memory="1g" \
  --memory-swap="1g" \
  --cpuset-cpus="0-1" \
  python:3.10-slim

# 限制 I/O 带宽
docker run -d \
  --device-read-bps /dev/sda:10mb \
  --device-write-bps /dev/sda:10mb \
  ubuntu:22.04

# 动态调整已运行容器的资源
docker update --cpus="4" --memory="2g" <containerID>

# 查看容器资源使用
docker stats <containerID>

RK3576 资源分配建议：

容器类型	CPU 限制	内存限制	说明
NPU 推理	2 核	1GB	NPU 硬件加速，CPU 占用较低
摄像头采集	2 核	512MB	视频解码主要由 VPU 处理
Web 服务	1 核	256MB	根据并发量调整
数据库	2 核	1GB	根据数据量调整

4.7 Docker Compose 多容器编排

# 安装 Docker Compose 插件（3.3 节已安装）
docker compose version

多容器编排示例（docker-compose.yml）：

services:
  web:
    image: nginx:latest
    ports:
      - '80:80'
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
    depends_on:
      - app
    restart: unless-stopped
    networks:
      - rk3576-net

  app:
    build: ./app
    ports:
      - '8080:8080'
    volumes:
      - ./app/data:/app/data
    depends_on:
      - redis
      - db
    environment:
      - REDIS_HOST=redis
      - DB_HOST=db
    restart: unless-stopped
    networks:
      - rk3576-net

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data
    restart: unless-stopped
    networks:
      - rk3576-net

  db:
    image: mysql:8.0
    volumes:
      - mysql-data:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=rootpass
      - MYSQL_DATABASE=myapp
    restart: unless-stopped
    networks:
      - rk3576-net

  npu:
    build: ./npu-service
    privileged: true
    devices:
      - /dev/rknpu0:/dev/rknpu0
    volumes:
      - /usr/lib/librknnrt.so:/usr/lib/librknnrt.so
      - ./models:/app/models
    ports:
      - '9090:9090'
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
    restart: unless-stopped
    networks:
      - rk3576-net

volumes:
  redis-data:
  mysql-data:

networks:
  rk3576-net:
    driver: bridge

# 启动所有服务
docker compose up -d

# 查看服务状态
docker compose ps

# 查看服务日志
docker compose logs -f npu

# 停止所有服务
docker compose down

# 重建并重启指定服务
docker compose up -d --build npu

4.8 Docker 安全加固

# 不以 root 运行容器
docker run -u 1000:1000 python:3.10-slim

# 只读文件系统
docker run --read-only --tmpfs /tmp ubuntu:22.04

# 丢弃 Linux capabilities
docker run --cap-drop=ALL --cap-add=NET_BIND_SERVICE nginx:latest

# 启用 seccomp 安全配置文件（默认已启用）
docker run --security-opt seccomp=default ubuntu:22.04

# 禁用容器间 inter-container 通信（同网络默认禁止）
docker network create --internal isolated-net

# 定期清理无用资源
docker system prune -a --volumes

安全配置建议：

安全措施	配置方式	说明
非 root 运行	-u UID:GID	减小容器逃逸影响面
只读根文件系统	--read-only	防止容器写入恶意文件
最小 capabilities	--cap-drop=ALL	仅保留必要权限
资源限制	--memory/--cpus	防止资源耗尽攻击
镜像签名验证	DOCKER_CONTENT_TRUST=1	确保镜像来源可信
日志轮转	daemon.json log-opts	防止日志撑满磁盘

4.9 CI/CD 流水线

在 RK3576 上使用容器化 CI/CD 构建和测试固件：

GitHub Actions Runner 容器部署：

# docker-compose.ci.yml
services:
  github-runner:
    image: myoung34/github-runner:latest
    environment:
      - RUNNER_NAME=rk3576-runner
      - RUNNER_TOKEN=${RUNNER_TOKEN}
      - RUNNER_REPO=https://github.com/your-org/your-repo
      - RUNNER_SCOPE=repo
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /home/user/builds:/builds
    restart: unless-stopped

RK3576 SDK 构建容器 Dockerfile：

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    build-essential gcc-aarch64-linux-gnu \
    git python3 python3-pip device-tree-compiler \
    u-boot-tools mtd-utils \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /build
COPY . /build/sdk/

CMD ["bash", "-c", "cd sdk && make ARCH=arm64 <实际内核编译目标> -j$(nproc)"]

4.10 Kubernetes 与轻量级编排

RK3576 可运行轻量级 Kubernetes 或其他编排工具：

K3s 轻量级 Kubernetes：

# 安装 K3s（单节点）
curl -sfL https://get.k3s.io | sh -

# 查看节点状态
kubectl get nodes

# 部署 NPU 推理应用
kubectl apply -f npu-deployment.yml

NPU 推理 Kubernetes Deployment 示例：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: npu-inference
spec:
  replicas: 1
  selector:
    matchLabels:
      app: npu-inference
  template:
    metadata:
      labels:
        app: npu-inference
    spec:
      containers:
        - name: npu-app
          image: my-registry/npu-inference:latest
          securityContext:
            privileged: true
          volumeMounts:
            - name: rknpu0
              mountPath: /dev/rknpu0
            - name: librknnrt
              mountPath: /usr/lib/librknnrt.so
            - name: models
              mountPath: /app/models
          resources:
            limits:
              cpu: '2'
              memory: '1Gi'
      volumes:
        - name: rknpu0
          hostPath:
            path: /dev/rknpu0
        - name: librknnrt
          hostPath:
            path: /usr/lib/librknnrt.so
        - name: models
          hostPath:
            path: /home/user/models

轻量级编排工具对比：

工具	内存占用	K8s 兼容	适用场景
Docker Compose	~30MB	否	单机多容器编排
K3s	~512MB	是	生产级边缘编排
Podman	~15MB	否	无守护进程的轻量替代

5. 代码详解

5.1 容器运行时架构

用户空间                              内核空间
┌──────────────────┐                ┌──────────────────┐
│ docker CLI       │                │                  │
│ docker build     │──API──>        │  containerd      │
│ docker run       │                │  (容器管理)       │
│ docker push      │                │    │             │
└──────────────────┘                │    ├── shim     │
                                    │    │   (进程监控)  │
                                    │    │     │       │
                                    │    │   runc     │
                                    │    │   (创建容器)  │
                                    │    │     │       │
                                    │  namespaces     │
                                    │  cgroups        │
                                    │  overlay2       │
                                    └──────────────────┘

技术	功能	RK3576 支持
namespace	进程、网络、文件系统隔离	PID、NET、MNT、UTS、IPC、USER
cgroups	CPU、内存、I/O 资源限制	CPU、内存、blkio、设备访问
overlay2	高效联合文件系统	内核原生支持

5.2 设备透传机制

RK3576 支持将硬件设备透传到容器内部：

# 方式 1：--device 指定单个设备
docker run --device /dev/rknpu0:/dev/rknpu0

# 方式 2：--privileged 特权模式（所有设备）
docker run --privileged

# 方式 3：--device-cgroup-rule 精细控制
docker run --device-cgroup-rule='c 189:* rwm' --device /dev/bus/usb

RK3576 常用设备映射：

设备	容器内路径	用途
NPU	/dev/rknpu0	AI 推理加速
摄像头	/dev/video0-N	视频采集
媒体总线	/dev/media0-N	V4L2 媒体设备
GPIO	/sys/class/gpio	通用 IO 控制
I2C	/dev/i2c-0	I2C 通信
SPI	/dev/spidev0.0	SPI 通信
UART	/dev/ttyS0	串口通信

5.3 overlay2 存储原理

容器层（可写）          ← 容器运行时的文件修改
┌─────────────────┐
│ /app/config.json │  ← 修改的文件
│ /app/cache/      │  ← 新建的目录
├─────────────────┤
│   diff 目录      │  ← 只保存与镜像层的差异
├─────────────────┤
镜像层（只读）          ← 镜像的多个只读层
┌─────────────────┐
│ base layer       │
├─────────────────┤
│ deps layer       │
├─────────────────┤
│ app layer        │
└─────────────────┘

6. 常见问题

序号	现象	已确认原因	处理方法	状态
1	docker pull 超时	网络无法访问 Docker 官方仓库	配置国内镜像加速：编辑 /etc/docker/daemon.json，添加 `"registry-mirrors"`，重启 Docker	参考说明
2	Git 报错 dubious ownership	容器内用户没有宿主机代码的所有权	执行 `git config --global --add safe.directory "*"`	参考说明
3	NPU 设备无法访问	未透传 NPU 设备节点	使用 --device /dev/rknpu0 参数或 --privileged，并挂载 librknnrt.so	待板上验证
4	Debian 网络异常	默认使用 iptables-nft，Docker 需要 iptables-legacy	`update-alternatives --set iptables /usr/sbin/iptables-legacy`	待板上验证
5	ARM64 镜像无法运行	镜像架构不匹配	确认镜像为 ARM64：`docker inspect <image> \| grep Architecture`	参考说明
6	容器内无法访问摄像头	未透传视频设备	使用 --device 映射 /dev/video* 和 /dev/media*	待板上验证
7	Compose 服务启动失败	依赖服务未就绪或端口冲突	检查端口占用 `ss -tlnp`，使用 depends_on 配置依赖	待板上验证

7. 相关文档

文档名称	路径	说明
NPU 架构与性能概览	NPU架构与性能概览	NPU 硬件架构和软件栈
RKNN Toolkit2 安装与使用	RKNN Toolkit2安装与使用	模型转换工具，准备容器内推理模型
Python 应用开发	Python应用开发	容器内 Python 推理应用基础
摄像头应用	摄像头应用	摄像头设备透传参考
OTA 远程升级	OTA远程升级	容器镜像与应用升级
硬件参考-核心板参数	核心板参数	C-3576BQ 核心板硬件规格