企业官网建设流程全解析

Proxmark3 在 Debian 13 (Trixie) ARM64 Docker 环境中的跨平台构建与测试指南

【免费下载链接】proxmark3Iceman Fork - Proxmark3项目地址: https://gitcode.com/GitHub_Trending/pr/proxmark3

Proxmark3 提供了一套按发行版与 CPU 架构划分的 Docker 测试环境，本文聚焦其中的 Debian 13 Trixie ARM64 镜像，讲解如何为 x86 主机配置 QEMU 用户态模拟、构建并进入该 ARM64 镜像，以及如何在镜像内以非 root 用户执行完整发布测试套件或单条测试命令。读完本文，你将掌握跨架构 Docker 镜像的运行方式、镜像内各构建依赖的用途，以及release_tests.sh与pm3_tests.sh两条测试链路的实际内容。

一、这个镜像在 Proxmark3 测试矩阵中的定位

Proxmark3 仓库的docker/目录下按「发行版 + 架构」组织了一组镜像配置，每个子目录包含同名三件套：Dockerfile、docker_conf.inc（镜像名称与平台声明）、run_tests.sh（容器内测试入口）。本目录对应的配置为：

# docker/debian-13-trixie-arm64/docker_conf.inc DOCKER_IMAGE=pm3-debian-trixie-arm64:1.0 DOCKER_PLATFORM="--platform linux/arm64" SKIPQT=1

三行配置的含义：

• DOCKER_IMAGE：本环境统一使用的镜像标签，build.sh打镜像、rm.sh删镜像都依据它；
• DOCKER_PLATFORM：声明目标平台为linux/arm64，这正是需要 QEMU 跨平台支持的原因（在 x86 主机上构建/运行 ARM64 镜像）；
• SKIPQT=1：构建时跳过 Qt6 图形界面依赖，只做 CLI 客户端，加快构建。

通用的构建、运行、清理脚本位于 docker/build.sh、docker/run.sh、docker/rm.sh。三个脚本都有相同的约束：必须在某个含docker_conf.inc的子目录下执行，脚本会先.加载该文件，再执行docker build/run/rm。

二、跨平台（ARM64）支持的前置条件

在 x86_64 主机上运行linux/arm64镜像，需要 QEMU 用户态模拟配合 binfmt 注册。仓库文档给出的安装命令是：

sudo apt install qemu-user qemu-user-binfmt binfmt-support

安装后，Docker 的binfmt机制会自动把 ARM64 可执行文件透明地交给qemu-aarch64解释执行。docker/build.sh中还有更完整的备选方案注释（使用multiarch/qemu-user-static、docker buildx），并特别指出两点：

• credential=yes参数用于保证跨平台容器内的 sudo 正常工作；
• 仓库实际采用的路径是「不用 buildx，直接docker build $DOCKER_PLATFORM ...」，即 docker/build.sh 最后一行：

docker build $DOCKER_PLATFORM $BUILDARG -t "$DOCKER_IMAGE" .

三、镜像内容解析：Dockerfile 逐项说明

本镜像的 Dockerfile 基于arm64v8/debian:trixie-slim，主要内容可以分成四块：

1. 基础构建依赖（第 6–13 行）

RUN apt-get update && \ apt-get upgrade -y && \ apt-get dist-upgrade -y && \ apt-get install -y --no-install-recommends git ca-certificates build-essential cmake pkg-config libreadline-dev gcc-arm-none-eabi libnewlib-dev libbz2-dev liblz4-dev zlib1g-dev libbluetooth-dev libpython3-dev libssl-dev libgd-dev sudo && \ apt-get clean RUN apt-get install -y opencl-dev && \ apt-get clean

这些依赖分别对应 Proxmark3 的不同构建目标：build-essential/cmake/pkg-config用于编译客户端；gcc-arm-none-eabi与libnewlib-dev用于交叉编译 ARM 固件（armsrc/目录下的固件源码）；liblz4-dev对应仓库内 vendored 的 common/lz4；libbluetooth-dev服务 PM5 的 BTADDON 构建；opencl-dev则支撑 hitag2crack 等 OpenCL 加速组件（tools/pm3_tests.sh --opencl）。

2. 可选的 Qt6 图形界面

ARG SKIPQT=false RUN if [ "${SKIPQT}" = "false" ]; then \ apt-get install -y qt6-base-dev && \ apt-get clean; \ fi

由于本环境的docker_conf.inc设置了SKIPQT=1，docker/build.sh 会以--build-arg SKIPQT=1传入，跳过 Qt 依赖——纯 CLI 测试环境不需要图形界面。

3. Python 运行环境与 rrg 用户

# uv COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/ RUN useradd -ms /bin/bash rrg RUN passwd -d rrg ... RUN printf 'rrg ALL=(ALL) ALL\n' | tee -a /etc/sudoers

• 从官方 uv 镜像中拷贝uv/uvx可执行文件。tools/pm3_tests.sh 开头会检测uv是否存在，若存在则用uv run --script代替裸python3来跑 Python 测试（可用SKIPUV=1强制忽略）；
• 创建无密码的普通用户rrg并赋予其 sudo 权限——这正是文档中测试命令要su - rrg的原因。

4. UART 串口组映射（UART_GID 构建参数）

ARG UART_GID # dialout group may already exist on another numeric ID than on host RUN if [ -n "${UART_GID}" ]; then \ groupadd -g ${UART_GID} mydialout || true; \ usermod -aG ${UART_GID} rrg; \ fi

Proxmark3 通过串口（/dev/tty*）与设备通信，宿主机上该串口通常归属于dialout组，而不同发行版的组 ID 不一致。docker/build.sh 在构建时会探测宿主机串口并注入对应 GID：

UART_PORT="$(../../pm3 --list|grep /dev|head -n1|cut -d' ' -f2)" if [ -n "$UART_PORT" ]; then UART_GID="$(stat -c '%g' $UART_PORT)" BUILDARG="$BUILDARG --build-arg UART_GID=$UART_GID" fi

这样容器内的rrg用户就拥有了访问宿主机串口的正确组 ID。docker/run.sh运行时再把设备本身挂进来：

UART_PORT="$(../../pm3 --list|grep dev|head -n1|cut -d' ' -f2)" if [ -n "$UART_PORT" ]; then DEV="--device=/dev/tty0 --device=$UART_PORT" else DEV="" fi docker run $DEV $DOCKER_PLATFORM --volume="$(pwd)/../..:/home/rrg/proxmark3" -w /home/rrg/proxmark3 --net=host --rm -it "$DOCKER_IMAGE"

即把仓库根目录挂载为容器内/home/rrg/proxmark3，以该目录为工作目录，启用 host 网络（便于串口/UDP 通信），并透传串口设备。WORKDIR在 Dockerfile 中也被设为/home/rrg，最终CMD ["/bin/bash"]给出交互式 shell。

四、在容器内运行完整测试（文档主流程）

README 给出的标准流程是：脚本需在 Docker 环境内的 Proxmark3 根目录执行：

su - rrg cd proxmark3 docker/debian-13-trixie-arm64/run_tests.sh;

为什么必须su - rrg？run_tests.sh 开头显式拒绝 root：

# Check that we are not running as root if [ "$EUID" -eq 0 ]; then echo "Error: This script should not be run as root" >&2 exit 1 fi

原因是git等工具在 root 下会对仓库检出报警/拒绝，且pm3_tests.sh的部分步骤（如sudo make install）需要普通用户身份来走 sudo 路径。脚本随后做两件事：

git config --global --add safe.directory /home/rrg/proxmark3 tools/release_tests.sh

safe.directory的登记解决跨用户属主导致的 git “dubious ownership” 报错；最后的连续 10 次响铃（echo -e "\a"循环）是测试全部通过后的听觉提示。

release_tests.sh 实际执行了什么

tools/release_tests.sh 是发布前的全量构建回归，按顺序执行：

1. 检查Makefile.platform中不存在SKIP_指令（会干扰全量构建），然后make clean && make -j编译三个平台组合：
   • PLATFORM=PM3GENERIC STANDALONE=LF_SAMYRUN，并紧接着跑tools/pm3_tests.sh --long（含慢速测试）；
   • PLATFORM=PM3RDV4 STANDALONE=HF_ST25_TEAROFF；
   • PLATFORM=PM3RDV4 PLATFORM_EXTRAS=BTADDON STANDALONE=HF_REBLAY；
2. 对 BTADDON 组合额外执行sudo make install，在/tmp下用proxmark3 -c 'data load -f lf_EM4x05.pm3; lf search -1'验证安装后的二进制能识别 FDX-B 卡，再sudo make uninstall；
3. 用 CMake 在client/build下分别按上述三个平台组合构建客户端，并对第一个组合跑pm3_tests.sh --clientbin $(pwd)/proxmark3 client；
4. 构建并测试hitag2crack工具，最后输出PASS。

任一环节失败脚本即exit 1，因此该脚本本身就是“能否发布”的判定器。

五、手动运行单条测试（文档第二流程）

README 的第二种用法是跳过release_tests.sh，手动编译后只跑一条测试：

apt update && sudo apt upgrade -y su - rrg cd proxmark3 git config --global --add safe.directory /home/rrg/proxmark3 make clean; make -j tools/pm3_tests.sh --long

其中--long的含义由 tools/pm3_tests.sh 的参数解析给出：它把SLOWTESTS=true打开，执行包含慢速测试的完整目标集。完整用法（脚本--help输出）为：

Usage: pm3_tests.sh [--long] [--opencl] [--clientbin /path/to/proxmark3] [mfkey|nonce2key|mf_nonce_brute|staticnested|mfd_aes_brute|mfulc_des_brute|cryptorf|fpga_compress|bootrom|armsrc|client|recovery|common] --long: Enable slow tests --opencl: Enable tests requiring OpenCL (preferably a Nvidia GPU) --clientbin ...: Specify path to proxmark3 binary to test If no target given, all targets will be tested

也就是说，单条测试只需把--long换成目标名即可，例如tools/pm3_tests.sh mfkey只跑 mfkey 相关测试，tools/pm3_tests.sh bootrom只验证 bootrom 构建产物。注意--opencl依赖 OpenCL 运行时——本 ARM64 镜像只装了opencl-dev（头文件/桩），在无 GPU 的模拟环境下该项基本只覆盖 CPU 回退路径，这是使用该镜像时需要了解的限制。

六、清理

用 docker/rm.sh 移除容器、镜像与构建缓存：

CONTAINER=$(docker ps -aq --filter ancestor="$DOCKER_IMAGE") if [ -n "$CONTAINER" ]; then docker rm $CONTAINER fi docker image rm "$DOCKER_IMAGE" docker builder prune --force

七、小结与适用前提

• 适用前提：宿主机已安装 Docker，并已按第二节安装qemu-user qemu-user-binfmt binfmt-support以支持 ARM64 模拟；build.sh/run.sh/rm.sh都必须在docker/debian-13-trixie-arm64/这类子目录下执行；
• 完整链路：build.sh（探测串口 → 注入UART_GID/SKIPQT→ 打pm3-debian-trixie-arm64:1.0镜像）→run.sh（挂载仓库、透传串口、host 网络进入容器）→ 容器内su - rrg && docker/debian-13-trixie-arm64/run_tests.sh或手动make -j && tools/pm3_tests.sh <target>；
• 该环境的价值在于：用一套与目标发行版一致的依赖（Debian Trixie + ARM 交叉工具链 + OpenCL 桩 + uv）保证 Proxmark3 各平台组合（PM3GENERIC/PM3RDV4/BTADDON）与客户端 CMake 构建在 CI 式环境中可复现，release_tests.sh的最终PASS即为回归通过标志。

【免费下载链接】proxmark3Iceman Fork - Proxmark3项目地址: https://gitcode.com/GitHub_Trending/pr/proxmark3