balenalib/spacely-tx2-fedora-node

balenalib/spacely-tx2-fedora-node 镜像文档

1. 镜像概述和主要用途

本镜像属于 https://balena.io/?ref=dockerhub IoT 设备基础镜像系列，专为物联网设备优化设计。其核心用途是作为 Node.js 应用的基础镜像，提供轻量、高效的运行环境。该镜像已针对 https://balena.io/?ref=dockerhub 平台和 https://www.balena.io/os/?ref=dockerhub 进行深度优化，同时也可兼容运行于其他符合架构要求的 Docker 环境。

!balenalogo

2. 核心功能和特性

2.1 简化的包管理工具 install_packages

• 功能：抽象底层包管理器（如 dnf）的差异，提供统一的包安装接口。
• 特性：
  • 自动安装指定软件包，仅包含必要依赖（忽略可选依赖），减小镜像体积。
  • 安装后自动清理包管理器元数据，避免冗余文件。
  • 支持安装失败时自动重试，提升稳定性。

2.2 动态设备支持

• 默认入口点：镜像内置入口点脚本 /usr/bin/entry.sh，负责初始化容器环境。
• UDEV 支持：通过设置环境变量 ENV UDEV=1 启用 udevd 守护进程，容器内 /dev 目录将动态生成接入设备的节点文件，适用于需要访问外设的 IoT 场景。

更多特性详情可参考 https://www.balena.io/docs/reference/base-images/base-images/#features-overview。

3. 镜像变体

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

3.1 :<version> 或 :<version>-run（默认变体）

• 定位：精简的运行时变体，仅包含 Node.js 应用运行所需的核心依赖。
• 适用场景：生产环境部署，追求最小镜像体积和资源占用。

3.2 :<version>-build

• 定位：构建时变体，包含编译源代码所需的工具链（如编译器、Make、Git 等）。
• 适用场景：应用构建阶段，减少手动安装依赖的操作，降低整体镜像构建链的复杂度。

变体差异详情可参考 https://www.balena.io/docs/reference/base-images/base-images/#run-vs-build?ref=dockerhub。

4. 使用场景和适用范围

• 目标设备：基于 spacely-tx2 架构的 IoT 设备（如 NVIDIA Jetson TX2 系列）。
• 应用类型：Node.js 编写的物联网应用（如传感器数据采集、边缘计算、设备控制等）。
• 典型流程：
  1. 使用 -build 变体编译应用源码（如 TypeScript 转译、原生模块编译）。
  2. 将构建产物复制到 -run 变体中，生成精简的生产镜像。
  3. 部署至 balenaOS 或其他支持的 Docker 环境，利用 UDEV 特性访问外设。

5. 详细使用方法和配置说明

5.1 在 Balena 平台使用

参考 https://www.balena.io/docs/learn/getting-started/spacely-tx2/nodejs/?ref=dockerhub 快速上手，或通过 https://www.balena.io/docs/learn/getting-started/spacely-tx2/nodejs/#example-projects?ref=dockerhub 了解实际应用场景。

5.2 Dockerfile 示例

在 Node.js 项目中创建 Dockerfile：

dockerfile
# 指定基础镜像版本（可替换为具体版本，如 18.18.0）
FROM balenalib/spacely-tx2-fedora-node:latest

# 暴露应用端口（根据实际需求修改）
EXPOSE 8888

# 复制应用代码并安装依赖（示例）
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .

# 启动命令
CMD ["node", "index.js"]

构建并运行容器：

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

# 运行容器（启用 UDEV 支持外设访问）
docker run -it --rm --name my-app -e UDEV=1 --privileged my-node-iot-app

5.3 Docker Compose 配置示例

创建 docker-compose.yml：

yaml
version: "2"
services:
  node-app:
    image: balenalib/spacely-tx2-fedora-node:latest
    user: node  # 使用非 root 用户运行，增强安全性
    working_dir: /home/node/app
    environment:
      - NODE_ENV=production  # 设置 Node.js 环境变量
      - UDEV=1  # 启用 UDEV 设备检测
    volumes:
      - ./:/home/node/app  # 挂载本地代码（开发环境用）
    devices:
      - /dev:/dev  # 映射主机设备（需 --privileged 权限）
    expose:
      - "8080"  # 暴露内部端口
    command: npm start  # 启动应用

启动服务：

bash
docker-compose up -d

5.4 运行单文件脚本

无需编写 Dockerfile，直接运行 Node.js 脚本：

bash
# 挂载当前目录至容器，执行脚本
docker run -it --rm \
  -v "$PWD":/usr/src/app \
  -w /usr/src/app \
  -e UDEV=1 \
  --privileged \
  balenalib/spacely-tx2-fedora-node:latest \
  node sensor-reader.js  # 替换为实际脚本路径

6. 支持的版本和官方资源

6.1 支持的 Node.js 版本

• 12.10.0（latest）、12.9.1、11.15.0、10.16.3、9.11.2、8.16.1、6.17.1

版本详情可查看 https://github.com/balena-io-library/official-images/blob/master/library/spacely-tx2-fedora-node（GitHub 仓库）。

6.2 环境变量配置

7. 用户反馈与贡献

7.1 问题反馈

如遇镜像使用问题，可通过 https://github.com/balena-io-library/base-images/issues 提交反馈。

7.2 贡献指南

欢迎提交 PR 改进镜像（如功能增强、bug 修复），建议先通过 https://github.com/balena-io-library/base-images/issues 讨论变更方案。

更多文档可参考 https://www.balena.io/docs/reference/base-images/base-images/#balena-base-images?ref=dockerhub 或 https://www.balena.io/blog/new-year-new-balena-base-images/?ref=dockerhub。