Skip to content

Home

Jump to bottom
re-zero-0 edited this page Sep 29, 2025 · 3 revisions

欢迎使用 Box

本 Wiki 提供一站式的下载、安装、配置和使用说明。（由 AI 润色而成）

📋 目录

📥 下载指南

提供两种方式获取最新的模块刷机包 (.zip 文件)。

通过 APP 检查更新 (推荐)

这是最简单、最快捷的更新方式。

  1. 打开配套 APP，进入 “设置” 页面，然后选择 “应用 & 模块”。
  2. 点击 “模块版本” 选项。
  3. APP 将自动检查 GitHub 上是否有新版本。如果检测到更新，会直接提供跳转链接，引导前往最新的 Actions 页面下载。

手动从 GitHub Actions 下载

首次安装或无法使用 APP 时，可通过以下步骤手动下载。此操作需要 登录 GitHub 账户。

  1. 进入 Actions 页面

    • 在项目主页顶部，点击 Actions 标签页。

  2. 选择最新的工作流

    • 在左侧工作流列表 (Workflows) 中，点击主要的构建流程（例如 Build 或 CI）。
    • 在右侧，会看到该工作流的运行记录列表。选择最顶部、带有绿色对勾 ✅ 的记录，代表最新一次成功构建。

  3. 下载构建产物 (Artifacts)

    • 点击进入该次运行的详情页面后，向下滑动到 Artifacts (构建产物) 部分。
    • 看到一个名为 Box 或类似名称的产物，这就是需要的模块刷机包。
    • 点击它即可开始下载。

提示: 如果在 Artifacts 区域没有看到任何文件，可能是因为该次构建失败，或者构建产物已过期被自动删除 (通常会保留90天)。请尝试选择其他成功运行的工作流。

🚀 安装教程

关于依赖 (yq & curl)

模块的正常运行需要 yq 和 curl 两个关键组件。

  • yq: 用于解析配置文件。
  • curl: 用于网络数据下载 (如更新订阅、规则等)。

在模块安装过程中，脚本会通过音量键提供一个交互式选项，询问是否需要自动下载这些依赖项。 推荐在安装时选择 “是”，以确保所有功能开箱即用。

如果选择跳过或下载失败，后续也可以通过命令行手动进行安装。

安装过程中的交互下载（音量键）

在刷入过程中，安装脚本（customize.sh）会通过音量键让你做以下选择（摘自模块实际逻辑）：

  • 是否需要下载内核或数据文件（GeoX、工具等）
  • 是否启用下载加速镜像（ghfast.top）
  • 自定义选择要下载的组件，或一键下载全部组件
    • GeoX 数据（GeoIP/GeoSite）
    • 工具：yq、curl
    • 代理核心：sing-box、mihomo、mihomo_smart、xray、v2fly、hysteria

安装脚本会在需要时自动创建目录、设置权限，并提取 box_service.sh 到系统 service.d 路径以实现开机管理。同时会自动备份旧的 /data/adb/box 内容并在安装后进行恢复（见下文“备份与恢复”）。

安装步骤

  1. 打开 Root 管理器

    • 打开设备上的 Magisk Manager 或 KernelSU Manager。

  2. 进入模块安装界面

    • Magisk: 切换到 模块 标签页。
    • KernelSU: 切换到 模块 标签页。

  3. 选择并刷入模块

    • 点击 从本地安装 按钮。
    • 在文件管理器中，找到并选择下载好的模块 .zip 文件。
    • 管理器会自动完成刷入过程。

  4. 完成安装

    • 刷入成功后，模块即可使用。 通常情况下，无需重启设备。

注意: 尽管无需重启即可使用，但若在安装后遇到任何问题，重启设备是首选的排错步骤，可以确保所有服务和进程都已正确加载。

备份与恢复（自动）

安装时若检测到已存在的 /data/adb/box，脚本会：

  • 备份旧目录内容到box.xxx文件夹（含各核心配置目录、根配置如 ap.list.cfg/package.list.cfg/crontab.cfg、bin 中的核心与工具、run 中的日志与 PID 等）。
  • 安装新版后自动恢复用户配置文件与数据。
  • 对 settings.ini 提供“覆盖/增量合并”两个策略：
    • 覆盖：使用新版默认配置，忽略旧值。
    • 增量合并：仅将旧文件中已有的键值写回新版对应键。

这意味着你可以直接“刷入新版”而无需手动迁移配置，绝大多数情况下即刷即用。

⚡ 快速上手

对于大多数使用 mihomo (Clash.Meta) 核心的用户，推荐使用配套 APP 完成初始配置，过程将更加简单直观。

模块内置了一套精简的 mihomo 配置文件，唯一需要做的就是填入代理订阅链接。

使用 APP 配置订阅

  1. 打开配套 APP 并进入 “配置” 页面。

  2. 看到当前的配置文件列表，例如 mihomo。

  3. 点击 mihomo 进入文件列表，看到 config.yaml。

  4. 点击 config.yaml，即可打开内置的文本编辑器。

  5. 在编辑器中，上方 “搜索框” 输入 填写订阅链接 可定位，将其替换成 Clash 订阅链接。

    proxy-providers:
  proxy1:
    # ... (其他配置省略)
    path: ./proxy_provider/proxy1.yaml
    url: "填写订阅链接"  # <--- 就是这里！

  6. 保存 文件修改。

  7. 返回 APP 主页，点击 “重启” 按钮使新配置生效。

至此，所有必要配置均已完成。

📱 配套APP

为了提供更便捷的管理体验，Box 提供了一个功能强大的配套管理APP。通过这个图形化界面，可以轻松完成模块的各项操作，而无需依赖命令行。

重要提示: 配套APP需要获取 Root 权限 才能正常工作。首次打开时，需要在 Root 管理工具（Magisk 或 KernelSU）中授予权限。

主要功能

  • 核心服务管理: 在主页即可一键 启动 / 停止 / 重启 代理服务。
  • 主页状态看板: APP 主页会实时展示丰富的工作状态信息，包括：
    • 服务状态: 运行状态、PID、运行时长、当前核心、CPU 及内存占用。
    • 网络信息: 实时上/下行速率、公网 IP 及归属地。
    • 延迟测试: 直观展示到 Google, Baidu 等网站的连接延迟。
  • 配置管理:
    • 多配置文件切换: 如果有多个核心的配置文件（如 mihomo, sing-box 等），可以轻松点击切换。
    • 在线编辑: 无需第三方文件管理器，直接在 APP 内长按即可编辑配置文件。
  • 应用管理 (黑白名单):
    • 进入 “应用” 页面，轻松管理不同代理模式下（如代理、直连）的 App 列表。
    • 支持按应用名、包名搜索，操作直观。
  • 日志查看: 实时查看模块运行日志，快速定位问题。
  • 订阅与规则更新: 手动触发订阅更新和 GeoX 规则库更新。
  • Web 面板: 内置入口，快速访问 Clash Web UI (Zashboard)。
  • 丰富设置: 提供模块运行模式、DNS、内核参数等多项自定义设置。

获取方式

目前，最新的配套管理APP需要通过以下 Telegram 频道 获取：

➡️ 点击这里跳转到发布频道

在该频道中查找最新发布的 .apk 安装包并下载安装。

📚 核心与官方文档

提示：本模块在启用/切换核心与网络模式时，会自动为上述配置补全所需字段（如 TUN、tproxy 端口、external-ui 等），并写入日志便于排错。

🧰 命令行工具与用法

所有命令默认在 Android 终端以 root 执行，路径为：/data/adb/box/scripts/

box.service（核心服务管理）

  • 用法：su -c /data/adb/box/scripts/box.service {start|stop|restart|status|cron|kcron}
    • start：启动当前核心，并根据 settings.ini 自动准备配置（写入 external-controller/external-ui、TUN/TProxy 入站等）
    • stop：停止核心与相关后台任务
    • restart：重启核心（常用于配置变更后生效）
    • status：显示运行状态、PID、端口等信息
    • cron：应用并启动内置定时任务（订阅/GeoX 定时更新等）
    • kcron：停止定时任务

常见示例：

  • 重启服务：su -c /data/adb/box/scripts/box.service restart
  • 查看状态：su -c /data/adb/box/scripts/box.service status

说明：首次启动如缺少必要字段，会自动为当前核心补全（如 external-controller/external-ui、TUN/TProxy 入站等），便于配合 Web UI/APP 使用。

box.iptables（透明代理与路由规则）

  • 用法：su -c /data/adb/box/scripts/box.iptables {enable|disable|renew}

    • enable：根据 network_mode 应用透明代理规则
    • disable：清理所有规则并恢复
    • renew：在不改变模式的情况下重置并重新应用规则

  • network_mode 行为概览：

    • tproxy：TCP/UDP 走 TProxy（mangle 表），可选 IPv6 同步规则；DNS 53 可由内核或 TProxy 处理（由 mihomo_dns_forward 控制）
    • redirect：TCP/UDP（本地）走 Redirect（nat 表），常配合直连 DNS
    • mixed：TCP Redirect + UDP 走 TUN；支持热点转发（tun_forward）
    • enhance：TCP Redirect + UDP TProxy，适合更强的兼容与性能组合
    • tun：不走上述透明代理，使用内核 TUN 转发，box.iptables 只负责 TUN 转发链路

  • 其它要点：

    • 自动识别内核进程的用户/用户组，用于避免自环流量
    • 支持 IPv6 开关；未启用时会彻底阻断 IPv6、避免泄漏（必要时自动添加 ip6tables 53/UDP DROP）
    • 根据 proxy_mode（blacklist/whitelist）将 UID/GID 写入相应规则中

常见示例：

  • 应用规则：su -c /data/adb/box/scripts/box.iptables enable
  • 重置规则：su -c /data/adb/box/scripts/box.iptables renew
  • 清理规则：su -c /data/adb/box/scripts/box.iptables disable

box.tool（更新/维护/优化工具）

  • 用法：su -c /data/adb/box/scripts/box.tool <subcommand> [args...]
  • 常用子命令：
    • geosub：更新订阅与 GeoX（GeoIP/GeoSite），成功后尝试通过 API 热重载
    • geox：仅更新当前核心的 GeoIP + GeoSite；subs：仅更新订阅
    • upkernel [name]：下载/更新指定核心（支持：sing-box、mihomo、mihomo_smart、xray、v2fly、hysteria）
    • upkernels [name...]：批量更新多个核心
    • upgeox_all：一次性更新所有核心的 GeoIP + GeoSite
    • upxui：更新 Web 前端（yacd/zashboard），并写入到核心目录供面板使用
    • upyq / upcurl：下载并更新内置 yq 与 curl（静态）
    • reload：调用 API 热重载当前核心配置（mihomo/sing-box）
    • webroot：根据当前核心生成本地 Web 面板根目录（并提示访问 URL）
    • memcg|cpuset|blkio：设置 cgroup（内存/CPU 亲和/IO 权重）
    • bond0|bond1：网络参数快速预设（传输队列、MTU、tcp_low_latency）
    • check：快速检查当前核心配置并输出报告
    • all：一键执行常用更新（yq/curl/GeoX/核心/订阅/UI）

常见示例：

  • 更新订阅并热重载：su -c /data/adb/box/scripts/box.tool subs
  • 仅更新当前核心的 GeoIP + GeoSite：su -c /data/adb/box/scripts/box.tool geox
  • 更新 sing-box 内核：su -c /data/adb/box/scripts/box.tool upkernel sing-box
  • 生成本地 Web 面板：su -c /data/adb/box/scripts/box.tool webroot
  • 强化 CPU/IO：su -c /data/adb/box/scripts/box.tool cpuset、blkio

🔎 更多要点与实用方法

以下要点能帮助你更好地理解与使用 Box：

切换核心与网络模式

  • 核心选择：在配套 APP 的设置中选择 mihomo 或 sing-box；命令行可编辑 settings.ini 中的核心项（APP 会代管此项）。
  • 网络模式：通过 APP 或编辑 settings.ini 的 network_mode（支持：tproxy、redirect、mixed、enhance、tun）。切换后执行：box.service restart 与必要时 box.iptables renew。

Web UI 面板访问

  • 执行 box.tool webroot 生成本地面板资源；APP 主页提供快捷入口。
  • Mihomo：确保 external-controller 与 external-ui 已写入（box.service start 会自动补全），常见端口 9090。
  • Sing-Box：使用第三方面板时通过 yacd/zashboard 静态资源访问。

日志与排错

  • 查看状态：su -c /data/adb/box/scripts/box.service status
  • 快速重启：su -c /data/adb/box/scripts/box.service restart
  • 核心日志：在 APP “日志”页查看，或在 /data/adb/box/run 目录中查找最新日志文件。
  • 规则异常时，先 box.iptables disable 再 enable/renew 以重置规则。

升级与卸载

  • 升级：直接刷入新版本的模块包（见“下载指南”）。安装脚本会自动备份与恢复配置；如遇异常，手动重启设备后再试。
  • 卸载：在 Magisk/KernelSU 管理器里禁用或卸载模块。

订阅与 Geo 数据

  • 手动更新：box.tool geosub（订阅+GeoX）或分别执行 geox/subs。
  • 定时任务：box.service cron 启用、kcron 停用。启用后会按 settings.ini 设定的周期更新。
  • 建议：订阅日更、GeoIP/GeoSite 周更；节点异常先在 Web UI/APP 内切换策略组以验证。

DNS、QUIC 与 IPv6

  • DNS 建议：开启内核 DNS 转发并与网络模式一致；出现污染或泄漏时，可关闭系统 Private DNS、由核心统一接管。
  • QUIC：如遇视频站点不稳定，可在设置中启用「阻断 QUIC」，避免 UDP/443 绕过。
  • IPv6：可在设置中开关；关闭时 box.iptables 会阻断 IPv6，避免泄漏。

应用分流（黑/白名单）

  • 在 APP 的“应用”页管理需要走代理或直连的 App 列表。
  • 高阶：box.iptables 会根据 proxy_mode 与 UID/GID 生成相应链路，避免核心自环流量。

兼容性与支持

  • Root 管理器：支持 Magisk、KernelSU、APatch。
  • 架构支持：以实际发布的核心二进制为准（常见为 arm64-v8a）。
  • 初次安装后如遇异常，建议先重启设备，再通过“日志与排错”小节进行自检。

问题反馈指南（强烈建议附复现视频与日志）

为了高效定位并解决问题，反馈时请尽量提供：

  • 复现视频（或屏幕录制）：
    • 清楚记录从 APP/命令操作到问题出现的完整步骤；
    • 建议在视频开头展示：APP 版本、模块版本、核心类型与版本（若可见）。
  • 复现步骤（文字）：
    • 精确到每一步点击/命令；期望结果 vs 实际结果；是否必现或偶发。
  • 设备与环境信息：
    • 设备型号、Android 版本、Root 管理器及版本（Magisk/KernelSU/APatch）、是否多用户/工作资料；
    • 当前核心（mihomo/sing-box 等）、network_mode、是否启用 IPv6/QUIC 阻断、是否启用黑白名单等关键设置；
  • 日志：APP → 日志；或查看 /data/adb/box/run 目录中最新日志文件。

❓ FAQ (常见问题)

Q1: 我在 GitHub Actions 页面找不到下载链接 (Artifacts)？

A: 请确保已经 登录 GitHub 账户。GitHub Actions 的构建产物 (Artifacts) 只对登录用户可见。如果登录后仍看不到，可能是该次构建失败或产物已过期 (通常保留90天)，请尝试其他成功的工作流。

Q2: 修改了 config.yaml 里的订阅链接，为什么没有生效？

A: 任何对配置文件的修改，都需要 重启服务 才能生效。可以在配套 APP 主页点击“重启”按钮，或执行命令 su -c /data/adb/box/scripts/box.service restart。

Q3: 安装或更新模块后，需要重新配置吗？

A: 不需要。安装脚本会自动检测现有的 /data/adb/box 目录（其中包含了所有配置文件），并进行 自动备份和恢复。只需像首次安装一样刷入新版模块包即可，所有配置都会被完整保留。

Q4: 我可以添加多个订阅链接吗？

A: 可以。通过编辑 config.yaml，在 proxy-providers 下添加多个 provider，或者在 proxy-groups 中手动聚合节点即可。这需要对 Clash 的配置规则有一定了解。对于大多数用户，使用单个高质量的订阅链接即可。

Q5: 缺少 yq 或 curl 导致启动失败怎么办？

A: 重新刷入并在安装交互中选择下载“实用工具（yq/curl）”；或刷入后执行：

su -c /data/adb/box/scripts/box.tool upyq
su -c /data/adb/box/scripts/box.tool upcurl

Q6: 关于配置有什么建议？

A: 模块内置了自用配置，但不推荐大家直接使用。建议有能力的用户自行修改，或选择适合自己的配置。

Q7: 为什么应用频繁请求 Root 权限？

A: 应用频繁请求 Root 权限属于正常现象。模块都位于 /data/adb/ 下，操作时自然会需要频繁授权。若介意此情况，可以只使用模块而不用应用。Magisk 用户也可以在 Root 权限管理中关闭通知。

Q8: 如何寻求帮助？

A: 首先通过配套 APP 的“日志”功能查看实时日志，可定位大部分问题。若问题无法解决，可加入项目的 Telegram 交流群组 (链接可在发布频道中找到) 寻求帮助。

Clone this wiki locally