XPipe 13.1.1 增量更新深度解读：Windows 安装器 ALLUSERS 重构、文件浏览器分屏固定与关键稳定性修复

本文基于 XPipe 开源仓库的官方增量更新说明 dist/changelog/13.1.1_incremental.md，逐条解读 13.1.1 版本带来的功能变更与问题修复，并深入 app/src/main/java 下的对应源码，说明每项能力的底层实现原理、配置方式与适用场景。读完本文，你将理解 XPipe 新版 Windows MSI 安装器如何借助 ALLUSERS 支持 Intune 等企业级批量部署、文件浏览器"固定标签"分屏机制的完整工作方式，以及若干关键修复（git 同步、Proxmox 检测、启动目录权限检查）背后的设计意图。

一、版本背景：什么是增量更新日志

XPipe 的更新日志分为完整版（如 dist/changelog/13.1.1.md）与增量版（incremental）两类。增量版只列出相对上一版本新增或变更的内容，条目更精简，适合快速了解一个小版本的重点。13.1.1 是在 13.1（引入 KVM/QEMU 虚拟机支持、文件浏览器分屏固定、后台 shell 会话复用、独立安全更新检查等重大功能）之后的小版本，整体以安装器重构、文件浏览器体验打磨与问题修复为主。本章节以下内容将逐条展开这 9 项变更。

二、Windows MSI 安装器重构：ALLUSERS 与 Intune 批量部署

原文：Rework Windows msi installer to support both per-user and system-wide installations. The installer will also now respect the properties ALLUSERS. This makes it possible to install XPipe with tools such as intune

这是 13.1.1 最核心的一项变更：Windows MSI 安装器被重构为同时支持**按用户安装（per-user）与系统级安装（system-wide）**两种模式，并且开始尊重 MSI 标准属性 ALLUSERS，从而让 XPipe 可以被 Intune 等企业终端管理工具批量部署。

2.1 ALLUSERS 属性如何驱动安装模式

在 MSI 规范中，ALLUSERS 是决定安装范围的标准属性：

• ALLUSERS=1：系统级安装，所有用户可用，需要管理员权限；
• ALLUSERS=0（或省略）：按用户安装，仅当前用户可用，无需提升权限。

在 AppInstaller.java 的 getPowershellCommand() 中，XPipe 自更新流程会根据当前安装是否为系统级，动态拼接 msiexec 的属性参数：

var property = "MSIFASTINSTALL=7 DISABLEROLLBACK=1" + (systemWide ? " ALLUSERS=1" : " ALLUSERS=0");
var startProcessProperty = ", MSIFASTINSTALL=7, DISABLEROLLBACK=1" + (systemWide ? ", ALLUSERS=1" : "");
var runas = systemWide ? "-Verb runAs" : "";

可以看到：系统级安装时传入 ALLUSERS=1 并使用 Start-Process -Verb runAs 提升权限；按用户安装时传入 ALLUSERS=0 且不要求提权。同时保留 MSIFASTINSTALL=7 DISABLEROLLBACK=1 加速静默安装并禁用回滚，这是 XPipe 自更新安装器的既有优化。对应的 CMD 分支（getCmdCommand()，AppInstaller.java）则通过 start "" /wait msiexec /i ... /qb 以最小化窗口执行静默安装。

2.2 "系统级"如何判定

XPipe 通过安装路径的位置判断当前安装是否属于系统级。AppInstallation.java 中：

public boolean isSystemWide() {
    return !getBaseInstallationPath()
            .startsWith(AppSystemInfo.ofWindows().getUserHome());
}

即：安装基础路径位于用户主目录之外即为系统级安装。这一判定同时被自更新安装器与卸载/产品查询逻辑复用。

2.3 产品代码查询区分安装上下文

执行卸载（/x）前需要查询已安装产品的 ProductCode。AppInstaller.java 通过 Windows Installer COM 对象查询：

var context = AppInstallation.ofWindows().isSystemWide() ? "4" : "3";

ProductsEx 的上下文参数中 4 表示系统级（per-machine）、3 表示按用户（per-user），确保无论以哪种范围安装都能定位到正确的产品记录。

2.4 与 Chocolatey 更新链路的配合

除了直接执行 MSI，XPipe 还支持通过 Chocolatey 分发更新。ChocoUpdater.java 在执行 choco upgrade xpipe -y 时，会根据 isSystemWide() 追加安装参数：

var propertiesArguments = systemWide ? ", --install-arguments=\"'ALLUSERS=1'\"" : "";

从而保证 Chocolatey 升级后仍保持系统级安装范围，与 13.1.1 的 MSI 重构保持行为一致。

2.5 Intune 场景的实际价值

由于安装器现在尊重 ALLUSERS，企业 IT 管理员可以在 Intune 等 MDM/终端管理平台中为 XPipe 的 MSI 包配置 ALLUSERS=1，实现静默、无交互的系统级部署，覆盖组织内所有用户账户。这是本次重构最直接的落地场景。

三、文件浏览器：菜单栏固定按钮与双文件系统分屏

原文：Add pin tab button to the file browser menu bar to make tab splitting more prominent

13.1 版本已在标签页右键菜单中提供"固定（pin）"选项；13.1.1 则把固定操作提升到了文件浏览器的菜单栏，使其更显眼、更易发现。

3.1 固定标签的底层机制

固定标签由 BrowserFullSessionModel.java 中的 globalPinnedTab 属性承载，同一时刻只允许存在一个全局固定标签。核心操作如下（BrowserFullSessionModel.java）：

• pinTab(tab)：将某标签设为固定标签，并自动把选中项切回此前浏览的其他标签；
• unpinTab()：清除固定标签。

分屏视图的关键在于 createEffectiveRightTab()（BrowserFullSessionModel.java）：当当前选中标签可关闭且未被固定标签占用时，固定标签会自动作为右侧面板与当前标签并排显示，形成真正的双文件系统对比视图。这样你就可以同时浏览本地机器与任意远程主机两个不同的文件系统，例如边看远程日志边在本地整理归档。

3.2 菜单栏按钮与右键菜单双入口

菜单栏固定按钮实现在 BrowserFileSystemTabComp.java：按钮按下时若当前标签未固定则执行 pinTab(model)，否则 unpinTab()，并通过属性绑定自动刷新图标状态。标签页右键菜单中的 Pin / Unpin 选项则位于 BrowserSessionTabsComp.java，两条路径操作同一份 globalPinnedTab 状态，互不冲突。

四、文件浏览器设置：启动时固定本地机器标签

原文：Add file browser setting to automatically start up with local machine tab pinned

13.1.1 新增设置项 pinLocalMachineOnStartup（"启动时固定本地机器标签"），开启后每次启动 XPipe，文件浏览器都会自动打开本地文件系统标签并将其固定，配合上一节的分屏机制，一打开应用即可进入"本地 + 远端"对照浏览状态。

该设置的注册位于 AppPrefs.java：

final BooleanProperty pinLocalMachineOnStartup = map(Mapping.builder()
        .property(new GlobalBooleanProperty(false))
        .key("pinLocalMachineOnStartup")
        .valueClass(Boolean.class)
        .requiresRestart(true)
        .build());

注意 requiresRestart(true)：修改该选项后需要重启 XPipe 才能生效（13.1 起设置界面会在这类选项旁显示重启提示按钮）。启动逻辑位于 BrowserFullSessionModel.java 的 init()：

DEFAULT.openSync(new BrowserHistoryTabModel(DEFAULT), null);
if (AppPrefs.get().pinLocalMachineOnStartup().get()) {
    var tab = new BrowserFileSystemTabModel(
            DEFAULT, DataStorage.get().local().ref(), ref -> ref.getStore().createFileSystem());
    try {
        DEFAULT.openSync(tab, null);
        DEFAULT.pinTab(tab);
    } catch (Exception ex) {
        // Don't fail startup if this operation fails
        ErrorEventFactory.fromThrowable(ex).handle();
    }
}

源码注释表明：即使本地文件系统打开失败，也不会阻断应用启动，只会记录错误事件，体现了良好的容错设计。该设置项在设置界面中位于 File Browser 分类（FileBrowserCategory.java）。

五、下载新入口：右键菜单下载动作

原文：Add download context menu action in file browser as an alternative to dragging files to the download box

此前从远程主机取回文件，主要通过将文件拖拽到界面底部的"下载盒子"完成。13.1.1 新增了右键菜单中的**下载（Download）**动作作为等价替代，对不习惯拖拽操作的用户（尤其是触摸板/触屏场景）更友好。

该菜单项由 DownloadMenuProvider.java 注册，属于文件浏览器的上下文菜单 provider 体系。其底层下载流程在 BrowserTransferModel.java 中：

1. downloadSingle(Item)（L136-L195）：通过 BrowserFileTransferOperation 以 COPY 模式把远端文件复制到本地临时目录 TEMP（AppLocalTemp 的 download 子目录，见 L42），并实时汇报进度；
2. transferToDownloads(boolean open)（L197-L207）：把已下载完成的临时文件移动到下载目录，可选择完成后在资源管理器中定位文件。

5.1 关联：自定义下载目录

与下载流程直接相关的是下载目标目录设置。getDownloadsTargetDirectory()（BrowserTransferModel.java）优先使用用户自定义的 downloadsDirectory 偏好，若未设置或路径无效则回退到系统默认下载目录。该设置在 Settings → File Browser 中通过文件路径选择组件配置（FileBrowserCategory.java）。此项能力源于 13.1 版本，与 13.1.1 的下载右键菜单共同构成完整的下载体验。

六、macOS：不兼容 coreutils Homebrew 包的启动警告

原文：Add warning message when the incompatible coreutils homebrew package is in the PATH on macOS

macOS 默认携带 BSD 风格的命令行工具。部分用户通过 Homebrew 安装 coreutils 公式后，如果将其（GNU 风格工具，如 grealpath、ginstall）加入 PATH 且覆盖了系统自带的同名工具，可能会与依赖 BSD 工具参数与输出格式的脚本产生兼容性问题。13.1.1 在启动检查中新增了检测逻辑：当检测到 PATH 中存在不兼容的 coreutils Homebrew 包时，会向用户显示明确警告，提示其排查环境配置，避免后续连接、脚本执行等操作在不知不觉中失败。

从仓库后续版本看，该问题被持续关注：17.4 增量日志（dist/changelog/17.4_incremental.md）中出现了 "Improve gnu coreutils homebrew package handling on macOS"，说明 XPipe 团队一直在改进对这一场景的处理方式。需要说明的是，警告触发的具体探测命令在 13.1.1 源码中未能直接定位（仓库源码中无 coreutils 字样），上述机制描述是基于更新说明与后续变更的合理推断。

七、关键修复逐一深挖

7.1 修复 git 同步在需要密码提示时失败

原文：Fix git sync failing when it required a password prompt

XPipe 支持通过 git 远程仓库同步 vault 数据（设置界面中的 Git Sync 分类，见 SyncCategory.java）。此前当远程仓库需要认证（如 SSH 密钥口令、用户名密码）时，后台同步进程因无法进行交互式密码提示而失败。13.1.1 修复了该场景，使 git 同步在需要认证时也能正常完成。

这其实是 XPipe 在 git 同步认证问题上的一贯演进脉络：11.x 系列修复过 SSH 密钥带口令导致的冻结与守护进程退出问题（见 dist/changelog/11.0.md 第 49-50 行），12.x 修复过 PATH 中存在多个 gpg 程序导致的失败（见 dist/changelog/12.0.md 第 39 行）。13.1.1 的修复补齐了"需要密码提示"这一交互认证路径，与前述修复共同覆盖了 git 同步的主要认证失败场景。

7.2 修复 Proxmox 检测在非 PVE 发行版、非 root 登录时不工作

原文：Fix proxmox detection not working when not using the PVE distro and not logging in as root

Proxmox 集成是 XPipe 管理虚拟化基础设施的重要能力（相关文档入口见 DocumentationLink.java）。Proxmox 节点检测此前存在两个盲区：

• 非 PVE 发行版：用户在 Debian/Ubuntu 等系统上自行安装 Proxmox VE 时，节点标识方式与官方 PVE 发行版不同；
• 非 root 登录：以普通用户登录时，用于识别 Proxmox 的探测命令输出与权限受限场景下的表现不一致，导致误判。

13.1.1 修复了这两个场景下的检测失败，使非 PVE 发行版、非 root 账号也能被正确识别为 Proxmox 节点，从而正常使用后续的 VM/容器管理、SSH 连接等功能。完整版 13.1 日志中亦有对应条目（dist/changelog/13.1.1.md 第 38 行）。需要说明的是，Proxmox 探测的具体命令由运行时脚本层执行，仓库 Java 源码中未包含其细节，以上描述基于更新说明与功能行为推断。

7.3 修复用户目录权限启动检查失效

原文：Fix startup check for user directory permissions not working

XPipe 启动时会检查数据目录（用户目录）的可写权限，以确保 vault、日志、临时文件等能够正常落盘。该检查实现在 AppDirectoryPermissionsCheck.java 中，修复前的版本存在"检查不生效"的缺陷。其核心逻辑为：

1. 仅守护进程执行该检查（-Dio.xpipe.app.isCli 模式下跳过，防止并发创建文件冲突）；
2. 在数据目录下创建 permissions_check 测试目录并立即删除，若创建失败或"静默失败"则抛出异常；
3. 额外创建并读取 sync_file 测试文件——注释说明这是为 OneDrive 等云同步目录设计的二次检查：目录可能标记为同步但实际文件尚未下载，此时文件操作同样会失败。

// For cloud providers like OneDrive, we need another check to guarantee that all files are synced
// The file operation might fail if the directory is designated to sync but the actual file is not
// downloaded yet
var testFile = dataDirectory.resolve("sync_file");
if (!Files.exists(testFile)) {
    Files.createFile(testFile);
}
Files.readString(testFile);

检查失败时，Windows 平台会额外提示用户检查权限、杀毒软件拦截以及云存储的登录/同步状态（AppDirectoryPermissionsCheck.java），帮助快速定位是权限问题还是安全软件或云同步问题。

7.4 其他杂项修复

原文：Fix various small bugs

13.1.1 还包含一批未逐一列举的小问题修复。结合前几个版本的修复风格（如 13.1 完整版中修复的 Proxmox 检测、隧道强制关闭、VMware 目录扫描、Tabby 启动、Windows Terminal Preview/Canary 识别等，见 dist/changelog/13.1.1.md 第 38-47 行），可以推断这批小修复同样覆盖了连接管理、终端集成与界面细节等日常使用路径。

八、小结

XPipe 13.1.1 是一个典型的"体验打磨 + 可靠性加固"增量版本：

• 安装链路：MSI 安装器支持 ALLUSERS，贯通自更新、Chocolatey 与企业 Intune 部署，覆盖个人用户与组织级两种场景；
• 文件浏览器：菜单栏固定按钮让分屏对比更易用，启动固定本地标签与右键下载动作进一步降低操作门槛；
• 可靠性：git 同步认证、Proxmox 检测、目录权限启动检查三处修复，消除了三个高频失败场景。

对于希望在 Linux/macOS 上管理远程基础设施的开发者而言，13.1.1 的增量内容展示了 XPipe 持续打磨连接中枢体验的方向；如需查阅完整变更，可对照仓库中的 dist/changelog/13.1.1.md 与 dist/changelog/13.1_incremental.md。