ProjectSend 介绍与选型指南

目标：面向需要在自有服务器上向客户交付文件（替代网盘外链与邮件附件）的团队，梳理开源客户文件投递系统 ProjectSend 的产品定位、技术架构、功能边界与同类选型对比。本文为联网溯源篇，全部事实来自官方仓库与官方发布渠道（来源与查询日期均已标注），不含本地推断与未经核实的指标。

一、环境信息

本文是 A1 认知篇，不依赖本地部署实验，只做联网溯源。为保证可复查性，先交代检索环境与全部事实的来源、查询日期。

检索环境：可访问 GitHub 与 shields.io 的网络（国外源直连偶发超时，部分请求经代理 192.168.1.62:7897 完成），查询日期 2026-11-01。

⚠️ 注意：星数、版本号、发布日期均随时间变化，上表数值仅代表查询日期 2026-11-01 当时状态；引用时请重新取证。

二、软件概述

本节回答"ProjectSend 是什么、解决什么问题、现在还活跃吗"三个基本问题，先给定位再给项目状态，帮助读者在两分钟内建立整体认知。

ProjectSend 是一个自托管（self-hosted）应用，官方一句话定位是"Share files with your clients, from your own server"——把文件交付给与你协作的客户，而文件始终在自己的服务器上（来源：仓库 README，2026-11-01）。它的核心工作流是：你上传要发送的文件，精确指定谁能看到，每个客户登录自己的私有页面下载。

README 用三个"没有"划清了与常见做法的边界（来源：README 原文，2026-11-01）：

• 没有靠邮件传阅的公开链接；
• 没有第三方服务持有你的客户文档；
• 没有按席位计费。

💡 技术拓展：自托管文件服务并非一个同质市场，选型前先分清三类产品——

类型	代表产品	交互模型	典型场景
账号制投递门户	ProjectSend	接收方持账号登录私有页面	长期服务客户，按客户隔离交付
一次性分享外发	Gokapi、PsiTransfer	公开链接 + 次数/天数到期消失	临时把大文件发给外部人员
Web 文件管理器	FileGator	登录后管理目录树，类网盘	团队内部文件管理与共享

本文主角 ProjectSend 属第一类：它的账号、配额、过期、审计都是围绕"客户"这个身份构建的，与后两类不是同一赛道的替代品。

项目状态与版本节奏（来源：releases.atom，查询日期 2026-11-01）：当前 2.x 是一次"重建（rebuild）"而非原位升级——上一代 ProjectSend（历史上的 r 编号版本）已独立为 projectsend/legacy 仓库维护；老站点通过官方迁移工具 projectsend/v1-migration-tool 把账号、客户、组、分类、文件夹、文件与历史导入新装实例，迁移工具"从不写旧站，任何一次运行都可单条命令撤销"。近两个月版本节奏如下：

关键解读：两个月内发布 9 个版本（平均约每周 1 个），且 2.8.0 与 2.7.1 间隔仅一周，说明 2.x 重建后处于高强度迭代期；对使用者是利好（缺陷修复快），但也意味着生产环境应锁定具体版本号并在升级窗口内跟随（官方 UPDATE.md 提供升级文档）。商业侧，同一团队运营官方托管版 ProjectSend Cloud，README 明确"每个订阅反哺这套免费软件"，免费核心与 Cloud 的边界由仓库 LICENSING.md 界定。

三、核心架构

本节从部署形态、组件拓扑与关键机制三个层面拆解 ProjectSend 的技术架构，全部依据官方 README 与官方 Docker 编排模板溯源。

部署形态（来源：README，2026-11-01）：官方提供两种安装路径——

1. 官方 Docker 镜像：projectsend/projectsend，镜像描述为"Client file sharing, self-hosted. Community edition."；README 称这是"最快的路径，也是我们推荐的路径"，镜像自带全部依赖且前端已预编译，无需本机构建；
2. 发布 zip 安装：面向不能使用 Docker 的服务器，INSTALL.md 覆盖依赖、.env、nginx、后台 worker 与 cron；zip 直接可跑，服务器上不需要 Composer 与 npm。

组件拓扑（来源：官方编排模板 docker/production/compose.example.yaml，2026-10-31 自 main 分支获取）：一套最小生产安装由三个服务组成——

模板另带一个可选的 clamav 病毒扫描服务（compose profile 方式启用，官方注释预算 1–1.5GB 内存用于病毒特征库）。

💡 技术拓展：文件下载的"投递通道"是这类系统最影响性能的机制。ProjectSend 官方 .env.example 提供四种 PROJECTSEND_FILE_DELIVERY 取值——

取值	原理	适用场景
auto（默认）	在 nginx 后自动交给 nginx 处理，其余环境经 PHP 流式发送	通用默认
nginx	由前置 nginx 直接服务 /protected-files/ 路径（X-Accel）	生产推荐，下载不占 PHP 进程
xsendfile	Apache mod_xsendfile（或 LiteSpeed）卸载下载	Apache 环境
php	始终经 PHP 流式输出	调试或极端受限环境；整个下载期间占用一个 PHP worker

官方注释明确："php 模式在任何环境都能工作，但整个下载期间会占住一个 PHP worker"。

关键机制（来源：README 与官方编排模板注释，2026-11-01）：

• 可断点续传的上传：分块上传，连接中断后可续传，"大文件才能真正送达"；
• APP_KEY 持久化：首次启动生成并保存在 storage 卷，官方注释强调"key 在重启间变化会使每个会话失效、让所有加密列永久不可读"；
• 可信代理（TRUSTED_PROXIES）：官方模板默认把端口绑到回环地址并设 TRUSTED_PROXIES: "*"，注释解释了两者必须成对修改的安全逻辑（否则访客可伪造来源 IP 绕过登录限速、污染下载日志）；
• 下载审计：活动日志与下载历史记录"谁在何时取走了什么"；
• 存储后端：本地磁盘、S3 兼容对象存储或 Google Cloud Storage（README）；
• REST API：带作用域令牌（scoped tokens），并自动生成 OpenAPI 文档（README；官方镜像内提供 api/docs 文档端点与 /api/v1 路由族）。

四、功能特性

本节把 README"它能做什么"清单按受益方分为三组转述，便于读者对照自己的需求勾选。

面向接收方（客户）（来源：README，2026-11-01）：

• 每个客户一个私有页面，只显示共享给该客户的内容；
• 邮箱登录，支持可选的两步验证（2FA）；
• 搜索、过滤、排序自己的文件；单个下载、多个打 zip 下载或整个文件夹下载；
• 可选的文件评论，让提问围绕文件本身；
• 有新文件时收到邮件通知，且以客户自己的语言显示。

面向管理方（你）：

• 断点续传上传，连接掉线后大文件仍能到达；
• 用文件夹、分类、客户组组织文件；
• 共享对象可选单个客户、整个组或公开，并可设置到期日期或下载次数上限；
• 图片与文档的缩略图与预览；
• 按客户的存储配额，以及记录客户补充信息的自定义字段；
• 完整的活动日志与下载历史。

面向安装与运维方：

• 内部团队的角色与权限体系（上传员不必是管理员）；
• 按既有体系登录：LDAP、社交登录或普通邮箱密码；
• 面向客户页面与外发邮件的主题定制；
• 16 种语言；
• REST API：作用域令牌 + 自动生成的 OpenAPI 文档；
• 隐私控制，包括 GDPR 级的账号擦除（带宽限期）；
• 本地磁盘、S3 兼容存储或 Google Cloud Storage；
• 官方编排模板内置可选的 ClamAV 病毒扫描服务（profile 启用，扫描地址与开关在系统设置中管理）。

关键解读：功能重心明显偏向"可控、可审计、可定制"的 B2B 交付场景——接收方体验（私有页 + 多语言通知）、管理方控制（配额/过期/次数）与合规能力（擦除、审计、扫描）三者齐备，而"匿名随便传"能力不是它的设计目标。

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

本节给官方 README 推荐的 Docker 最小路径（仅转述官方步骤，逐条实测部署与排障见本专栏《ProjectSend 2.8.0 Docker Compose 部署指南》）。来源：README"Getting started"，查询日期 2026-11-01。

前提：机器已装 Docker Engine 与 Compose 插件；README 特别提醒把当前用户加入 docker 组后重新登录，否则每条命令都会报 permission denied。

mkdir -p /srv/projectsend && cd /srv/projectsend
curl -o compose.yaml https://raw.githubusercontent.com/projectsend/projectsend/main/docker/production/compose.example.yaml
# 编辑 compose.yaml 中的数据库密码、管理员口令与 APP_URL，然后：
docker compose up -d

打开 APP_URL，首次访问会出现创建管理员账号的安装向导；也可以在 compose 里先取消 ADMIN_EMAIL / ADMIN_PASSWORD 的注释，实现无人值守建号（README 原文）。

⚠️ 注意：管理员口令至少 12 个字符，且不能命中公开泄露库（首次启动脚本会逐条校验并拒绝启动）——这是 2.8.0 实测到的强制策略，短口令或常见口令（如 8 位测试口令）会在初始化阶段直接失败，导致容器反复重启。口令设置失败的具体报错与修复实录见本专栏部署篇。

六、适用场景与限制

本节把功能清单映射为"什么该选它、什么不该选它"，并给出 2.x 时代必须知道的三条边界。

适用场景（与功能一一对应）：

• 设计、法务、财务、代理记账等需要按客户长期隔离交付文件的团队：客户只看得到自己名下的文件；
• 文件不出机房的合规敏感行业：数据落自有服务器或自有对象存储，配合 GDPR 级账号擦除与宽限期；
• 需要下载审计的场景：活动日志 + 下载历史回答"谁在何时取走了什么"；
• 需要对接既有身份体系的团队：LDAP / 社交登录 / 2FA；
• 需要把文件交付嵌入自动化流程：REST API（作用域令牌 + OpenAPI 文档）。

限制与边界（均可在官方文档溯源）：

1. 不是匿名临时网盘：虽然支持公开共享，但产品核心是账号制投递；一次性链接外发场景更适合 Gokapi/PsiTransfer 类工具（见第七章对比）；
2. 2.x 与 1.x 不互通：2.x 是重建，老站点（r 编号版本）只能用官方 v1-migration-tool 做导入式迁移（装新 → 导旧），客户唯一可感知的变化是"改用邮箱登录、密码不变"（README MIGRATING-FROM-V1.md 概述）；
3. 版本要求高：运行要求 PHP 8.4+（README 徽章）；zip 安装时主机的 PHP 版本必须达标，Docker 形态则无此顾虑；
4. 资源预算：启用官方 ClamAV 病毒扫描需预算约 1–1.5GB 内存（官方 compose 模板注释）；
5. 版本迭代快：平均约每周一个版本（第二章节奏表），生产环境建议锁定版本、规划升级窗口。

七、同类选型对比

本节给量化对比。星数为 shields.io 徽章取证值（查询日期 2026-11-01），定位与许可证、技术栈来自 Awesome Selfhosted 收录信息与各自仓库；各项目仍在演进，引用前请重新取证。

关键解读：星数只代表社区热度，不等于场景匹配度。三类的本质差异在接收方交互模型——ProjectSend 是"每个客户一个账号一个页面"，Gokapi/PsiTransfer 是"一个链接发出去、到期即焚"，FileGator 是"登录后管目录树"。若你的诉求是"客户随时能回来取自己的文件、且取了什么有账可查"，ProjectSend 是六者中唯一为此设计的。

"如果……则……"选型建议：

• 如果要按客户长期交付 + 审计 → ProjectSend；
• 如果要临时外发大文件、链接过期自动消失 → Gokapi 或 PsiTransfer；
• 如果要团队内部的类网盘文件管理 → FileGator；
• 如果要轻量拖拽分享 → Chibisafe；
• 如果要收发双向、允许匿名上传方 → Sharry；
• 如果不能跑 Docker 且想要单二进制 → Gokapi（Go 单文件部署）；
• 如果团队 PHP 运维栈成熟、想与既有 PHP 环境统一 → ProjectSend（zip）或 FileGator。

八、参考链接

• GitHub 仓库：https://github.com/projectsend/projectsend
• Releases 页：https://github.com/projectsend/projectsend/releases
• Releases 订阅源（本文发布节奏取证来源）：https://github.com/projectsend/projectsend/releases.atom
• 官方 README（master 分支，功能与安装形态来源）：https://raw.githubusercontent.com/projectsend/projectsend/master/README.md
• 官方 Docker 编排模板（compose.example.yaml）：https://raw.githubusercontent.com/projectsend/projectsend/main/docker/production/compose.example.yaml
• 上一代项目（ProjectSend Legacy）：https://github.com/projectsend/legacy
• 官方 v1 迁移工具：https://github.com/projectsend/v1-migration-tool
• 官方托管版 ProjectSend Cloud：https://projectsend.cloud
• 星数/版本取证徽章示例：https://img.shields.io/github/stars/projectsend/projectsend 与 https://img.shields.io/github/v/release/projectsend/projectsend