ansible-openwisp2-imagegenerator

这个 Ansible 角色允许为不同的组织构建多个 openwisp2 固件镜像，同时记录它们的配置。

注意：这个角色尚未在实际环境中测试。如果你打算使用它，可以试试看，如果出现问题，请报告你的问题，但请记住，你需要了解 构建过程 及其内部工作原理，以便使其正常工作。

必需的角色变量

以下变量是必需的：

• openwisp2fw_source_dir：指示在 编译 中使用的 OpenWRT 源代码目录
• openwisp2fw_generator_dir：指示用于 生成器准备 的目录
• openwisp2fw_bin_dir：指示在 构建最终镜像 时使用的目录
• openwisp2fw_organizations：一个组织列表；请查看 创建剧本章节 中的示例 playbook.yml 文件以了解其结构

使用方法（教程）

如果你不知道如何使用 Ansible，不要惊慌，这个过程将逐步指导你。

如果你已经知道如何使用 Ansible，可以跳过此部分，直接进入“安装此角色”部分。

首先，你需要理解两个关键概念：

• “编译服务器”指的是用于编译镜像的服务器
• “本地机器”指的是你启动 Ansible 的主机，例如：你自己的笔记本电脑或 CI 服务器

Ansible 是一个配置管理/自动化工具，通过 SSH 进入编译服务器并执行一系列命令。

1. 安装 Ansible

如果你还没有在 本地机器 上安装 Ansible，可以使用多种方式来完成，但我们建议使用官方的 Python 包管理器，例如：

sudo pip install ansible

如果你没有安装 pip，请查看 安装 pip 的文档网站。

以其他方式安装 Ansible 也可以，只需确保安装 2.0.x 版本（这是我们测试该剧本所使用的版本）。

2. 安装此角色

为了简便起见，最简单的方法是在 本地机器 上通过 ansible-galaxy 安装此角色（该命令在安装 Ansible 时已被安装），因此运行：

sudo ansible-galaxy install openwisp.openwisp2-imagegenerator

3. 选择工作目录

选择一个 本地机器 上用于放置固件镜像配置的工作目录。

例如：

mkdir ~/my-openwisp2-firmware-conf
cd ~/my-openwisp2-firmware-conf

将此工作目录置于版本控制之下也是一个很好的主意，这会帮助你跟踪更改，回滚，设置 CI 服务器以自动构建镜像等等。

4. 创建清单文件

清单文件是定义服务器组的地方。在我们的简单情况下，我们可以定义一个只包含一台服务器的组。

在 本地机器 上创建一个新文件 hosts，内容如下：

[myserver]
mycompiler.mydomain.com ansible_user=<youruser> ansible_become_pass=<sudo-password>

将 mycompiler.mydomain.com 替换为你的主机名（也可以使用 IP 地址）。

同样，将你的 SSH 用户和密码分别放在 <youruser> 和 <sudo-password> 位置（必须是 sudo 权限且非 root 用户）。这些凭据在 安装依赖项步骤 中使用。

5. 创建剧本文件

在 本地机器 上创建一个新剧本文件 playbook.yml，内容如下：

# playbook.yml
- hosts: your_host_here
  roles:
    - openwisp.openwisp2-imagegenerator
  vars:
    openwisp2fw_source_dir: /home/user/openwisp2-firmware-source
    openwisp2fw_generator_dir: /home/user/openwisp2-firmware-generator
    openwisp2fw_bin_dir: /home/user/openwisp2-firmware-builds
    openwisp2fw_source_targets:
        - system: ar71xx
          subtarget: generic
          profile: Default
        - system: x86
          subtarget: generic
          profile: Generic
    openwisp2fw_organizations:
        - name: snakeoil # 组织名称
          flavours: # 支持的种类
            - standard
          luci_openwisp: # /etc/config/luci_openwisp
            # 其他配置键可以自由添加
            username: "operator"
            # 明文密码将在 /etc/config/luci_openwisp 中加密
            password: "<CHANGE_ME>"
          openwisp: # /etc/config/openwisp
            # 其他配置键可以自由添加
            url: "https://my-openwisp2-instance.com"
            shared_secret: "my-openwisp2-secret"
            unmanaged: "{{ openwisp2fw_default_unmanaged }}"
          # 明文密码将在 /etc/shadow 中加密
          root_password: "<CHANGE_ME>"

该剧本将让你为名为 snakeoil 的组织编译固件镜像，仅使用 standard 种类（包含默认的 OpenWRT 19.07 镜像和标准的 OpenWISP2 模块），支持 ar71xx 和 x86 两种体系结构。

请参见 角色变量 部分，了解如何自定义可用的配置。

此时，你的目录结构应如下所示：

.
├── hosts
└── playbook.yml

6. 运行剧本

现在是时候 开始编译 OpenWISP2 固件。

从 本地机器 启动剧本，命令如下：

ansible-playbook -i hosts playbook.yml -e "recompile=1 cores=4"

你可以将 cores=4 替换为你拥有的核心数量。

当剧本运行完成后，你将在 编译服务器 中找到图像，位于 openwisp2fw_bin_dir 指定的目录中，在我们的示例中为 /home/user/openwisp2-firmware-builds，其目录结构如下所示：

/home/user/openwisp2-firmware-builds
├── snakeoil/                                      # (每个组织都有自己的目录)
├── snakeoil/2016-12-02-094316/ar71xx/standard/    # (包含 ar71xx 的标准种类镜像)
├── snakeoil/2016-12-02-094316/x86/standard/       # (包含 x86 的标准种类镜像)
└── snakeoil/latest/                               # (latest 是指向最后一次编译的符号链接)

现在，如果你按照本教程操作且一切正常，你就可以准备好自定义配置以满足你的需求！继续阅读以了解如何完成此任务。

角色变量

如果需要，可以自定义许多变量，请查看 默认值 以获取详细列表。

部分变量也在 组织 和 种类 中进行了说明。

组织

如果你正在使用 OpenWISP，可能需要为不同的群体编译镜像：盈利客户、非盈利组织或任何可以定义为“组织”的群体。

组织可以在 openwisp2fw_organizations 中随意定义。

具体示例请参考 “示例 playbook.yml 文件” 。

如果需要为每个组织的镜像文件系统树中添加特定文件，请参见 “为特定组织添加文件” 。

种类

种类是包含在镜像中的软件包组合。

你可能希望为你的镜像创建不同的种类，例如：

• standard：最常见的用例
• minimal：适合存储空间较小的设备的镜像
• mesh：用于实现网状网络所需的包的镜像

默认情况下，仅有 standard 种类可用。

你可以通过设置 openwisp2fw_image_flavours 来定义自己的种类——查看 默认变量以了解其结构。

构建过程

构建过程由以下几个步骤组成。

1. 安装依赖项

标签： install

在此阶段，安装或升级后续步骤所需的操作系统依赖项。

2. 编译

标签： compile

编译 OpenWRT 源代码以生成称为 “图像生成器” 的内容。 图像生成器 是一个包含预编译包和一个特殊的 Makefile 的档案，该 Makefile 用于为每个组织生成定制的镜像。

源代码在 openwisp2fw_source_dir 指定的目录中下载和编译。

3. 生成器准备

标签： generator

在此步骤中，图像生成器 被提取和准备，用于为不同的 组织 构建不同的镜像，每个组织可以为不同的 种类 构建镜像（例如：全功能、最小、网状等）；

图像在 openwisp2fw_generator_dir 指定的目录中提取和准备。

4. 构建最终镜像

标签： build

在此阶段，生成一系列镜像。

将为每个架构、组织和种类构建多个镜像。 这可能会生成很多文件，因此请谨慎使用这个功能：最好从较少的选项开始，随着进展逐步添加更多案例。

例如，如果你选择使用 2 种架构（ar71xx 和 x86）、2 个组织（例如：A 和 B）和 2 个种类（例如：standard 和 mini），你将获得 8 组镜像：

• 组织： A / 种类： standard / 架构： ar71xx
• 组织： A / 种类： standard / 架构： x86
• 组织： A / 种类： mini / 架构： ar71xx
• 组织： A / 种类： mini / 架构： x86
• 组织： B / 种类： standard / 架构： ar71xx
• 组织： B / 种类： standard / 架构： x86
• 组织： B / 种类： mini / 架构： ar71xx
• 组织： B / 种类： mini / 架构： x86

图像将创建在 openwisp2fw_bin_dir 指定的目录中。

5. 上传镜像到 OpenWISP 固件升级器

最后一步是将镜像上传到 OpenWISP 固件升级器模块。 此步骤是可选的，并默认禁用。

要启用此功能，需配置变量 openwisp2fw_uploader 和 openwisp2fw_organizations.categories ，如下示例所示：

- hosts:
    - myhost
  roles:
    - openwisp.openwisp2-imagegenerator
  vars:
    openwisp2fw_controller_url: "https://openwisp.myproject.com"
    openwisp2fw_organizations:
      - name: staging
        flavours:
          - default
        openwisp:
          url: "{{ openwisp2fw_controller_url }}"
          shared_secret: "xxxxx"
        root_password: "xxxxx"
        categories:
          default: <CATEGORY-UUID>
      - name: prod
        flavours:
          - default
        openwisp:
          url: "{{ openwisp2fw_controller_url }}"
          shared_secret: "xxxxx"
        root_password: "xxxxx"
        categories:
          default: <CATEGORY-UUID>
    openwisp2fw_uploader:
        enabled: true
        url: "{{ openwisp2fw_controller_url }}"
        token: "<REST-API-USER-TOKEN>"
        image_types:
            - ath79-generic-ubnt_airrouter-squashfs-sysupgrade.bin
            - ar71xx-generic-ubnt-bullet-m-xw-squashfs-sysupgrade.bin
            - ar71xx-generic-ubnt-bullet-m-squashfs-sysupgrade.bin
            - octeon-erlite-squashfs-sysupgrade.tar
            - ath79-generic-ubnt_nanostation-loco-m-xw-squashfs-sysupgrade.bin
            - ath79-generic-ubnt_nanostation-loco-m-squashfs-sysupgrade.bin
            - ath79-generic-ubnt_nanostation-m-xw-squashfs-sysupgrade.bin
            - ar71xx-generic-ubnt-nano-m-squashfs-sysupgrade.bin
            - ath79-generic-ubnt_unifiac-mesh-squashfs-sysupgrade.bin
            - x86-64-combined-squashfs.img.gz
            - x86-generic-combined-squashfs.img.gz
            - x86-geode-combined-squashfs.img.gz
            - ar71xx-generic-xd3200-squashfs-sysupgrade.bin

示例中的以下占位符需要替换：

• <CATEGORY-UUID> 是 OpenWISP 固件升级器中固件类别的 UUID
• <REST-API-USER-TOKEN> 是具有上传镜像权限的用户的 REST 认证令牌

你可以通过使用 OpenWISP 的可浏览 API Web 界面发送 POST 请求来检索 REST 认证令牌：

1. 在浏览器中打开 https://<openwisp-base-url>/api/v1/user/token/。
2. 在页面底部的表单中输入用户名和密码。
3. 提交表单后，你将获得响应中的 REST 认证令牌。

上传脚本创建一个新的构建对象，然后上传 image_types 中指定的固件镜像，这些镜像需要对应于 OpenWISP 固件升级器 中定义的标识符，如 ar71xx-generic-tl-wdr4300-v1-il-squashfs-sysupgrade.bin。

关于 upload_firmware.py 脚本的其他重要信息：

• 脚本从 OpenWrt 源代码的 .config 文件中读取 CONFIG_VERSION_DIST 和 CONFIG_VERSION_NUMBER 以确定构建版本。
• 脚本将查找是否已经存在相同版本和类别的构建，并尝试将图像添加到该构建中，而不是创建一个新的构建；如果发现重复，控制台将打印失败消息，但脚本不会终止；这样可以为新硬件型号生成图像，并将其添加到现有构建中。

向镜像添加文件

你可以通过将这些文件放置在剧本目录中的名为 files/ 的目录中，向每个生成的镜像添加任意文件。

示例：

.
├── hosts
├── playbook.yml
└── files/etc/profile

files/etc/profile 将被添加到每个生成的镜像中。

为特定组织添加文件

你也可以向特定组织的镜像添加文件。

假设你有一个名为 snakeoil 的组织，并想添加一个自定义横幅，你可以通过创建以下目录结构来完成：

.
├── hosts
├── playbook.yml
└── organizations/snakeoil/etc/banner

由于这个步骤是在构建最终镜像之前执行的最后几个步骤之一，因此你可以利用此功能覆盖之前步骤中自动构建的任何文件。

额外参数

你可以将以下额外参数传递给 ansible-playbook：

• recompile：是否重复编译步骤
• cores：在编译步骤中使用的核心数量
• orgs：如果需要将镜像生成限制为特定组织，可以使用逗号分隔的组织名称列表

示例

用 16 个核心重新编译：

ansible-playbook -i hosts playbook.yml -e "recompile=1 cores=16"

仅生成组织 foo 的镜像：

ansible-playbook -i hosts playbook.yml -e "orgs=foo"

仅生成组织 foo 和 bar 的镜像：

ansible-playbook -i hosts playbook.yml -e "orgs=foo,bar"

运行特定步骤

由于过程中的每个步骤都带有标签，你可以使用 Ansible 标签运行特定步骤。

示例 1，仅运行生成器准备：

ansible-playbook -i hosts playbook.yml -t generator

示例 2，仅运行生成器准备和构建步骤：

ansible-playbook -i hosts playbook.yml -t generator,build

没有子目标的目标

这个示例展示如何填写 openwisp2fw_source_targets 以编译不指定子目标的目标（例如：sunxi、ARMv8、QEMU）：

openwisp2fw_source_targets:
    # Allwinner SOC, Lamobo R1
    - system: sunxi
      profile: sun7i-a20-lamobo-r1
    # QEMU ARM 虚拟镜像
    - system: armvirt
      profile: Default

支持

请查看 OpenWISP 支持渠道。