安卓部署Alist时存储权限获取失败

Question

在安卓设备上部署Alist时，常因Android 11及以上版本的Scoped Storage（分区存储）机制导致存储权限获取失败。应用无法直接访问外部存储根目录或公共目录文件，即使已声明WRITE_EXTERNAL_STORAGE权限也无法正常读写。尤其在Android 13中进一步收紧权限管理，需使用MediaStore API或请求MANAGE_EXTERNAL_STORAGE特殊权限，但后者在Google Play上架时受限。此外，部分定制ROM对存储权限进行额外限制，加剧了授权失败问题，导致Alist无法挂载目录或写入缓存。

Answer 1

1. 问题背景与演进：从传统存储到Scoped Storage的转变

在Android系统早期版本中，应用通过声明WRITE_EXTERNAL_STORAGE权限即可访问外部存储的根目录和公共文件夹（如Download、DCIM等）。然而自Android 10（API 29）引入Scoped Storage机制以来，应用对文件系统的访问受到严格限制。这一设计旨在提升用户隐私安全，防止应用滥用存储权限。

到了Android 11（API 30），系统进一步收紧了访问策略，即使拥有写权限也无法直接操作公共目录。而Android 13（API 33）则将READ_MEDIA_IMAGES、READ_MEDIA_VIDEO、READ_MEDIA_AUDIO作为细粒度媒体权限替代旧权限模型，并强化了对MANAGE_EXTERNAL_STORAGE特殊权限的审核机制。

2. 核心挑战分析：Alist部署中的权限困境

• 权限声明失效：尽管Alist应用已声明WRITE_EXTERNAL_STORAGE，但在Android 11+设备上无法实际读写公共目录。
• MANAGE_EXTERNAL_STORAGE受限：该权限可绕过Scoped Storage限制，但Google Play政策要求“核心功能依赖”才可申请，多数文件管理类应用难以通过审核。
• 定制ROM额外封锁：华为EMUI、小米MIUI、OPPO ColorOS等厂商在系统层面增加二次权限控制，即使授予仍可能被后台拦截。
• 缓存与挂载失败：Alist需持久化缓存元数据并挂载远程目录至本地路径，若无法写入指定目录，则服务初始化失败。

3. 技术演进路径与适配方案对比

Android版本	主要存储机制	可用API	是否支持直接路径访问	推荐使用方式
≤ Android 9	Legacy External Storage	File API	是	直接路径操作
Android 10	Scoped Storage (初步)	Storage Access Framework, MediaStore	否（沙盒化）	SAF + MediaStore
Android 11-12	Scoped Storage 强化	MediaStore, SAF, MANAGE_EXTERNAL_STORAGE	仅特殊权限	按需请求MANAGE权限
Android 13+	细粒度媒体权限	READ_MEDIA_* 权限组	否	结合MediaStore与DocumentFile

4. 解决方案深度解析

1. 采用MediaStore API进行媒体文件管理：适用于图片、视频、音频类资源的读写。可通过MediaStore.Files查询并插入非媒体文件（如.db、.json），但不支持任意路径创建目录。
2. 利用Storage Access Framework（SAF）选择器：调用Intent.ACTION_OPEN_DOCUMENT_TREE引导用户手动授权一个可持久访问的目录树，获得Uri后可长期读写其子结构。
3. 条件性申请MANAGE_EXTERNAL_STORAGE：对于非Google Play分发渠道（如APK直装、第三方商店），可在AndroidManifest.xml中声明并动态请求该权限，注意需配合android:requestLegacyExternalStorage="true"兼容旧行为。
4. 使用DocumentFile封装抽象路径：基于SAF返回的Tree Uri构建DocumentFile.fromTreeUri()对象，实现跨Scoped Storage的递归遍历与文件操作。
5. 缓存路径重定向至App私有目录：getExternalFilesDir()或getCacheDir()始终可访问，可将Alist元数据、临时文件存储于此，规避公共目录限制。

5. 实际代码示例：SAF目录授权与持久化

// 请求用户选择根目录
private void requestDirectoryAccess() {
    Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT_TREE);
    intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION |
                    Intent.FLAG_GRANT_WRITE_URI_PERMISSION |
                    Intent.FLAG_GRANT_PERSISTABLE_URI_PERMISSION);
    startActivityForResult(intent, REQUEST_CODE_DIRECTORY);
}

// 在onActivityResult中保存持久化Uri
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_CODE_DIRECTORY && resultCode == RESULT_OK) {
        Uri treeUri = data.getData();
        getContentResolver().takePersistableUriPermission(treeUri,
                Intent.FLAG_GRANT_READ_URI_PERMISSION |
                Intent.FLAG_GRANT_WRITE_URI_PERMISSION);
        // 存储treeUri供后续使用
        SharedPreferences sp = getSharedPreferences("alist_prefs", MODE_PRIVATE);
        sp.edit().putString("root_uri", treeUri.toString()).apply();
    }
}

6. 流程图：Alist存储权限获取逻辑

graph TD
    A[启动Alist服务] --> B{Android版本 >= 11?}
    B -- 是 --> C[检查MANAGE_EXTERNAL_STORAGE权限]
    C -- 已授权 --> D[尝试挂载指定目录]
    C -- 未授权 --> E[提示用户前往设置开启]
    B -- 否 --> F[请求WRITE_EXTERNAL_STORAGE]
    F --> G{权限授予?}
    G -- 是 --> H[使用File API直接访问]
    G -- 否 --> I[降级至私有目录运行]
    D --> J{挂载成功?}
    J -- 否 --> K[回退到SAF选择器流程]
    K --> L[用户选择目录]
    L --> M[持久化Tree Uri]
    M --> N[基于DocumentFile操作文件]

7. 定制ROM适配策略

部分国产ROM（如MIUI、EMUI）在权限管理系统中加入了“访问媒体以外文件”的开关，默认关闭。开发者需在应用内提供跳转引导：

Intent intent = new Intent();
intent.setClassName("com.miui.securitycenter",
    "com.miui.permcenter.permissions.PermissionsEditorActivity");
intent.putExtra("package_name", getPackageName());
startActivity(intent); // 小米示例

同时建议在文档中列出主流品牌的手动设置路径，提升用户体验。

8. Google Play合规性考量

若计划上架Google Play，应避免滥用MANAGE_EXTERNAL_STORAGE。可行策略包括：

• 默认使用私有目录运行Alist核心服务；
• 仅当用户主动点击“高级挂载”时弹出说明，解释为何需要广泛存储权限；
• 提交审核时提供详细用途说明（如“用于挂载网络存储映射到本地文件夹”）；
• 准备备用方案：使用SAF让用户选择单个目录进行映射。