PsiTransfer 2.4.5 介绍与选型指南

PsiTransfer（psi-4ward/psitransfer）2.4.5 开源一次性文件分享服务介绍：核心架构、tus 分块续传等 14 项功能特性、适用边界与同类选型对比，全部信息标注来源与查询日期。

PsiTransferNodejs文件传输文件分享自托管2026/11/01

PsiTransfer 2.4.5 介绍与选型指南

目标：面向「想把大文件一次性分享给客户/同事，又不想引入账号体系」的自托管场景，讲清 PsiTransfer 的定位、核心架构、功能边界与同类选型差异，帮助读者在 10 分钟内完成「是否选用」的判断。本文为认知与选型篇，全部事实信息均来自官方仓库与官方文档的联网溯源，关键信息已标注来源与查询日期（2026-11-01）。

一、环境信息

二、软件概述

2.1 项目定位

PsiTransfer 是一款开源（BSD-2-Clause）的自托管文件分享服务，官方 README 对它的一句话定义是「Simple open source self-hosted file sharing solution」，明确把自己定位为 Dropbox、WeTransfer 这类付费服务的替代品（来源：官方 README，2026-11-01 查询）。

它的核心工作流与 WeTransfer 高度一致：

  1. 上传者打开首页，拖入若干文件，设置保留时长（可选设置 bucket 密码）；
  2. 服务返回一个形如 http://<host>/<bucket-id> 的下载页链接；
  3. 接收者打开链接即可浏览文件清单、预览、单个下载或整包下载；
  4. 到期或「一次性下载」次数用完后，文件自动从服务端删除。

与网盘类产品（Nextcloud、Seafile）最大的差异是：PsiTransfer 没有任何账号体系——无注册、无登录、无用户目录，上传者打开页面即可传，接收者拿到链接即可下。这让它成为「临时大文件中转」这一单一场景下最轻量的方案之一。

2.2 项目活跃度与可信度

维度数据来源与查询日期
GitHub Stars约 2kshields.io 徽章 https://img.shields.io/github/stars/psi-4ward/psitransfer.json 返回 {"label":"stars","message":"2k"}，2026-11-01
最新稳定版v2.4.5GitHub Releases 页面首个非预发布条目，2026-11-01
npm 最新发布2.4.4npmjs.com/package/psitransfer，2026-11-01（npm 侧发布略滞后于 GitHub Releases）
维护节奏2026 年仍持续维护（v2.4.2 于 2026-04-13 发布，v2.4.0 于 2026-01-31 发布，均含依赖升级与安全修复）LibHunt changelog 镜像，2026-11-01
安全响应有据可查：v2.3.1 修复「Slip Path Traversal」路径穿越漏洞；v2.4.0 说明「This release includes some security fixes」；CVE-2026-41180 标注修复于 2.4.3GitHub Releases 说明与 SynScan CVE 库，2026-11-01

💡 说明：作者 psi-4ward（psi.cx 站长）在官方 README 维护了系列博客（https://psi.cx/tags/PsiTransfer/ ），设计与使用心得可直接溯源；仓库同时提供了 /admin 管理页截图与功能演示 GIF，文档完善度在同类小工具中属中上水平。

2.3 版本沿革要点

  • v2.x 主线：当前唯一活跃主线，要求 Node ≥12；v2.3.0 起加入反向代理（Reverse proxy）支持与无障碍改进；
  • v1.1/v1.0：旧主线，官方镜像仍保留 1.1、1.0.0 标签，新部署不应选用；
  • 安全演进：路径穿越（v2.3.1）、CVE-2026-41180（v2.4.3）两个案例说明该项目对安全报告有实际响应，选型时应取 ≥2.4.3 的版本（本文取最新 v2.4.5）。

三、核心架构

PsiTransfer 是典型的单体 Node.js Web 应用，全部组件打包在一个进程、一个镜像内（来源：官方仓库目录结构与 README，2026-11-01 查询）：

层实现说明
Web 框架Express单进程监听 3000 端口（可配 PSITRANSFER_PORT 改）
上传协议tus.io 分块续传协议官方 README 明确「Resumable up- and downloads (tus.io)」，服务端以 tusboy 中间件挂载在 /files 路径，支持 POST 创建 + PATCH 分块 + HEAD 查进度
前端Vue 轻量应用官方 README：「Gzipped (on by default) less than 100k」，上传页与下载页均为独立 Vue 应用
模板渲染pug上传页/下载页/admin 页/错误页四张 pug 模板，可自行改写换 LOGO 与样式
存储本地文件系统上传目录默认 /app/data（官方镜像通过 PSITRANSFER_UPLOAD_DIR=/data 重定向到 /data），元数据 JSON 与文件本体同目录存放
事件机制内部 eventBus文件上传完成、文件下载完成等事件广播给插件，驱动 Webhook 通知
插件内置 2 个file-downloaded-webhook、file-uploaded-webhook，分别对下载/上传事件发 HTTP POST 通知

三个设计特征值得在选型时注意：

  1. 流式处理（Streams）：官方 README 强调「Supports many and very big files (Streams ftw)」，上传与下载全程走 Node 流，不在内存中缓存文件体，这是它能承载大文件的关键；
  2. bucket 语义：一次上传会话即一个 bucket，bucket ID 可由服务端生成，也可在上传时显式指定（README：「Explicit named bucket IDs with query param sid=<myBucketID>」），API 集成时可固定语义化 ID；
  3. 无外部依赖：不依赖数据库、缓存、对象存储，/data 目录即全部状态——备份与迁移等价于「拷走一个目录」。

四、功能特性

以下清单逐项来自官方 README（2026-11-01 查询），并附功能含义解读：

特性官方原文解读
免账号免登录No accounts, no logins打开页面即可上传/下载，零用户管理成本
移动端自适应Mobile friendly responsive interface手机浏览器可直接收发文件
大文件与多文件Supports many and very big files (Streams ftw)流式转发，不受单文件内存限制
分块续传Resumable up- and downloads (tus.io)上传中断后可从断点继续，弱网环境友好
保留时长Set an expire-time for your upload bucket内置 1 小时～8 周共 8 档时长 + 一次性下载
一次性下载One-time downloads首个接收者下载后文件即从服务端删除
整包下载Download all files as zip/tar.gz archive服务端即时打包，无需预压缩
文件预览Modal-style file preview下载页弹窗预览（限制大小可配 maxPreviewSize）
bucket 密码Password protected download list (AES)密码经 AES 加密保护文件清单，清单接口返回密文
管理页/admin Page lists bucket information列出全部 bucket 与下载状态；未设置 adminPass 时自动禁用
上传密码PSITRANSFER_UPLOAD_PASS可选的站点级上传口令，防陌生人占用存储
显式 bucket IDsid=<myBucketID>API 集成可指定 bucket ID，便于流程对接
多语言defaultLanguage 配置内置英语/德语语言包，可扩展
Webhook 通知event webhooks上传完成/下载完成可 POST 通知外部系统

两点官方明确声明的能力边界（README「Side notes」，2026-11-01 查询）：

  1. There is no (end-to-end) payload encryption (yet)：没有端到端加密，服务端管理员可见文件明文——涉密文件不应使用；
  2. Download all as ZIP does not support resuming the download：整包下载不支持断点续传（单文件下载才支持）。

五、快速开始（最小可用示例）

官方 README 给出的最短启动路径是一条 docker run（来源：官方 README Quickstart，2026-11-01 查询）：

docker run -p 0.0.0.0:3000:3000 -e PSITRANSFER_ADMIN_PASS=secret -v $PWD/data:/data psitrax/psitransfer
# data volume needs UID 1000
sudo chown -R 1000 $PWD/data

官方镜像标签体系同样来自 README：

  • latest：对应 master 分支；
  • 2：最新稳定 2.x（本文溯源时即 2.4.5）；
  • 1.1 / 1.0.0：旧主线。

💡 说明：生产部署不建议直接用上面的一行命令——数据目录属主（UID 1000）、admin 密码、保留时长默认值、上传口令等都需要按场景调整。完整的 Compose 部署、持久化与运维闭环见本专栏 《PsiTransfer 2.4.5 Docker Compose 部署指南》。

六、适用场景与限制

6.1 适用场景

  1. 对客交付大文件：给客户发安装包、视频样片、数据集，设置 1～8 周保留期，到期自动清理，不留存储尾巴；
  2. 一次性敏感 medium 传输：口令/密钥文件用「one-time download」档，首个接收者取走后服务端即焚，避免链接二次扩散；
  3. 跨部门/跨公司临时中转：无账号体系意味着无需为外部协作者开账号，一个链接完成交接；
  4. 自动化流程的文件投递点：tus 上传 API + 显式 bucket ID + Webhook 通知，可作为 CI 产物、扫描报告的自动投递端。

6.2 限制与不适用

限制影响应对
无端到端加密服务端可见文件明文涉密内容先本地加密再上传，或改用 OnionShare 等端到端方案
单机文件系统存储无分布式/对象存储后端，容量受单盘限制大规模长期存储应选 Nextcloud/MinIO 形态产品
无账号体系无法做用户级权限、配额、审计需要组织级管控时选 FileGator、ProjectSend 等带用户体系的
整包下载无续传zip/tar.gz 下载中断需重来大集合改分批单文件下载
无内置 HTTPS需自行前置反向代理v2.3.0 起官方支持反向代理头，Nginx/Caddy 前置即可

七、同类选型对比

下表把 PsiTransfer 与同类「轻量一次性文件分享」自托管组件横向对比（同类组件的功能口径取自各项目官方仓库描述，2026-11-01 整理；星数为约数，取自各项目 shields.io 徽章口径）：

组件技术栈账号体系一次性下载分块续传整包下载管理页存储依赖适用取舍
PsiTransfer 2.4.5Node.js无✅（保留档之一）✅ tus✅ zip/tar.gz✅ /admin本地目录大文件、弱网、要 API 集成的默认之选
JirafeauPHP无✅❌❌简易 admin本地目录极简 PHP 环境，功能克制
PlikGo可选 token✅✅ 分块✅✅ + CLI本地/对象存储偏运维团队，API/CLI 能力强
PicoShareGo单管理员✅❌❌✅本地/对象存储极简直链分享
GokapiGo单管理员✅❌❌✅本地/S3带 S3 后端的轻量替代
ChibisafeNode.js多用户❌（按链接管理）✅✅✅ 较全本地/S3偏个人网盘/图床混合场景

关键差异解读：

  1. 「真一次性」语义：PsiTransfer 的 one-time 是「首个下载完成后服务端即删除文件」，且与保留时长在同一个 retention 下拉框中并列（one-time 本身就是一种 retention 档位），语义清晰、无歧义；PicoShare/Gokapi 的「一次性」靠过期/次数配置实现，行为各有细节差异；
  2. 上传可靠性：PsiTransfer 与 Plik 是表中仅有的两个原生 tus/分块续传实现，弱网或大文件（GB 级）场景应优先二者；
  3. 存储弹性：PsiTransfer 只支持本地目录（单机形态），需要 S3 后端时 Gokapi/Plik/Chibisafe 更合适；
  4. 管理能力：PsiTransfer 的 /admin 是只读的 bucket 清单（含下载时间），没有用户管理、配额管理——它是「工具」而非「平台」。

选型结论：如果诉求是「无账号、大文件、可续传、到点即焚、单二进制级运维成本」，PsiTransfer 是当前自托管领域平衡度最好的选择之一；一旦诉求偏移到「长期存储、多用户、对象存储、细粒度权限」，应转向表格右侧的组件或网盘类产品。

八、参考链接