balenalib/raspberrypi3-debian-node 镜像文档

镜像概述和主要用途

本镜像属于 balena.io IoT 设备基础镜像系列，专为物联网设备设计。该镜像针对 balena.io 平台和 balenaOS 进行了优化，同时也可在其他支持相应架构的 Docker 环境中使用。镜像集成 Node.js 运行时，主要用于部署和运行 IoT 设备上的 Node.js 应用程序。

核心功能和特性

1. install_packages 包管理脚本

• 功能：抽象底层包管理器（如 apt）的具体实现，简化包安装流程。
• 特性：
  • 最小化依赖：仅安装必要依赖，忽略可选依赖项。
  • 自动清理：安装后清理包管理器元数据，减少镜像体积。
  • 重试机制：包安装失败时自动重试，提高可靠性。

2. 动态设备支持

• 默认入口点：镜像默认 ENTRYPOINT 为 ["/usr/bin/entry.sh"]。
• udevd 守护进程：通过设置环境变量 ENV UDEV=1 启用 udevd 守护进程，使容器内 /dev 目录能动态生成设备节点，支持热插拔设备识别。

更多特性详情参见 balena ***文档 - 特性概述。

镜像变体

balenalib 镜像提供多种变体，适用于不同场景：

:<version> 或 :<version>-run

• 定位：默认镜像，精简的运行时变体。
• 特点：仅包含运行 Node.js 应用所需的核心组件，体积小巧，适合生产环境部署。

:<version>-build

• 定位：构建环境变体。
• 特点：包含大量源码构建工具（如编译器、链接器等），减少手动安装依赖的需求，从而降低整体镜像体积。

更多变体详情参见 balena ***文档 - Run vs Build。

使用场景和适用范围

1. 运行时场景（run 变体）

• 部署预编译的 Node.js 应用到 IoT 设备。
• 对镜像体积敏感的生产环境。

2. 构建场景（build 变体）

• 从源码编译 Node.js 应用或依赖（如原生模块）。
• 需要减少 Dockerfile 中手动安装构建工具的场景。

3. 平台适配

• 与 balena.io 平台和 balenaOS 深度集成，支持设备管理、远程部署等 IoT 功能。
• 兼容标准 Docker 环境，适用于非 balena 生态的 IoT 设备。

使用方法和配置说明

环境变量配置

1. 通过 Dockerfile 使用

基本 Dockerfile 示例

dockerfile
# 指定基础镜像版本（如 latest 或具体版本号）
FROM balenalib/raspberrypi3-debian-node:latest
# 暴露应用端口（根据实际需求修改）
EXPOSE 8888

构建和运行命令

bash
# 构建镜像
docker build -t my-nodejs-app .

# 运行容器（交互式，退出时自动删除）
docker run -it --rm --name my-running-app my-nodejs-app

2. 通过 Docker Compose 使用

docker-compose.yml 配置示例

yaml
version: "2"
services:
  node:
    image: "balenalib/raspberrypi3-debian-node:latest"
    user: "node"                # 使用 node 用户运行
    working_dir: /home/node/app # 工作目录
    environment:
      - NODE_ENV=production     # Node.js 环境变量
      - UDEV=1                  # 启用 udevd（如需动态设备支持）
    volumes:
      - ./:/home/node/app       # 挂载本地代码到容器
    expose:
      - "8081"                  # 暴露端口
    command: "npm start"        # 启动命令（需 package.json 定义 start 脚本）

启动命令

bash
# 后台启动服务
docker-compose up -d

3. 运行单文件 Node.js 脚本

对于简单项目，可直接运行单文件脚本，无需编写 Dockerfile：

bash
docker run -it --rm --name my-running-script \
  -v "$PWD":/usr/src/app \  # 挂载当前目录到容器
  -w /usr/src/app \         # 设置工作目录
  balenalib/raspberrypi3-debian-node:latest \
  node your-daemon-or-script.js  # 运行脚本

支持的版本

更多版本信息参见 balena ***镜像清单。

用户反馈

问题反馈

如遇镜像相关问题或疑问，请通过 GitHub Issues 提交。

贡献指南

欢迎贡献新功能、修复或更新。建议先通过 GitHub Issues 讨论计划，以确保方向一致。

更多文档参见 balena 基础镜像文档 和 迁移指南。