wehub/kernalix7--winpodx
1
0
Fork 0
Code Issues Pull Requests Actions 10 Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
3efeee21f623b3a5942d9d6fa00ffbc66923947c
kernalix7--winpodx/README.md
T
wehub-resource-sync 3efeee21f6
CI / test (3.14, ubuntu-latest) (push) Waiting to run
Details
CI / test (3.9, ubuntu-latest) (push) Waiting to run
Details
CI / discover-apps-ps (push) Waiting to run
Details
CI / audit (push) Waiting to run
Details
CI / lint (push) Waiting to run
Details
CI / test (3.10, ubuntu-latest) (push) Waiting to run
Details
CI / test (3.11, ubuntu-latest) (push) Waiting to run
Details
CI / test (3.12, ubuntu-latest) (push) Waiting to run
Details
CI / test (3.13, ubuntu-latest) (push) Waiting to run
Details
CI / test (3.14, ubuntu-24.04-arm) (push) Waiting to run
Details
docs: make Chinese README the default
2026-07-13 10:23:05 +00:00

25 KiB
Raw Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

WinPodX

点击应用。Word 就打开了。就这么简单。

为每个 Windows 应用提供原生 Linux 窗口 — 真实图标、真实 WM_CLASS、
固定到任务栏。FreeRDP RemoteApp + dockur/windows。零配置。

# Latest stable release (default)
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash

# Latest main HEAD (development; may be unstable)
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash -s -- --main

# Uninstall (keeps Windows VM data; pass --purge to wipe everything)
curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/uninstall.sh | bash -s -- --confirm
WinPodX in action — Windows apps as native Linux windows on KDE

Windows 关于 / 任务管理器 / PowerShell 各自在独立的 Linux 窗口中运行，旁边是 WinPodX 仪表板（实时 Pod / 内存 / CPU 仪表、工作区磁贴）。

Beta Latest

license python tests CI stars downloads

适用于

openSUSE Fedora Fedora Atomic Desktops Debian Ubuntu RHEL family Arch NixOS AppImage

English  ·  한국어  ·  Install  ·  Usage  ·  Features  ·  Architecture  ·  Comparison

状态：Beta

WinPodX 正在积极开发中（v0.9.0）。v0.7.0 引入了裸机伪装（bare-metal disguise，#246，可选 / 默认关闭）：配合 pod.disguise_level balanced | max，Windows 客户机对虚拟机检测软件呈现为物理机（Nvidia GPU 直通「code 43」、启动门控 VM 检查、敌视 VM 的安装程序）—— 已在 al-khaser 0.82 上验证 —— 且默认客户机用户名改为 WPX-User。v0.7.1 是 UX + 集成版本：发现的 Windows 应用现可注册自动文件关联，从而出现在文件管理器的「打开方式」菜单中（#545，默认开启，仅添加 — 从不设为默认处理程序）；GUI 新增应用管理 — 重置为检测状态、自定义图标选择器、多选批量隐藏/移除，以及已删除应用的恢复列表（#530）；快速应用启动器（winpodx launch，#561）提供类似开始菜单的选择器，可绑定到桌面环境快捷键；winpodx gui 不再阻塞终端（#549）；winpodx doctor 在旧版 FreeRDP 导致 RemoteApp 窗口异常时发出警告（#546）；且 install.sh --main 现已在 Atomic Fedora 上生效（#548）。v0.7.2 是错误修复版本：修复 KDE/Plasma 上 Refresh Apps 导致的 GUI 崩溃（#567）以及托盘 Terminate Session / USB Devices 子菜单问题（#573），可发现中文/日文/韩文名称的应用（#553），在 pod stop 时保留容器（更新时不再重建），并在缺少 Windows 凭据时给出明确错误（#569）。v0.7.3 新增在 Windows 虚拟机本身上反向打开文件 — 不仅是共享的主目录，客户机 C: 通过 SMB 共享并用 kio-fuse 挂载，使主机应用打开真实的客户机文件且编辑可写回（#616，KDE）— 可选的空闲自动停止以释放虚拟机内存（#622），以及用于触摸屏 / 手写笔 / 触控笔直通的 +multitouch 标志（#623）；还修复了 winpodx app refresh 在慢速客户机上超时（#619）、仪表板内存 / 磁盘仪表卡在「n/a」（#634），并移除了导致安装不稳定的 USB 盘符自动映射器（#613、#638）。v0.7.4 允许你选择 Windows 虚拟机存放位置（install.sh --storage-dir，#646）并从本地 Windows ISO 安装以跳过下载（--win-iso，#647），24 GB 及以上主机默认 8 GB 虚拟机内存（#630）；另含修复 — 在已运行应用中打开第二个文档、在 Deepin 等精简 PATH 桌面上的打开方式、缺少 RDP 密码时的明确错误（#569）、GUI 日志按钮遵循 Docker 后端、.deb 拉取 podman-compose（#644），以及维护对话框尺寸（#550）。v0.8.0 使应用发现默认仅扫描开始菜单 — 仅显示 Windows 开始菜单中实际出现的应用，分组为嵌套文件夹子组，并提供 desktop.full_app_scan 可选以恢复旧的「扫描一切」行为（#581）；将 [pod] keyboard 传递给 FreeRDP 作为会话布局（#660）；在 compose-up 之前暂存 --win-iso，使 dockur 从中安装而非下载（#647）；自愈反向打开监听器；将捆绑的 rdprrap 升级至 0.3.0；并修复若干 GUI 崩溃 — Refresh Apps SIGSEGV、离线程显示缩放 SIGABRT、Debloat 任务对话框未自动关闭（#550），以及长 / CJK 应用名称导致的布局递归 SIGSEGV（#553）。v0.9.0 让 Windows 应用处理来自 Linux 的 URL scheme 链接 — 点击 mailto: 链接即可打开 Outlook；slack: / vnc: 等应用 scheme 路由到正确的 Windows 应用，在发现过程中自动收集并注册为 x-scheme-handlers（#421、#694）。同时加固信任边界：已发现的客户机应用不再能静默成为默认 http/https 处理程序（仅可选），会话窗口回收器不再误杀刚重新启动的应用，或在短暂扫描失败时批量终止会话（#680 后续）；另含 kio-fuse 在多架构/KF6 布局上的检测修复（#697）、反向打开监听器随托盘自动启动（#691）、挂起/恢复 D-Bus 订阅（#690），以及安装单行命令在缺失时自动安装 git（#705）。AppImage 为 Thin（约 110 MB）— 仅含 FreeRDP + Python + Qt + winpodx — 并使用主机的 podman / docker。0.6.0 定型的 CLI 界面保持不变：winpodx guest（客户机侧操作）、winpodx install（安装 / 磁盘操作）和 winpodx doctor（诊断，含 --json / --quick / --fix）；创建后链为单一的 winpodx provision。首次安装仍需约 5–10 分钟（Windows 虚拟机 ISO 下载 + Sysprep + OEM 应用）；winpodx pod wait-ready --logs 显示实时进度。如有问题请在 https://github.com/kernalix7/winpodx/issues 提交 issue。

无需全屏 RDP。 每个 Windows 应用都会成为独立的 Linux 窗口，并显示其真实图标——可固定到任务栏、可用 Alt+Tab 切换、可关联文件，双向互通。只有在你真正需要时，才切换到完整 Windows 桌面（winpodx app run desktop）。

WinPodX 在后台通过 dockur/windows)) 运行 Windows 容器，并通过 FreeRDP RemoteApp 将 Windows 应用呈现为原生 Linux 应用；访客机内的 bearer 认证 HTTP 代理负责处理主机→访客命令通道，且不会闪现 PowerShell 窗口。反向流程——在 Windows「打开方式…」菜单中显示 Linux 应用——由主机端监听器处理，该监听器消费访客机内按 slug 划分的 Rust shim 写入的 JSON 请求。近乎零外部 Python 依赖（Python 3.11+ 仅使用标准库；3.9/3.10 上有一个纯 Python tomli 回退方案）。

最低要求

安装前，请确认你的机器确实支持虚拟化。WinPodX 在基于 KVM 的容器中运行 Windows；若缺少以下三项，安装过程会顺利完成，但 Windows 永远无法启动。

要求 如何检查 修复方法
已在 BIOS / UEFI 中启用 Intel VT-x 或 AMD-V lscpu | grep -i virtualization 显示 VT-x 或 AMD-V 重启 → 进入固件设置 → 启用「Intel Virtualization Technology」/「SVM Mode」/「VT-x」。许多笔记本默认关闭。
kvm 内核模块已加载 lsmod | grep kvm 列出 kvm_intel 或 kvm_amd sudo modprobe kvm_intel（Intel）或 sudo modprobe kvm_amd（AMD）。BIOS 允许后，下次启动会自动加载。
你的用户属于 kvm 组 id -nG | tr ' ' '\n' | grep kvm 返回 kvm sudo usermod -aG kvm $USER，然后注销并重新登录。

硬件：配备虚拟化扩展的 x86_64 或 aarch64 CPU，8 GB 以上内存（建议 12 GB 以上），Windows 镜像约需 30 GB 可用磁盘空间。若包安装步骤后仍缺少 /dev/kvm，install.sh 会以相同诊断信息中止——大多数「安装正常但 Windows 无法启动」的问题报告都可追溯到上表中的某一行。

快速安装

一行命令（任何受支持的 Linux 发行版）：

curl -fsSL https://raw.githubusercontent.com/kernalix7/winpodx/main/install.sh | bash

或通过原生包管理器：

# openSUSE Tumbleweed / Leap / Slowroll
sudo zypper addrepo https://download.opensuse.org/repositories/home:/Kernalix7/openSUSE_Tumbleweed/home:Kernalix7.repo
sudo zypper install winpodx

# Fedora 42 / 43 / 44 (dnf5 — Fedora 41+)
sudo dnf config-manager addrepo --from-repofile=https://download.opensuse.org/repositories/home:/Kernalix7/Fedora_43/home:Kernalix7.repo
sudo dnf install winpodx

# Debian / Ubuntu — grab the matching .deb from the latest release
sudo apt install ./winpodx_<version>_all_debian13.deb

# AlmaLinux / Rocky / RHEL 9 / 10 — grab the matching .rpm
sudo dnf install ./winpodx-<version>-0.noarch.el10.rpm

# Arch
yay -S winpodx

# Nix
nix run github:kernalix7/winpodx

# AppImage (distro-agnostic, single file)
# Download winpodx-<version>-x86_64.AppImage from the latest GitHub release
chmod +x winpodx-*-x86_64.AppImage
./winpodx-*-x86_64.AppImage setup

通过包管理器 / AppImage 安装后： 请运行一次 winpodx setup 以生成 ~/.config/winpodx/winpodx.toml + compose.yaml。curl 一行命令会自动完成此步骤（并等待 Windows 首次启动约 5–10 分钟）；包安装仅分发二进制文件，因此 apt install / dnf install / yay -S / 首次启动 AppImage 不会突然触发长达 10 分钟的 Windows ISO 下载。完成设置后，只需启动应用（winpodx app run desktop），首次运行时会自动配置 pod。

精简版 AppImage（0.6.0）仅捆绑 Python + Qt + winpodx + FreeRDP——容器运行时位于主机上（推荐 podman ≥ 4，也支持 docker），因此 AppImage 不再与主机上已有的技术栈冲突（#357、#363）。0.6.0 之前的完整版 AppImage 捆绑了整个 podman 栈并覆盖了主机的配置。主机端仍需：通过包管理器安装容器运行时、/dev/kvm、加入 kvm 组，以及用于 rootless Podman 的 /etc/subuid / /etc/subgid。winpodx setup-host 通过单次 pkexec 提示修复 kvm / subuid 相关配置；winpodx doctor 会列出仍缺失的项。

离线 / 气隙构建、源码安装、版本锁定和卸载请参阅 docs/INSTALL.md。

首次设置

如果你使用了 curl install.sh 一行命令，设置已完成且 Windows 虚拟机正在启动——请跳转到启动。对于其他所有安装方式（包管理器、AppImage、源码、pip），请在首次启动应用前运行一次设置：

# Auto setup -- host-detected defaults, no prompts
winpodx setup

# Interactive wizard -- pick backend, cores, RAM, edition, language, timezone, debloat preset
winpodx setup --customize

设置会写入 ~/.config/winpodx/winpodx.toml + compose.yaml，注册 GUI 启动器，并确认主机已安装 FreeRDP + Podman / Docker + KVM。若缺少其中任何一项，输出末尾会给出针对各发行版的安装命令（例如 Debian / Ubuntu 上为 sudo apt install xfreerdp3 podman podman-compose，Fedora 上为 sudo dnf install ...）——运行该命令后重新执行 winpodx setup。

首次启动应用时会配置 pod、拉取 dockur 镜像、执行 Windows ISO 下载 + Sysprep + OEM 应用，并在约 5–10 分钟内达到可用的 RDP 会话。winpodx pod wait-ready --logs 会实时跟踪容器进度，便于你观察每个阶段：

winpodx app run desktop          # First launch -- ~5-10 min, subsequent launches near-instant
winpodx pod wait-ready --logs    # Optional: watch first-boot progress live

之后可随时运行 winpodx doctor，重新检查主机状态，若配置发生变化则显示下一步修复命令：

winpodx doctor                   # Read-only -- prints what would need fixing
winpodx guest apply-fixes        # Re-applies guest-side runtime fixes (RDP timeouts, NIC power-save, etc.)

启动

winpodx app run word              # Launch Word
winpodx app run word ~/doc.docx   # Open a file
winpodx app run desktop           # Full Windows desktop
winpodx launch                    # Quick app launcher (Start-menu style picker)

或直接点击应用菜单中的应用图标。winpodx launch 会打开可搜索的 Windows 应用选择器——可将其绑定到桌面环境的自定义快捷方式（KDE：系统设置 → 快捷方式 → 自定义；GNOME：设置 → 键盘 → 自定义快捷键），以设置全局热键。完整 CLI、Qt6 GUI、健康检查和配置请参阅 docs/USAGE.md。

主要特性

裸机伪装（VM 检测规避） — 0.7.0 新增 · 可选启用，默认关闭

  • 使拒绝在已检测到的虚拟机管理程序下运行的软件将 Windows 访客机识别为物理机——包括 Nvidia GPU 直通「code 43」、启动门禁 VM 检查、反虚拟机安装程序
  • pod.disguise_level balanced | max：balanced（平衡）隐藏 CPUID 虚拟机管理程序位 + KVM 签名，并镜像主机真实 SMBIOS/DMI；max（「Hardened」加固）额外添加本地构建的修补版 QEMU 镜像（winpodx disguise build-image），重写 ACPI / 磁盘 / 传感器 / USB 指纹，并移除 virtio + Red-Hat PCI 标识（保留 USB3）
  • 源自主机的字符串仅保存在本地镜像中（绝不会提交到 git）；序列号 / UUID / 资产标签均不会被读取
  • 已通过 al-khaser 0.82 验证 — 通过 winpodx config set pod.disguise_level max 或 GUI 设置中的「Bare-metal」选项启用
  • 详情 →

反向打开

  • Linux 应用默认出现在 Windows 访客机右键「打开方式…」菜单中
  • 在快捷菜单和较长的「选择其他应用」对话框中均显示正确的各应用图标
  • 选择后会将文件打开操作往返传递至主机 xdg-open
  • 根据 freedesktop 标准自动发现主机端 Linux 应用及其 MIME 关联
  • 通过 winpodx host-open CLI 或 GUI 设置面板管理
  • 详情 →

无缝应用窗口

  • RemoteApp (RAIL) 将每个 Windows 应用渲染为原生 Linux 窗口——无需完整桌面
  • 通过 WM_CLASS 匹配实现按应用显示任务栏图标（/wm-class:<stem> + StartupWMClass）
  • 双向文件关联：在文件管理器中双击 .docx → Word 打开
  • 多会话 RDP：捆绑的 rdprrap 自动启用最多 10 个独立会话
  • 多显示器 RAIL（0.6.0）：远程应用窗口拖到第二块显示器时仍保持可用输入——默认开启（cfg.rdp.multimon，默认 span）
  • 无人值守安装期间自动配置 RAIL 前置条件

零配置启动

  • 首次点击应用即自动配置一切：配置、容器、桌面项
  • 首次启动时自动发现会扫描正在运行的 Windows 来宾并注册每个已安装应用及其实际图标（Registry App Paths、开始菜单、UWP/MSIX、Chocolatey、Scoop）
  • 随时通过 winpodx app refresh 或 GUI 刷新按钮手动重新扫描
  • 多后端：Podman（默认）、Docker、手动 RDP（0.6.0 已移除 libvirt 后端——请继续使用 ≤0.5.x，或使用手动后端连接你自己的 libvirt 域）

外设与共享

  • 剪贴板：双向复制粘贴（文本 + 图片）——默认开启
  • 声音：RDP 音频流（/sound:sys:alsa）——默认开启
  • 打印机：Linux 打印机共享给 Windows——默认开启
  • 主目录：以 \\tsclient\home 共享
  • USB 驱动器：通过 FileSystemWatcher 自动映射为盘符（E:、F:、…）；会话开始后插入的驱动器子文件夹也可用；USB 桌面快捷方式（\\tsclient\media）始终可用，未挂载时打开空文件夹而非报错
  • 主机 USB / PCI 设备直通（0.6.0）：将真实主机设备传入 Windows 来宾——winpodx device list / attach <id> / detach <id>、GUI「Devices」标签页（双列主机↔来宾移动器）以及系统托盘 USB 切换器。USB 热插拔实时生效（cfg.pod.usb_live，默认开启）；PCI 在启动时添加，需要来宾重启以及 --force / 对话框确认

自动化与安全

  • 自动挂起/恢复：空闲时暂停容器，下次启动时恢复
  • 登录时 Pod 自动启动（v0.5.9，可选）：winpodx autostart on 安装托盘自启动项，使 pod 在登录时启动/恢复——默认关闭（autostart off|status，或 GUI 设置复选框）
  • UNRESPONSIVE → 恢复（v0.5.5）：在 RUNNING → UNRESPONSIVE 上检测卡死的 RDP 来宾，通过来宾内 TermService 循环自愈，无需 pod restart
  • 主机自适应 Windows-on-KVM 调优配置（v0.5.5）：+invtsc、platform_tick 等，按主机能力门控——tuning_profile = auto|safe|off
  • 密码自动轮换：20 位加密密码，7 天周期，支持原子回滚
  • 智能 DPI 缩放：从 GNOME、KDE、Sway、Hyprland、Cinnamon、xrdb 自动检测
  • Windows 精简：默认禁用遥测、广告、Cortana、搜索索引
  • FreeRDP extra_flags 白名单（正则验证）作为用户输入安全边界
  • 时间同步：主机休眠/唤醒后强制 Windows 时钟重新同步

运维与韧性

  • 多语言 UI（v0.5.9）：托盘 / GUI / CLI 完整翻译为 7 种语言（en / ko / zh / ja / de / fr / it），从 $LANG 自动检测——通过 winpodx language <code> 或 GUI 设置 → "WinPodX UI language" 覆盖
  • Windows 磁盘自动扩容（v0.5.9）：空闲时 C: 在超过阈值后自动增长，受主机可用空间限制——或按需扩容（winpodx install grow-disk [SIZE]、winpodx install disk-usage、GUI Tools → Grow Disk）
  • 来宾同步（v0.5.9）：主机升级后将更新的 agent / urlacl / rdprrap / 修复推送到正在运行的来宾——每次 pod 启动自动一次，或通过 winpodx guest sync [--force]
  • 离线 / 气隙安装（--source + --image-tar）
  • 一行命令卸载（除非 --purge，否则保留 Windows VM 数据）
  • 通过 winpodx doctor 进行健康检查（deps / pod / RDP / agent / disk / round-trip / password age；--json 用于机器可读输出，--quick 用于轻量子集，--fix 用于对常见发现进行幂等自动修复）
  • 重新设计的 Qt6 GUI（0.6.0）：左侧开始菜单风格导航侧栏 + 全新 Dashboard 主页，含实时 Pod / RAM / CPU 环形仪表、磁盘用量、自动恢复状态卡片、固定/最近工作区磁贴及反向打开切换；应用启动器现为「All apps」页面，与 Devices / Settings / Tools / Terminal / Info 并列——以及更轻量的系统托盘。自研 SVG 图标集、响应式重排，以及兼作命令栏的主搜索框
  • 偏向标准库的 Python（3.11+ 无 pip 依赖；3.9 / 3.10 上有一个 tomli 回退）

深入细节请参阅 docs/FEATURES.md，包括多会话 RDP 内部机制、应用配置文件架构以及反向打开架构。

文档

文档 内容
INSTALL.md 所有安装路径——一行命令、包管理器、AppImage、离线、Nix、源码
USAGE.md CLI 参考、Qt6 GUI 导览、健康检查、配置文件
FEATURES.md 反向打开、多会话 RDP、外设、应用配置文件、自动发现
ARCHITECTURE.md 工作原理（图示）、技术栈、源码树、数据流
COMPARISON.md WinPodX 对比 winapps / LinOffice / winboat，以及 WinPodX 对比 Wine
CHANGELOG.md 完整版本历史
CONTRIBUTING.md 开发环境搭建与工作流
SECURITY.md 安全披露流程

支持的发行版

发行版 包管理器 状态
openSUSE Tumbleweed / Leap 15.6 / Leap 16.0 / Slowroll zypper 已测试
Fedora 42 / 43 / 44 / Rawhide dnf 支持
Fedora Silverblue / Kinoite / Sericea / Bluefin / Bazzite（42 / 43 / 44） rpm-ostree（OBS，--apply-live） 支持
Debian 12 / 13，Ubuntu 24.04 / 25.04 / 25.10 / 26.04 apt 支持
AlmaLinux / Rocky / RHEL 9 / 10 dnf 支持
Arch / Manjaro pacman + yay -S winpodx 支持
NixOS（及任意发行版上的 Nix） nix flake 支持

每次标签推送（v*.*.*）会自动发布到所有渠道——维护者详情请参阅 packaging/。

测试

# From repo root (no install needed)
export PYTHONPATH="$PWD/src"
python3 -m pytest tests/    # 1800+ tests
ruff check src/ tests/      # Lint
ruff format --check src/ tests/

贡献

开发环境搭建、分支命名、提交规范及 CI 要求请参阅 CONTRIBUTING.md。

安全

安全问题请遵循 SECURITY.md 中的流程。

Star 历史

Star History Chart

支持

如果 WinPodX 让你的 Linux 桌面更好用一些：

GitHub Sponsors Ko-fi Fairy

GitHub Sponsors 支持定期或一次性赞助；Ko-fi 支持国际银行卡和 PayPal；fairy.hada.io 是韩国打赏平台。Bug 报告、PR 和给仓库点 Star 同样受欢迎，而且免费。

许可证

MIT — Kim DaeHyun (kernalix7@kodenet.io)

Reference in New Issue View Git Blame Copy Permalink