Linux 版 BitComet 安装指南

Linux 版 BitComet 提供 AppImage、Flatpak 及 deb 安装包，也提供 Docker 镜像。

AppImage 格式

AppImage 打包文件无需管理员权限安装即可直接运行。
关于 AppImage 格式的详细信息可以参阅 https://www.appimage.org/

第1步 检查 Linux 发行版版本（可选）

Linux 发行版	支持的版本
Ubuntu	18.04
Debian	12.1
Fedora	38
openSUSE	Leap 15.5 / Tumbleweed
CentOS	Stream 9
深度 Deepin	23
优麒麟 Ubuntu Kylin	22.04
开放麒麟 openKylin	1.0.1
其它	GLIBCXX_3.4.22 或更高

在 Linux 发行版中运行 BitComet 的唯一要求是 libstdc++.so 中的 GLIBCXX 版本。
如果 Linux 发行版中的 GLIBCXX 版本低于 GLIBCXX_3.4.22，BitComet将无法运行。

如果您的 Linux 发行版未在表中列出，可以通过以下命令找到 Linux 发行版中已安装的 GLIBCXX 版本：

# 查找 libstdc++.so.6 文件
find /usr/ -name libstdc++.so.6

# 获取 GLIBCXX 版本，通常可使用
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX

# 或者
strings /usr/lib64/libstdc++.so.6 | grep GLIBCXX

第2步 下载 BitComet

Linux 版 BitComet 的 AppImage 文件可以从官网页面下载。

第3步 设置 AppImage 文件可执行权限后，直接运行

使用图形界面

打开您的文件管理器，定位到 AppImage 文件所在目录
右键单击 AppImage 文件，选择“属性”
切换到权限页面，点击“允许将文件作为程序运行”复选框
关闭对话框
双击 AppImage 文件，运行程序

使用命令行终端(Terminal)

打开 terminal 窗口
切换当前目录到 AppImage 文件所在目录：

cd <my directory>

设置 AppImage 文件可执行权限：

chmod +x BitComet.AppImage

运行 AppImage 文件：

./BitComet.AppImage

第4步 如果运行 AppImage 文件失败，请安装缺少的依赖库（与发行版相关）

如果您的 Linux 发行版不包含 BitComet 所依赖的一些第三方库，请尝试手动安装它们。

打开 terminal 窗口
切换当前目录到 AppImage 文件所在目录：

cd <my directory>

再次尝试运行 AppImage 文件：

./BitComet.AppImage

根据错误信息安装缺少的依赖库：

Ubuntu / Debian 发行版

库	查看已安装版本及安装依赖库的命令
libfuse2	apt list \| grep libfuse sudo apt install libfuse2
libwebkit2gtk-4.0	apt list \| grep libwebkit2gtk sudo apt install libwebkit2gtk-4.0-37

注： Ubuntu 24.04 及以上版本需要添加 22.04 的 apt 下载源

sudo nano /etc/apt/sources.list.d/ubuntu.sources
# Suites: xxx xxx xxx 后面加上 jammy
# Suites: xxx-security 后面加上 jammy-security
# 存盘退出
sudo apt update
sudo apt install libwebkit2gtk-4.0-37
# 如有必要可恢复 apt 下载源

sudo nano /etc/apt/sources.list.d/ubuntu.sources

Fedora / RedHat / CentOS 发行版

库	查看已安装版本及安装依赖库的命令
libfuse2	yum list fuse* sudo yum --enablerepo=epel install fuse-sshfs sudo usermod -a -G fuse $(whoami)
libwebkit2gtk-4.0	yum list webkit2gtk* sudo yum install webkit2gtk-4.0.x86_64

openSUSE 发行版

库	查看已安装版本及安装依赖库的命令
libfuse2	zypper search -i libfuse sudo zypper install fuse libfuse2
libwebkit2gtk-4.0	zypper search -i webkit2gtk sudo zypper install webkit2gtk-4_0-37

更多与“FUSE”相关的错误信息，请访问此页面

Flatpak 格式

BitComet 从 2.22.0 版开始提供 Flatpak 安装包。目前安装包仅支持 x86_64 Linux 系统，ARM64、龙芯等其他架构不能直接安装。

第1步 安装 Flatpak

Ubuntu / Debian

sudo apt update
sudo apt install flatpak

Linux Mint 通常已预装 Flatpak。如果系统中没有 flatpak 命令，可使用上述 Ubuntu / Debian 命令安装。

Fedora

Fedora Workstation 通常已预装 Flatpak。如果尚未安装，请执行：

sudo dnf install flatpak

Arch Linux / Manjaro

sudo pacman -S flatpak

openSUSE Leap / Tumbleweed

sudo zypper install flatpak

安装 Flatpak 后，建议注销并重新登录，以便桌面环境加载应用菜单和其他桌面集成功能。仅通过命令行运行 BitComet 时通常不需要此步骤。

第2步 添加 Flathub 软件源

为当前用户添加 Flathub：

flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

可以使用以下命令确认 Flathub 已配置：

flatpak remotes --user

第3步 下载并安装 BitComet

从官网下载 BitComet-x.y.z-x86_64.flatpak，打开命令行终端并进入安装包所在目录，然后执行：

flatpak install --user ./BitComet-x.y.z-x86_64.flatpak

首次安装时不要添加 --no-deps。Flatpak 会自动从 Flathub 下载所需的 org.gnome.Platform//50 运行时。该运行时可能占用数百 MB 存储空间，但当前用户安装的其他 Flatpak 应用可以共享它。

第4步 运行 BitComet

安装完成后，可以从应用菜单启动 BitComet，也可以执行：

flatpak run com.bitcomet.BitComet

安装新版本

下载新版 .flatpak 文件后，再次执行安装命令，并将 x.y.z 替换为实际版本号：

flatpak install --user ./BitComet-x.y.z-x86_64.flatpak

BitComet 安装包是本地分发的单文件 bundle，因此应用本身不会通过 flatpak update 从 Flathub 自动更新。Flatpak 仍可更新由 Flathub 提供的运行时：

flatpak update --user

查看信息和权限

flatpak info com.bitcomet.BitComet
flatpak info --show-permissions com.bitcomet.BitComet

当前沙箱允许网络访问、音频、Wayland/X11 显示、桌面通知、GPU 加速以及访问当前用户的下载目录。其他文件系统位置默认不开放。

卸载 BitComet

flatpak uninstall --user com.bitcomet.BitComet

如需清理不再被任何当前用户安装的 Flatpak 应用使用的运行时，请执行：

flatpak uninstall --user --unused

常见问题

应用菜单中没有 BitComet

先注销并重新登录，然后确认 BitComet 已安装：

flatpak list --app --user

即使应用菜单尚未刷新，也可以使用 flatpak run com.bitcomet.BitComet 启动。

提示找不到 org.gnome.Platform//50

确认已为当前用户添加 Flathub，然后手动安装运行时：

flatpak remotes --user
flatpak install --user flathub org.gnome.Platform//50

随后重新执行 BitComet 安装命令。

文件选择窗口中的下载目录为空

Flatpak 通过 XDG 用户目录配置定位宿主机的下载目录。使用以下命令检查当前设置：

xdg-user-dir DOWNLOAD

如果命令输出的不是正确的下载目录，请安装 xdg-user-dirs、更新目录设置，然后重新启动 BitComet。安装包使用标准 XDG 下载目录，以兼容不同用户名和 Linux 发行版。

Deb 格式

第1步 下载 BitComet

Linux 版 BitComet 的 deb 打包文件可以从官网下载。

第2步 安装 deb 打包文件

打开 terminal 窗口
切换当前目录到 deb 文件所在目录：

cd <my directory>

安装 deb 文件：

sudo apt install ./BitComet-2.12.0-x86_64.deb

第3步 运行程序

运行GUI图形界面主程序：

BitComet

运行WebUI界面的命令行模式主程序：

bitcometd

**注：**两种模式的主程序在同一时间只能运行一个实例。

Docker 镜像（GUI 图形界面模式）

GUI 镜像通过浏览器提供 BitComet GTK 图形界面，支持 linux/amd64 和 linux/arm64。镜像标签及更多说明请参阅 Docker Hub。

浏览器 GUI 强制使用 HTTPS Web Authentication。原生 VNC 是可选功能，默认不开放 5900 端口。可选的 BitComet WebUI 使用 BitComet 程序内单独配置的账号和密码，不与浏览器 GUI 共用认证信息。

使用 Docker Compose 部署

先在命令行或 .env 文件中设置浏览器 GUI 登录密码。不要将真实密码提交到代码仓库：

export BITCOMET_GUI_PASSWORD='请替换为安全密码'

将以下内容保存为 docker-compose.yml。请根据实际情况修改冒号左侧的宿主机目录：

services:
  bitcomet:
    container_name: bitcomet
    image: wxhere/bitcomet:latest
    restart: unless-stopped
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      # BitComet 配置及 GUI 状态。
      - /docker/appdata/BitComet:/config:rw

      # 下载文件。
      - /home/user/Downloads:/output:rw
    ports:
      # 浏览器 GUI：https://HOST:6080
      - "6080:5800"

      # 可选的 BitComet WebUI。如不使用，请同时删除此映射及下面的
      # BITCOMET_WEBUI_PORT。
      - "6081:8080"

      # BitTorrent 入站及 DHT 端口。
      - "6082:6082/tcp"
      - "6082:6082/udp"
    environment:
      # 这两个值只控制应用进程身份和卷权限，不负责认证。
      # 仅在宿主机目录所有者不同时修改。
      USER_ID: "1000"
      GROUP_ID: "1000"

      # 可选的浏览器桌面尺寸。
      DISPLAY_WIDTH: "1280"
      DISPLAY_HEIGHT: "768"

      WEB_AUTHENTICATION_USERNAME: "bitcomet"
      WEB_AUTHENTICATION_PASSWORD: "${BITCOMET_GUI_PASSWORD:?BITCOMET_GUI_PASSWORD is required}"

      # 可选的 BitComet WebUI 容器内部端口。
      BITCOMET_WEBUI_PORT: "8080"

      # BitTorrent 容器内部监听端口。
      BITCOMET_BT_PORT: "6082"

      # 仅当从 v2.22.0 或更早版本升级，且旧任务保存了这个容器内
      # 绝对路径时设置。
      # LEGACY_DOWNLOAD_PATH: "/home/sandbox/Downloads"

启动容器：

docker compose up -d

打开 https://HOST:6080，使用用户名 bitcomet 和 BITCOMET_GUI_PASSWORD 提供的密码登录。由于容器会生成自签名 HTTPS 证书，浏览器可能显示证书警告。如启用了可选的 BitComet WebUI，可打开 http://HOST:6081，并使用 BitComet 程序中配置的独立账号和密码登录。

使用 Docker 命令行部署

先设置密码，并确保卷映射使用的宿主机目录可由配置的 USER_ID 和 GROUP_ID 写入：

export BITCOMET_GUI_PASSWORD='请替换为安全密码'

启动容器：

docker run -d \
  --name bitcomet \
  --restart unless-stopped \
  --ulimit nofile=65536:65536 \
  -v /docker/appdata/BitComet:/config:rw \
  -v "$HOME/Downloads":/output:rw \
  -p 6080:5800 \
  -p 6081:8080 \
  -p 6082:6082/tcp \
  -p 6082:6082/udp \
  -e USER_ID=1000 \
  -e GROUP_ID=1000 \
  -e DISPLAY_WIDTH=1280 \
  -e DISPLAY_HEIGHT=768 \
  -e WEB_AUTHENTICATION_USERNAME=bitcomet \
  -e WEB_AUTHENTICATION_PASSWORD="$BITCOMET_GUI_PASSWORD" \
  -e BITCOMET_WEBUI_PORT=8080 \
  -e BITCOMET_BT_PORT=6082 \
  wxhere/bitcomet:latest

如不使用可选的 BitComet WebUI，请删除 -p 6081:8080 和 -e BITCOMET_WEBUI_PORT=8080。生产环境建议固定使用不可变的 wxhere/bitcomet:v2.23.0 标签，以便可靠回滚。

从 v2.22.0 或更早版本升级

升级前先停止旧容器并备份宿主机配置目录。卷映射冒号左侧的宿主机路径可以保持不变，但需将容器内目标改为 /config 和 /output。

如果旧任务保存了 /home/sandbox/Downloads 等容器内绝对下载路径，请在环境变量中加入实际旧路径：

LEGACY_DOWNLOAD_PATH: "/home/sandbox/Downloads"

使用 Docker 命令行时，增加 -e LEGACY_DOWNLOAD_PATH=/home/sandbox/Downloads。旧镜像允许自定义 Linux 用户名，因此必须以旧任务属性中显示的实际路径为准，不能假定用户名一定是 sandbox。全新安装或已有任务已经使用 /output 时不要设置该变量。镜像不会扫描或改写任务数据。

Docker 镜像（WebUI-only 模式）

WebUI-only 镜像不包含 Linux 桌面、X Server、VNC 或 noVNC，只提供 BitComet WebUI 和 BT/DHT 服务，支持 linux/amd64 和 linux/arm64。镜像标签及更多说明请参阅 Docker Hub。

使用 Docker Compose 部署

先在命令行或 .env 文件中设置独立的 BitComet WebUI 登录凭据：

export BITCOMET_WEBUI_USERNAME='bitcomet'
export BITCOMET_WEBUI_PASSWORD='请替换为安全密码'

将以下内容保存为 docker-compose.yml：

services:
  bitcomet-webui:
    container_name: bitcomet-webui
    image: wxhere/bitcomet-webui:latest
    restart: unless-stopped
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      # BitComet 配置文件。
      - /docker/appdata/BitComet:/config:rw

      # 下载文件。
      - /home/user/Downloads:/output:rw
    ports:
      # BitComet WebUI。
      - "7080:8080"

      # BitTorrent 入站及 DHT 端口。
      - "7082:6082/tcp"
      - "7082:6082/udp"
    environment:
      # 这两个值只控制应用进程身份和卷权限，不负责认证。
      USER_ID: "1000"
      GROUP_ID: "1000"

      # 容器内部端口。
      BITCOMET_WEBUI_PORT: "8080"
      BITCOMET_BT_PORT: "6082"

      WEBUI_USERNAME: "${BITCOMET_WEBUI_USERNAME:-bitcomet}"
      WEBUI_PASSWORD: "${BITCOMET_WEBUI_PASSWORD:?BITCOMET_WEBUI_PASSWORD is required}"

      # 仅当从 v2.22.0 或更早的 WebUI-only 镜像升级，且旧任务
      # 保存了这个容器内绝对路径时设置。
      # LEGACY_DOWNLOAD_PATH: "/root/Downloads"

启动容器，然后打开 http://HOST:7080：

docker compose up -d

使用 Docker 命令行部署

先设置登录凭据，并确保卷映射使用的宿主机目录可由配置的 USER_ID 和 GROUP_ID 写入：

export BITCOMET_WEBUI_USERNAME='bitcomet'
export BITCOMET_WEBUI_PASSWORD='请替换为安全密码'

启动容器：

docker run -d \
  --name bitcomet-webui \
  --restart unless-stopped \
  --ulimit nofile=65536:65536 \
  -v /docker/appdata/BitComet:/config:rw \
  -v "$HOME/Downloads":/output:rw \
  -p 7080:8080 \
  -p 7082:6082/tcp \
  -p 7082:6082/udp \
  -e USER_ID=1000 \
  -e GROUP_ID=1000 \
  -e BITCOMET_WEBUI_PORT=8080 \
  -e BITCOMET_BT_PORT=6082 \
  -e WEBUI_USERNAME="$BITCOMET_WEBUI_USERNAME" \
  -e WEBUI_PASSWORD="$BITCOMET_WEBUI_PASSWORD" \
  wxhere/bitcomet-webui:latest

生产环境建议固定使用不可变的 wxhere/bitcomet-webui:v2.23.0 标签，以便可靠回滚。

从 v2.22.0 或更早版本升级

停止旧容器并备份宿主机配置目录。保持宿主机路径不变，将容器内卷目标从 /root/.config/BitComet 和 /root/Downloads 更新为 /config 和 /output。

只有旧任务仍保存 /root/Downloads 或其他旧容器内绝对路径时，才加入实际旧路径：

LEGACY_DOWNLOAD_PATH: "/root/Downloads"

使用 Docker 命令行时，增加 -e LEGACY_DOWNLOAD_PATH=/root/Downloads。全新安装或新版镜像之间升级时不要设置该变量。删除旧容器或旧镜像前，请确认旧任务、下载文件、WebUI 登录及 BT/DHT 端口均正常。