在 Android(arm64)上把 Agent2API 跑成开机自启的 Magisk 模块。 不 chroot、不做 Debian rootfs:二进制只依赖 glibc 的 4 个 .so,用模块自带的 loader 直跑。
- 适用 APatch / Magisk / KernelSU
- 仓库名沿用社区习惯:上游名 +
-Magisk(同OpenList-Magisk、box_for_magisk)
上游与致谢:服务本体、panel UI、官方插件全部来自 aimod-cc/agent2api(MIT,镜像
aimodcc/agent2api)。 本项目只做「把它装进 Android」这层壳——挂载逻辑、启动/看门狗、插件解释器修复、WebUI 入口页、打包与 CI。 Release 里的运行体由 CI 原样取自上游(优先用上游 Release 资产并校验其.sha256,没有资产才从官方镜像aimodcc/agent2api抽),未改二进制。详见 THIRD-PARTY.md。
- 从 Releases 下最上面那个 zip(预发/正式跟随上游:上游还是 beta 时我们发 Pre-release,上游转正就是正式版;不想分辨就按时间倒序取第一行),在管理器里刷入;
- 按音量键答(音量下=下一项,音量上=确认)——端口(3065 ↔ 52018,首项是当前值)、自动更新(开/关,首次默认开); 5 秒内一个键都不按=全部取默认值,后面的问题一个都不问(升级安装就是配置一个字都不动,等于免配置); 想改就在这 5 秒内按,之后的每一题都会一直等你按,不会自己跳过; 已装过的机器会先多问一题「是否重新设置」,音量上直接确认=同样一个字都不动;
- 首次安装要重启手机:刷 zip 只解到
modules_update/,模块目录要重启才整体替换,安装器会提示「首次安装,重启设备后自动运行」。 只有升级安装(模块已在)才不用重启:customize.sh会把bin/+ui/同步到/data/adb/ag2a/rt/,再用新脚本停旧起新; - 重启后打开
http://127.0.0.1:<第 2 步选的端口>/(默认 3065)自己建管理员(密码 ≥8 位,不预设默认账号)。
| 按钮 | 来源 | 行为 |
|---|---|---|
| 打开 | webroot/index.html |
集成面板:端口、进程状态、模块版本/运行体、有无新版、run.log 尾部;按钮=打开面板 / 重启进程 / 停止进程 / 用浏览器打开 / 打开 GitHub 更新地址 |
| 执行 | action.sh |
重启网关进程,并推一条系统通知报结果 |
| 卸载 | 管理器自带 | 走 uninstall.sh,只删自己那三个写死路径 |
- 「打开」依赖管理器的模块 WebUI:APatch(≥10568)、KernelSU 及各分支原生支持;Magisk 上游没有 WebView,装 KsuWebUI 或 MMRL 才会出现。没有也不影响,
sh action.sh open用系统浏览器打开。 - 面板里的「更新」一栏读的是仓库的
update.json(跟管理器自己弹的更新提示同一个数据源);网络不通就只显示「查不到」,点下面的按钮自己看。 - 起不来先看「打开」页最下面的日志块(
/data/adb/ag2a/run.log尾部,已滤掉看门狗的「重拉中」):网关自己的报错都在那儿。 - 这两个按钮的行为由模块目录里的脚本决定,刷完要重启一次才换成新版(网关服务本身不受影响)。
- 点「执行」成功后管理器会自己退回模块列表(APatch
ExecuteAPMActionScreen的popBackStack())。结果看通知,或看模块说明行:运行中 · IP:端口 · 23:25 启动 | 执行=重启进程。
module.prop 里有一行 updateJson=,指向仓库根目录的 update.json(走 GitHub Pages 直链,管理器 1~2 秒能拉到):
updateJson=https://huxc573.github.io/Agent2API-Magisk/update.json
{ "version": "26.10.30_5", "versionCode": 26103005,
"zipUrl": "https://gh-proxy.com/https://github.com/…/releases/download/v26.10.30_5/…zip",
"changelog": "https://huxc573.github.io/Agent2API-Magisk/changelog.txt" }Magisk / KernelSU / APatch 都会读这行,拿 update.json 的 versionCode 和本机的比,大于本机就在模块列表里显示「更新」,点一下直接下 zipUrl 刷入。每次 CI 出包后按打好的 zip 自动重写这个文件并提交,所以它永远指向最新那个包——所以不管发的是 Pre-release 还是正式版,管理器更新都一样能用(它不看 Release 的「Latest」,只看这个 JSON)。
zipUrl走gh-proxy.com镜像(国内直连github.com/…/releases/download/…超时)。镜像不可用时,直接到 Releases 手动下载刷入。- 装的是没有
updateJson的旧版时,需手动刷一次本版,之后才会出现更新提示。 - 维护相关(
updateJson/changelog为什么走 Pages、changelog.txt怎么生成)写在与改仓库的人有关的文件里,见scripts/ci/notes.sh顶部注释与.github/workflows/build.yml的同段注释。
M=/data/adb/modules/ag2a
su -c "sh $M/check.sh" # 自检:文件 / 依赖 / 端口 / 进程 / 面板探活
su -c "sh $M/action.sh config" # 改端口、管理员、更新钟点(会重启网关)
su -c "sh $M/action.sh open" # 系统浏览器打开面板
su -c "sh $M/action.sh reset" # 清账号库,回到「创建账号」页
su -c "sh $M/action.sh fixplugins" # 查插件 spawn hook 状态(见下)
su -c "sh $M/service.sh stop|start|restart"
su -c "sh $M/rt.sh status" # rt/ 与模块目录各是哪个版本
su -c "tail -50 /data/adb/ag2a/run.log"卸载会清干净,但只碰 /data/adb/modules/ag2a、/data/adb/modules_update/ag2a、/data/adb/ag2a 三个逐字写死的路径(uninstall.sh 的 safe_rm 白名单)。
想重装保留账号:卸载前 touch /data/adb/ag2a/keep。
/data/adb/modules/ag2a 由管理器管,刷 zip 只解到 modules_update/,重启才整体替换——运行体放那儿,
跑着的自然还是旧二进制。所以会变的部分搬到数据目录:
| 位置 | 内容 |
|---|---|
/data/adb/ag2a/rt/bin/、rt/ui/ |
二进制 + 面板前端(权威位置) |
模块目录/bin/、ui/ |
同份副本:首次安装的来源 + rt 缺失时的回退 |
模块目录/lib/、etc/、zoneinfo/ |
glibc 四件套 + 根证书 + 时区,上游从不换 |
rt.sh sync 用 cp → .new → mv 原子替换,全部到位后最后写 rt/.rtver 当提交点;断电半份的话,
下次启动发现「rt 比模块旧或缺戳」就整份重同步。代价:多占约 22 MB。
插件是上游单独发布的包,面板自己下载、验签、解压到 /data/adb/ag2a/plugins/<id>/<版本>/bin/ 后 exec 直接拉起。
它们同样是 glibc 二进制,ELF 解释器写死 /lib/ld-linux-aarch64.so.1——Android 根目录没有 /lib,
execve 返回 ENOENT,面板日志就是 启动插件进程失败(…): No such file or directory (os error 2)(文件其实在)。
不改插件,改网关的 spawn。 网关本来就是我们用 loader 拉起来的,启动时给它多带一个参数:
ld-linux-aarch64.so.1 --library-path <模块lib> --preload <模块lib>/libspawnhook.so agent2api-server
libspawnhook.so 拦下 posix_spawnp / posix_spawn / execve / execvp:
发现目标 ELF 的解释器是 /lib/ld-linux-aarch64.so.1 且该路径不存在,就改用模块自带的 loader 拉起同一个文件。
好处是插件文件一个字节都不动——官方签名完好,面板里「下载并安装」和自动升级照常成功,
装完立刻就能跑,不需要重启、不需要手动修、也没有任何时间窗口要抢。
/system/bin/* 这类 bionic 程序(解释器是 /system/bin/linker64)不匹配,完全不碰。
排障:touch /data/adb/ag2a/spawnhook.off 即完全旁路;启动前会用 --list 自检,库加载不了就不带这个参数,
不会因为一个 hook 把网关拖死。action.sh fixplugins 可查当前状态。
service.sh start ──setsid──> watchdog.sh ──fork──> service.sh run ──exec──> agent2api-server
└── wait(阻塞,零 CPU) ──────────────┘
网关是看门狗的直接子进程,wait 等它:活着 0 tick,一死立刻重拉。存活 <60 秒算异常,退避 1/2/5/10/30/60 秒。
⛔ 不用 sleep+pgrep 轮询,也不用 setsid 起网关(脱离父子关系会让 wait 立即返回,变成每秒重启)。
默认开启(首次安装 86400=每天 04:00 查一次;2026-11-21 在 OP12 上实测 api.github.com 直连 200 / 1.2 秒,
gh-proxy.com 镜像也通,所以不再默认关着)。开启后:按通道挑 tag → 逐条比版本(防降级)
→ 取官方 digest 校 sha256 → 多源下载 → 验 aarch64 → 只写 rt/bin、rt/ui → 重启网关。
su -c "sh $M/action.sh auto on|off|status" # 开关 / 状态(status 会显示定时器 pid)
su -c "sh $M/action.sh auto 03:30" # 换钟点
su -c "sh $M/action.sh auto channel beta|stable"
su -c "sh $M/updater.sh now" # 立刻查一次- 不用
/releases/latest:上游正式版最高只到 v3.0.8(其后全是 beta),latest 永远返回它 ⇒ 按 tag 列表挑。 - 资产下载走多源:
gh-proxy.com → ghproxy.net → ghfast.top → GitHub 直连,每个源都用 API 给的 digest 校验。 - 定时器是「睡到点才醒」的进程,不是轮询;关掉时它根本不启动。
auto on会当场把定时器拉起来(关闭状态下它本来不存在),不用等重启手机。
- 多占约 22 MB(rt 副本)。
- 仅 arm64;glibc 需求不能超过模块自带的 2.36。
- 面板自带的「软件更新」默认关(
AGENT2API_SELF_UPDATE=0),避免和模块更新互相覆盖。
| 路径 | 说明 |
|---|---|
src/ |
脚本壳(module.prop、*.sh、webroot/) |
rootfs/ |
运行体,不入库,由 scripts/ci/rootfs.sh 抽取(先试上游 Release 资产,缺了才走镜像) |
build_module.py |
组装 zip:注入仓库地址、映射目录、校验 ELF 必须 aarch64、统一 LF、脚本 0755 |
update.json |
管理器更新源(CI 每次出包后重写并提交) |
.github/workflows/build.yml |
每小时查上游(cron 30 * * * *),有新版就出包;发正式版还是 Pre-release 跟随上游那个 release 的 pre 标记 |
上游一发版,下一轮定时就会出包;想立刻出包不用等,在 Actions 里手动跑 build(勾 force 可强制出)。
版本号是日期制 YY.MM.DD_序号,versionCode = YYMMDD*100 + 序号:
python build_module.py 26.10.26_1 # → publish/Agent2API-Magisk-v26.10.26_1.zip
scripts/ci/rootfs.sh 3.3.0-beta.4 # 本地抽运行体(需要 docker + gh 登录)本仓库 MIT;随包分发的上游二进制(MIT)、glibc/libgcc(LGPL/GPL+异常)、CA 证书(MPL-2.0)、tzdata 见 THIRD-PARTY.md。