IPFS Desktop

IPFS Desktop 让您在便捷的桌面应用中尽享 IPFS 的全部功能：完整的 IPFS 节点，外加实用的操作系统菜单栏/任务栏快捷方式，以及集文件管理器、节点地图和内容浏览器于一体的全能工具。

借助 IPFS Desktop，您无需接触终端即可轻松了解 IPFS；如果您已是资深用户，可将强大的菜单栏/任务栏快捷方式与命令行配合使用，让您的 IPFS 工作流程更加高效。

文件屏幕	探索屏幕	节点屏幕	设置屏幕	菜单栏/任务栏

快速安装快捷方式

若有疑问，建议选择具有内置自动更新机制的软件包格式：

• Windows： ipfs-desktop-setup-0.50.0-win-x64.exe
• Mac： ipfs-desktop-0.50.0-mac.dmg
• Linux： ipfs-desktop-0.50.0-linux-x86_64.AppImage
  • 如果您希望自行管理更新，请参见下方的其他软件包格式。

目录

• 功能特性
  • 系统启动时自动启动节点，并通过操作系统进行控制
  • 快速将文件、文件夹和截图导入 IPFS
  • 轻松管理节点内容
  • 可视化全球 IPFS 节点连接情况
  • 探索 IPFS 文件的“默克尔森林”
  • 享受系统级的 IPFS 文件和链接支持
  • 在使用过程中学习 IPFS 命令
• 安装
  • Windows 系统
  • Mac 系统
  • Linux/FreeBSD 系统
  • 从源代码安装
• 贡献
  • 翻译
  • 开发者说明
• 常见问题与故障排除
  • 为什么在 Linux 系统上看不到系统托盘菜单？
  • 为什么无法在 Debian 11 系统下安装 IPFS Desktop？
  • 为什么无法在 Debian 10 系统下启动 IPFS Desktop？
  • 为什么 AppImage 运行时出现 FUSE 错误？
  • 检测到 GTK 2/3 符号。不支持在同一进程中同时使用 GTK 2/3 和 GTK 4
  • 配置文件和日志文件存放在哪里？
    • IPFS Desktop 配置
    • Kubo 仓库和配置
      • IPFS Desktop 如何选择 IPFS 仓库位置？
  • 支持哪些操作系统？
  • IPFS Desktop 使用哪个版本的 IPFS？
  • IPFS Desktop 启动时使用哪些标志？
  • 出现 repo.lock 错误，如何解决？
  • 出现网络错误（例如 Error fetching），该怎么办？
  • 错误：初始化守护进程中...
    • 错误：程序版本 (N) 低于仓库版本 (N+x)。
    • 发现过时的 fs-repo，需要运行迁移。- 错误获取：上下文超时
  • 守护进程启动失败且未产生任何输出，该怎么办？
  • 我需要更多帮助！
• 许可证

功能特性

IPFS Desktop 将完整的 IPFS 节点（运行 kubo）和 IPFS Web UI 整合到一个便捷的桌面应用中，并在操作系统的菜单栏/系统托盘中添加了一个菜单，方便您访问各种常见的 IPFS 任务。

如果您的计算机上已经有 IPFS 节点，IPFS Desktop 将充当该节点的控制面板和文件浏览器。如果没有，它会为您安装一个。无论哪种情况，IPFS Desktop 都会自动检查更新。

系统启动时启动节点并通过操作系统控制

IPFS Desktop 让您可以直接从操作系统菜单栏/系统托盘中的 IPFS 图标菜单停止或重启节点。对于 Mac 和 Windows 用户，IPFS Desktop 还可以设置为在系统启动时自动运行，确保您的节点在计算机开机时就处于运行状态。

快速将文件、文件夹和截图导入 IPFS

通过多种便捷方式将文件和文件夹导入您的 IPFS 节点：

• 将项目拖放到 IPFS Desktop 的“文件”屏幕上
• 点击“文件”屏幕上的“导入”按钮，从您的计算机或 IPFS 内容标识符（CID） 添加项目
• （Windows）右键单击文件/文件夹图标，从弹出菜单中选择添加到 IPFS
• （Mac）将文件/文件夹拖放到菜单栏中的 IPFS 图标上

此外，您可以使用 IPFS 图标菜单下的“截取屏幕截图”命令来拍摄截图，将其导入节点，并一键将可分享链接复制到剪贴板。

轻松管理节点内容

IPFS Desktop 的“文件”屏幕为您提供了一个简单、熟悉的界面，用于管理节点内容：

• 轻松重命名、移动或删除文件和文件夹
• 直接在 IPFS Desktop 中预览多种常见文件格式
• 将文件/文件夹的 IPFS 内容标识符（CID） 或可分享链接复制到剪贴板
• 将文件"固定"到您的 IPFS 节点或第三方固定服务

可视化全球 IPFS 节点连接

访问“节点”页面，查看您当前连接的节点、节点所在位置、使用的连接方式等详细信息。

探索 IPFS 文件的“默克尔森林”

通过“探索”页面浏览示例数据集或您自己的文件，直观了解 IPFS 上存储的内容如何被分解为基于内容寻址的片段。

享受全系统 IPFS 文件与链接支持

IPFS Desktop 使大多数操作系统（Mac、Windows 及部分 Linux 发行版）能够支持 ipfs:// 和 ipns:// 等协议。这意味着当您电脑上的应用尝试打开以这些协议开头的链接时（例如，浏览器遇到 ipns://en.wikipedia-on-ipfs.org 链接），系统会自动通过 IPFS Desktop 打开。

为获得更佳的 ipfs:// 和 ipns:// 地址使用体验，我们建议安装 IPFS Companion，为您常用的浏览器添加支持！

边用边学 IPFS 命令

如果您想学习如何通过命令行使用 IPFS，IPFS Desktop 的 CLI 教程模式可以在您操作时展示常用命令。只需在“设置”页面勾选“CLI 教程模式”即可启用该功能。

安装

发行说明和旧版本可在 发布页面 查看。

未找到您常用的包管理器？访问我们的 包管理器支持页面，帮助我们添加支持！

Windows

• 安装程序： ipfs-desktop-setup-0.50.0-win-x64.exe
  
• Chocolatey（社区维护）：choco install ipfs-desktop
• Scoop（社区维护）：scoop bucket add extras; scoop install extras/ipfs-desktop
• WinGet（社区维护）：winget install IPFS.IPFS-Desktop
• ℹ️ 现有用户更新检查：

Mac

• 安装程序： ipfs-desktop-0.50.0-mac.dmg
  
  
• Homebrew（社区维护）：brew install --cask ipfs
• ℹ️ 现有用户的更新检查：

Linux/FreeBSD

• AppImage： ipfs-desktop-0.50.0-linux-x86_64.AppImage
  
• 压缩包（tar.gz）（用于为发行版构建软件包）：ipfs-desktop-0.50.0-linux-x64.tar.xz
  
• Debian（DEB）（实验性）：ipfs-desktop-0.50.0-linux-amd64.deb
  
• Red Hat（RPM）（实验性）：ipfs-desktop-0.50.0-linux-x86_64.rpm
  
• FreeBSD（实验性）：ipfs-desktop-0.50.0-linux-x64.freebsd（需要启用Linux二进制兼容性）
  
• Snapcraft 支持已弃用且不推荐使用，原因是存在限制问题，请改用 .AppImage
• ℹ️ 现有用户的更新检查：

还存在其他第三方软件包，但内置的自动更新机制已被禁用。 更新周期由各自的社区维护：

从源代码安装

若要从源代码安装并运行 IPFS Desktop，你还需要：

• Node.js – 选择当前的 LTS 版本
• node-gyp 所需的任何特定平台依赖项

然后，按照以下步骤克隆源代码、安装依赖项并运行应用程序。

git clone https://github.com/ipfs/ipfs-desktop.git
cd ipfs-desktop
npm ci
npm run build
npm start

构建说明： npm ci 将使用 ipfs-or-gateway npm 包从 IPFS 下载 webui 代码，以便在 electron 中运行。有关详细信息，请参阅 构建流程 和 webui 代码。

本地 webui 开发： 若要使用 ipfs-webui 的本地构建进行测试，请设置 IPFS_WEBUI_PATH 以指向 webui 构建输出目录。这会将本地构建复制到 assets/webui/，而不是通过 CID 下载发行版：

IPFS_WEBUI_PATH=../ipfs-webui/build npm run build
npm start

IPFS Desktop 本身是一个简单的容器，它确保 Kubo 和 IPFS Webui 能够以独立方式协同工作，并能访问其他特定于操作系统的功能，如托盘和上下文集成。

有多种方式可以访问 IPFS Webui：

• https://webui.ipfs.io/#/welcome
• http://127.0.0.1:5001/webui（随 Kubo 一同提供）
• IPFS Desktop 本身

所有这些 IPFS Webui 实例都是相同的，只是分发方式略有不同。您看到正在下载的文件是 IPFS Webui 的特定发行版，例如 v4.1.1 版本的内容标识符 (CID) 为 bafybeiamycmd52xvg6k3nzr6z3n33de6a2teyhquhj4kspdtnvetnkrfim，您可以在 IPFS Webui 发行页面 上验证此 CID。

贡献

我们欢迎所有对 IPFS Desktop 的贡献！入门的最佳方式是查看当前的 未解决问题（或者专门查看 标记为“help wanted”的问题），并找到您感兴趣的内容。所有问题均使用 IPFS 项目通用的 标准标签分类法 进行分类，因此您也可以按主题筛选（例如，UX 相关问题）。

无论您以何种方式贡献，请确保您已阅读并遵循 IPFS 贡献指南 和 IPFS 社区行为准则。

翻译

贡献您所在语言的翻译非常有价值！我们使用 Transifex 来管理国际化，这意味着您无需修改任何代码即可添加翻译 — 只需注册一个 Transifex 账户。

由于 IPFS Desktop 应用包含来自 IPFS Web UI 和 IPLD Explorer Components 的文本，因此您需要加入所有三个 Transifex 项目才能查看所有文本：

• https://explore.transifex.com/ipfs/ipfs-desktop/
• https://explore.transifex.com/ipfs/ipfs-webui/
• https://explore.transifex.com/ipfs/ipld-explorer/

开发者注意事项：我们将英语作为基准语言。这意味着如果您添加任何新文本，请在 ./assets/locales/en.json 中进行添加，这些添加的内容将自动同步到 Transifex 供其他语言翻译。

开发者说明

有关 IPFS Desktop 开发的更多详细信息，包括发布清单，请参阅完整的 开发者说明。

常见问题与故障排除

为什么我在 Linux 上看不到系统托盘菜单？

IPFS Desktop 是使用 Electron 构建的，遗憾的是，系统托盘支持不佳一直是 Electron 应用的长期问题。

您可以尝试根据 Electron v9.3.0 文档 进行故障排除：

• 在 Linux 上，如果支持应用指示器（app indicator），则会使用它；否则将使用 GtkStatusIcon
• 在仅支持应用指示器的 Linux 发行版上，您必须安装 libappindicator1 才能使托盘图标正常工作

如果您发现在 IPFS Desktop v0.13 中旧的系统托盘又回来了，这是因为 Electron 团队 移除了对 StatusNotifier 的支持，并恢复了 Linux 上名为 XEmbed 的旧托盘接口。

为何无法在 Debian 11 下安装 IPFS Desktop？

您可以安装。libappindicator3-1 已不再存在于 Debian 11 及更高版本中，electron-builder 已将其从 Depends 移至 Recommends，因此 apt 会在没有该库的情况下安装并配置软件包。

该库仍用于绘制系统托盘图标。如果安装后图标缺失，您可以自行安装该库，或改用 .AppImage 版本。

为何无法在 Debian 10 下启动 IPFS Desktop？

部分 Linux 用户在尝试启动 IPFS Desktop 时可能会遇到以下错误之一：

双击应用图标启动时：

已找到 SUID 沙箱辅助二进制文件，但配置不正确。 为安全起见，我将终止启动，而非在无沙箱模式下运行。您需要确保 chrome-sandbox 归 root 所有，且权限模式为 4755。

从终端启动时：

$ ipfs-desktop
$Trace/breakpoint trap

这是 Electron/Chrome 与某些强化内核存在的已知问题。更多详细信息可参见此处，不过修复方法是通过终端启动 IPFS Desktop 并附加以下参数：

$ ipfs-desktop --no-sandbox

在 Ubuntu 24.04 及更高版本上也会出现同样的错误，这些版本通过 AppArmor 限制了非特权用户命名空间。此问题在使用 .AppImage 时最为明显，因为其只读挂载无法将 chrome-sandbox 呈现为 root 所有且权限为 4755。若要保留沙箱功能，请改用 .deb 版本：其安装后脚本会将 chrome-sandbox 权限设置为与您的内核匹配，并安装 AppArmor 配置文件。

为什么 AppImage 会出现 FUSE 错误？

如果您在运行 AppImage 时看到以下错误：

dlopen(): error loading libfuse.so.2
AppImages require FUSE to run.

这是因为现代 Linux 发行版附带的是 FUSE 3，而 AppImages 当前需要 FUSE 2（libfuse2）。这两个版本可以安全共存。

按发行版修复：

发行版	命令
Ubuntu 24.04+, Debian 13+	sudo apt install libfuse2t64
Ubuntu 22.04/23.x, Debian 12	sudo apt install libfuse2
Fedora	sudo dnf install fuse-libs
Arch	sudo pacman -S fuse2

替代方案： 使用提取模式在不借助 FUSE 的情况下运行：

./ipfs-desktop-*.AppImage --appimage-extract-and-run

注意： 这是 electron-builder 所使用的 AppImage 运行时的已知限制。未来版本可能会包含一个静态运行时，从而移除这一依赖。有关上游进展，请参见 AppImage/AppImageKit#1120。

更多详情，请参见 AppImage FUSE 文档。

检测到 GTK 2/3 符号。不支持在同一进程中同时使用 GTK 2/3 和 GTK 4

请参见 ipfs-desktop#2952。

我的配置文件和日志文件在哪里？

IPFS Desktop 配置

您可以通过 IPFS 图标菜单打开桌面应用程序和日志文件，方法是从“高级”子菜单中选择“打开日志目录”或“打开配置文件”。

或者，您也可以在您的操作系统中按以下路径查找：

• Mac： ~/Library/Application Support/IPFS Desktop/
• Windows： %APPDATA%\IPFS Desktop\
• Linux： ~/.config/IPFS Desktop/

Kubo 仓库和配置

要从 IPFS 图标菜单打开您的 Kubo 仓库目录，请从“高级”子菜单中选择“打开仓库目录”。

或者，在您的操作系统中按以下路径查找（假设未设置自定义 $IPFS_PATH）：

• Mac： $HOME/.ipfs/
• Windows： %USERPROFILE%\.ipfs\（C:\Users\Username\.ipfs\）
• Linux： $HOME/.ipfs/

配置文件名为 .ipfs/config

IPFS Desktop 如何选择 IPFS 仓库位置？

IPFS Desktop 使用 ipfsd-ctl 来定位 Kubo 仓库。

1. 首先，它会检查 IPFS_PATH 环境变量。
2. 如果未设置该变量，则回退到 $HOME/.ipfs（Windows 上为 %USERPROFILE%/.ipfs/）。首次运行成功后，仓库位置信息会保存在配置文件中，该文件将成为事实来源。

要从 IPFS 图标菜单打开您的 Kubo 仓库目录，请从“高级”子菜单中选择“打开仓库目录”。

支持哪些操作系统？

操作系统	最低版本
macOS	12 Monterey，支持 Intel 和 Apple Silicon
Windows	10，x64 和 arm64
Linux	发行商仍支持的任何版本，x64

此最低版本要求由 IPFS Desktop 所基于的 Electron 以及 Kubo 所使用的 Go 语言共同设定。这两者均未为旧版本系统提供二进制文件，因此即使安装程序本身成功，IPFS Desktop 也无法在这些系统上启动。Windows 7 是用户最常遇到的不支持系统，详情可参见 #2823。

旧版本的 IPFS Desktop 构建仍可在 发布页面 获取，但它们不再接收修复更新。如果您的操作系统版本较旧，IPFS 论坛 是寻求帮助的最佳场所。

IPFS Desktop 使用哪个版本的 IPFS？

IPFS Desktop 包含其自身嵌入的 Kubo 二进制文件（kubo 版本在 package.json 中定义）；这是通过 IPFS Desktop 使用质量 assurance 的最新版 Kubo。

您可以通过 IPFS 徽标菜单中的“关于”子菜单查看当前运行的 IPFS 版本。

IPFS Desktop 启动时使用哪些标志？

默认情况下，IPFS Desktop 使用标志 --migrate=true --enable-gc=true 启动 IPFS 守护进程。

您可以通过“高级”子菜单中的“打开配置文件”选项，在 IPFS Desktop 配置文件中修改此设置。

我遇到了 repo.lock 错误，如何解决？

通常，此错误表示先前的进程未能从仓库目录中移除仓库锁（指示文件正在被使用）。正常情况下，系统会自动处理此问题，但有时可能无法正常处理。如果遇到此错误，在关闭所有正在运行的 IPFS 守护进程或应用程序后，通常可以安全地删除此文件。具体步骤如下：

1. 停止所有 ipfs 进程；
2. 手动删除位于 仓库 内的锁文件；
3. 尝试重新启动 ipfs desktop（或其他出现 repo.lock 错误的进程）。

我遇到了网络错误（例如 Error fetching）。该怎么办？

升级时，IPFS 可能需要执行迁移操作，为此我们需要稳定的网络连接来下载迁移所需的信息。有时，互联网连接可能会中断，或者被防火墙、杀毒软件拦截，这时就会出现网络错误。提交问题之前，请先尝试以下操作：

1. 检查是否已连接到互联网；
2. 确保防火墙或杀毒软件没有拦截相关请求，例如 P2P 流量；
3. 重启 IPFS Desktop 后重试。

错误：Initializing daemon...

当 Kubo 守护进程启动失败时，ipfsd-ctl 会弹出这些错误。以下是可能遇到此错误的几种情况。

错误：Your programs version (N) is lower than your repos (N+x)。

这表示你尝试运行的 ipfs-desktop 或 Kubo 版本比之前在你机器上运行过的版本旧。每个 Kubo 版本（已包含在 ipfs-desktop 中）都与特定的 IPFS 仓库版本相关联，具体可查看 https://github.com/ipfs/fs-repo-migrations#when-should-i-migrate。

理想的解决方法是确保你运行的是最新版本的 ipfs-desktop，因为向上迁移会自动进行。

可能你的 PATH 中存在与 IPFS Desktop 捆绑版本不同的 kubo 版本，这种情况下，你还应将其更新为最新的 kubo 二进制文件。

不过，如果你是高级用户，确实需要运行引发此错误的旧版本，则需要手动反向运行迁移。你可以按照官方说明此处操作，但需添加额外参数：fs-repo-migrations -revert-ok -to N。有关更多信息，请参阅 fs-repo-migrations --help。

Found outdated fs-repo, migrations need to be run. - Error fetching: context deadline exceeded

当下载 fs-repo-migrations 所需的迁移文件出现问题时，会发生这种情况。错误通常看起来像这样：

Error: Initializing daemon...
Kubo version: 0.22.0
Repo version: 14
System version: amd64/darwin
Golang version: go1.19.12
Found outdated fs-repo, migrations need to be run.
Looking for suitable migration binaries.
Need 1 migrations, downloading.
Downloading migration: fs-repo-13-to-14...
Fetching with HTTP: "https://ipfs.io/ipfs/QmYerugGRCZWA8yQMKDsd9daEVXUR3C5nuw3VXuX1mggHa/fs-repo-13-to-14/versions"
Fetching with HTTP: "https://ipfs.io/ipfs/QmYerugGRCZWA8yQMKDsd9daEVXUR3C5nuw3VXuX1mggHa/fs-repo-13-to-14/versions"
Fetching with HTTP: "https://ipfs.io/ipfs/QmYerugGRCZWA8yQMKDsd9daEVXUR3C5nuw3VXuX1mggHa/fs-repo-13-to-14/versions"
Error fetching: exceeded number of retries. last error was http.DefaultClient.Do error: Get "https://ipfs.io/ipfs/QmYerugGRCZWA8yQMKDsd9daEVXUR3C5nuw3VXuX1mggHa/fs-repo-13-to-14/versions": dial tcp 199.16.156.40:443: i/o timeout
Fetching with IPFS: "fs-repo-13-to-14/versions"
Error fetching: context deadline exceeded
could not get latest version of migration fs-repo-13-to-14: 2 errors occurred:
	* exceeded number of retries. last error was http.DefaultClient.Do error: Get "https://ipfs.io/ipfs/QmYerugGRCZWA8yQMKDsd9daEVXUR3C5nuw3VXuX1mggHa/fs-repo-13-to-14/versions": dial tcp 199.16.156.40:443: i/o timeout
	*

您可以更新 Kubo 配置以尝试不同的迁移文件来源。

通过 IPFS-Desktop

1. 前往“设置”标签页
2. 在配置中找到“Migrations”，并将 DownloadSources 数组更新为 ["IPFS", "https://trustless-gateway.link", "HTTP"]

通过终端

使用此方法时，您需要确保命令行中可以使用 ipfs 二进制文件：

ipfs config --json Migration.DownloadSources '["IPFS", "https://trustless-gateway.link", "HTTP"]'

手动在编辑器中修改（不推荐）

你也可以手动编辑配置文件（~/.ipfs/config 或 C:\Users\Username\.ipfs\config）。请确保完成编辑后 JSON 文件格式有效。

守护进程启动失败且未产生输出，该怎么办？

此消息表示 IPFS Desktop 已启动 Kubo 守护进程，但该守护进程立即退出，且在退出过程中未输出任何内容。错误原因未在消息中体现，因此仅引用此消息的问题无法得到处理。

真正的错误信息位于 error.log 中。打开 IPFS 图标菜单，从“高级”子菜单中选择“打开日志目录”，然后查看该文件的末尾内容。

常见原因包括：

• 防病毒软件或终端安全软件删除、隔离或阻止了捆绑的 ipfs 二进制文件
• Kubo 仓库 所在的磁盘已满、只读或已断开连接
• 另一个 ipfs 进程已在使用相同的仓库

如果日志指向上述涵盖的某个错误，请按照相应部分进行操作。否则，请提交 issue 并将 error.log 的最后 50 行粘贴到其中。

我需要更多帮助！

如果在使用 IPFS Desktop 时需要帮助，获取答案最快的方式是在官方 IPFS 论坛上发帖提问。

如果你认为发现了 IPFS Desktop 本身的错误或其他问题，请提交 issue。

许可证

MIT