OpenWrt 25.12+: dùng apk thay cho opkg mà không tự làm hỏng router

Từ OpenWrt 25.12, package manager là apk phiên bản 3; opkg đã kết thúc phát triển và không còn là lựa chọn chính trên release mới. Tên apk ở đây là Alpine Package Keeper, không liên quan tới Android APK.¹

Điều kiện đầu tiên: kiểm tra release trước khi chạy lệnh. Bài này tập trung vào OpenWrt 25.12 trở lên. Nếu firmware còn dùng opkg, hãy theo đúng tài liệu của release đó và đừng trộn repository hoặc package manager giữa hai hệ.

1
2

cat /etc/openwrt_release
apk --version

1. Bộ lệnh cơ bản

Các lệnh tương ứng trong tài liệu OpenWrt là:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

apk update
apk add <package>
apk add <package>*
apk add --allow-untrusted ./<package>.apk
apk add --allow-untrusted ./*.apk
apk del <package>
apk del <package>*
apk list -I
apk list -a [<package>*]
apk search [<needle>*]

apk update cập nhật database package ở máy. apk add cài package, còn dấu * là mask để chọn nhiều tên. --allow-untrusted dành cho package tự build hoặc tải từ feed ngoài; vì vậy chỉ dùng khi tôi đã kiểm tra nguồn và chữ ký/độ tin cậy của file. apk del gỡ package, apk list -I liệt kê package đã cài, apk list -a liệt kê package có thể có, và apk search tìm theo chuỗi.

Cài nhiều package sau một lần cập nhật database bằng:

1

apk -U add package1 package2 package3

2. Repository feeds

Database repository được liệt kê trong các file dưới /etc/apk/repositories.d/. Đọc feed đang dùng:

1

cat /etc/apk/repositories.d/distfeeds.list

Tài liệu cho một output x86_64 mẫu của release 25.12 như sau; đây là ví dụ để nhận diện cấu trúc, không được chép feed x86_64 vào router target khác:

1
2
3
4
5
6
7
8

https://downloads.openwrt.org/releases/25.12/targets/x86/64/packages/packages.adb
https://downloads.openwrt.org/releases/25.12/packages/x86_64/base/packages.adb
https://downloads.openwrt.org/releases/25.12/targets/x86/64/kmods/6.12.60-1-41eae5d636a323424ce95c71d55e15f0/packages.adb
https://downloads.openwrt.org/releases/25.12/packages/x86_64/luci/packages.adb
https://downloads.openwrt.org/releases/25.12/packages/x86_64/packages/packages.adb
https://downloads.openwrt.org/releases/25.12/packages/x86_64/routing/packages.adb
https://downloads.openwrt.org/releases/25.12/packages/x86_64/telephony/packages.adb
https://downloads.openwrt.org/releases/25.12/packages/x86_64/video/packages.adb

Feed tùy chỉnh nên nằm trong file riêng để không bị mất khi nâng cấp. Tài liệu minh họa:

1

cat /etc/apk/repositories.d/customfeeds.list

Nội dung mẫu có thể là:

1
2
3

# add your custom package feeds here
# http://www.example.com/path/to/files/packages.adb
https://dev.melmac.net/apk/packages.adb

Chỉ thêm feed khi nó đúng target, release và ABI của firmware; --allow-untrusted không sửa được package sai kernel hoặc sai kiến trúc.

3. Cập nhật package: phần dễ làm brick nhất

Không dùng lệnh sau để mass-update mù quáng:

1

apk upgrade

Tài liệu cảnh báo một số package như hostapd-*, wpad-*, ucode-mod-* và các thư viện có thể có conflict hoặc dependency chưa hoàn chỉnh. Chạy apk upgrade bừa bãi có thể làm router cấu hình sai và cuối cùng không boot hoặc mất Wi-Fi.¹

Cách an toàn để nâng toàn bộ package là sysupgrade lên firmware mới có bộ package đồng bộ. Có thể dùng một trong các ASU client như LuCI Attended Sysupgrade, owut hoặc Firmware Selector; ngoài ra có thể dùng Image Builder hoặc full toolchain trên Linux build host. Hãy backup trước khi sysupgrade.

Nếu tôi vẫn chủ động cập nhật package riêng lẻ sau khi hiểu rõ rủi ro, lệnh của nguồn là:

1

apk upgrade

Đây là nhánh có điều kiện, không phải lời khuyên nâng cấp định kỳ. Trước khi chạy, phải có backup, console hoặc đường recovery, và kiểm tra release/target của feed.

4. Các nhóm lệnh mà tài liệu để dành cho tra cứu

Trang nguồn có các mục Invocation, Package manipulation, Informational commands, Options, Configuration, Adjust repositories và Change architectures, nhưng không đưa thêm ví dụ lệnh trong nội dung đã công bố. Tôi không tự bịa cú pháp cho các mục trống; hãy dùng apk --help và tài liệu apk v3 đúng phiên bản khi cần tra cứu.

Một phần có thông tin cụ thể là proxy. apk đọc các biến môi trường http_proxy và https_proxy; chạy một lần qua proxy:

1

https_proxy=http://yourproxyserver:3128/ apk upgrade

Đổi yourproxyserver và port bằng proxy thật của mạng, không ghi credential vào command history hoặc bài viết công khai.

5. Troubleshooting và giới hạn

Khác biệt apk v3

OpenWrt 25.12 dùng apk v3. Alpine Linux cũng dùng v3, nhưng Wolfi, Apko, Melange và Chainguard có thể còn dùng apk v2; không bê nguyên man page của apk v2 sang OpenWrt.

Hết chỗ

Trang nguồn có mục Out of space nhưng không cung cấp đoạn lệnh cụ thể. Khi hết chỗ, không cố xóa file hệ thống hoặc đổi repository ngẫu nhiên. Kiểm tra filesystem và package đã cài, sau đó dùng extroot hoặc expand_root đúng release nếu thiết bị hỗ trợ.

Cài vào vị trí không chuẩn

Mục Non-standard installation destinations cũng không đưa quy trình hoàn chỉnh. Tôi không coi apk add là cách an toàn để chuyển toàn bộ root filesystem sang một thư mục khác; cần đọc tài liệu target và init system trước khi làm.

Known Issues

Nguồn ghi nhận:

1

apk adbdump

có thể tạo YAML không chuẩn trong một số trường hợp biên. Nếu gặp, hãy báo lỗi theo issue tracker của apk thay vì dùng output đó làm input cho script tự động.

6. Checklist trước khi cài package

1. Kiểm tra cat /etc/openwrt_release và xác định đang ở 25.12+.
2. Đọc feed trong /etc/apk/repositories.d/distfeeds.list, chắc chắn đúng target/arch.
3. Chạy apk update, xem lỗi repository trước khi cài.
4. Với package ngoài feed, kiểm tra chữ ký, target và dùng --allow-untrusted chỉ khi hiểu rõ lý do.
5. Không dùng apk upgrade để thay thế sysupgrade firmware.
6. Backup trước mọi thao tác có thể đụng wpad, hostapd, kernel module hoặc thư viện nền.

Kết luận

apk giúp OpenWrt 25.12 có hệ package mới, nhưng thay đổi package manager không làm mất các giới hạn cũ của firmware nhúng: ABI, kernel module, dung lượng flash và tính nhất quán của cả image vẫn quan trọng hơn việc chạy một lệnh upgrade. Tôi dùng apk update/apk add cho package có mục đích rõ ràng, còn nâng cả hệ thống thì đi qua sysupgrade đồng bộ.

Nguồn