先说主线:传一次大文件,为什么这么难
场景很常见:你要给朋友或客户传一个几个 GB 的视频工程、数据集或者系统镜像。公共网盘要注册、要装客户端、要开会员解除限速,对方还得再注册一遍才能下;聊天软件有大小上限;国外那几个临时分享站,免费版限体积、限次数,速度还看运气。说到底,「把一个大文件点对点交到另一个人手里」这件小事,一直没有顺手的解法。
Pingvin Share X 就是冲着这个场景来的:一个自托管的文件分享平台,定位是 WeTransfer 的自建替代品。你把文件传到自己的服务器上,生成一个链接发给对方,对方打开链接就能下,不用注册、不用装任何东西,大小只受你自己的硬盘限制。分享可以设过期时间、访问次数上限和密码,还能反过来生成「反向分享」链接,让别人往你的服务器里传文件——收稿、收作业、收客户素材时特别好用。
先把定位说清:它管的是「传一次」,不是「存长期」。文件要长期保存、随时取用,那是网盘本体的活,去看本系列的 Cloudreve 私人云盘;这一篇解决的是临时交接。
先讲来历:原版归档之后,X 接棒
Pingvin Share X 是 Pingvin Share 的社区分支(fork)。原版 Pingvin Share 由独立开发者维护了三年多,2025 年 6 月 29 日,作者把原仓库归档停更,说明自己精力有限,决定专注于另一个项目 Pocket ID。难得的是,作者在原版 README 里亲自推荐了这个社区继任分支——Pingvin Share X 由 smp46 维护,2025 年 9 月建仓以来保持活跃更新,已经发了 40 个版本,界面支持 34 种语言。所以现在新部署,装 X 就是正路:功能和原版一脉相承,修复和更新有人接着做。
WARNING不要再新装原版 Pingvin Share 仓库了:它已经归档,不会再有功能更新和安全修复。网上搜到的很多老教程指向的还是 stonith404 的原版仓库,照着装能跑起来,但等于把一个停更的服务放上公网。新部署一律用 Pingvin Share X;已经在跑原版的,迁移大体是换镜像、沿用数据卷,具体步骤以 X 的官方文档为准,不要凭老经验硬套。
功能一览:分享这件事,它做全了
| 功能 | 说明 |
|---|---|
| 链接分享 | 上传后生成分享链接,对方免注册直接下载 |
| 文件大小 | 不设上限,只受服务器磁盘空间限制 |
| 过期控制 | 每个分享可设过期时间,到期自动失效 |
| 访问限制 | 可设访问次数上限,并可加访问密码 |
| 邮件直达 | 创建分享时直接填收件人邮箱,系统发邮件通知对方 |
| 反向分享 | 生成专属链接,让别人上传文件到你的服务器,可设有效期与次数 |
| 登录集成 | 支持 OIDC 与 LDAP,团队已有账号体系时可直接接入 |
| 病毒扫描 | 可集成 ClamAV,对上传文件做安全扫描 |
| 存储后端 | 本地磁盘或 S3 兼容对象存储,二选一 |
对个人用户,最常用的就是前六项;OIDC、LDAP、ClamAV 是给团队和公网部署准备的,后面进阶部分会各带一句。
部署:一个 docker-compose.yml 就够了
准备一台装好 Docker 的服务器(或 NAS、家用小主机),磁盘留足——分享站的空间消耗全看你传多大的文件。官方推荐的部署方式就是 Docker Compose,X 的仓库根目录自带 docker-compose.yml:
mkdir -p ~/pingvin-share-x && cd ~/pingvin-share-x# 下载 X 仓库自带的 compose 文件curl -O https://raw.githubusercontent.com/smp46/pingvin-share-x/main/docker-compose.yml它的核心内容如下(时区按需改成你自己的):
services: pingvin-share: image: smp46/pingvin-share-x restart: unless-stopped ports: - 3000:3000 environment: - TZ=Asia/Shanghai volumes: - "./data:/opt/app/backend/data" - "./data/images:/opt/app/frontend/public/img"镜像有两个来源,任选其一:Docker Hub 上的 smp46/pingvin-share-x,或 GitHub 容器仓库的 ghcr.io/smp46/pingvin-share-x,哪个拉取顺畅用哪个。两个数据卷要留意:data 存的是数据库与全部上传文件,是这个服务的命根子,备份就备它;images 存站点图标等自定义图片。拉起服务:
docker compose up -ddocker compose logs -f pingvin-share # 看到监听日志后 Ctrl+C 退出浏览器打开 http://服务器IP:3000,能看到登录页就说明跑起来了。首次使用先注册一个账号——第一个注册的账号会自动成为管理员,之后所有站点级配置都在这个账号的后台里完成。注册完管理员,第一件事建议先去后台把「允许注册」关掉(下一节的配置项),分享站不是社区,不需要开放注册。
想尝鲜:beta 通道
X 维护着一个 beta 通道:新修复和新功能先发到 beta 镜像验证,稳定后再进正式版。把 compose 里的镜像换成带 :beta 标签即可:
image: smp46/pingvin-share-x:beta改完 docker compose up -d 就会拉 beta 版。适合愿意帮忙试新功能、反馈问题的用户;正经在用的分享站建议留在稳定版,等 beta 验证过的更新自然跟进。
关键配置:后台界面与 config.yaml
Pingvin Share X 的配置有两条路:管理员登录后在后台设置页里改,或者写 config.yaml 文件。文件方式的规则是:写进 config.yaml 的值以文件为准,后台界面里对应项会被锁定,适合用 Git 管理配置、或者怕手滑改错的场景。仓库里有 config.example.yaml 包含全部可配项,下面只摘日常真正要动的几组。文件放在数据目录中,改完重启容器生效:
general: appName: "Pingvin Share" # 对外访问地址:分享链接和邮件里用的都是它,必须填公网能打开的地址 appUrl: "https://share.example.com" secureCookies: true # 走 HTTPS 时开启
share: allowRegistration: false # 管理员建好后关掉开放注册 allowUnauthenticatedShares: false # 是否允许未登录用户创建分享,按需 maxExpiration: "0 days" # 分享最长有效期,0 表示不限制 maxSize: "10000000000" # 单个分享总大小上限(字节),这里约 10 GB chunkSize: "10000000" # 上传分片大小(字节),默认 10 MB,别乱动
smtp: enabled: true # 要用邮件发送功能必须先配 SMTP host: "smtp.example.com" port: "587" email: "share@example.com" username: "share@example.com" password: "你的邮箱密码或授权码"
email: enableShareEmailRecipients: true # 允许创建分享时填写收件人邮箱
s3: enabled: false # 改 true 则文件存进 S3,本地只留数据库 endpoint: "" region: "" bucketName: "" bucketPath: "" key: "" secret: ""几个配置点的取舍:
- appUrl 是最容易踩的坑。appUrl 填错,分享链接和通知邮件里生成的全是错误地址,对方点开必然打不开。本机测试时是
http://localhost:3000,一旦绑了域名走公网,第一时间把它改成正式地址。 - maxSize 与磁盘的关系:maxSize 只是单分享上限,挡不住有人反复建分享把盘塞满。公网部署建议同时在系统层给 data 目录留配额或单独挂盘。
- S3 后端适合文件量大的场景:本地盘只放数据库,文件本体进对象存储,服务器迁移和扩容都轻松;个人小规模用本地盘更简单,备份也直观。
- SMTP 不配也能用:链接分享不受影响,只是「邮件发送给收件人」和找回密码这类功能用不了。
日常用法:发分享、收文件
发一个分享:登录后点新建分享,把文件拖进去(支持大文件分片上传,浏览器别关),然后设三件套——过期时间、最大访问次数、访问密码。生成链接后发给对方即可;配了 SMTP 的话,创建时直接填对方邮箱,系统会把链接邮件送过去,省得你再转述。对方打开链接看到的是干净的下载页,输密码(如果设了)就能下,次数用完或到期后链接自动失效。
收文件用反向分享:在后台创建一个反向分享链接,设好有效期和允许上传的次数,把链接发给需要给你传文件的人。对方打开链接只能上传、看不到你服务器上的其他内容,文件直接落进你的分享站,你登录后台就能取。收客户素材、收投稿、让家人传手机里的原图,都比逐个教他们装网盘客户端省事。
团队场景的两个开关:用户多、有现成账号体系时,在配置里接 OIDC 或 LDAP,成员用统一账号登录,不用在分享站里再维护一套密码;上传入口对公网开放时,建议再按官方文档给 Compose 加一个 ClamAV 服务并开启扫描,多一道病毒拦截。细节以官方文档(smp46.github.io)为准,这里不展开。
反向代理与 HTTPS:上线前把这几件事做对
正式对外用,一般会套一层反向代理加 HTTPS。以 Nginx 为例:
server { listen 443 ssl; server_name share.example.com;
# 必须大于上传分片大小(chunkSize 默认 10 MB),否则大文件上传会被拦腰截断 client_max_body_size 50m; # 大文件传输耗时长,超时给足 proxy_read_timeout 600s; proxy_send_timeout 600s;
location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; }}用 Nginx Proxy Manager 这类面板同理:建代理主机指向 3000 端口,把请求体大小上限调到分片大小以上即可。代理配好后记得回头改两处:appUrl 改成 https://share.example.com,secureCookies 打开。
安全上再强调一句:分享站一旦对公网开放上传,就等于把一块公共硬盘挂在了网上。务必关掉开放注册、禁止未登录创建分享,给每个分享都设过期时间;长期不用时宁可停掉容器,也不要让一个无人看管的上传入口一直暴露着——被陌生人当免费图床和违规文件中转站,锅全在服务器所有者身上。
和 PsiTransfer 怎么选
同为自建临时分享,本系列还有一篇 PsiTransfer,两者气质差别不小:
| 维度 | Pingvin Share X | PsiTransfer |
|---|---|---|
| 定位 | 功能完整的分享平台 | 极简的临时文件中转 |
| 账号体系 | 有注册体系,可接 OIDC / LDAP | 无账号,开箱即传 |
| 分享控制 | 过期、访问次数、密码、邮件发送、反向分享 | 过期、一次性下载、密码 |
| 存储后端 | 本地磁盘或 S3 | 本地磁盘 |
| 界面与管理 | 现代界面,后台配置项丰富 | 轻量界面,配置靠文件与环境变量 |
| 维护状态 | 社区继任分支,活跃维护 | 仍在持续维护 |
结论很简单:要「平台感」——多用户、正规分享管理、邮件通知、反向收文件——选 Pingvin Share X;只想给自己留一个随手传文件的极简入口,PsiTransfer 更轻、更省心。
排障清单
- 容器起来了但页面打不开:先
docker compose logs看后端是否报错,再查 3000 端口是否被其他服务占用、安全组/防火墙是否放行。 - 分享链接发给别人打不开:九成是
appUrl还是localhost或内网地址。改成公网正式地址后,旧链接需要重新生成。 - 大文件传到一半失败:先查反向代理的
client_max_body_size是否小于分片大小,再查代理超时设置;直连 3000 端口测试能过、走域名不行,问题就在代理层。 - 邮件发不出去:确认
smtp.enabled已开、邮箱用的是授权码而非登录密码(多数邮箱服务商要求)、enableShareEmailRecipients已开启;改完配置记得重启容器。 - 后台改了配置不生效:检查是否被
config.yaml里的同名值锁定——文件里写了的值,后台改不动,改文件并重启容器。 - S3 模式上传报错:核对 endpoint、region、桶名与密钥,确认密钥对该桶有读写权限;先切回本地存储验证服务本身没问题,再回头查对象存储侧。
- 磁盘莫名被占满:多半是过期分享之外的历史文件堆积或有人反复上传。去后台清掉无用分享,并给分享设默认过期时间,养成习惯。
- 升级或迁移后数据丢失:这个服务的全部状态都在
data卷里,迁移就是搬data目录加同一份 compose 文件;动手前先整目录备份。从原版迁过来的,先在测试环境验证数据卷兼容,再切生产,并以官方文档的迁移说明为准。
小结
Pingvin Share X 把「传大文件」这件小事做成了一个完整的产品:链接分享、过期与次数、密码、邮件、反向收文件,该有的都有,部署却只要一个 Compose 文件。它接过的原版已经归档,但 X 本身在活跃维护,这条线没有断。长期公网部署时记住把注册关严、过期设好,它就是一个可靠的自建分享站。如果你的需求其实是「随时能打开的常驻网盘」,那不在这一篇的范围里,去看零服务器的 Davflare 或者自有服务器的 Cloudreve;只论点对点交接文件,Pingvin Share X 这一类自建分享站,仍然是比公共网盘顺手得多的答案。