Cleer Arc5耳机Jenkins Pipeline构建固件镜像

原创于 2025-11-20 13:25:33 发布 · 919 阅读

26 ·

CC 4.0 BY-SA版权

文章标签：

#Jenkins #Pipeline #固件构建

AI助手已提取文章相关产品：

Cleer Arc5耳机Jenkins Pipeline构建固件镜像

在智能音频设备飞速迭代的今天，你有没有遇到过这样的场景：凌晨两点，QA团队等着测试新固件，结果构建失败了——原因是某位同事本地用的是旧版编译器？😅 或者更糟，OTA升级后耳机变“砖”，调查发现是漏签了固件……这些问题，在Cleer Arc5的研发过程中，我们都踩过坑。

于是我们决定： 把固件构建这件事，彻底交给机器去做。

现在，每当开发者敲下 git push ，几分钟后就能收到一条 Slack 消息：

🚀 构建成功 | Cleer Arc5 固件 v123
📦 镜像已生成：cleer_arc5_v123.img
🔗 提交哈希：a1b2c3d
👷 构建耗时：4分38秒

这一切的背后，就是我们基于 Jenkins Pipeline 打造的自动化固件构建系统。它不只是“自动跑个 make”，而是一整套覆盖安全、效率、可追溯性的工程实践。

为什么是 Jenkins？

虽然 GitHub Actions、GitLab CI 等新兴工具越来越流行，但在我们的嵌入式环境中，Jenkins 依然是那个“稳如老狗”的选择 🐶。原因很简单：

支持复杂的并行任务调度（比如左右耳并发编译）
对私有网络和物理构建机的支持成熟
插件生态丰富，能轻松对接内部 OTA 平台、Slack、Nexus 等系统
可以精细控制资源分配，避免主控节点被编译任务拖垮

更重要的是， 我们可以把整个流程写成代码 —— 这就是所谓的“流水线即代码”（Pipeline as Code）。

pipeline {
    agent { label 'embedded-builder' }
    stages {
        stage('Checkout') { ... }
        stage('Build Left/Right') { 
            parallel { ... } 
        }
        stage('Sign & Upload') { ... }
    }
}

这个叫 Jenkinsfile 的文件，就躺在项目根目录里，和代码一起版本化管理。谁改了构建逻辑？查 Git 历史就知道。是不是比口头通知“我改了编译脚本”靠谱多了？😎

构建一次，处处一致：交叉编译环境怎么搞？

Cleer Arc5 耳机的主控芯片是基于 ARM Cortex-M4 的定制音频 SoC，这意味着我们必须在 x86_64 的服务器上进行 交叉编译 。

早期我们吃过亏：不同工程师用的 GCC 版本不一，有的开了硬件浮点，有的没开，导致同样的代码在 CI 上跑不过。后来我们统一使用 arm-none-eabi-gcc 工具链，并通过 Docker 镜像固化版本：

FROM ubuntu:20.04
RUN apt-get update && \
    apt-get install -y gcc-arm-none-eabi python3-pip
COPY toolchain /opt/toolchain
ENV PATH="/opt/toolchain/bin:$PATH"

现在所有构建都在同一个镜像中运行，真正做到“在我机器上能跑，在哪都能跑”。

关键编译参数也锁死了：

参数	作用
`-mcpu=cortex-m4`	目标 CPU 架构
`-mfloat-abi=hard`	启用硬件浮点，提升 ANC 算法性能
`-Os`	优化体积，Flash 只有 1MB 怎么办？省着用！
`--gc-sections`	删除未引用函数，进一步瘦身

💡 小贴士：别小看 --gc-sections ，我们曾经靠它从镜像里抠出 37KB 空间，刚好够塞进一个新的语音唤醒模型！

固件打包 ≠ 把 bin 文件拼起来

你以为打包就是把左耳、右耳的 .bin 文件合并一下？Too young too simple 😏

我们的 .img 镜像是一个带 头部元数据 + 数字签名 的完整容器，结构长这样：

struct firmware_header {
    uint32_t magic;         // 0xCLEER5AA ← 防止误刷其他设备
    uint32_t version;
    uint32_t timestamp;
    uint32_t le_offset, le_size;
    uint32_t re_offset, re_size;
    uint32_t crc32;         // 整体校验，防止传输损坏
    uint8_t  signature[256]; // RSA-2048 PKCS#1 v1.5 ← 安全防线！
};

打包过程由 Python 脚本 package_firmware.py 自动完成：

python3 scripts/package_firmware.py \
    --left build/left/app.bin \
    --right build/right/app.bin \
    --output build/cleer_arc5_v${BUILD_NUMBER}.img \
    --version ${GIT_COMMIT_SHORT}

然后立刻用 OpenSSL 签名：

openssl dgst -sha256 -sign ${SIGNING_KEY} \
    -out build/firmware.sig build/cleer_arc5_v${BUILD_NUMBER}.img

🔐 安全提示：私钥绝对不能硬编码！我们通过 Jenkins Credentials Binding 插件注入：

environment {
    SIGNING_KEY = credentials('arc5-signing-key-pem')
}

这样即使有人看到 Jenkinsfile，也拿不到密钥本体。真正的“口令不外泄”。

并行构建：让时间缩短40%

TWS 耳机有两个独立单元，那为啥要串行编译？我们直接上 parallel ：

stage('Build Firmware') {
    parallel {
        stage('Build Left Ear') {
            steps { sh 'make EAR=LEFT ...' }
        }
        stage('Build Right Ear') {
            steps { sh 'make EAR=RIGHT ...' }
        }
    }
}

这一招让我们平均构建时间从 7 分多钟降到 4 分半 ，节省近 40%！对于每天要构建几十次的开发节奏来说，简直是“时间就是金钱”的真实写照 💸。

而且 Jenkins 的 Stage View 会清晰展示两个分支的执行状态，哪个失败了一目了然。

动态 Agent：用完即焚，干净利落

早期我们用固定 Linux 构建机，结果经常因为缓存堆积、依赖污染导致奇怪问题。后来转向 Kubernetes + 动态 Pod ，体验直接起飞 ✈️。

通过 podTemplate ，每次构建都拉起一个全新的容器：

podTemplate(containers: [
  containerTemplate(name: 'builder', image: 'cleer/embedded-toolchain:arm-gcc-v10', 
                    command: 'sleep', args: 'infinity')
]) {
  node(POD_LABEL) {
    container('builder') {
      sh 'make all'
    }
  }
}

优点太明显了：
- 环境纯净，无历史残留
- 资源隔离，不影响 Jenkins Master
- 高峰期可自动扩容，低峰期缩容省钱
- 构建结束自动销毁，磁盘永不爆炸 💣➡️🗑️

⚠️ 注意事项：记得挂载大容量临时卷！一次完整编译产生的中间文件可能超过 3GB。

构建失败不可怕，可怕的是没人知道

我们最怕的不是构建失败，而是 失败了没人察觉 。所以通知机制必须到位。

Jenkins 的 post 区块就是我们的“消息中心”：

post {
    success {
        slackSend channel: '#firmware-builds', message: """
🚀 构建成功 | Cleer Arc5 固件 v${BUILD_NUMBER}
...
"""
    }
    failure {
        slackSend channel: '#alerts', message: """
❌ 构建失败 | 请查看：${env.BUILD_URL}
"""
    }
    always {
        cleanWs() // 清理 workspace，防止磁盘溢出
    }
}

成功时发到 #firmware-builds，全员同步进展；失败则直达 #alerts，@相关责任人。再也不会出现“咦，怎么没人做测试？”的尴尬局面。

我们解决了哪些“经典痛点”？

问题	我们的解法
“在我机器上好好的！”	Docker 镜像统一环境
忘记签名导致 OTA 失败	强制签名步骤，少一步都不行
多人提交版本混乱	每次构建绑定唯一 BUILD_NUMBER 和 Git SHA
编译太慢影响调试	并行 + ccache 缓存中间产物
私钥泄露风险	Jenkins Credentials + 权限分级

特别是最后一点—— 权限控制 。只有特定角色才能触发发布分支的构建，普通 PR 只能跑编译和静态检查，杜绝误操作。