查看英文说明 | View English description
Github Actions 是 Microsoft 推出的一项服务，它提供了性能配置非常不错的虚拟服务器环境，基于它可以进行构建、测试、打包、部署项目。对于公开仓库可免费无时间限制地使用，且单次编译时间长达 6 个小时，这对于编译 Armbian 来说是够用的（我们一般在3小时左右可以完成一次编译工作）。分享只是为了交流经验，不足的地方请大家理解，请不要在网络上发起各种不好的攻击行为，也不要恶意使用 GitHub Actions。
- Armbian 构建及使用方法
- 目录
- 1. 注册自己的 Github 的账户
- 2. 设置隐私变量 GITHUB_TOKEN
- 3. Fork 仓库并设置 GH_TOKEN
- 4. 个性化 Armbian 固件定制文件说明
- 5. 编译固件
- 6. 保存固件
- 7. 下载固件
- 8. 安装 Armbian 到 EMMC
- 9. 编译 Armbian 内核
- 10. 更新 Armbian 内核
- 11. 安装常用软件
- 12. 常见问题
注册自己的账户，以便进行固件个性化定制的继续操作。点击 github.com 网站右上角的 Sign up 按钮，根据提示注册自己的账户。
设置 Github 隐私变量 GITHUB_TOKEN 。在固件编译完成后，我们需要上传固件到 Releases ，我们根据 Github 官方的要求设置这个变量，方法如下：
Personal center: Settings > Developer settings > Personal access tokens > Generate new token ( Name: GITHUB_TOKEN, Select: public_repo )。其他选项根据自己需要可以多选。提交保存，复制系统生成的加密 KEY 的值，先保存到自己电脑的记事本，下一步会用到这个值。图示如下：
现在可以 Fork 仓库了，打开仓库 https://github.com/ophub/amlogic-s9xxx-armbian ，点击右上的 Fork 按钮，复制一份仓库代码到自己的账户下，稍等几秒钟，提示 Fork 完成后，到自己的账户下访问自己仓库里的 amlogic-s9xxx-armbian 。在右上角的 Settings > Secrets > Actions > New repostiory secret ( Name: GH_TOKEN, Value: 填写刚才GITHUB_TOKEN的值 )，保存。并在左侧导航栏的 Actions > General > Workflow permissions 下选择 Read and write permissions 并保存。图示如下：
固件编译的流程在 .github/workflows/build-armbian.yml 文件里控制，在 workflows 目录下还有其他 .yml 文件，实现其他不同的功能。编译固件时采用了 Armbian 官方的当前代码进行实时编译，相关参数可以查阅官方文档。
- name: Compile Armbian [ ${{ env.ARMBIAN_BOARD }} ]
id: compile
run: |
cd build/
sudo chmod +x compile.sh
sudo ./compile.sh BRANCH=${{ env.ARMBIAN_BRANCH }} RELEASE=${{ env.ARMBIAN_RELEASE }} BOARD=${{ env.ARMBIAN_BOARD }} \
BUILD_MINIMAL=no BUILD_DESKTOP=no HOST=armbian KERNEL_ONLY=no KERNEL_CONFIGURE=no \
CLEAN_LEVEL=make,debs COMPRESS_OUTPUTIMAGE=sha
echo "status=success" >> ${GITHUB_OUTPUT}固件编译的方式很多，可以设置定时编译，手动编译，或者设置一些特定事件来触发编译。我们先从简单的操作开始。
在自己仓库的导航栏中，点击 Actions 按钮，再依次点击 Build armbian > Run workflow > Run workflow ，开始编译，等待大约 3 个小时，全部流程都结束后就完成编译了。图示如下：
在 .github/workflows/build-armbian.yml 文件里，使用 Cron 设置定时编译，5 个不同位置分别代表的意思为 分钟 (0 - 59) / 小时 (0 - 23) / 日期 (1 - 31) / 月份 (1 - 12) / 星期几 (0 - 6)(星期日 - 星期六)。通过修改不同位置的数值来设定时间。系统默认使用 UTC 标准时间，请根据你所在国家时区的不同进行换算。
schedule:
- cron: '0 17 * * *'固件保存的设置也在 .github/workflows/build-armbian.yml 文件里控制。我们将编译好的固件通过脚本自动上传到 github 官方提供的 Releases 里面。
- name: Upload Armbian Firmware to Release
uses: ncipollo/release-action@main
if: ${{ steps.build.outputs.status }} == 'success' && env.UPLOAD_RELEASE == 'true' && !cancelled()
with:
tag: Armbian_${{ env.FILE_DATE }}
artifacts: ${{ env.FILEPATH }}/*
allowUpdates: true
token: ${{ secrets.GH_TOKEN }}
body: |
This is Armbian firmware for Amlogic s9xxx TV Boxes
* Firmware information
Default username: root
Default password: 1234从仓库首页右下角的 Release 版块进入，选择和自己盒子型号对应的固件。图示如下：
登录 Armbian 系统 (默认用户: root, 默认密码: 1234) → 输入命令：
armbian-install默认将安装主线 u-boot，以便支持 5.10 及以上内核的使用。如果选择不安装，请在第 1 个输入参数中指定，如 armbian-install no
支持在 Ubuntu20.04/22.04 或 Armbian 系统中编译内核。支持本地编译，也支持使用 GitHub Actions 云编译，具体方法详见 内核编译说明。
登录 Armbian 系统 → 输入命令：
# 使用 root 用户运行 (sudo -i)
# 如果不指定其他参数，以下更新命令将更新到当前同系列内核的最新版本。
armbian-update如果当前目录下有成套的内核文件，将使用当前目录的内核进行更新（更新需要的 4 个内核文件是 header-xxx.tar.gz, boot-xxx.tar.gz, dtb-amlogic-xxx.tar.gz, modules-xxx.tar.gz。其他内核文件不需要，如果同时存在也不影响更新，系统可以准确识别需要的内核文件）。如果当前目录没有内核文件，将从服务器查询并下载同系列的最新内核进行更新。你也可以查询可选内核版本，进行指定版本更新：armbian-update 5.10.125。在设备支持的可选内核里可以自由更新，如从 5.10.125 内核更新为 5.15.50 内核。内核更新时，默认从 stable 内核版本分支下载，如果下载其他 版本分支 的内核，请在第 2 个参数中根据分支文件夹名称指定，如 armbian-update 5.10.125 dev 。默认不安装主线 u-boot（部分设备安装后可以获得更好的支持），如果选择安装，请在第 3 个输入参数中指定，如 armbian-update 5.10.125 stable yes
内核中的 headers 文件默认安装在 /use/local/include 目录下。
登录 Armbian 系统 → 输入命令：
armbian-software使用 armbian-software -u 命令可以更新本地的软件中心列表。根据用户在 Issue 中的需求反馈，逐步整合常用软件，实现一键安装/更新/卸载等快捷操作。包括 docker 镜像、桌面软件、应用服务 等。详见更多说明。
在 Armbian 的使用中，一些可能遇到的常见问题汇总如下。
请查阅说明
请查阅说明
通常使用 armbian-ddbr 备份恢复，或者使用 Amlogic 刷机工具恢复原安卓 TV 系统。
建议您在全新的盒子里安装 Armbian 系统前，先对当前盒子自带的原安卓 TV 系统进行备份，以便在需要恢复系统时使用。请从 TF/SD/USB 启动 Armbian 系统，输入 armbian-ddbr 命令，然后根据提示输入 b 进行系统备份，备份文件的存放路径为 /ddbr/BACKUP-arm-64-emmc.img.gz ，请下载保存。在需要恢复安卓 TV 系统时，将之前备份的文件上传至 TF/SD/USB 设备的相同路径下，输入 armbian-ddbr 命令，然后根据提示输入 r 进行系统恢复。
-
一般情况下，重新插入电源，如果可以从 USB 中启动，只要重新安装即可，多试几次。
-
如果接入显示器后，屏幕是黑屏状态，无法从 USB 启动，就需要进行盒子的短接初始化了。先将盒子恢复到原来的安卓系统，再重新刷入 Armbian 系统。首先下载 amlogic_usb_burning_tool 系统恢复工具并安装好。准备一条 USB 双公头数据线，准备一个 曲别针。
-
以 x96max+ 为例，在盒子的主板上确认 短接点 的位置，下载盒子的 Android TV 固件包。其他常见设备的安卓 TV 系统固件及对应的短接点示意图也可以在此下载查看。
操作方法：
1. 打开刷机软件 USB Burning Tool:
[ 文件 → 导入固件包 ]: X96Max_Plus2_20191213-1457_ATV9_davietPDA_v1.5.img
[ 选择 ]：擦除 flash
[ 选择 ]：擦除 bootloader
点击 [ 开始 ] 按钮
2. 使用 [ 曲别针 ] 将盒子主板上的 [ 两个短接点进行短接连接 ]，
并同时使用 [ USB 双公头数据线 ] 将 [ 盒子 ] 与 [ 电脑 ] 进行连接。
3. 当看到 [ 进度条开始走动 ] 后，拿走曲别针，不再短接。
4. 当看到 [ 进度条 100% ], 则刷机完成，盒子已经恢复成 Android TV 系统。
点击 [ 停止 ] 按钮, 拔掉 [ 盒子 ] 和 [ 电脑 ] 之间的 [ USB 双公头数据线] 。
5. 如果以上某个步骤失败，就再来一次，直至成功。
如果进度条没有走动，可以尝试插入电源。通长情况下不用电源支持供电，只 USB 双公头的供电即可满足刷机要求。
当完成恢复出厂设置，盒子已经恢复成 Android TV 系统，其他安装 Armbian 系统的操作，就和你之前第一次安装系统时的要求一样了，再来一遍即可。
- 把刷好固件的 USB/TF/SD 插入盒子。
- 开启开发者模式: 设置 → 关于本机 → 版本号 (如: X96max plus...), 在版本号上快速连击 5 次鼠标左键, 看到系统显示
开启开发者模式的提示。 - 开启 USB 调试模式: 系统 → 高级选选 → 开发者选项 (设置
开启USB调试为启用)。启用ADB调试。 - 安装 ADB 工具：下载 adb 并解压，将
adb.exe，AdbWinApi.dll，AdbWinUsbApi.dll三个文件拷⻉到c://windows/目录下的system32和syswow64两个文件夹内，然后打开cmd命令面板，使用adb --version命令，如果有显示就表示可以使用了。 - 进入
cmd命令模式。输入adb connect 192.168.1.137命令（其中的 ip 根据你的盒子修改，可以到盒子所接入的路由器设备里查看），如果链接成功会显示connected to 192.168.1.137:5555 - 输入
adb shell reboot update命令，盒子将重启并从你插入的 USB/TF/SD 启动，从浏览器访问固件的 IP 地址，或者 SSH 访问即可进入固件。
默认情况下启用对红外接收器的支持，但如果您将电视盒用作服务器，那么您可能希望禁用 IR 内核模块以防止错误地关闭您的盒子。 要完全禁用 IR，请添加以下行：
blacklist meson_ir至 /etc/modprobe.d/blacklist.conf 并重启。
-
目前已知的设备中，只有
T95(s905x)/T95Z-Plus(s912)盒子需要使用/bootfs/extlinux/extlinux.conf文件。将固件写入 USB 后，双击打开，将固件自带的/boot/extlinux/extlinux.conf.bak文件名称中的.bak删除即可使用。当写入 eMMC 时armbian-install会自动检查，如果存在extlinux.conf文件，会自动创建。 -
其他设备只需要
/boot/uEnv.txt即可启动，不要修改extlinux.conf.bak文件。
网络配置文件 /etc/network/interfaces 的内容如下：
source /etc/network/interfaces.d/*
# Network is managed by Network manager
# You can choose one of the following two IP setting methods:
# Use # to disable another setting method
# 01. Enable dynamic DHCP to assign IP
auto eth0
iface eth0 inet dhcp
hwaddress ether 12:34:56:78:9A:BC
# 02. Enable static IP settings(IP is modified according to the actual)
#auto eth0
#allow-hotplug eth0
#iface eth0 inet static
#address 192.168.1.100
#netmask 255.255.255.0
#gateway 192.168.1.6
#dns-nameservers 192.168.1.6
# 03. Docker install OpenWrt and communicate with each other
#allow-hotplug eth0
#no-auto-down eth0
#auto eth0
#iface eth0 inet manual
#
#auto macvlan
#iface macvlan inet dhcp
# hwaddress ether 12:34:56:78:9a:bc
# pre-up ip link add macvlan link eth0 type macvlan mode bridge
# post-down ip link del macvlan link eth0 type macvlan mode bridge
#
#auto lo
#iface lo inet loopback默认采用 DHCP 动态 分配 IP 的策略（方法1），由 Armbian 所接入的网络路由器自动分配 IP。如果想改为静态 IP，可以把设置方法 1 禁用或删除，启用方法 2 的静态 IP 设置。
source /etc/network/interfaces.d/*
auto eth0
iface eth0 inet dhcp其中的 IP 和网关和 DNS 根据自己的网络情况修改。
source /etc/network/interfaces.d/*
auto eth0
allow-hotplug eth0
iface eth0 inet static
address 192.168.1.100
netmask 255.255.255.0
gateway 192.168.1.1
dns-nameservers 192.168.1.1其中的 MAC 地址根据自己的需要修改。
source /etc/network/interfaces.d/*
allow-hotplug eth0
no-auto-down eth0
auto eth0
iface eth0 inet manual
auto macvlan
iface macvlan inet dhcp
pre-up ip link add macvlan link eth0 type macvlan mode bridge
post-down ip link del macvlan link eth0 type macvlan mode bridge
auto lo
iface lo inet loopback新增网络接口 eth0 并立即生效（默认设置 DHCP 获取动态 IP 地址），其中 MYETH 根据自己的情况修改。
MYETH=eth0
nmcli connection add \
con-name $MYETH type ethernet ifname $MYETH \
ipv6.method disabled
nmcli connection up $MYETH修改网络接口 eth0 为静态 IP 地址并立即生效，其中 MYETH、 IP、 GW、 DNS 根据自己的网络情况修改。
MYETH=eth0
nmcli connection modify $MYETH \
ipv4.method manual \
ipv4.addresses 192.168.67.167/24 \
ipv4.gateway 192.168.67.1 \
ipv4.dns 119.29.29.29,223.5.5.5 \
ipv6.method disabled
nmcli connection up $MYETH修改网络接口 eth0 为 DHCP 获取动态 IP 地址并立即生效，其中 MYETH 根据自己的情况修改。
MYETH=eth0
nmcli connection modify $MYETH \
ipv4.method auto \
ipv6.method disabled
nmcli connection up $MYETH修改网络接口 eth0 的 MAC 地址并立即生效，以解决局域网 MAC 地址冲突问题，其中 MYETH、MYMAC 根据自己的情况修改。
MYETH=eth0
MYMAC=12:34:56:78:9A:BC
nmcli connection modify $MYETH \
ethernet.cloned-mac-address $MYMAC
nmcli connection up $MYETH
if [[ -f "${DIR_INSTALL}/etc/network/interfaces" ]]; then
cp -f /etc/network/interfaces /etc/network/interfaces.bak
rm -f /etc/network/interfaces
fi- 新增、设置或修改部分网络参数，以太网卡会断开现有连接，并重新连接网络。
- 以上使用 NetworkManager 设置网络，默认禁用 ipv6 ，如需使用 ipv6 设置并启用即可。
- 由于软硬件环境不同（盒子，系统，网络设备等），生效所需时间 2-15 秒左右。更长时间未生效的建议检查软硬件环境。
系统中已经添加了自定义开机启动任务脚本文件，在 Armbian 系统中的路径是 /etc/custom_service/start_service.sh 文件，可以根据个人需求在该脚本中自定义添加相关任务。
使用 armbian-sync 命令可以一键将本地系统中的全部服务脚本更新到最新版本。
在 12.10 - 12.11 中制作安卓系统分区表及 u-boot 的方法整理自 unifreq 在社群中指导大家制作相关文件的教学聊天内容，制作源码在他的仓库中。
我们将 Armbian 系统写入 eMMC 系统时，需要首先确认设备的安卓系统分区表，确保将数据写入至安全区域，尽量不要破坏安卓系统分区表，以免造成系统无法启动等问题。如果写入了不安全的区域，会无法启动，或出现类似下面的错误：
以下是详细的手动操作过程，其中 12.10.2 - 12.10.3 中的提取工作，也可以使用一键脚本完成：get_android_system_partition_table_information.tar.xz，使用方法在一键脚本文件的备注里。
adb 工具包是由 Google 开发的一款安卓系统辅助工具，可以帮助用户管理安卓设备，使用它进行刷机、安装相关程序等。点此 下载 adb 工具包，然后在 Windows 系统下，将 adb.exe，AdbWinApi.dll 和 AdbWinUsbApi.dll 三个文件拷⻉到 c://windows/ 目录下的 system32 和 syswow64 两个文件夹内，在电脑开始菜单的运行中输入 cmd 回车，打开 cmd 面板，输入执行 adb --version 命令，如果有显示就表示可以使用了。
我们将电视盒子插入网线、电源、显示器开机，正常进入安卓 TV 系统桌面后，在它的网络信息里查看其 IP 信息。为方便说明，下面以 192.168.1.111 作为安卓电视盒子的 IP 进行操作说明。在 cmd 面板中，依次输入下面的命令并回车执行，先看下分区情况：
adb connect 192.168.1.111
adb shell
cd /dev/block
ls -l | grep 179 | sort -t6
依次输入一下命令，将以下几个位置的分区信息文件保存下来：
cat /proc/partitions >/data/local/partitions.txt
cat /proc/ntd >/data/local/ntd.txt
ls -l /dev/block >/data/local/block.txt
在本地 window 电脑的 C 盘根目录下创建名称为 mybox 的文件夹，在 cmd 面板中依次输入以下命令，把电视盒子里的文件下载到本地电脑：
adb pull /data/local/partitions.txt C:\mybox
adb pull /data/local/ntd.txt C:\mybox
adb pull /data/local/block.txt C:\mybox打开 excel 模板 android_partition_table_template.xlsx，我们根据上面得到的三个分区信息文件把数据套进去，得到设备最终的安卓系统分区表。通过分类，确定了混合区域和安全区域。其中混合区域的 cache 中可以作为 Armbian 或 OpenWrt 系统的 boot 分区的使用，安全区域可以作为 rootfs 分区使用。
根据混合区域和安全区域的具体位置，在 armbian-install 中添加对应的分区信息。以我们制作的 tx3 盒子的安卓系统分区表为例。跳过 68 MiB（BLANK1=68） 的不安全区域；它的 cache 分区共有 1120 MiB 可以使用，但一般 BOOT 分区设置 256 MiB（BOOT=256） 已经够用了，其他容量弃用了；混合区域共有 1350 MiB 空间，所以 BLANK2 的值为 1350-68-256=1026（BLANK2=1026） MiB。结果如下：
# Set partition size (Unit: MiB)
elif [[ "${AMLOGIC_SOC}" == "s905x3" ]]; then
BLANK1="68"
BOOT="256"
BLANK2="1026"u-boot 文件是引导系统正常启动的重要文件。
提取需要使用 HxD 软件。可以从 官网下载链接 或 备份下载链接 获取安装。
在 cmd 面板中依次执行以下命令提取相关文件，并下载到本地电脑。
# 使用 adb 工具进入盒子
adb connect 192.168.1.111
adb shell
# 导出 bootloader 命令
dd if=/dev/block/bootloader of=/data/local/bootloader.bin
# 导出 dtb 命令
cat /dev/dtb >/data/local/mybox.dtb
# 导出 gpio 命令
cat /sys/kernel/debug/gpio >/data/local/mybox_gpio.txt
# 依次把 bootloader、dtb 和 gpio 文件都下载到本地电脑C盘根目录下的 mybox 文件夹
adb pull /data/local/bootloader.bin C:\mybox
adb pull /data/local/mybox.dtb C:\mybox
adb pull /data/local/mybox_gpio.txt C:\mybox主线 u-boot 最重要的是 acs.bin，用于初始化内存的部分，原厂 u-boot 位于固件最前面的 4MB 位置。使用刚才获得的 bootloader.bin 文件提取 acs.bin 文件。
打开 HxD 软件，打开上面导出的 bootloader.bin 文件，右键 - 选择范围，起始位置 F200，长度 1000，选十六进制。
复制选择的结果，然后新建文件，插入式粘贴，警告忽略，另存为 acs.bin 文件。
如果是锁了 bootloader 的话这个区域的代码是是乱码就没用了。正常的应该像上图中这样有很多 0 ，有 cfg 会连续出现几次，中间会出现 ddr 相关的字样，这种正常代码就是可以使用的。
制作 u-boot 需要 https://github.com/unifreq/amlogic-boot-fip 和 https://github.com/unifreq/u-boot 这两个源码库，编译自己盒子的两个 u-boot 文件。
在 amlogic-boot-fip 源码里面每个机型只有 acs.bin 这个文件是不同的，其它的文件都可以通用。
制作 u-boot 的方法详见 https://github.com/unifreq/u-boot/tree/master/doc/board/amlogic 里的具体说明，选择自己设备的型号进行编译测试。
根据 unifreq 的方法制作 u-boot 需要用到盒子的 acs.bin，dts 和 config 文件。其中安卓系统导出来的 dts 不能直接转换成 Armbian 的格式，需要自己编写一个对应的 dts 文件。根据自己设备具体硬件上的区别部分，比如开关、led、电源控制、tf卡、sdio wifi模块等，使用内核源码库中相似的 dts 文件进行修改制作。
以制作 X96Max Plus 的 u-boot 为例：
~/make-uboot
├── amlogic-boot-fip
│ ├── x96max-plus # 自己创建目录
│ │ ├── asc.bin # 自己制作源文件
│ │ └── other-copy-files... # 复制其他目录的文件
│ │
│ ├── other-source-directories...
│ └── other-source-files...
│
└── u-boot
├── configs
│ └── x96max-plus_defconfig # 自己制作源文件
├── arch
│ └── arm
│ └── dts
│ ├── meson-sm1-x96-max-plus-u-boot.dtsi # 自己制作源文件
│ ├── meson-sm1-x96-max-plus.dts # 自己制作源文件
│ └── Makefile # 编辑
├── fip
│ ├── u-boot.bin # 生成文件
│ └── u-boot.bin.sd.bin # 生成文件
├── u-boot.bin # 生成文件
│
├── other-source-directories...
└── other-source-files...- 下载 amlogic-boot-fip 源码。在根目录创建 x96max-plus 目录，里面的文件除了自己制作的
asc.bin文件外，其他文件可以从其他目录下复制。 - 下载 u-boot 源码。制作对应的 x96max-plus_defconfig 文件放入 configs 目录。制作对应的 meson-sm1-x96-max-plus-u-boot.dtsi 和 meson-sm1-x96-max-plus.dts 文件放入 arch/arm/dts 目录，并编辑此目录中的 Makefile 文件，添加
meson-sm1-x96-max-plus.dtb文件的索引。 - 进入 u-boot 源码目录根目录下，根据文档 https://github.com/unifreq/u-boot/blob/master/doc/board/amlogic/x96max-plus.rst 中的步骤操作。
最终生成的文件有两类：在 u-boot 根目录下的 u-boot.bin 文件是 /boot 目录下使用的不完整版 u-boot（对应仓库中的 overload 目录）；在 fip 目录下的 u-boot.bin 和 u-boot.bin.sd.bin 是 /usr/lib/u-boot/ 目录下使用的完整版 u-boot 文件（对应仓库中的 bootloader 目录），完整版的两个文件相差 512 字节，大的那个是填充了 512 字节的 0 在前面。
💡提示：在写入 eMMC 进行测试前，请先查看 12.3 的救砖方法。务必掌握短接点位置，有原厂 .img 格式的安卓系统文件，并进行过短接刷机测试，确保救砖方法都已经掌握的情况下再进行写入测试。
如果内存大小识别不正确（4G内存识别为1-2G是不正常，识别为3.7G是正常），可以尝试手动复制一份 /boot/UBOOT_OVERLOAD 文件（注意是复制一份，不要改名，改名后安装与更新等操作后将无法启动），在 USB 中使用时另存为 /boot/u-boot.ext，在 eMMC 中使用时另存为 /boot/u-boot.emmc。
除了想尝试解决内存的问题外，不要手动复制 u-boot 文件，添加不正确会导致无法启动以及出现各种问题。