Android MTP目录限定访问：Framework层白名单方案与实现

接手过不少Android系统定制项目，这个算比较典型的“行业终端数据管控”诉求：电脑用USB线连上设备后，只能看到我们指定的目录，其余文件一概不可见。Android默认的MTP（Media Transfer Protocol）服务一开，整个共享存储（大家叫惯了的sdcard）都会被端到PC端，DCIM、Download、Documents以及各种应用落在公共区域的文件，电脑上一拉一个准。真正要在Framework层做的事，就是给MTP服务加上“目录限定访问”：把USB文件传输这个口子收窄，只暴露白名单内的那棵树，其余目录保持不可见、不可读、不可写。

这篇文章把我实际改过的方案、选型过程、关键代码思路和踩过的坑完整写出来。项目背景是行业平板和教育/企业终端，核心场景就是防数据外带和合规审计。做Android Framework定制、系统集成，或者在为设备数据防外泄方案发愁的同学，可以直接参考。

1. 先捋清楚MTP这条访问链路

1.1 MTP协议短课：Storage、Root、Object、Handle

MTP是从PTP（Picture Transfer Protocol）扩展而来的传输协议，大量用在数码相机、Android手机连接电脑的场景。它和U盘LUN（UMS）有一个本质区别：UMS是PC直接挂着块设备读写，MTP则在应用层把文件抽象成“对象”，PC端通过协议命令来浏览、读取、写入，从不直接操作文件系统。

协议里几个关键概念容易混淆，先理清楚：

• Storage：一个存储区。MTP设备可以有多个Storage，PC客户端（Windows资源管理器）会把每个Storage显示成一个存储库。
• Root / PARENT_ROOT：每个Storage有一个根对象。枚举根对象的子对象，相当于看这个存储的根目录内容。
• Object：一个文件或目录。每个Object有ObjectHandle（对象句柄）、ParentHandle（父句柄）、Format（对象格式类型）、ProtectionStatus（保护属性）等元数据。
• Handle：会话期间对对象的引用。PC拿到一个ObjectHandle后，才能继续请求对象的属性、内容、缩略图等。

Android设备一个常见特殊情况是：通常把内部共享存储作为一个Storage暴露，路径就是/storage/emulated/0，由FUSE挂载。标题里说的“sdcard”，在现代Android设备上其实就是指这个内部共享存储，而不是物理SD卡。MTP默认端出去的是这一整棵树。

1.2 Android Framework里的MTP组件和各自职责

Android系统实现MTP，涉及一批Framework层组件，各自职责如下：

平时大家说“改MTP”，大多数情况改的是MtpServer和MtpDatabase这两层。MtpServer是协议逻辑层，它翻译PC发来的MTP命令；MtpDatabase是数据访问层，它负责把/storage/emulated/0下的文件树映射成MTP对象树。

1.3 一次文件列表请求在链路里走多远

以Windows资源管理器打开MTP设备根目录为例，完整链路是：

PC发送GetObjectList(PARENT_ROOT)请求 →MtpServer.handleGetObjectList→MtpDatabase.getObjectList→ MediaProvider查询数据库/FUSE → 返回对象列表 →MtpServer.sendObjectList回复PC。

读文件也类似：PC先GetObjectInfo拿对象属性，再GetObject拿到文件内容，中间会经过MtpDatabase.getObjectFilePath解析真实路径，然后打开文件流。

这个链路里看似每一环都能做限制，但实际效果和改动成本差别巨大。理解了链路，才能理解下面选型为什么这样做。

2. 限定访问的落点选在哪里：四个候选位置

2.1 Root/存储卷层：直接把白名单目录注册成存储根

最直觉的做法，是在MtpStorageManager创建Storage时，把白名单目录路径直接当成Storage的根路径。这样PC端看到的存储卷根，就是我们的共享目录。

这个方案实现简单，一个目录替换就能生效。但问题也很明显：MTP的对象句柄在会话内是全局的，如果底层存储卷的注册没有彻底收口，PC仍然可能通过已知句柄直接请求其他对象。而且这种方式只影响“PC看到什么根”，并没有影响“MTP能解析哪些句柄”。

所以只改Root层不够，适合作为体验优化的一部分。

2.2 数据库查询层：给MediaStore查询加白名单条件

MTP的对象列表最终来自MediaProvider的数据库查询。如果能在MtpDatabase.getObjectList等方法内，把查询条件加上_data = 白名单目录 或 _data LIKE '白名单目录/%'，那PC无论怎么枚举，都只能拿到白名单目录内的对象。

这是真正的“源头切断”，性能也最好，SQLite的LIKE 'base/%'能走_data字段的前缀匹配，大数据量下依然可接受。这条还有一个隐藏优势：MtpDatabase实现只服务于MTP模块，不会误伤其他内容提供者的MediaStore查询。

2.3 MTP协议层：句柄与路径的全面校验

在MtpServer的各个操作码入口，对目标句柄做路径白名单校验。比如PC发来GetObjectInfo(handle)时，先调getObjectFilePath(handle)解析出真实路径，判断路径是否在白名单内。

这是覆盖面最全的兜底方案，能覆盖所有协议命令，包括GetObject、DeleteObject、MoveObject、SendObject等。缺点也明显：如果每个对象列表里的元素都去回查数据库，会产生大量Binder IPC和SQLite查询，性能很差。所以协议层适合用在校验读写入口，而不是列表枚举。

2.4 文件读写层：openFile时的最终检查

最后还有一道防线是openFile，即真正要打开文件流时再做一次路径校验。这个层面更多是防“穿透”，比如某个对象曾经是合法句柄，但文件被替换或目录被重命名，导致路径变化。

做了这一层，哪怕前面漏了，最终打开文件时也能拦住。

四个位置对比下来，我的结论是：查询层做源头切断，协议层做关键入口兜底，Root层做PC端体验优化，读写层做最终防线。四层组合起来，才能把“限定目录”这件事做扎实。

3. 我的最终方案：查询层过滤加协议层兜底

3.1 准备一份“暴露路径白名单”

首先要解决一个问题：白名单到底怎么写。很多项目会用系统属性持久化，方便工厂和运维改配置，比如ro.mtp.allowed.root。也可以写成配置文件，但行业设备尤其是离线部署场景，系统属性更稳，Framework层读取时机也好控制。

我在这个项目里用系统属性做了个默认值，同时兼容配置读取：

public final class MtpPathGuard { // 白名单目录示例：/storage/emulated/0/SharedBox public static final String DEFAULT_ALLOWED_DIR = "/storage/emulated/0/SharedBox"; public static String getAllowedDir() { String dir = SystemProperties.get("ro.mtp.allowed.root"); if (dir == null || dir.isEmpty()) { dir = DEFAULT_ALLOWED_DIR; } // 统一去掉末尾斜杠，方便后续拼接判断 while (dir.endsWith("/") && dir.length() > 1) { dir = dir.substring(0, dir.length() - 1); } return dir; } }

路径写死/storage/emulated/0前缀有个隐患，/data/media/0和/storage/emulated/0可能是同一个FUSE视图的不同路径表达。正常MTP会话拿到的路径都是/storage/emulated/0开头，所以实际项目里可以按这个前缀约定来，但如果设备启用了多用户或多存储卷，最好动态取Environment.getExternalStorageDirectory()再拼白名单目录。

另外，启动MTP服务时最好确认目录存在，不存在就创建：

private void ensureExposedDirExists() { File dir = new File(MtpPathGuard.getAllowedDir()); if (!dir.exists() && !dir.mkdirs()) { Log.w(TAG, "create exposed dir failed: " + dir); } }

3.2 拦截点一：getObjectList 从源头切断目录树

getObjectList是MTP枚举目录的核心方法。以AOSP中MtpDatabase的实现为基础，思路是：当PC枚举根对象（parentHandle为0xFFFFFFFF）时，不再返回存储根下的真实内容，而是返回白名单目录这一个对象作为根“子”节点。这样从根开始，PC能枚举到的整棵树都在白名单目录内部。

关键代码示意如下：

// 基于AOSP MtpDatabase实现的改动示例 public int getObjectList(int storageId, int parentHandle, int format, Object[] out) { if (parentHandle == 0xFFFFFFFF) { // 根枚举：只返回白名单目录对象 return queryExposedRoot(storageId, out); } // 子节点枚举：先验证父句柄是否在白名单树内 if (!isHandleInAllowedTree(parentHandle)) { out[0] = new MtpObjectInfo[0]; return 0; } return doQueryChildren(storageId, parentHandle, format, out); }

queryExposedRoot的实现，我建议直接查数据库里_data = 白名单目录的对象记录。如果MediaStore已经有这个目录的扫描记录，那返回的MtpObjectInfo里天然带正确句柄，后续getObjectFilePath也能解析；如果数据库里还没收录，需要手动构造一个MtpObjectInfo并且维护一套“句柄到路径”的映射表，否则PC拿到句柄后无法继续访问。

这就是为什么我强调开机后要确保白名单目录被MediaStore扫描收录。我在ensureExposedDirExists之后，会主动触发一次扫描：

private void triggerScanForExposedDir(Context context) { MediaScannerConnection.scanFile(context, new String[]{MtpPathGuard.getAllowedDir()}, new String[]{"*/directory"}, null); }

3.3 拦截点二：getObjectInfo 与 getObjectFilePath 双重校验

目录树虽然从源头收窄了，但MTP协议允许PC直接按已知句柄请求对象信息，比如GetObjectInfo(0x10001)。要防止PC端绕过枚举逻辑，getObjectInfo和getObjectFilePath必须做路径校验。

核心校验函数：

public static boolean isAllowedPath(String path) { if (path == null) return false; try { String target = new File(path).getCanonicalPath(); String base = new File(getAllowedDir()).getCanonicalPath(); if (target.equals(base)) return true; // 必须带斜杠判断，防止 /SharedBoxEvil 这类目录绕过 String prefix = base.endsWith("/") ? base : base + "/"; return target.startsWith(prefix); } catch (IOException e) { return false; } }

getObjectFilePath(handle, path)是MTP服务从数据库拿真实路径的通道，在返回路径前再校验一次：

public int getObjectFilePath(int handle, String[] outFilePath) { // 原逻辑先解析出路径 int result = doGetObjectFilePath(handle, outFilePath); if (result != 0 || !MtpPathGuard.isAllowedPath(outFilePath[0])) { return -1; } return 0; }

getObjectInfo也一样，要么返回对象在数据库里的真实属性，要么直接返回内部错误。我实测中遇到过一种情况：PC端一次性通过枚举拿到一批句柄，然后逐个GetObjectInfo。如果这些对象里混入了一条白名单外的，处理方式不是“跳过这条”，而是整个请求返回错误或者跳过该对象，否则PC端会报错卡界面。

3.4 拦截点三：写操作收口

MTP不只读，还有写。SendObjectInfo、SendObject对应PC拖文件进设备，DeleteObject对应删除，MoveObject对应移动。这些操作如果只查根目录树，不校验目标路径，会出现“白名单外的目录里有文件，但因为句柄解析漏洞被写入”的情况。

写操作校验重点是目标父句柄：

public int beginSendObject(int storageId, int parentHandle, int format, String name, long size, long modified) { // 父句柄必须存在于白名单树内 if (!isHandleInAllowedTree(parentHandle)) { return -1; } return doBeginSendObject(storageId, parentHandle, format, name, size, modified); }

DeleteObject、MoveObject类似，校验目标句柄即可。值得一提的是，这些方法里如果只校验了“父句柄在白名单内”，还得防止父目录被换过，比如父目录本身在白名单内，但它下面通过符号链接把目标文件链到了外部路径。FUSE挂载的共享存储默认不开放任意symlink，所以这个风险很低，但做严格的系统定制时，getCanonicalPath的规范化已经够用。

3.5 一个容易被忽略的根Root处理

根处理是整个方案的体验关键。我当时花了点时间想清楚：要让PC双击设备后，直接看到共享目录的内容，最好的做法是把Storage的根路径直接设置为白名单目录，而不是保留存储根再返回一个“虚拟子目录”。

第一种做法（推荐），在MtpStorageManager创建MtpStorage时直接指定根路径：

MtpStorage baseStorage = new MtpStorage( STORAGE_ID_INTERNAL, MtpPathGuard.getAllowedDir(), // 根路径 = 白名单目录 "SharedBox");

这样做之后，getObjectList(根)枚举的就是白名单目录下的直接子项，PC看到的是“一进去就是共享目录内容”，逻辑最简单，也完全不需要合成虚拟句柄。

第二种做法是保留原存储根，在根枚举时只返回一个“SharedBox”子目录。这样PC能看到一个“存储库 > SharedBox > 子内容”的结构。听起来更“专业”，但要合成为一个MtpObjectInfo，得自己管理一个句柄映射表，否则GetObjectInfo、GetObjectFilePath都没法从MediaStore查到这个虚构根对象。除非客户明确要求“根下要有一层文件夹”，否则别选这个，维护成本高，容易出诡异Bug。

4. 必踩的坑和排查经验

4.1 PC端目录缓存，怎么都刷新不出来

Windows资源管理器对MTP设备是有缓存机制的。改完MTP白名单，PC上可能还显示旧的目录树，或者明明已经过滤掉了某个目录，PC侧依然能看到“幽灵目录”，点进去才报错。

排查思路：先在PC端把“便携设备”从设备管理器里卸载，或者直接重启电脑再试，这能排除90%的缓存问题。另外MTP会话内的对象句柄缓存也要注意，重启MTP服务相应地会清掉句柄映射。实测定制机上，断开USB重连比只刷新资源管理器更可靠。

4.2 目录里有文件但MTP列表是空的

这是很典型的场景：白名单目录是应用运行时创建的，MediaStore还没来得及收录，MTP枚举时数据库里查不到这个目录，于是PC端看到的是一个空白的存储卷。

解决办法就是上面说的，创建目录后主动触发MediaScannerConnection.scanFile。如果项目里无法用这个类，可以直接发起一条数据库插入事件的广播，或者调用MediaProvider的scanFile服务。我这里遇到过一次更深的坑：scanFile只扫描了目录本身，没有递归扫描子目录。对于运行期动态生成的内容，子目录的文件还是在列表里时有时无。最终做法是在目录创建时，就规划好固定子目录结构，并在创建完成后统一扫描一遍整棵白名单树。

4.3 路径规范化：别让相对路径绕过白名单

路径判断最忌讳用path.contains("/SharedBox/")这种字符串判断。路径里出现..、双斜杠、软链接时就会漏。比如/storage/emulated/0/SharedBox/../Downloads/secret.txt，字符串层面上它是从SharedBox开头的，但规范化后实际指向的是Downloads。

所以校验必须走getCanonicalPath()，并且判断前缀是base + "/"而不是base本身，否则/SharedBoxEvil这种目录也会被误判成白名单内目录。

4.4 性能：别在MtpServer层逐对象回查数据库

我最早版本的方案是在MtpServer的列表枚举里，对每个对象都调getObjectFilePath校验一次。结果一个几千文件的目录，在Windows上枚举要卡几秒，因为每个对象都要走一次Binder IPC到MediaProvider。

正确做法是“查询层过滤优先”：在MtpDatabase.getObjectList阶段，直接把白名单条件拼进数据库查询，比如追加(_data LIKE '/storage/emulated/0/SharedBox/%')，让SQLite一次性过滤。这样MtpServer拿到的对象列表本来就是合法的，不需要逐对象回查。协议层兜底校验只放在GetObjectInfo、GetObject、Delete、Move这类单个对象操作上，数量不大，性能影响可以忽略。

优化前枚举一个5000文件的目录约3秒，优化后基本在1秒内。这个差别在客户现场是能明显感受到的，值得专门强调。

4.5 句柄与路线一致性：重命名、移动后的“幽灵项”

MTP对象句柄在很多实现里来自MediaStore数据库的_id。如果白名单目录本身被重命名，或者内部文件被移动，数据库里的路径变了，但PC会话里缓存的句柄可能还是旧的。此时如果再请求这些句柄，getObjectFilePath能拿到新的路径，校验可能通过也可能失败，但文件内容对不上，PC会显示损坏或无法访问。

我的处理方式很实际：在定制系统里，白名单目录及其根级别的子目录，不允许通过MTP改名或移动。另外在MTP服务启动时，手动清空句柄映射缓存，保证每次新会话从最新数据库状态开始。如果业务上确实需要动态更新目录结构，就在更新完成后强制重启MTP服务，让PC端重连。

5. 上线前验证清单与安全复盘

5.1 多平台MTP客户端验证

改完框架层，不能只看Windows资源管理器正常就完事。不同MTP客户端的差异很大，macOS的Android File Transfer走的一套协议，Linux的GVFS又是另一套。我整理了下面这张验证清单，直接在定制机上过一遍：

Windows、macOS、Linux三个平台都跑一遍，才算完整验证。我自己的经验是，Windows对协议错误比较宽容，某些非法句柄它会静默跳过；macOS出现异常时反而会整个设备弹错。两边通过的方案，基本可以放心。

5.2 常见MTP错误码补充

调试时logcat里常看到MTP返回的错误码，列出来方便快速定位：

• 0x2001General Error：内部异常，通常是因为路径解析失败或数据库查询返回异常。
• 0x2009Invalid ObjectHandle：句柄无效，常见于白名单目录被重建后，旧句柄失效。
• 0x200FAccess Denied：访问拒绝，路径校验没通过时会返回这个，正好作为白名单拦截的响应。
• 0x2010No Such Object：对象不存在，数据库里没有对应记录。

我在框架层过滤时，对不在白名单内的对象更倾向于直接返回0x200F，而不是0x2001。因为0x2001容易被误报成系统错误，0x200F语义明确，PC端也更好处理，日志里也方便区分是“真故障”还是“被拦截”。

5.3 别忘了MTP不是唯一外传通道

最后想提醒一句：MTP只是USB口上一个功能模块。如果设备上开着USB调试（ADB），adb pull可以绕过MTP白名单直接拉取共享存储内容；如果开了FTP服务或蓝牙文件传输，也有同样问题。行业终端做数据防泄露，通常是组合拳：

• USB接口功能裁剪到最小集，行业设备常见做法是关闭ADB、关闭UMS大容量存储，只留MTP白名单模式。
• 系统层做应用级文件访问审计，白名单目录的读写事件记日志。
• 若设备面向儿童或教育场景，还要同步限制蓝牙、WiFi直连和第三方网盘应用的可用性。

我见过不少项目只封堵了MTP，结果客户现场用ADB一拉数据就穿了。所以MTP限定访问是“USB传输”这个场景的正解，但它不能替代整体数据安全方案。我做这类定制时，都会在交付文档里专门列出“其他外传通道”的关闭建议。

最终小结

这套方案目前在实际定制机上运行得比较稳定，核心就三点：MtpDatabase查询层从根上限制对象树，MtpServer协议层对单对象操作做路径兜底，MtpStorageManager把存储根直接改成白名单目录。实现上不难，真正花时间的是把PC端各种MTP客户端的异常行为和数据库收录细节调顺。

如果你正在做类似功能，建议先从MtpDatabase.getObjectList的根枚举下手，把一个目录过滤做通，再逐步补上写操作和协议层校验。遇到PC端“看到了却打不开”、目录空白这类问题，先查MediaStore有没有收录，再查路径校验是否被相对路径绕过，基本都能定位。这个功能做完之后，客户那边再也没提过“电脑上能看到所有文件”的问题，算是Framework定制里性价比很高的一次改动。