主题
Micro 业务上机教程
1. 业务介绍
Micro 业务是我们专为不常见设备或低质网络打造的兜底业务。它几乎支持市面上常见的设备类型,同时支持任意 NAT 类型的 IPv4 网络。
客户端采用内存上报方式:统计数据经内存队列直接上报,不在设备上落地统计文件,适合闪存空间和写入寿命有限的设备。业务日志需单独配置,闪存设备建议按第 5.5 节关闭日志文件写入。
资源占用参考与网络要求
内存和 CPU 数值是客户端运行占用的参考,具体以设备实测为准;设备还需要为操作系统和其他程序预留资源。
| 项目 | 参考值或接入要求 | 说明 |
|---|---|---|
| 内存 | 可低至 15 MB | 客户端内存占用参考 |
| CPU | 可低至 1 个核心的 10% | 客户端 CPU 占用参考 |
| 上行带宽 | 至少 5 Mbps | -bandwidth 按设备实际可提供的上行带宽填写 |
| 网络 | 任意 NAT 类型 | 不限制 NAT 类型 |
| 设备类型 | 几乎覆盖所有常见设备 | 包括不常见设备、嵌入式设备和低配置设备 |
当前支持的操作系统与架构及测试状态见下表。如果您的设备不在列表中,请主动联系我们,我们会及时进行适配。
2. 已支持架构
下表列出各架构的下载标识、常见设备和部分型号示例,方便对照设备信息选择客户端。型号示例用于识别架构,具体兼容性以实测为准;下载时请以设备实际运行的操作系统和架构为准。
| 操作系统 | 设备架构(下载标识) | 常见设备与识别参考 |
|---|---|---|
| Linux | x86_64(amd64) | 使用 Intel/AMD 64 位处理器的 PC、服务器、NAS、云主机 |
| Linux | ARM64(arm64) | 运行 64 位 ARM 系统的开发板、工控机、路由器、摄像头等设备 |
| Linux | ARM32(arm) | 运行 32 位 ARM 系统的开发板、路由器、摄像头等嵌入式设备 |
| Linux | LoongArch64(loong64) | 采用 LoongArch 架构的新款龙芯 PC、服务器 |
| Linux | MIPS64 小端(mips64le) | 采用 MIPS 架构的旧款龙芯 PC、服务器,需确认是 64 位小端系统 |
| Linux | MIPS32 大端(mips) | 采用 32 位 MIPS 大端系统的路由器、嵌入式设备 |
| Linux | MIPS32 小端(mipsle) | 采用 32 位 MIPS 小端系统的路由器、嵌入式设备 |
| Linux | RISC-V 64 位(riscv64) | 荔枝派 4A / LicheePi 4A(TH1520)、昉·星光 2 / VisionFive 2(JH7110)等开发板 |
| Windows | x86_64(64 位) | 使用 Intel/AMD 64 位处理器、运行 64 位 Windows 的电脑、云桌面 |
| Android | ARM64(arm64) | 运行 arm64-v8a 系统的手机、平板、电视、机顶盒等设备 |
| Android | ARMv7(arm) | 运行 armeabi-v7a 系统的手机、平板、电视、机顶盒等设备 |
| macOS | Apple Silicon(arm64) | 使用 Apple M 系列芯片的 MacBook、iMac、Mac mini 等 Mac |
| macOS | Intel x86_64(amd64) | 使用 Intel 处理器的 MacBook、iMac、Mac mini 等 Mac |
Linux 的架构查看命令与下载版本对应关系见第 4.2 节,Android 和 macOS 的选择方法见第 5.3、5.4 节。确认后,按操作系统和设备架构选择第 6 节的下载链接;不确定时请联系我们。
3. 已支持设备类型
| 序号 | 设备类型 | 测试状态 |
|---|---|---|
| 1 | 统信 UOS/麒麟 OS/信创服务器 | ✅ 已测 |
| 2 | 网吧电脑/办公PC/笔记本/NAS/蜗牛机 | ✅ 已测 |
| 3 | 云主机/云桌面/云手机 | ✅ 已测 |
| 4 | 容器 Docker/K8S | ✅ 已测 |
| 5 | 虚拟化 KVM/QEMU/LXD/VMware/Hyper-V | ✅ 已测 |
| 6 | 安卓 手机/平板/学习机/电视/机顶盒/投影仪 | ✅ 已测 |
| 7 | CPE/工控机 | ✅ 已测 |
| 8 | 智能设备 路由器/摄像头/打印机/音箱/门锁 | ✅ 已测 |
| 9 | 智能家居 冰箱/洗衣机/空调/空气净化器 | ✅ 已测 |
| 10 | 收银机/自助终端 | ✅ 已测 |
| 11 | 苹果 MacOS 电脑/笔记本 | ✅ 已测 |
已测表示当前已有真机验证记录。
4. 前置准备
设备需要能够访问客户端下载地址和平台服务。下载、启动前请先确认以下参数和设备架构。
4.1 启动前替换参数(所有系统通用)
Linux、Windows、Android、macOS,以及环境变量和开机自启方式,都使用相同的参数。执行前必须替换示例中的 ID,不能直接使用测试值 10086、sn001 上机。
| 命令中的内容 | 替换为 |
|---|---|
YOUR_VENDOR_ID | 平台分配给你的供应商 ID(UID/vendorID),填写实际数字;不要使用测试 ID、客户 ID 或签约 ID。 |
YOUR_UNIQUE_DEVICE_ID | 当前设备在整个平台内唯一的编号(NID),不能与任何其他设备重复。建议使用「供应商 ID + 设备序列号」等不含空格的组合,并自行确保唯一。 |
10 | 按设备实际可提供的上行带宽填写,单位 Mbps,至少 5 Mbps。例如 10 Mbps 填写 10,不要填写 10M。 |
后续命令中的 YOUR_VENDOR_ID、YOUR_UNIQUE_DEVICE_ID 都是待替换的占位符,不能原样执行。同一设备重启、升级或切换启动方式时,保持原 UID 和 NID 不变。
4.2 查看 Linux 架构
bash
uname -m常见返回值与下载版本的对应关系如下:
uname -m 返回值 | 对应下载架构 |
|---|---|
x86_64 | amd64 |
aarch64 | arm64 |
armv7l | arm |
armv6l | arm,请联系我们确认设备兼容性 |
loongarch64 | loong64 |
mips64el | mips64le |
mips64 | 还需确认大小端;64 位小端系统使用 mips64le |
mips | 还需确认位数和大小端;32 位大端使用 mips,32 位小端使用 mipsle |
mipsel | mipsle |
riscv64 | riscv64 |
MIPS 设备的 uname -m 结果可能不包含大小端信息,请结合设备规格和系统信息确认后选择下载版本。当前 MIPS64 仅提供小端版本;无法确认时请联系我们。
5. 手动下载接入
请点击第 6 节对应的「下载链接」,在弹窗中点击「下载」保存客户端。下载后保留原始文件名,按下面对应系统的步骤放置文件并启动。首次上机先在前台确认平台设备状态,再按需切换到后台运行。同一运行环境只启动一个客户端实例。
5.1 Linux
以下以 Linux x86_64 为例。先准备固定且可写的客户端目录,以下目录需要相应写入权限:
bash
mkdir -p /opt/microaio点击第 6.1 节中 x86_64 对应的「下载链接」,在弹窗中点击「下载」。将下载好的文件传到设备的 /opt/microaio 目录。其他架构请选择对应文件,并在以下命令中使用实际下载的文件名。
文件放好后,执行以下命令。首次上机先在前台启动,查看注册与提交结果:
bash
cd /opt/microaio
# 添加执行权限
chmod +x microaio_linux_amd64_memory_v1.0.6
# 替换 UID、NID 和带宽后,前台启动并显示日志
./microaio_linux_amd64_memory_v1.0.6 -uid=YOUR_VENDOR_ID -nid=YOUR_UNIQUE_DEVICE_ID -bandwidth=10 -console命令里的 -console 让日志显示在当前窗口。客户端会持续运行,不返回终端提示符属于正常现象。请按第 7.1 节确认平台上机结果。
确认成功后,按 Ctrl+C 停止前台实例,确认进程已经退出,再启动后台实例:
bash
nohup ./microaio_linux_amd64_memory_v1.0.6 -uid=YOUR_VENDOR_ID -nid=YOUR_UNIQUE_DEVICE_ID -bandwidth=10 > microaio-startup.log 2>&1 &启动后查看业务日志:
bash
tail -n 100 -f logs/microaio.log以上后台命令会将业务日志写入客户端目录下的 logs/microaio.log,启动阶段的标准输出和错误保存在 microaio-startup.log。闪存设备需要关闭日志文件写入时,请改用第 5.5 节的启动方式。如果业务日志尚未生成,先查看 microaio-startup.log。Ctrl+C 只会退出这里的日志查看,不会停止后台客户端。nohup 不会配置开机自启,有需要请联系支持协助配置。
首次启动会在程序同目录生成名称带
_b的业务进程文件;客户端运行和后续更新需要使用该文件,请保留。
停止后台客户端
通过上面的 nohup 命令启动后,可先查看客户端进程:
bash
ps -ef | grep '[m]icroaio'根据实际启动的文件名和参数找到主程序所在行,读取其 PID;名称带 _b 的是业务进程。将下面的 YOUR_MAIN_PID 替换为主程序的实际 PID 后执行:
bash
kill -TERM YOUR_MAIN_PID主程序收到正常退出信号后会停止业务进程。再次查看进程,确认这两个进程均已退出后,再重启或升级。如果由系统服务或其他守护程序拉起,请通过对应的服务停止,避免被自动重新启动。
5.2 Windows
客户端需要放在固定且可写的目录(本教程使用 C:\microaio),请按下面四步操作。
第一步:打开管理员命令行
同时按 Win 键和 X 键,在弹出菜单里选择「终端(管理员)」或「Windows PowerShell(管理员)」,出现权限确认时选「是」。
第二步:下载客户端
先在 PowerShell 中创建并进入客户端目录:
powershell
New-Item -ItemType Directory -Path C:\microaio -Force | Out-Null
Set-Location C:\microaio点击第 6.2 节 Windows 客户端的「下载链接」,在弹窗中点击「下载」。将下载好的 microaio_memory_v1.0.6.exe 移动到 C:\microaio。
如果目录中已有客户端,请先按本节「停止客户端」步骤停止原实例,再按第 7.3 节处理升级或重新安装。
第三步:先前台启动一次,确认能上机
先按第 4.1 节填写自己的 UID、平台全局唯一的 NID 和实际带宽,再执行:
powershell
.\microaio_memory_v1.0.6.exe -uid=YOUR_VENDOR_ID -nid=YOUR_UNIQUE_DEVICE_ID -bandwidth=10 -console日志出现 submit success 或 register success 后,到平台核对名下设备及状态。确认平台能看到这台设备后,再进入第四步。
客户端会持续运行,不返回 PowerShell 提示符属于正常现象,不要重复执行启动命令。
首次验证请保留 -console,让日志显示在当前窗口。确认成功后按 Ctrl+C 停止前台实例,等 PowerShell 提示符返回后再进入第四步。如果后续仍提示端口占用,按本节「停止客户端」步骤清理原实例。
第四步默认将日志写在
C:\microaio\logs\microaio.log;关闭日志文件写入的方法见第 5.5 节。
第四步:改成后台运行(开机自动启动、没有窗口)
在同一个管理员 PowerShell 窗口中先创建任务,三个值保持与第三步一致:
cmd
schtasks /create /tn MicroAio /tr "C:\microaio\microaio_memory_v1.0.6.exe -uid=YOUR_VENDOR_ID -nid=YOUR_UNIQUE_DEVICE_ID -bandwidth=10" /sc onstart /ru SYSTEM /f创建成功后,打开 Windows「任务计划程序」,找到 MicroAio 并进入「属性」:
- 在「设置」中,取消勾选「如果任务运行时间超过以下时间,停止任务」。
- 如需笔记本使用电池时也保持运行,在「条件」中取消勾选「只有在计算机使用交流电源时才启动此任务」及「如果计算机改用电池电源则停止」。
保存设置后,回到管理员 PowerShell 窗口启动任务:
cmd
schtasks /run /tn MicroAio按下面的方法查看日志,确认客户端启动成功。
确认正常运行后,不需要保留任何窗口,重启电脑也会自动启动。
查看日志
powershell
Get-Content C:\microaio\logs\microaio.log -Tail 100停止客户端
需要临时停止或升级时,执行下面三行。这会保留开机任务,设备下次启动时仍会自动运行客户端。
以下以 v1.0.6 为例。停止旧版本时,请把两条 taskkill 中的文件名替换为旧版本实际的主程序和 _b.exe 文件名,例如 v1.0.5 对应 microaio_memory_v1.0.5.exe 和 microaio_memory_v1.0.5_b.exe。
cmd
schtasks /end /tn MicroAio
taskkill /f /im microaio_memory_v1.0.6.exe
taskkill /f /im microaio_memory_v1.0.6_b.exe两条
taskkill都要执行。客户端由主程序和microaio_memory_v1.0.6_b.exe两个进程组成,只结束主程序可能留下microaio_memory_v1.0.6_b.exe,导致下次启动提示端口被占用。
保持原文件和配置、只需恢复运行时,执行 schtasks /run /tn MicroAio;升级时按第 7.3 节更新启动命令。
取消开机自启或卸载
先按上面的步骤停止客户端,再删除计划任务:
cmd
schtasks /delete /tn MicroAio /f只取消开机自启时保留客户端文件;需要卸载时,确认两个进程均已退出后,再删除客户端目录。
首次启动会生成
microaio_memory_v1.0.6_b.exe;后台运行时还会生成logs目录。正常运行期间请保留这些文件,只启动下载的主程序,不要单独运行_b.exe。停止命令提示某个任务或进程不存在时,继续执行其余命令。如系统提示文件被拦截,请联系客服确认后再放行。
5.3 Android
点击第 6.3 节对应架构的「下载链接」,在弹窗中点击「下载」,获取 microaio_android_arm64_memory_v1.0.6 或 microaio_android_arm_memory_v1.0.6。将文件传到设备上可执行且可写的目录;如需集成到设备系统,请联系支持确认部署方式。
设备架构可用以下命令确认:
sh
getprop ro.product.cpu.abiarm64-v8a 使用 ARM64 文件,armeabi-v7a 使用 ARM32 文件。Android ARM32 设备不能直接使用 ARM64 文件。
在设备 Shell 中进入客户端所在目录,按第 4.1 节填写参数后启动。以下以 ARM64 为例,ARM32 请把文件名中的 arm64 换成 arm:
sh
chmod +x microaio_android_arm64_memory_v1.0.6
./microaio_android_arm64_memory_v1.0.6 -uid=YOUR_VENDOR_ID -nid=YOUR_UNIQUE_DEVICE_ID -bandwidth=10 -console按第 7.1 节确认平台上机结果。前台验证时保持当前会话,按 Ctrl+C 停止。长期运行和开机自启请按设备的集成方式配置,或联系支持协助处理。
5.4 macOS
先在「终端」中准备客户端目录:
bash
mkdir -p "$HOME/microaio"点击第 6.4 节对应的「下载链接」,在弹窗中点击「下载」:Apple Silicon 选择 ARM64 文件,Intel Mac 选择 x86_64 文件。将下载好的文件移动到个人目录下的 microaio 文件夹。
文件放好后,在「终端」中执行。以下以 Apple Silicon 文件名为例,Intel Mac 请把命令中的 arm64 换成 amd64:
bash
cd "$HOME/microaio"
chmod +x microaio_darwin_arm64_memory_v1.0.6
./microaio_darwin_arm64_memory_v1.0.6 -uid=YOUR_VENDOR_ID -nid=YOUR_UNIQUE_DEVICE_ID -bandwidth=10 -console按第 7.1 节确认平台上机结果。需要后台运行时,先按 Ctrl+C 停止前台实例,再参考第 5.1 节的 nohup 方式,将目录和文件名换成当前 macOS 客户端的实际值。开机自启请联系支持协助配置。如系统拦截客户端,请联系支持确认处理方式。
5.5 日志设置与闪存设备配置
UID、NID 和带宽的填写要求统一见第 4.1 节。首次验证时加上 -console,日志只显示在当前窗口,不同时写入日志文件。需要排障时,请复制该窗口中的相关日志。
需要保留文件日志时,去掉 -console,日志会保存在客户端目录下的 logs/microaio.log。联系支持排障时,可按指导添加 -logLevel=debug 查看详细日志。
闪存设备:关闭日志文件写入
内存上报模式负责避免统计文件落盘,业务日志需单独关闭。首次按第 7.1 节确认上机成功后,先停止原实例,再在启动参数中同时加入 -console -logLevel=silent:-console 避免创建日志目录和日志文件,-logLevel=silent 关闭常规日志输出。仅设置 -logLevel=silent 仍会创建日志文件,因此请同时保留这两个参数。
Linux 后台启动示例: 以下以 x86_64 为例,其他架构请使用实际下载的文件名。
bash
cd /opt/microaio
nohup ./microaio_linux_amd64_memory_v1.0.6 -uid=YOUR_VENDOR_ID -nid=YOUR_UNIQUE_DEVICE_ID -bandwidth=10 -console -logLevel=silent </dev/null >/dev/null 2>&1 &这里将标准输入、输出和错误重定向到 /dev/null,同时避免生成 microaio-startup.log 或 nohup.out。macOS 可使用相同方式,替换为实际客户端目录和文件名;Android 集成时也可使用上述两个参数,并将标准输出和错误丢弃。
Windows 计划任务: 先按第 5.2 节停止原实例,再使用下面的命令重新创建任务,参数放在 /tr 的双引号内:
cmd
schtasks /create /tn MicroAio /tr "C:\microaio\microaio_memory_v1.0.6.exe -uid=YOUR_VENDOR_ID -nid=YOUR_UNIQUE_DEVICE_ID -bandwidth=10 -console -logLevel=silent" /sc onstart /ru SYSTEM /f创建后仍按第 5.2 节完成任务设置,再执行 schtasks /run /tn MicroAio。这里的 -console 控制日志输出位置,计划任务仍按后台方式运行。
如果通过 -f 配置文件启动,将现有配置中的 log 字段设置如下,保留 UID、NID、带宽等其他字段:
json
{
"log": {
"console": true,
"level": "silent"
}
}关闭日志后,通过平台查看设备状态;需要排障时,停止当前实例,改用 -console -logLevel=info 或 -console -logLevel=debug 前台启动。使用配置文件时,也需把其中的 log.level 改为 info 或 debug。首次生成业务进程文件、保存节点 ID 和程序升级仍需要写入设备存储。
5.6 使用环境变量启动(可选)
v1.0.6 及以上版本支持通过环境变量填写 UID、NID 和带宽。可以先设置这三个值,再使用较短的命令启动。请先完成对应系统的下载和文件放置步骤;已有客户端运行时,先停止原实例。
| 环境变量 | 填写内容 | 示例 |
|---|---|---|
MICROAIO_UID | 平台分配的供应商 ID | YOUR_VENDOR_ID |
MICROAIO_NID | 设备在整个平台内唯一的编号 | YOUR_UNIQUE_DEVICE_ID |
MICROAIO_BANDWIDTH | 上行带宽,单位 Mbps | 10 |
请按第 4.1 节替换下面的占位符和带宽,NID 必须在整个平台内唯一。
Windows PowerShell:
powershell
Set-Location C:\microaio
$env:MICROAIO_UID = "YOUR_VENDOR_ID"
$env:MICROAIO_NID = "YOUR_UNIQUE_DEVICE_ID"
$env:MICROAIO_BANDWIDTH = "10"
.\microaio_memory_v1.0.6.exe -consoleLinux: 以下以 x86_64 为例,其他架构请替换为实际下载的文件名。
bash
cd /opt/microaio
export MICROAIO_UID="YOUR_VENDOR_ID"
export MICROAIO_NID="YOUR_UNIQUE_DEVICE_ID"
export MICROAIO_BANDWIDTH="10"
./microaio_linux_amd64_memory_v1.0.6 -consolemacOS: 以下以 Apple Silicon 为例,Intel Mac 请把文件名中的 arm64 换成 amd64。
bash
cd "$HOME/microaio"
export MICROAIO_UID="YOUR_VENDOR_ID"
export MICROAIO_NID="YOUR_UNIQUE_DEVICE_ID"
export MICROAIO_BANDWIDTH="10"
./microaio_darwin_arm64_memory_v1.0.6 -consoleAndroid 在设备 Shell 中也可以使用上面的 export 方式设置变量,再运行对应的 Android 客户端。
- 上面的变量只在当前终端会话中生效;重新打开终端后,需要重新设置。已经启动的客户端不需要因此重新配置。
- Windows 开机自启仍按第 5.2 节配置计划任务,并在任务命令中填写 UID、NID 和带宽;当前 PowerShell 中的变量不会自动应用到该任务。
- 如果启动命令同时填写了
-uid、-nid或-bandwidth,对应值以命令行参数为准。使用-f配置文件启动时,这三个值以配置文件为准。
6. 客户端下载
请点击表格中的「下载链接」,再点击弹窗中的「下载」。如果下载失败,请重新点击页面中的「下载链接」获取地址,仍有问题请联系我们。
6.1 Linux 客户端
| 架构 | 下载链接 |
|---|---|
x86_64 | 下载链接 |
aarch64 | 下载链接 |
armv7l | 下载链接 |
loongarch64 | 下载链接 |
MIPS64 小端(mips64le) | 下载链接 |
MIPS32 大端(mips) | 下载链接 |
MIPS32 小端(mipsle) | 下载链接 |
riscv64 | 下载链接 |
6.2 Windows 客户端
| 架构 | 下载链接 |
|---|---|
x86_64 | 下载链接 |
6.3 Android 客户端
| 架构 | 下载链接 |
|---|---|
ARM64(arm64-v8a) | 下载链接 |
ARM32(armeabi-v7a) | 下载链接 |
6.4 macOS 客户端
| 架构 | 下载链接 |
|---|---|
| Apple Silicon(ARM64) | 下载链接 |
| Intel(x86_64) | 下载链接 |
7. 启动检查与常见问题
7.1 怎样确认上机成功
日志出现 submit success 或 register success 后,到平台核对设备归属和状态。终端不返回提示符是前台运行的正常现象;仅看到进程或网络流量,还需要到平台确认设备。
平台查询使用客户端生成的节点 ID。可以从日志里的 register node: ... 获取,也可以在客户端目录查看 niulink-id 文件:
Windows:
powershell
Get-Content .\niulink-idLinux、macOS:
bash
cat niulink-idniulink-id 在注册前就会生成,文件存在不代表已经上机成功。NID 必须在整个平台内唯一,同一设备重启或升级时保持原 NID。
7.2 遇到错误怎么办
| 现象 | 处理方式 |
|---|---|
提示 listen on port :56632 failed | 单实例端口已被占用,可能已有客户端或残留业务进程在运行。Windows 按第 5.2 节停止原实例;其他系统先停止原客户端,仍有问题请联系支持。不要通过更换 NID 重复启动。 |
有 error 日志,或平台始终看不到设备 | 核对 UID、NID 和设备联网情况,把错误发生时间附近的完整日志发给我们。 |
| 提示无法执行、文件损坏或系统拦截 | 核对下载版本是否匹配设备,联系支持确认处理方式。 |
联系支持时,请提供供应商 ID、NID、节点 ID(如已生成)、客户端版本、操作系统和日志。前台运行时复制终端日志;保留文件日志时,Windows 日志查看方法见第 5.2 节,Linux、macOS 可在客户端目录执行 tail -n 100 logs/microaio.log。使用关闭日志的配置时,请按第 5.5 节恢复前台日志后复现问题。
7.3 运行与升级
- 客户端需要持续运行。Windows 按第 5.2 节配置后台运行和开机自启;其他系统按对应章节运行,需要开机自启时请联系支持。
- 客户端放在固定、可执行且可写的目录。正常运行期间保留自动生成的
_b业务进程文件、niulink-id和已有的日志目录,始终启动下载的主程序。 - 手动升级前先停止旧客户端,再使用新版本的原始文件名启动;配置过开机自启时,同步更新启动命令中的文件名。继续使用原 UID 和 NID,不能同时运行新旧版本。
- 如需使用相同文件名覆盖安装,请先联系支持确认替换步骤;仅覆盖主程序可能继续运行已有的业务进程版本。
上机过程如果有任何问题,请联系我们解决。
