第 6 章：虚拟文件系统与网络¶

在现代数字化工作流中，文件管理早已超越了单块物理硬盘的边界。软件工程师需要通过 SFTP 维护云端测试与生产集群；系统管理员要管理基于 SMB/CIFS 的局域网企业共享存储；创作者常常借助 WebDAV 存取私有云 NAS 和媒体资源；而极客与技术人员更是每天都要在本地检视、修改并打包动辄数以 GB 计的各类压缩包。

传统桌面操作系统往往强迫用户在割裂的应用之间来回切换：打开专门的解压工具将 ZIP 解包到临时目录，改完后再重新打包；打开第三方 FTP/SFTP 客户端上传文件；或者通过操作系统挂载弹窗把远程网络盘散乱堆放在互不相通的访达 (Finder) 窗口中。

ATBCmder 通过其强大的 虚拟文件系统 (Virtual File System, 简称 VFS) 引擎彻底消除了这种割裂。基于统一的 vfs:// URI 抽象层，ATBCmder 将远程服务器和压缩包一视同仁地视为标准文件夹。您可以直接回车进入 .tar.gz 压缩包，按 F3 预览代码文件，按 F4 原地编辑深层配置文件（并在保存时自动无感重新打包回写），甚至直接在两个面板之间按下 F5，把文件从加密 SFTP 服务器高速流式拷入内网 SMB NAS——全程无需任何手动解压或临时文件落地！

1. 快速入门：VFS 架构总览与命令矩阵¶

ATBCmder 将所有底层文件系统的读写逻辑收敛到统一抽象层。无论是本地 APFS 固态硬盘分区、多层嵌套 .zip 压缩包内部的子目录，还是远在大洋彼岸 Linux 节点上的 SFTP 目录，双面板均提供完全一致的操作交互。

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                              ATBCMDER 双面板主界面                                     │
│            左侧面板 (当前激活)                  右侧面板 (对侧闲置 / 目标)             │
│  [1] 本地物理文件系统                    │  [2] 压缩包虚拟文件系统 (Archive VFS)       │
│      file:///Users/brain/projects/       │      vfs:///Users/brain/backup.tar.gz/src/  │
│      直接高速访问本地 APFS 固态硬盘      │      原地免解压浏览、F3查看、F4实时编辑回写 │
│                                          │                                             │
│  [3] 远程网络文件系统 (SFTP / SSH)       │  [4] 局域网网络存储 (SMB / WebDAV)          │
│      vfs://sftp://deploy@aws.prod/app/   │      vfs://smb://admin@truenas/Pool/Media/  │
│      Paramiko / SSH 密钥 / 钥匙串安全认证│      macOS 原生 mount_smbfs / WebDAV 客户端 │
│                                          │                                             │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                         统一 VFS 路由调度分发引擎 (vfs://)                             │
│     FileSystemModel ➔ VFSManager ➔ SessionCache ➔ StreamCopyWorker / RepackWorker      │
└────────────────────────────────────────────────────────────────────────────────────────┘

VFS 与网络双矩阵速查表¶

2. 统一的 vfs:// URI 抽象规范¶

传统文件管理器往往把远程网络盘和压缩包视为次等公民，必须依赖第三方挂载工具或先全量解压到临时目录。ATBCmder 将所有文件源全部收敛至标准化、结构严谨的统一资源定位符 (URI)：

vfs://[协议类型]://[用户名]@[主机地址]:[端口号]/[远端绝对路径]

2.1 虚拟路径两大范式¶

根据不同的数据载体与应用场景，vfs:// URI 主要呈现为两种规范格式：

1. 压缩包虚拟路径 (Archive Virtual Paths)：

   vfs:///Users/brain/Documents/release_v1.7.zip/src/main.py
   

2. 外层协议头：vfs:// 告知底层 FileSystemModel 拦截物理文件系统调用。

3. 物理容器路径：/Users/brain/Documents/release_v1.7.zip 精准定位本地磁盘上实际存在的归档文件。

4. 包内虚拟成员：src/main.py 定位压缩包内部层级深处的虚拟目标文件。

5. 网络服务器路径 (Network Server Paths)：

   vfs://sftp://developer@staging.internal.net:2222/var/www/html/index.php
   vfs://smb://admin@192.168.1.50/StoragePool/Backups/2026/
   vfs://webdavs://user@cloud.mycompany.com:443/remote.php/dav/files/user/
   

6. 协议标识符：指定具体的传输驱动（sftp、ftp、ftps、smb、webdav、webdavs、gdrive、dropbox）。

7. 身份验证凭据：编码用户名与指定端口号。
8. 远端目标路径：对应远程服务器主机上的绝对目录或文件系统路径。

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                              VFS 路径解析全流程示意                                    │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│   输入示例: vfs://sftp://deploy@aws.infra:22/var/log/nginx/access.log                  │
│                 │      │        │        │   └────────────────────► 远端绝对路径       │
│                 │      │        │        └────────────────────────► 端口 (默认 22)     │
│                 │      │        └─────────────────────────────────► 远程主机 / 域名    │
│                 │      └──────────────────────────────────────────► 登录用户名         │
│                 └─────────────────────────────────────────────────► 网络传输协议驱动   │
│                                                                                        │
│   输入示例: vfs:///Volumes/Data/Archive.zip/docs/manual.pdf                            │
│                 │                      │        └─────────────────► 压缩包内部文件     │
│                 │                      └──────────────────────────► 物理压缩包文件     │
│                 └─────────────────────────────────────────────────► 虚拟文件系统协议头 │
└────────────────────────────────────────────────────────────────────────────────────────┘

2.2 双面板无缝协同交互¶

因为所有虚拟路径在 ATBCmder 内部都遵循统一的抽象目录模型，所以您能享受到完整的双面板交互能力：

• 多标签虚拟工作区：在左侧面板标签页 1 打开远程 SFTP 服务器，标签页 2 打开本地加密 ZIP 包，标签页 3 打开本地 ~/Downloads 目录，多源自由切换。
• 定向双向复制 (F5)：在本地激活面板中选中文件并按下 F5，即可将其直接推送到对侧面板展示的远程服务器或压缩包内部。
• 直接拖拽传输 (Drag-and-Drop)：跨越面板边界，在本地磁盘、网络共享以及归档内部层级之间直接拖拽文件，无需中间繁琐落地。
• 动态交互式面包屑导航条：面包屑路径栏能够智能解析虚拟 URI 为可点击的层级按钮。点击任何父级目录或根服务器徽标，即可瞬间折跃至对应层级。

3. 压缩包虚拟文件系统 (Archive VFS)：免解压原地畅游¶

在 ATBCmder 中打开压缩包完全无需先解压到临时目录或借助第三方解压软件。只需高亮选中的压缩包并按下 Enter（回车键）或双击鼠标，ATBCmder 便会瞬间在原地挂载该归档，将当前面板转化为高效的虚拟目录浏览器。

图 6.1：将多层嵌套压缩包视为普通虚拟目录原地浏览，清晰展现未压缩体积、时间戳与子目录层级。

3.1 原生支持的归档与压缩格式¶

ATBCmder 原生内置工业级主流归档与压缩格式驱动：

3.2 原地畅游的日常操作流¶

在压缩包内部漫游浏览时：

1. 进入子目录：在压缩包内的任何文件夹上按下 Enter（回车），立即展开深层嵌套目录。
2. 返回上一级 (..)：按下 Backspace（退格键 ⌫）或双击 .. [上一层目录] 返回上级。到达压缩包的根目录后再按退格键，即可优雅返回包含该压缩包的外部物理文件夹。
3. 即时预览 (F3 / Fn+F3)：在包内的任何文档、图片或源码文件上按下 F3，ATBCmder 会在沙箱中仅流式提取该单项，并在全能查看器中毫秒级展现。
4. 按需单项提取 (F5 / Fn+F5)：不必为了取出几个小文件而解压几十 GB 的庞大压缩包。直接在包内选中需要的文件并按下 F5，ATBCmder 会单独将选中的条目解压并投递到对侧面板中。

4. 实时重打包 (Live Repacking)：在压缩包内原地编辑¶

ATBCmder 最受极客欢迎的核心功能之一就是 实时重打包 (Live Repacking)。在传统工作流中，修改压缩包内的一个配置文件需要极度繁琐的六个步骤：解压整个包 ➔ 找到目标文件 ➔ 编辑并保存 ➔ 重新压缩为同名文件 ➔ 删除原压缩包 ➔ 清理临时解压目录。

ATBCmder 让修改压缩包内的文件变得像修改本地普通文件一样直观自然。

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                              实时重打包 (LIVE REPACKING) 生命周期                      │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│  1. 用户在 "package.zip" 内部对 "config.json" 按下 F4 编辑                             │
│     │                                                                                  │
│     ├──► ATBCmder 提取 "config.json" 到沙箱: /tmp/dc_repack_xyz/config.json            │
│     └──► 唤起内置 EditorDialog，窗口标题显示: "config.json — Editor"                   │
│                                                                                        │
│  2. 用户在编辑器中修改配置并按下 Cmd+S (保存)                                          │
│     │                                                                                  │
│     ├──► 编辑器发出 file_saved 信号                                                    │
│     └──► RepackWorker 后台线程比对原压缩包体积与 ArchiveRepackWarningMB 安全阈值       │
│                                                                                        │
│  3. 原子级重打包执行 (Atomic Repack)                                                   │
│     │                                                                                  │
│     ├──► 将修改后的流式数据写入暂存归档: /tmp/package.zip.tmp                          │
│     ├──► 校验新生成容器的完整性与内部签名                                              │
│     ├──► 执行原子替换: os.replace("/tmp/package.zip.tmp", "/original/package.zip")     │
│     └──► 自动刷新当前激活面板，并彻底清理临时沙箱 /tmp/dc_repack_xyz/                  │
│                                                                                        │
└────────────────────────────────────────────────────────────────────────────────────────┘

4.1 分步实操：修改压缩包内的配置文件¶

1. 按 Enter 回车进入压缩包（如 application_bundle.zip）。
2. 定位到需要调整的配置文件（如 settings.yaml）。
3. 按下 F4（或 Fn+F4）。ATBCmder 会自动将该文件提取到沙箱缓存中，并调出内置全功能代码编辑器。
4. 在编辑器中按需修改内容。
5. 按下 Cmd+S（⌘S）保存文件。
6. 按 Cmd+W 或 Esc 关闭编辑器。
7. ATBCmder 的 RepackWorker 守护进程会自动捕获变更，在后台将更新后的文件重新打包装入原归档，执行原子替换，并实时刷新文件列表。

5. 创建与提取压缩包 (Alt+F5 / Alt+F9)¶

ATBCmder 为归档的创建与提取配置了独立的后台工作线程，确保在执行耗时数分钟的大体积压缩任务时，双面板界面依然流畅可用、绝不假死卡顿。

图 6.2：压缩打包对话框 (Alt+F5 / cm_PackFiles)，支持目标路径定制、格式切换、压缩级别调优与 AES-256 密码加密。

5.1 压缩打包文件 (Alt+F5 / ⌥F5 / cm_PackFiles)¶

创建新归档只需以下几步：

1. 在当前激活面板中，选中一个或多个需要打包的文件或文件夹。
2. 按下 Alt+F5（⌥F5），或从顶部菜单栏选择 文件 ➔ 打包压缩...。
3. 弹出 打包压缩 对话框：
4. 目标归档路径：生成归档的存储路径。默认自动指向对侧闲置面板所在的目录，并以当前焦点条目命名。
5. 归档格式：自由选择 ZIP、TAR、TAR.GZ、TAR.BZ2、TAR.XZ 或 7Z。
6. 压缩级别：
   • 存储 (Store)：仅打包不压缩；适合用于本身已高度压缩的媒体文件（MP4、JPEG、MKV）。
   • 极速 (Fast)：CPU 占用极低，优先保证打包速度。
   • 标准 (Normal Deflated)：兼顾压缩比与运行性能（日常通用推荐配置）。
   • 最大 (Maximum)：极限压缩模式（在支持的格式下启用 LZMA/Bzip2 极限算法）。
7. 保护密码 (仅限 ZIP)：输入加密口令，对归档内的文件进行加密保护。
8. 点击 确定（或回车）。压缩任务将在非阻塞的后台线程中平稳运行，同时呈现精确的进度条与逐文件处理状态。

工业级 AES-256 密码加密防护¶

传统的 ZIP 加密方式（老旧的 ZipCrypto）在密码学上已被证实极易被破解，存在严重的明文已知字典攻击漏洞。在 ATBCmder 中为 ZIP 压缩包设置密码时，系统原生采用基于 pyzipper 的 AES-256 工业级高强度加密（遵循 WZ_AES 国际标准）。该标准不仅完全兼容 macOS 原生解压机制、WinZip 与 7-Zip，还能有效阻断暴力破解与中间人刺探。

超大文件跨介质分卷压缩与合并¶

若您需要通过邮件附件发送大文件，或将大体积素材分发到受 FAT32 单文件 4GB 限制的 U 盘与云存储：

1. 先使用 Alt+F5 (cm_PackFiles) 将文件完整打包。
2. 光标停留在生成的 .zip 或 .tar 文件上，按下 Alt+F6 唤起文件分割器 (cm_FileSpliter)。
3. 选择预设分卷大小（如 100 MB、4.7 GB DVD、CD 700 MB，或输入自定义字节大小）。
4. ATBCmder 会批量生成带序列编号的分卷切片（如 archive.zip.001、archive.zip.002 等）并附带 CRC32 校验清单。接收方在任何电脑上随时可以通过 cm_FileLinker（文件合并器）将其无损复原。

5.2 解压提取归档 (Alt+F9 / ⌥F9 / cm_ExtractFiles)¶

将压缩包批量解压落地到磁盘中：

1. 在激活面板中选中一个或多个压缩包文件。
2. 按下 Alt+F9（⌥F9），或从顶部菜单栏选择 文件 ➔ 解压...。
3. 弹出 解压文件 对话框：
4. 待解压文件：显示当前选中的归档路径。
5. 解压目标路径：解压落地目录（默认自动对齐对侧闲置面板的当前路径）。
6. 包内预览列表：支持在弹窗内动态检视压缩包内部的文件清单。
7. 解压密码：针对受密码保护的归档输入解密口令。
8. 点击 确定。解压过程中若遇到目标目录已有同名文件，ATBCmder 会主动暂停并弹出交互式冲突处理窗口：
9. 覆盖：替换当前冲突的单个目标文件。
10. 跳过：保留现有目标文件不动，继续解压下一个条目。
11. 全部覆盖：后续所有重名文件全部静默覆盖。
12. 全部跳过：后续所有重名文件全部自动跳过。
13. 取消：安全中止解压任务，保留已解压好的部分。

6. 远程网络文件系统：主流协议与远端存储¶

ATBCmder 原生内置对多主流网络传输协议的支持，无需任何第三方插件或中间服务，即可直接在双面板中无缝挂载并操作远程服务器。

图 6.3：通过高安全性 SFTP 协议浏览远程 Linux 服务器目录，直观显示文件属性、所属权限并支持面板间双向流式拷贝。

图 6.4：支持丰富的网络连接类型：安全 SFTP、传统 FTP/FTPS、WebDAV 云存储以及局域网 SMB 共享。

6.1 支持的网络传输协议¶

6.2 协议深度解析与专属特性¶

SFTP (SSH 文件传输协议)¶

基于业界标杆级 paramiko SSH 核心引擎，ATBCmder 的 SFTP 驱动在端口 22 上建立加密隧道：

• 主机指纹安全防护 (WarningPolicy)：严格遵循安全准则，ATBCmder 会自动调阅本地 ~/.ssh/known_hosts。连接已知主机时自动校验公钥指纹；遇到未知服务器时，系统会弹出明确的安全告警，绝不静默信任来历不明的公钥。
• SSH 私钥免密登录：除了传统密码登录外，完全支持加载本地 SSH 私钥（如 ~/.ssh/id_rsa、~/.ssh/id_ed25519）。
• UNIX 文件属性无损映射：完整保留远程文件的八进制文件权限模式 (chmod)、所属用户/用户组属性以及精确的 POSIX 修改时间戳。

FTP 与 FTPS (明文 / TLS 加密传输)¶

基于 Python 内置 ftplib 深度重构的 FTP 驱动支持：

• 被动传输模式 (PASV)：默认强制开启被动模式，确保在穿透复杂 NAT 家用路由器与企业级防火墙时依然保持稳定通信。
• 多语言编码自适应切换：彻底告别跨平台中文乱码！支持在 UTF-8、ISO-8859-1、GB18030 与 Windows-1252 字符编码之间一键切换。

SMB / Samba (Windows 局域网共享与 NAS 设备)¶

不同于传统的慢速纯用户态 Python SMB 库，ATBCmder 采用了混合加速架构：

• macOS 原生内核级硬件加速 (mount_smbfs)：在 macOS 上，ATBCmder 的 SambaMounter 深度联动系统底层的 /sbin/mount_smbfs。它将远程网络共享直接挂载进 macOS 原生 VFS 树（/Volumes/ 或隔离挂载点），释放出纯原生硬件加速的 SMB3 极致吞吐带宽。
• 现存挂载点智能感知：若 macOS 访达或系统开机脚本已经挂载了目标 SMB 卷，ATBCmder 会自动从系统的 mount 挂载表中嗅探并瞬间定位进入，避免重复建立冗余连接。

WebDAV 与 WebDAVS (Nextcloud 私有云与云存储)¶

基于 webdavclient3 驱动，提供与现代私有云存储的双向同步通道：

• SSL 证书校验模式：对公网 WebDAVS 服务执行严苛的 SSL 证书链验证；针对家庭自建的局域网自签名证书服务，提供一键信任跳过开关。
• 递归深层目录创建 (makedirs)：在批量上传文件时，若远端不存在父级多层目录，驱动会自动执行递归建构，防止批量上传失败。

6.3 Google Drive 云存储配置指南¶

在网页端管理 Google Drive 时，上传大文件或整理多层文件夹往往会感到繁琐迟缓；而 Google Drive 官方桌面客户端又通常倾向于将整个云端文件夹全量同步到本地 Mac 固态硬盘，白白挤占宝贵的存储空间。

ATBCmder 巧妙地将 Google Drive 虚拟化为实时直连磁盘 (gdrive://)。您可以在双面板中直接穿透浏览云端文件、按 F3 全能预览、按 F5 在 Mac 与云端之间高速双向拷贝——全程无需将整个云盘下载同步到本地。

图 6.5：通过连接管理器配置 OAuth2 客户端凭据直连 Google Drive，在双面板中与本地文件夹并行浏览与传输。

为什么需要 "Client ID" 和 "Client Secret"？¶

为了捍卫您的隐私与账户安全，Google 严格禁止第三方桌面软件索取或保存您的 Google 账户明文密码，统一强制采用 OAuth 2.0 官方授权机制。

通过在 Google Cloud Console 中免费申请属于您个人的 OAuth 凭据：

• 100% 隐私与直连：所有数据均在您的 Mac 与 Google 官方服务器之间点对点传输，绝无任何第三方服务器中转或窥探您的文件与密钥。
• 独享专属带宽与配额：拥有完全私有的 API 调用配额，不会与其他任何用户抢占速度。
• 随时可吊销：控制权始终在您手中，您可以随时在 Google 账户安全控制台中一键撤销 ATBCmder 的访问权限。

整个配置流程耗时不超过 3 分钟，且只需一次性配置！

步骤 1：在 Google Cloud 中免费创建凭据（耗时 2 分钟）¶

1. 在浏览器中打开 Google Cloud Console — 凭据页面，并登录您的 Google 账号。
2. 选择或新建项目：
3. 点击页面顶部的组织/项目下拉菜单。
4. (企业/组织提示：如果您拥有 Google Workspace 或 Cloud Identity 组织（如 aitobox.com），请在下拉菜单中选择该组织，以便将项目创建在企业域名下)。
5. 如果尚未创建项目，点击 新建项目，输入任意项目名称（如 ATBCmder），点击 创建。
6. 启用 Google Drive API：
7. 在左侧菜单栏或顶部搜索框中进入 已启用的 API 和服务（或点击 + 启用 API 和服务）。
8. 搜索 Google Drive API，点击进入后点击蓝色的 启用 按钮。
9. 配置 OAuth 同意屏幕 (首次创建时若提示)：
10. 若系统提示配置同意屏幕，选择 外部 (External) 并点击 创建。
11. 填写 应用名称（如 ATBCmder），填写用于技术支持与开发者联系的电子邮件地址。
12. 在 应用网域 下，将 应用首页 设置为您需要的域名（如 https://cmder.aitobox.com）。
13. 在 已获授权的网域 下，添加根域名（如 aitobox.com）。
14. 一路点击 保存并继续 完成后续配置。
15. 创建桌面端凭据：
16. 返回 API 和服务 ➔ 凭据。
17. 点击顶部 + 创建凭据，选择 OAuth 客户端 ID。
18. 在 应用类型 下拉菜单中选择 桌面应用 (Desktop app)。
19. 在 名称 字段中输入 ATBCmder Desktop（或任意名称）。
20. 点击 创建。
21. 复制您的专属密钥：
22. 弹窗将展示生成的 客户端 ID (Client ID)（以 .apps.googleusercontent.com 结尾）与 客户端密钥 (Client Secret)。
23. 点击复制两串密钥（或保持网页开启，后续亦可随时在凭据列表中查看）。

自定义企业品牌：理解“访问权限授予对象” (Access Granted To)¶

当您在 Google 账户安全中心 (myaccount.google.com/connections) 查看已绑定的第三方应用时，Google 会展示 ATBCmder 的应用详情卡片：

• 应用名称：ATBCmder
• 访问权限授予对象 (Access granted to)：例如 aitobox.com 或 oplist.org
• 首页：https://cmder.aitobox.com

为什么 Google 会显示特定的组织名称？¶

“访问权限授予对象” (Access granted to) 一行是由 Google 根据创建 OAuth 客户端 ID 所在 GCP 项目归属的 Google Cloud 组织（或 Google Workspace 机构主域）自动决定的：

• 如果客户端 ID 是在挂靠某第三方组织（如 oplist.org）的 GCP 项目下创建的，Google 便会展示该组织的域名以警示用户 API 客户端的归属方。
• 如果项目创建在个人 Google 账户名下，Google 则会展示您的开发者联系人身份。

如何将授予对象绑定为自有企业域名（如 aitobox.com）¶

若您希望 Google 账户安全页面中显示您自有的公司域名（如 aitobox.com）：

1. 在企业组织下创建项目：
2. 使用属于企业域名的管理员账号（如 admin@aitobox.com）登录 Google Cloud Console。
3. 在顶部组织选择框中，确认已选定企业主域（如 aitobox.com），再在此组织下新建项目。
4. 在 OAuth 同意屏幕中设置企业品牌：
5. 前往 API 和服务 ➔ OAuth 同意屏幕。
6. 将 应用主页 填写为官方主页（如 https://cmder.aitobox.com）。
7. 在 已获授权网域 中登记根域名（如 aitobox.com）。
8. 将 支持邮箱 与 开发者联络邮箱 均设置为域名邮箱。
9. 重新签发桌面应用客户端 ID：
10. 前往 API 和服务 ➔ 凭据，新建 桌面应用 类型的 OAuth 客户端 ID。
11. 在 ATBCmder 中更新密钥并重新授权：
12. 将全新的 Client ID 与 Client Secret 粘贴入 ATBCmder 连接管理器，点击 重新授权...。
13. 授权成功后，Google 账户安全中心即会清爽地将您的企业域名 (aitobox.com) 显示为授予方！

步骤 2：在 ATBCmder 中录入并一键授权¶

拿到密钥后，在 ATBCmder 中添加连接只需几秒：

1. 在 ATBCmder 顶部菜单栏选择 网络 ➔ 连接管理器...（或快捷键 cm_ManageConnections）。
2. 点击左下角的 + 新建 按钮开始创建新配置。
3. 在右侧 连接详细配置项 表单中：
4. 连接别名：输入直观名称（如 我的 Google Drive 或 工作云盘）。
5. 连接协议：在下拉列表中选择 gdrive。
6. 客户端 ID：粘贴在 Google Cloud 复制的 Client ID。
7. 客户端密钥：粘贴在 Google Cloud 复制的 Client Secret。
8. (贴心提示：您亦可随时点击输入框下方的蓝色快捷链接 Create OAuth 2.0 credentials in Google Cloud Console 直达 Google Cloud)。
9. 点击 授权（或 重新授权...）按钮：
10. ATBCmder 会自动调起系统默认浏览器打开 Google 官方授权页面。
11. 核心安全提示（完全正常与预期）：
    由于您使用的是自己在 GCP 开发者后台私有签发的 Client ID，而非从 Google 官方公开商业应用市场下载的预审核 App，Google 会弹出警示页面提示 “Google 尚未验证此应用” / “存在安全风险”。
    这完全属于正常现象且极其安全。 页面中点击 高级 (Advanced)，选择展开选项底部的 “转到应用/仍然继续 (unsafe)” 即可进入下一步授权。
12. 选择您的 Google 账号，确认授予 Google Drive 读写权限。
13. 点击 继续 / 允许。
14. 授权完成后浏览器将提示成功。切回 ATBCmder，状态将更新为：
    ✓ Authorized (your_account@gmail.com)！

1. 点击 💾 保存 将该连接加入书签，随后点击 🔗 立即连接（或在左侧列表中双击它）。
2. 当前面板将瞬间打开一个新标签页，路径直指：

   vfs://gdrive://your_account@gmail.com//
   

   您的所有 Google Drive 云端文件与多层文件夹已尽在眼前！

步骤 3：像操作本地硬盘一样畅游 Google Drive¶

建立连接后，Google Drive 的交互与本地文件夹毫无二致：

• 免下载极速预览：双击或回车进入文件夹。选中任意图片、PDF、代码文件或文档，按 F3 即可在全能查看器中瞬间流式开箱预览，无需预先保存到本地。
• 上传到云端 (F5)：在本地面板中（如 Mac 的 Downloads 目录）选中文件或目录，按下 F5 即可直传到当前 Google Drive 远端路径。
• 下载到本地 (F5)：在 Google Drive 面板中选中远端文件，按下 F5 即可流式下载至对侧本地文件夹。
• 鼠标拖拽自由交互：支持直接在本地面板与 Google Drive 面板之间用鼠标随意拖拽文件与文件夹。
• 一键极速刷新 (F9 / Ctrl+R)：当同事分享了新文件或您在手机端有新改动时，按下 F9（或工具栏刷新按钮）即可毫秒级同步最新云端变动。
• 实时云端配额监视：顶部工具栏右侧的状态胶囊实时显示 Google Drive 的剩余存储容量（例如 259.7 GB free of 994.7 GB），云盘用量一目了然。
• 多账号无缝穿梭：您可在连接管理器中添加多个 Google Drive 账号（如 个人云盘 与 工作云盘），甚至可以左侧面板打开账号 A，右侧面板打开账号 B，直接在两套云盘之间对拷文件！
• 苹果安全飞地硬件加密：客户端密钥与 OAuth 刷新令牌直接由 macOS 系统钥匙串 (ATBCmder_VFS) 与 Apple Secure Enclave 硬件加密保护，绝不会在磁盘上以明文留存。

6.4 Dropbox 云存储配置指南¶

与 Google Drive 类似，直接在 ATBCmder 中接入 Dropbox，让您摆脱数以百计 GB 云端文件对 Mac 本地固态硬盘的无端侵占，尽享轻装上阵的极速云端漫游体验。

ATBCmder 将 Dropbox 作为实时在线的虚拟磁盘 (dropbox://)，支持使用 F3 全能预览照片与文档、F5 高性能分块流式上传与下载，并在顶部工具栏实时呈现云盘配额。

为什么需要 "App Key" 和 "App Secret"？¶

为了彻底保护您的数据隐私与账号安全，Dropbox 不允许第三方桌面工具索取或保存您的 Dropbox 登录密码，全程采用 OAuth 2.0 授权机制。

通过在官方 Dropbox App Console 中免费创建专属于您的 App Key 与 App Secret：

• 100% 隐私与直连：所有网络通信均在您的 Mac 与 Dropbox 官方服务器之间点对点加密传输，绝无任何第三方服务器代理或窥探。
• 独享专属带宽与配额：拥有完全私有的 API 配额限制，告别公共应用的高峰拥堵与频控限制。
• 随时可吊销：控制权完全在您手中，您可以随时在 Dropbox 账户安全设置中一键撤销访问权限。

配置整个流程耗时不足 2 分钟，且一次配置永久生效！

步骤 1：在 Dropbox App Console 中创建应用¶

1. 在浏览器中打开 Dropbox App Console，登录您的 Dropbox 账号。
2. 点击右上角蓝色的 Create app 按钮。
3. 参考下图所示配置您的应用参数：

图 6.6：在 Dropbox 开发者中心创建全新 App，选择 Scoped access 并开启 Full Dropbox 全量访问权限。

• 1. Choose an API：选择 Scoped access。
• 2. Choose the type of access you need：选择 Full Dropbox（允许访问整个 Dropbox 内的所有文件与文件夹）。
  (注：若仅希望 ATBCmder 访问独立的沙盒文件夹，亦可按需选择 "App folder")。
• 3. Name your app：为应用起一个独一无二的名称（如 ATBCmder 或 ATBCmder-YourName）。
• 勾选 I agree to Dropbox API Terms and Conditions 协议复选框。
• 点击右下角蓝色的 Create app 按钮。

步骤 2：配置重定向回调 URI 并复制密钥 (Settings 标签页)¶

创建成功后系统会自动跳转至应用详情页。点击顶部的 Settings 标签页。

图 6.7：配置本地回环回调地址 (http://127.0.0.1:53682/callback) 并复制获取 App key 与 App secret。

1. 设置 OAuth 2 重定向回调 URI：
2. 向下滚动找到 OAuth 2 配置区域。
3. 定位到 Redirect URIs 输入框。

4. 输入或粘贴以下准确 URL：

   http://127.0.0.1:53682/callback
   

5. 点击输入框旁的 Add 按钮添加该 URI。
   (原理解析：ATBCmder 在发起授权请求时会在本地 53682 端口建立临时安全回环监听服务。登记该 URI 能够让 Dropbox 在授权完毕后瞬间自动回调激活 ATBCmder，实现一键无感闭环)。

6. 允许公共客户端 (PKCE)：
7. 确认 Allow public clients (Implicit Grant & PKCE) 选项保持为 Allow（或默认值）。
8. 复制您的 App Key 与 App Secret：
9. 在 Settings 标签页上方，找到 App key 并点击复制。
10. 在其正下方找到 App secret，点击 Show 链接显示出完整密钥并复制保存。
    (保持该浏览器页面开启或临时保存这两串密钥，稍后将在步骤 4 中粘贴至 ATBCmder)。

步骤 3：配置所需授权范围与权限 (Permissions 标签页)¶

接下来，点击应用设置页面顶部的 Permissions 标签页。

图 6.8：在 Permissions 标签页勾选必要的权限范围，包含 files.metadata.read/write 与 files.content.read/write。

1. 在 Account Info 区域：
2. account_info.read：检视 Dropbox 账户基本信息（默认已勾选，让 ATBCmder 连入后可自动感知并显示您的账户邮箱）。
3. 在 Files and folders 区域，确保勾选以下权限项：
4. files.metadata.write：读取并修改 Dropbox 文件与文件夹的元数据信息。
5. files.content.write：修改 Dropbox 文件与文件夹的内容（支持上传与写入文件）。
6. files.content.read：读取 Dropbox 文件与文件夹的内容（支持下载与查看文件）。

步骤 4：在 ATBCmder 中添加 Dropbox 并一键授权¶

配置好 Dropbox 开发者应用后，接入 ATBCmder 仅需寥寥数步：

1. 在 ATBCmder 菜单栏选择 网络 ➔ 连接管理器...（或快捷键 cm_ManageConnections）。
2. 点击左下角的 + 新建 按钮开启新配置。
3. 在右侧 连接详细配置项 表单中：
4. 连接别名：输入别名（如 我的 Dropbox 或 团队 Dropbox）。
5. 连接协议：下拉列表选择 dropbox。
6. App Key：粘贴从 Dropbox Settings 标签页复制的 App key。
7. App Secret：粘贴从 Dropbox Settings 标签页复制的 App secret。
8. (贴心提示：您亦可随时点击输入框下方的辅助链接 Create app in Dropbox App Console 直达开发者后台)。
9. 点击 浏览器登录...（或 授权）按钮：
10. ATBCmder 会自动在系统默认浏览器中唤起 Dropbox 官方授权审批页。
11. 检查请求的权限范围，点击 Allow (允许)。
12. 批准后浏览器将提示成功。切回 ATBCmder，状态指示器将更新为：
    ✓ Authorized (your_account@email.com)！
13. 点击 💾 保存 将配置固化，随后点击 🔗 立即连接（或在左侧列表中双击该项）。
14. 当前面板将立即弹出全新标签页并导航至：

    vfs://dropbox://your_account@email.com//
    

    所有 Dropbox 文件与目录尽收眼底！

常见故障排查与急救¶

步骤 5：像操作本地硬盘一样畅游 Dropbox¶

接入成功后，Dropbox 的操作体验与高速本地磁盘高度一致：

• 双面板极速拷贝 (F5)：在本地面板选中文件（如 Mac 的 Documents 或 Downloads），按下 F5 直接上传至 Dropbox；反之选中远端文件按下 F5 即可高速下载到本地。
• 智能分块流式传输：后台采用非阻塞分块流式传输会话，配合毫秒级动态进度指示，从容应对数 GB 级的大型视频或压缩包，绝不溢出系统内存。
• 免下载瞬时预览 (F3)：在 Dropbox 面板中选中任意图片、PDF、Markdown 或文本文件，按下 F3 即可调出全能查看器原地检视，无需预先落地保存。
• 创建远端目录 (F7)：按下 F7 快速创建远端新目录，支持自动递归创建缺失的各级父目录。
• 鼠标拖拽自由互通：支持通过鼠标直接在本地面板与 Dropbox 面板之间任意拖拽复制文件与文件夹。
• 实时云端容量胶囊：右上角工具栏实时呈现 Dropbox 的剩余空间与总容量（如 1.8 GB free of 2.0 GB），配额状况尽在掌握。
• 一键极速刷新 (F9 / Ctrl+R)：轻按快捷键即刻获取在其他设备上的云端变动或同步最新配额。
• 苹果硬件级安全加固：OAuth 刷新令牌与凭据全程经由 macOS 系统钥匙串 (ATBCmder_VFS) 与 Apple 芯片的 Secure Enclave 硬件加密存储。

6.3 App Store 沙盒云存储（OneDrive、Google Drive、iCloud）¶

在 Mac App Store 沙盒版本的 ATBCmder 中，对第三方本地云同步目录（如 Microsoft OneDrive、Google Drive 桌面端、Dropbox 和 iCloud Drive）的直接文件系统访问受到 Apple 沙盒安全机制的管理：

• 安全作用域书签 (Security-Scoped Bookmarks)：位于 ~/Library/CloudStorage/OneDrive-*、~/Library/CloudStorage/GoogleDrive-* 或 ~/Library/Mobile Documents/com~apple~CloudDocs/ 的云同步目录需要系统签发的安全访问令牌。
• 盘符选择器与路径无缝集成：ATBCmder 会全自动发现本机已配置的本地云存储目录，并在磁盘驱动器选择器（Alt+D / ⌥D）、驱动器按钮栏与路径面包屑中直观呈现。
• 持久授权凭据存储：首次点击进入某个云存储目录时，macOS 系统会自动弹出授权确认工作表。一旦用户选择授权，ATBCmder 会将加密的安全作用域书签持久化保存在偏好设置中，在应用重启后依然保持读写畅通，无需反复弹出授权对话框。

7. 快速连接 vs 连接管理器¶

ATBCmder 为连接远程主机提供了两套相辅相成的方案：针对临时调试的 快速连接，以及面向固定服务器资产的 连接管理器。

7.1 快速临时连接 (cm_NetworkConnect)¶

当您需要临时连入某台设备处理突发问题，不想把配置持久保存污染书签时：

1. 选择菜单栏 网络 ➔ 快速连接...（或运行命令 cm_NetworkConnect）。
2. 弹出精简轻快的快速拨号弹窗：
3. 协议：选择 sftp、ftp、ftps、smb、webdav、webdavs、gdrive 或 dropbox。
4. 服务器地址与端口：输入主机 IP 或域名（端口随协议自动回填默认值）。
5. 用户名与密码：输入远端认证信息。
6. 远程起始路径：指定登入后的初始目录（默认为 /）。
7. 记住密码：临时连接建议保持不勾选。
8. 点击 测试连接，在正式载入前先行验证网络握手与身份认证是否通畅。
9. 点击 连接。ATBCmder 会立即在当前面板新建一个标签页，直连远端服务器。

7.2 连接管理器 (cm_ManageConnections)¶

对于日常频繁往来的开发集群、测试机与公司 NAS，连接管理器提供了全维度的配置中枢：

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                              网络连接管理器 (CONNECTION MANAGER)                       │
├──────────────────────────────┬─────────────────────────────────────────────────────────┤
│  已保存的书签列表            │  连接详细配置项                                         │
│  ┌────────────────────────┐  │  连接别名:     [ AWS 生产集群跳板机                   ] │
│  │ 🔐 AWS 生产集群跳板机  │  │  连接协议:     [ SFTP (port 22)                     ▼ ] │
│  │ 🖧 办公区主力群晖 NAS  │  │  主机地址:     [ ec2-54-210-10-2.compute.amazonaws.com] │
│  │ 🌐 Nextcloud 私有云盘  │  │  端口号:       [ 22                                   ] │
│  │ 📂 实验室旧版归档 FTP  │  │  用户名:       [ ubuntu                               ] │
│  │                        │  │  登录密码:     [ ••••••••••••••••••                   ] │
│  │                        │  │  远端起始路径: [ /var/www/production                  ] │
│  │                        │  │  [✓] 将安全密码存入 macOS 系统钥匙串 (Keychain)         │
│  └────────────────────────┘  │                                                         │
│  [➕ 新建] [⧉ 克隆] [🗑 删除]  │  [🔍 测试连通性]             [💾 保存]  [🔗 立即连接] │
└──────────────────────────────┴─────────────────────────────────────────────────────────┘

维护服务器连接配置¶

• 新建 (➕ 新建)：清空右侧表单，录入全新服务器的连接参数。
• 克隆 (⧉ 克隆)：快速复制当前选中的连接模板。对于配置相同、仅 IP 或端口不同的开发、测试、预发多套环境，能够极大减少重复输入。
• 删除 (🗑 删除)：安全移除该连接书签，并同步清理系统中绑定的钥匙串安全密码。
• 测试连通性 (🔍 测试连通性)：在后台派遣 ConnectionTestWorker 发起连通性探针，校验认证有效性，不影响当前面板的正常操作。
• 立即连接 (🔗 立即连接)：保存改动，立即建立远程会话并在新标签页中打开。

菜单栏动态书签直达¶

所有在管理器中保存的连接，都会自动同步映射到 macOS 顶部菜单栏的 网络 ➔ 已保存的连接 中。只需一次点击，即可像打开本地书签一样快速挂载：

• 网络 ➔ 已保存的连接 ➔ 🔐 AWS 生产集群跳板机
• 网络 ➔ 已保存的连接 ➔ 🖧 办公区主力群晖 NAS

8. 凭据安全与 macOS 钥匙串原生集成¶

在各类针对开发者的网络安全攻击中，文件管理器的配置文件往往是重灾区。许多传统文件管理工具把 FTP/SFTP 密码明文存放在用户家目录的 XML 或 INI 文本中，极易被恶意扫描脚本盗取。

ATBCmder 承诺：绝不在磁盘配置文件中以任何明文形式存储敏感凭据！

8.1 凭据安全存储架构¶

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                           凭据多层安全存储体系架构                                     │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│   持久化配置 XML 文本                           macOS 系统原生安全钥匙串               │
│   (~/.config/atbcmder/atbcmder.xml)            (服务标识: "ATBCmder_VFS")              │
│   ┌─────────────────────────────────────┐      ┌─────────────────────────────────────┐ │
│   │ <connection>                        │      │ 标识: "AWS 生产集群跳板机"          │ │
│   │   <label>AWS 生产集群跳板机</label> │      │ 密文: 硬件安全区高强度加密口令      │ │
│   │   <scheme>sftp</scheme>             │      │ 访问: 受 Apple 安全芯片硬件隔离守护 │ │
│   │   <host>aws.infra.net</host>        │      └─────────────────────────────────────┘ │
│   │   <user>deploy</user>               │                         ▲                    │
│   │   <password></password>             │                         │                    │
│   │ </connection>                       │                         │                    │
│   └─────────────────────────────────────┘                         │                    │
│         ▲                                                         │                    │
│         │ 保存时强制剔除密码置空                                   │ 经由系统          │
│         └─────────────────── ConnectionManager ───────────────────┘ keyring 安全存入   │
│                                                                                        │
└────────────────────────────────────────────────────────────────────────────────────────┘

1. XML 配置文件明文脱敏：无论在任何时候将连接配置序列化落盘到 atbcmder.xml，ConnectionManager.save() 方法均会在执行前强制执行 d["password"] = "" 置空。即便配置文件被意外读取或泄漏，也不会暴露任何服务器密码。
2. Apple 原生 Keychain 硬件加密：若勾选了 记住密码，系统会调用 Python keyring 模块直接把密码存入 macOS 钥匙串，服务名为 ATBCmder_VFS。密钥派生与数据加解密全程受 Apple 芯片硬件 Secure Enclave 保护。
3. 动态会话内存保护：若未勾选“记住密码”，凭据仅保存在当前运行期的动态内存结构（VFSSessionCache）中，在退出 ATBCmder 的瞬间即被彻底抹除。

9. ⚡ 高手进阶：高性能远程与归档实战技巧¶

技巧 1：非阻塞后台传输队列 (cm_OperationsPanel)¶

当跨越远程服务器拷贝海量目录，或通过 SFTP 下载数十 GB 的系统镜像时，切勿让界面冻结。ATBCmder 的所有网络与归档操作均原生接入 后台任务队列系统：

• 按 F5 启动传输时，可直接点击 后台 按钮将任务派入队列。
• 通过菜单栏 显示 ➔ 后台任务面板（cm_OperationsPanel）随时调出监视窗口，查看实时传输速率曲线、逐文件进度与剩余时间估算。
• 您可以随时对任务进行暂停、继续或调整先后次序，期间完全不影响双面板对本地文件的正常浏览与操作。

技巧 2：异构协议间的点对点流式直传¶

ATBCmder 内置的 stream_copy_file 引擎支持跨协议直接管道流式传输。例如将左侧面板 SFTP 服务器上的大文件夹直接拖拽到右侧面板的内网 SMB 共享盘中：

• ATBCmder 不会先将庞大的目录全量下载到本地 Mac 固态硬盘，再重新上传到 SMB。
• 系统在内存中构建环形缓冲区，将源端 Socket 读取到的数据块直接管道写入目标端 Socket。不仅减少了对本地 SSD 寿命的磨损，而且即使 Mac 本地磁盘可用空间不足，也能从容完成远端之间海量数据的无缝迁移！

技巧 3：网络长连接保活与自动重连机制¶

复杂的企业级硬件防火墙或家庭 NAT 路由常会在闲置 60 到 300 秒后强制切断空闲 TCP 连接。为避免在浏览深层远程树形目录时连接断开：

• ATBCmder 的 BaseNetworkVFS 基类会自动在空闲时段向远端发送轻量级心跳探针包，维持会话活性。
• 若遭遇偶发性网络抖动，内部的 _retry() 故障恢复机制会自动执行最多 3 次重试，采用平滑的指数退避策略（每次间隔 2^attempt 秒），确保在弱网环境下依然坚如磐石。

技巧 4：远程代码文件的编辑与自动回传流水线¶

需要直接修改远端 Linux 服务器上的 nginx.conf 或 Python 脚本？

1. 在 SFTP 或 WebDAV 面板中选中目标远程文件。
2. 按下 F4（Fn+F4）。
3. ATBCmder 会将该文件快速拉取到隔离临时沙箱（/tmp/）并在内置编辑器中打开。
4. 每次按下 Cmd+S（⌘S）保存时，系统都会触发 _upload_vfs_temp() 异步将修改后的文件推回远程服务器，并在状态栏轻量提示上传成功。
5. 关闭编辑器后，本地临时沙箱文件会被安全擦除。

10. 系统权限与安全警示¶

11. 双矩阵快捷键全景速查表¶