TorchPod

TorchPod是跨平台的容器化Linux桌面环境，它

• 以Docker image形式封装（遵循OCI规范的image），
• 支持multi-arch（目前是amd64、arm64），
• 以GNU/Linux KDE桌面系统呈现（neon），
• 托管在docker hub上，
• 可以在Linux、macOS、Windows操作系统上部署。

TorchPod的主要组件

以目前最新版本gemfield/torchpod:latest为例：

gemfield/torchpod	版本号
Ubuntu	24.04
KDE Plasma	6.3
KDE Framework	6.11
Qt	6.8
Python	3.12
openjdk	21
firefox	135
fcitx5	5.1
vs code	1.92
libreoffice	24.2
vlc	3.0

部署和运行TorchPod

TorchPod可以部署在如下平台上：

• Linux
• Windows
• macOS

都支持intel处理器和arm64处理器（包含Apple Silicon）。需要注意两点：

• 由于TorchPod是multi-arch的，自动拉取的镜像将会是和host上cpu arch一致的镜像版本。如果要拉取不同cpu arch的版本，则使用docker pull的--platform参数；
• 由于macOS（Apple Silicon）上有出色的Rosetta2指令集转译程序，它允许用户在Apple silicon 上运行包含x86_64指令集的程序，因此你可以在macOS（Apple Silicon）上使用TorchPod的amd64版本。结合上一条，可以这样拉取镜像：

docker pull --platform linux/amd64 gemfield/torchpod

1, Linux

部署后可以在本地、vnc客户端、rdp客户端、浏览器中访问图形界面。共有如下6种部署方法：

protocol	mode	部署方式	备注
x11	local	命令1	同时支持ssh
x11	rdp	命令2	同时支持ssh
x11	vnc	命令3	同时支持ssh、web
wayland	local	命令4	同时支持ssh
wayland	rdp	命令5	同时支持ssh，尚未开发完成
wayland	vnc	命令6	同时支持ssh、web，尚未开发完成

• 命令1: 启动图形化容器（X11），使用本地宿主机的X11服务端（注意：本地系统需要运行X服务）

Xephyr :2 -screen 1920x1080 -resizeable #如果本地没有X服务，启动Xephyr新建一个
docker run -it --rm -eTORCHPOD_MODE=local -ePROTOCOL=x11 -e DISPLAY=:2 -v /tmp/.X11-unix:/tmp/.X11-unix gemfield/torchpod

或者

#在vt5（一般来说就是ctrl+Alt+F5对应的terminal）上启动X服务
sudo X :5 -terminate vt5
#切换回来
docker run -it --device=/dev/dri --rm -eTORCHPOD_MODE=local -ePROTOCOL=x11 -e DISPLAY=:5 -v /tmp/.X11-unix:/tmp/.X11-unix gemfield/torchpod

• 命令2：启动图形化容器（X11），通过RDP来访问

docker run -it --rm -eTORCHPOD_MODE=RDP -ePROTOCOL=x11 -p 3389:3389 gemfield/torchpod

• 命令3：启动图形化容器（X11），通过VNC来访问，ssh端口可选

docker run -it --rm -eTORCHPOD_MODE=VNC -ePROTOCOL=x11 -p 7030:7030 -p 5900:5900 -p 20022:22 gemfield/torchpod

• 命令4：启动图形化容器（wayland），使用本地宿主机的wayland compositor（或者本地的wayland服务端）

docker run -it --rm --cap-add SYS_NICE --device=/dev/dri -eTORCHPOD_MODE=local -ePROTOCOL=wayland -v /tmp/.X11-unix:/tmp/.X11-unix -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/run/gemfield/wayland-0 -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY.lock:/run/gemfield/wayland-0.lock gemfield/torchpod

当然，你也可以在本地启动一个新的wayland compositor（e.g. Kwin），然后TorchPod作为客户端连接这个新的wayland compositor：

export $(dbus-launch)
kwin_wayland --xwayland --socket /tmp/torchpod
#指定该unix socket来连接上述的新的wayland compositor
docker run -it --rm --cap-add SYS_NICE --device=/dev/dri -eTORCHPOD_MODE=RDP -ePROTOCOL=wayland -v /tmp/.X11-unix:/tmp/.X11-unix -v /tmp/torchpod:/run/gemfield/wayland-0 -v /tmp/torchpod.lock:/run/gemfield/wayland-0.lock -p 3389:3389 gemfield/torchpod

• 命令5：启动图形化容器（wayland），通过RDP来访问（备注：仍需要你手动在“系统设置”中打开“远程桌面”，并设置用户名密码，并手动启动/usr/bin/krdpserver，并在连接时点击确认按钮等）

docker run -it --rm --cap-add SYS_NICE --device=/dev/dri -eTORCHPOD_MODE=RDP -ePROTOCOL=wayland -v /tmp/.X11-unix:/tmp/.X11-unix -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/run/gemfield/wayland-0 -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY.lock:/run/gemfield/wayland-0.lock  -p 3389:3389 gemfield/torchpod

• 命令6：启动图形化容器（wayland），通过VNC来访问，ssh端口可选（备注：仍需要你手动启动/usr/bin/krfb，包括设置密码，并在连接时点击确认按钮等）

docker run -it --rm --cap-add SYS_NICE --device=/dev/dri -eTORCHPOD_MODE=VNC -ePROTOCOL=wayland -v /tmp/.X11-unix:/tmp/.X11-unix -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/run/gemfield/wayland-0 -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY.lock:/run/gemfield/wayland-0.lock -p 7030:7030 -p 5900:5900 -p 20022:22 gemfield/torchpod

参数中的端口号用途：

端口号	协议	用途
3389	rdp	通过rdp客户端，Windows远程桌面连接客户端
5900	vnc	通过vnc客户端
7030	http	通过浏览器来访问图形界面
20022	ssh	用于ssh客户端、sftp客户端、KDE Dolphin、vscode remote ssh等

注意，上表中的ssh端口号用于vscode remote ssh功能时，首先在vscode上新建ssh target，然后在"Enter SSH Connection Command"输入框中输入：

#密码为:gemfield（$TORCHPOD_PASSWORD)
ssh -p 20022 gemfield@<your_host_running_torchpod>

此外，如果要使用k8s集群部署方式（需要k8s集群运维经验，适合团队的协作管理），请访问基于k8s部署torchpod以获得更多部署信息。

2, macOS

下载并安装最新版docker desktop，以及TigerVNC Viewer客户端。启动docker desktop后：

• 1，在docker desktop的设置——General中，配置虚拟机选项：

注意：如果在Apple Silicon上使用amd64处理器架构的TorchPod，则必须按照上图配置，因为docker desktop在Apple Silicon上需要借助Rosetta2来运行TorchPod的x86_64/amd64版本。

• 2，在docker desktop的设置-Resources中，可以配置CPU、内存、磁盘资源。如果需要设置代理，可以参考下图：

除了HTTP/HTTPS代理外，也支持SOCKS5代理：

• 3，下载gemfield/torchpod镜像（在中国大陆境内可能需要按照上述方式设置代理），点击pull按钮：

以上是GUI操作方式，对应的还有命令行方式。

当用命令行的方式时，你可以在docker desktop的Terminal中使用docker pull命令：

• 4，启动容器，在docker desktop的Images界面，点击启动按钮，进行如下配置：

当然你也可以在docker desktop的Terminal中使用docker run命令。

注意1：Volumes区域自定义。

注意2：你也可以将TORCHPOD_MODE配置为RDP，以使用RDP远程桌面协议。这种情况下，上述的端口号需要启用3389而非5900。

注意3：macOS默认的文件系统不支持区分文件名大小写，如果要将宿主机的目录挂载到TorchPod容器中，务必注意这个问题！你也可以在macOS宿主机上新建“宗卷”，选择区分文件名大小写的文件系统格式。

• 5，启动TigerVNC Viewer客户端：

输入VNC服务器地址：localhost；点击“连接”即可。你也可以在连接前点击“选项”按钮，进行一些参数配置。

3, Windows

下载并安装最新版docker desktop。启动docker desktop后：

• 1，在docker desktop的设置——General中，配置虚拟机选项：WSL2。该项为默认配置，也就是在Windows系统上默认是用WSL2来运行TorchPod镜像（Linux镜像）；
• 2，配置代理，参考上述macOS中的示意图；
• 3，下载gemfield/torchpod镜像（在中国大陆境内可能需要按照上述方式设置代理），参考上述macOS中的示意图；
• 4，启动容器，在docker desktop的Images界面，点击启动按钮，进行如下配置：

启动后docker desktop的界面可能会出现“等待转圈”的现象，这可能是bug所致。这个时候可以在docker desktop的Terminal中用命令来查看容器的启动情况：

当然你也可以在docker desktop的Terminal中使用docker run命令。

注意1：Volumes区域自定义。

注意2：你也可以将TORCHPOD_MODE配置为VNC，以使用VNC远程桌面协议。这种情况下，上述的端口号需要启用5900而非3389。

注意3：Windows默认的文件系统不支持区分文件名大小写，如果要将宿主机的目录挂载到TorchPod容器中，务必注意这个问题！你也可以在宿主机上新建区分文件名大小写的文件系统格式。

• 5，打开Windows自带的远程桌面连接，输入localhost、用户名（$TORCHPOD_USER)、密码($TORCHPOD_PASSWORD)来连接。

登录

上面已经演示过了一些TorchPod的登录方式。总共有5种方式：

• 1，docker命令：docker exec -it
• 2，vnc客户端，推荐TigerVNC Viewer客户端，其可以在运行时动态调整窗口大小;
• 3，rdp客户端，比如KRDC、remmina、Windows远程桌面等;
• 4，浏览器：http://your_host:7030
• 5，docker desktop的GUI界面上登陆：

账户信息

TorchPod默认提供了如下账户：

• 用户:gemfield
• 密码:gemfield
• HOME:/home/gemfield

如果要改变该默认行为，可以在docker命令行上（或者k8s yaml中）通过-e参数注入以下环境变量：

• TORCHPOD_USER=<my_name>
• TORCHPOD_PASSWORD=<my_password>
• HOME=<my_home_path>

为了安全，用户在初始登录TorchPod后，最好使用passwd命令来修改账户密码。

中文输入法

要启动中文输入法，非常简单，只需要点击桌面左下角的Applications——>系统——>Fcitx 5即可启动，然后就可以使用中文输入法了（通过桌面右下角输入法图标右键切换，或者ctrl+space组合键来切换）。

基于TorchPod的生态

目前有如下项目基于TorchPod：

• torchpod-ai: 基于TorchPod的PyTorch、ollama开发运行环境；
• ：基于TorchPod的OpenHarmony开发和编译环境。

已知问题

• macOS（Apple Silicon）上使用amd64处理器架构的TorchPod时，vscode无法正常运行，应该是vscode的chromium被Rosetta2翻译为arm指令时有问题；
• PROTOCOL设置为wayland时，vnc和rdp的服务端都需要手工运行多步才能开启，因为截至目前这些服务还没有命令行启动方式。