安装

本页介绍用 Docker、Linux 二进制和 Windows 二进制安装 pt-tools 的步骤，以及首次登录和数据目录的说明。

方式	适用系统	说明
Docker Compose	任何能运行 Docker 的系统	推荐。升级只需要拉取新镜像
docker run	同上	单条命令，适合临时试用
Linux 二进制	Linux amd64、arm64	安装脚本会校验 SHA-256；可以注册为 systemd 服务
Windows 二进制	Windows amd64、arm64	PowerShell 安装脚本或手动解压
NAS	1Panel、Unraid、飞牛 fnOS	用 deploy/ 里的应用定义安装

不提供 macOS 二进制，macOS 请使用 Docker。

本站文档按 1.0 预览版编写。下面的命令默认安装正式版 0.48.0，其中没有标「1.0 预览版」的功能；要使用这些功能，按安装预览版安装预览版。

Docker Compose（推荐）

把下面的内容保存为 compose.yml：

services:
  pt-tools:
    image: sunerpy/pt-tools:latest
    container_name: pt-tools
    environment:
      PT_HOST: "0.0.0.0"
      PT_PORT: "8080"
      TZ: "Asia/Shanghai"
      PUID: "1000"
      PGID: "1000"
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/.pt-tools
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

然后启动：

docker compose up -d

重要

必须持久化 /app/.pt-tools。这个目录包含数据库、配置和用于加密站点凭证的 secret.key；删除或丢失密钥后，已保存的 Cookie 无法恢复。

logging 一节限制容器标准输出日志的大小。不设置时，长时间运行会让 Docker 的日志文件持续增长，NAS 用户尤其需要注意，详见配置说明。

镜像同时发布在 Docker Hub（sunerpy/pt-tools）和 GHCR（ghcr.io/sunerpy/pt-tools，附带构建证明），两者内容相同。国内拉取 Docker Hub 较慢时，可以在 Docker 的 daemon.json 里配置 registry-mirrors（镜像加速地址），镜像名不用改。

docker run

docker run -d \
  --name pt-tools \
  -p 8080:8080 \
  -v ~/pt-data:/app/.pt-tools \
  -e TZ=Asia/Shanghai \
  sunerpy/pt-tools:latest

常用环境变量

变量	说明	默认值
PT_HOST	监听地址	0.0.0.0
PT_PORT	监听端口	8080
TZ	时区	Asia/Shanghai
PUID、PGID	容器内运行程序的用户 ID 和组 ID	1000
PT_ADMIN_USER	初始管理员用户名	admin
PT_ADMIN_PASS	初始管理员密码	adminadmin
PT_ADMIN_RESET	设为 1 时按上面两个变量重置管理员密码	未设置
HTTP_PROXY 等	代理，见配置说明	未设置

NAS

仓库的 deploy/ 目录里有 1Panel、Unraid 和飞牛 fnOS 的应用定义，下面是不经应用商店、直接用这些文件安装的方法。三者都把数据目录映射到容器的 /app/.pt-tools，升级、重装时保留这个目录并备份其中的 secret.key。

容器以 PUID、PGID 指定的用户运行，启动时把 /app 下的文件交给这个用户。NAS 上常用的组 ID 100 在镜像里已经存在（users 组），直接沿用。这需要 1.0.0-rc.4 或更新的镜像：更早的版本在 PGID 是镜像里已有的组时启动失败（日志里是 addgroup: gid in use）。

1Panel

把 deploy/1panel/pt-tools 整个目录复制到服务器的 /opt/1panel/resource/apps/local/pt-tools，在 1Panel 的应用商店里刷新本地应用列表，找到 pt-tools 安装，填写网页端口和时区。数据在应用目录下的 data/ 里。

Unraid

把 deploy/unraid/pt-tools.xml 下载到 U 盘的 /boot/config/plugins/dockerMan/templates-user/my-pt-tools.xml，在 Docker 页面点 Add Container，从 Template 下拉框里选 pt-tools。模板默认 PUID=99、PGID=100（Unraid 的 nobody 与 users），数据目录是 /mnt/user/appdata/pt-tools。

飞牛 fnOS

在 fnOS 的 Docker 应用里新建一个 Compose 项目，内容用上面的 Compose 文件，把 ./data 换成共享文件夹里的一个目录（例如 /vol1/1000/docker/pt-tools），再按这个目录所属用户设置 PUID、PGID（用 ls -n 查看）。deploy/fnos 是提交给第三方应用中心 fnos-apps 的打包配置。

Linux 二进制

用安装脚本

curl -fsSL https://raw.githubusercontent.com/sunerpy/pt-tools/main/scripts/install.sh | sh

脚本会下载最新版本的压缩包和同一版本的 checksums.txt，SHA-256 不一致时拒绝安装。默认装到 ~/.local/bin，可以用环境变量调整：

• TOOL_VERSION：安装指定版本，例如 TOOL_VERSION=v0.48.0。
• TOOL_INSTALL_DIR：安装目录。

每个版本的发布说明里都有固定到该版本的安装命令，可以直接复制使用。

手动下载

从发布页面下载对应架构的压缩包和 checksums.txt，先校验再解压：

sha256sum -c checksums.txt --ignore-missing
tar -xzf pt-tools-linux-amd64.tar.gz
chmod +x pt-tools
./pt-tools web --host 0.0.0.0 --port 8080

如果需要确认压缩包由本项目的发布流水线构建，可以用 GitHub CLI 校验构建证明：

gh attestation verify pt-tools-linux-amd64.tar.gz --repo sunerpy/pt-tools \
  --signer-workflow sunerpy/pt-tools/.github/workflows/release.yml \
  --deny-self-hosted-runners

注册为 systemd 服务

创建 /etc/systemd/system/pt-tools.service，把 User 和路径换成你自己的：

[Unit]
Description=pt-tools
After=network.target

[Service]
Type=simple
User=your_username
WorkingDirectory=/home/your_username
ExecStart=/usr/local/bin/pt-tools web --host 0.0.0.0 --port 8080
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now pt-tools
sudo journalctl -u pt-tools -f

数据保存在运行用户的 ~/.pt-tools 目录下。

Windows 二进制

在 PowerShell 中运行：

irm https://raw.githubusercontent.com/sunerpy/pt-tools/main/scripts/install.ps1 | iex

需要安装指定版本时，先设置 $env:TOOL_VERSION = "v0.48.0" 再运行。也可以从发布页面下载 pt-tools-windows-amd64.exe.zip，解压后运行：

.\pt-tools.exe web --host 0.0.0.0 --port 8080

数据保存在用户目录下的 .pt-tools 文件夹中。

安装预览版

预览版发布在 GitHub Releases 里标为 Pre-release 的版本中，版本号形如 v1.0.0-rc.N。latest 镜像标签和安装脚本默认安装的仍是正式版；预览版要写明版本号，下面以 v1.0.0-rc.36 为例，实际请换成 Releases 页面上最新的预览版。

• Docker：把镜像写成 sunerpy/pt-tools:v1.0.0-rc.36（或 ghcr.io/sunerpy/pt-tools:v1.0.0-rc.36），再重新创建容器。预览版不会更新 latest 标签，有新的预览版时要手动改版本号。
• Linux：curl -fsSL https://raw.githubusercontent.com/sunerpy/pt-tools/main/scripts/install.sh | TOOL_VERSION=v1.0.0-rc.36 sh。
• Windows：先设置 $env:TOOL_VERSION = "v1.0.0-rc.36"，再运行上面的安装命令。
• 手机 App：现在的预览版里，安装包和服务端在同一个 Release 里，见手机 App。

预览版用于测试，不建议直接用在生产环境。从正式版升级前先按备份保存数据目录：预览版启动时会迁移数据库结构，要回到 0.48.0 时请换回升级前备份的数据目录。

首次登录

打开 http://服务器地址:8080，使用初始账号登录：用户名 admin，密码 adminadmin。如果启动时设置了 PT_ADMIN_USER 和 PT_ADMIN_PASS，以这两个变量为准。

登录后请立即在「修改密码」中更换密码。忘记密码时，按配置说明中「重置管理员密码」一节操作。

注意

不要把 pt-tools 直接暴露在公网上。需要远程访问时，请放在启用 HTTPS 的反向代理之后，或者通过 VPN 访问。

数据目录

所有方式的数据目录结构相同：

.pt-tools/
├── secret.key     # 凭证加密密钥，必须与数据库一起备份
├── torrents.db    # SQLite 数据库：配置、任务记录和用户数据缓存
├── downloads/     # 暂存的 .torrent 文件
├── backups/       # 自动生成的历史配置备份
└── logs/          # 轮转日志

备份和恢复的方法见升级与备份。

下一步

安装完成后，按快速开始添加下载器、站点和第一个 RSS 订阅。