PsiTransfer 2.4.5 配置参数详解

目标：讲清 PsiTransfer 2.4.5 全部配置参数的语义、默认值、类型转换规则与修改方式（配置文件挂载 / 环境变量），并给出公网生产配置模板；所有默认值取自镜像内置 config.js，关键参数的行为差异均在本机实测验证。已在 Ubuntu 24.04 LTS（x86_64）+ PsiTransfer 2.4.5（官方镜像 psitrax/psitransfer:2）环境实测通过（2026-11-01）。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• 软件版本：PsiTransfer 2.4.5（镜像标签 psitrax/psitransfer:2，GitHub Releases 最新稳定版，2026-11-01 查询）
• 服务地址：http://192.168.1.172:8130/（宿主 8130 → 服务 3000）
• 部署目录：/opt/psitransfer/（compose 文件与数据目录同置，部署过程见 《PsiTransfer 2.4.5 Docker Compose 部署指南》）
• 配置来源：镜像内置 /app/config.js（默认值）+ 挂载的 /app/config.production.js（覆盖层）+ PSITRANSFER_* 环境变量（最高优先级）

二、前置条件

1. 已按部署指南完成 PsiTransfer 2.4.5 部署并能访问首页（curl http://localhost:8130/ 返回 HTTP 200）；
2. 服务器上可读写 /opt/psitransfer/（修改配置文件与重启服务）；
3. 理解两类运行时配置视图：/config.json 接口只暴露前端相关子集（retentions、大小限制等），服务端全部配置需从配置文件与环境变量层面核对。

三、参数查看与修改方式

3.1 三层配置加载机制

镜像内置 config.js 定义了全部默认值，并按以下顺序逐层合并（逻辑来自内置源码，2026-11-01 实读核对）：

1. 内置默认值：/app/config.js 内 config 对象，勿直接修改（官方注释明确「Do not edit this」）；
2. 环境配置文件：NODE_ENV=production 时加载 /app/config.production.js，以 Object.assign 合并——官方推荐的修改方式；
3. 环境变量：扫描所有 PSITRANSFER_* 环境变量，把 PSITRANSFER_ADMIN_PASS 映射回 adminPass（驼峰转下划线），有值即覆盖——优先级最高。

3.2 环境变量的类型转换规则

环境变量都是字符串，服务端按配置项默认值类型自动转换（内置源码逻辑，逐类实测验证）：

对象类型实测：设置 PSITRANSFER_RETENTIONS={"300":"5 Minutes","604800":"1 Week"} 后重启，/config.json 返回的保留档由 9 档变为：

retentions= {'300': '5 Minutes', '604800': '1 Week'}
defaultRetention= 3600

JSON.parse 生效，保留档集合被整体替换为自定义两档。

3.3 运行时查看生效配置

curl -s http://localhost:8130/config.json | python3 -m json.tool

实测回显（挂载 config.production.js 覆盖后）：

{
    "retentions": {
        "3600": "1 Hour",
        "21600": "6 Hours",
        "86400": "1 Day",
        "259200": "3 Days",
        "604800": "1 Week",
        "1209600": "2 Weeks",
        "2419200": "4 Weeks",
        "4838400": "8 Weeks",
        "one-time": "one time download"
    },
    "defaultRetention": "3600",
    "mailTemplate": "mailto:?subject=File Transfer&body=You can download the files here: %%URL%%",
    "requireBucketPassword": false,
    "maxFileSize": 5242880,
    "maxBucketSize": 1073741824
}

💡 说明：/config.json 是前端上传页的取数接口，只返回 6 个前端消费的参数；port、uploadDir、adminPass 等服务端参数不出现在此接口，需在配置文件/环境变量层核对。

3.4 修改与生效流程

修改 config.production.js 或 compose 环境变量后：

cd /opt/psitransfer
docker compose up -d   # 环境变量变更需重建；仅改配置文件用 restart 亦可
curl -s http://localhost:8130/config.json | python3 -m json.tool   # 复核生效值

四、参数总览

全部配置项、默认值与作用一览（默认值取自镜像内置 config.js 逐行核对）：

内置 retentions 默认 9 档：

五、核心参数分类详解

5.1 网络与服务类（port / iface / baseUrl / uploadAppPath / ssl 三件套 / forceHttps）

服务默认 0.0.0.0:3000 单端口 HTTP。需要调整的场景：

• 容器端口冲突：改 PSITRANSFER_PORT（容器内端口），同步调整 compose 端口映射右值；
• 子路径部署（如 https://example.com/files/ 背后是 PsiTransfer）：前置反代把 /files/ 转发到服务，同时设 baseUrl=/files/，服务生成的下载链接会自动带上前缀；
• 原生 TLS：sslKeyFile/sslCertFile 给出证书路径后服务同时在 sslPort 监听 HTTPS；forceHttps 设为 true（按 Host 头拼 https 地址）或具体 URL（如 https://files.example.com）即可把 HTTP 请求 301 到 HTTPS。

5.2 存储与清理类（uploadDir / retentions / defaultRetention / maxAge）

• uploadDir：全部文件与元数据的根目录，镜像已定向 /data，一般不动；
• retentions：既是界面下拉选项也是上传 API 的合法值集合——上传时 retention 不在集合内会被服务端直接拒绝（实测：retention=999 返回 HTTP 400 与报错）：

HTTP/1.1 400 Bad Request
invalid tus meta prop retention. Value 999 not in [3600,21600,86400,259200,604800,1209600,2419200,4838400,one-time]

自定义集合时注意保留键的格式：时长档用秒数（字符串）作键，一次性档固定用 one-time；

• defaultRetention：前端默认选中的档位，必须是 retentions 的键，否则前端取不到默认值；
• maxAge：兜底清理线——即使是从未被下载的 one-time 文件，超过 75 天（默认）也会被清理扫描删除；缩小该值可加快孤儿 partial 记录回收。

5.3 访问控制类（adminPass / uploadPass / requireBucketPassword）

三层控制逐项实测：

1. adminPass（管理页口令）：false 时 /admin 与 /admin/data.json 整体禁用——实测未设口令时 curl -o /dev/null -w '%{http_code}' http://localhost:8130/admin 返回 404；设为 q1w2e3r4 后重启返回 200。/admin/data.json 接口凭 x-passwd 头认证，实测三态：

curl -s -o /dev/null -w 'no passwd:    HTTP %{http_code}\n' http://localhost:8130/admin/data.json
curl -s -o /dev/null -w 'wrong passwd: HTTP %{http_code}\n' -H 'x-passwd: wrongpass' http://localhost:8130/admin/data.json
curl -s -o /dev/null -w 'right passwd: HTTP %{http_code}\n' -H 'x-passwd: q1w2e3r4' http://localhost:8130/admin/data.json

no passwd:    HTTP 401
wrong passwd: HTTP 403
right passwd: HTTP 200

2. uploadPass（上传口令）：启用后 POST /files、PATCH /files、/config.json 都要求 x-passwd 头。实测（设置 PSITRANSFER_UPLOAD_PASS=upload123 后）：

curl -s -o /dev/null -w 'POST no x-passwd:  HTTP %{http_code}\n' -X POST http://localhost:8130/files -H 'Tus-Resumable: 1.0.0' -H 'Upload-Length: 40'
curl -s -o /dev/null -w 'POST wrong passwd: HTTP %{http_code}\n' -X POST http://localhost:8130/files -H 'x-passwd: bad' -H 'Tus-Resumable: 1.0.0' -H 'Upload-Length: 40'
curl -s -o /dev/null -w 'config right:      HTTP %{http_code}\n' -H 'x-passwd: upload123' http://localhost:8130/config.json

POST no x-passwd:  HTTP 401
POST wrong passwd: HTTP 403
config right:      HTTP 200

无头与错口令的响应均有约 0.5 秒人为延迟（内置防爆破设计）； 3. requireBucketPassword：设为 true 后前端上传页强制填写 bucket 密码（密码在下载清单接口以 AES 密文返回，见 5.5），服务端此开关只影响前端表单校验，属体验性约束。

5.4 大小限制类（maxFileSize / maxBucketSize / maxPreviewSize）

默认全部不限。公网部署必设。实测 PSITRANSFER_MAX_FILE_SIZE=1048576（1MB）后上传 2MB 文件：

curl -s -w '\nHTTP %{http_code}\n' -X POST http://localhost:8130/files -H 'Tus-Resumable: 1.0.0' -H 'Upload-Length: 2097152' -H "Upload-Metadata: name $(echo -n big.bin | base64),sid $(echo -n demobig | base64),retention $(echo -n 604800 | base64)"

{"message":"File exceeds maximum upload size 1048576."}
HTTP 413

maxBucketSize 在同一 bucket 累计体积超限时同样返回 413（Bucket exceeds maximum upload size …）。maxPreviewSize（默认 2MB）只控制下载页弹窗预览的文件大小上限，超过的文件仅提供下载按钮，不影响上传。

5.5 通知与扩展类（fileDownloadedWebhook / fileUploadedWebhook / plugins / mailTemplate）

内置两个插件（由 plugins 数组启用），事件经内部 eventBus 分发：

• file-downloaded-webhook：监听 fileDownloaded 与 archiveDownloaded 事件，向 fileDownloadedWebhook URL POST {"fid": "<sid>", "file": "<文件名>", "date": <毫秒时间戳>}；
• file-uploaded-webhook：监听 fileUploaded 事件，向 fileUploadedWebhook URL POST {"metadata": {…完整上传元数据…}, "date": <毫秒时间戳>}。

通知失败只打印错误日志，不影响上传/下载主流程。mailTemplate 是前端「邮件分享」按钮生成的 mailto 链接模板，%%URL%% 占位符会被替换为下载页地址。

💡 技术拓展：事件通知的常见实现路径对比——

路径	原理	适用
应用内 Webhook（本文所用）	应用自身向回调 URL 发 POST	无外部组件，秒级接入
访问日志轮询	分析 accessLog 中下载请求	免侵入但延迟高
文件系统 inotify	监听数据目录变化	与应用解耦但拿不到业务元数据

本文采用应用内 Webhook：PsiTransfer 内置插件开箱即用，元数据（bucket、文件名、时间）完整，是三者中集成成本最低的。

5.6 日志与语言类（accessLog / defaultLanguage）

• accessLog：默认 :date[iso] :method :url :status :response-time :remote-addr（morgan 格式）。实测日志样例（访问 /config.json 时）：

2026-11-01T02:58:54.953Z GET /config.json 200 1.805 10.89.66.1

设为 false 可关闭访问日志；设为 dev 启用 morgan 开发者彩色格式（仅建议调试用）；

• defaultLanguage：默认 en，内置语言包仅 en/de 两个文件（/app/lang/），中文界面需自行新增语言文件并覆盖该参数。

六、生产配置模板

适用于「公网可访问、8GB 内存、SSD 磁盘、日上传峰值 10GB 级」的通用场景，两个文件配合使用：

/opt/psitransfer/config.production.js：

module.exports = {
  // 保留档：保留官方 9 档即可，按需增删（键为秒数字符串，one-time 固定）
  // defaultRetention 必须是下方键之一
  defaultRetention: "604800",
  // 单文件 10GB、单 bucket 20GB：大文件分享服务的主流上限
  maxFileSize: Math.pow(2, 30) * 10,
  maxBucketSize: Math.pow(2, 30) * 20,
  // 预览上限 2MB（默认即可，明确写出便于复核）
  maxPreviewSize: Math.pow(2, 20) * 2,
  // 兜底清理线：30 天未处理文件一律回收（默认 75 天偏长）
  maxAge: 3600 * 24 * 30,
};

compose environment 段（与配置文件叠加，环境变量优先）：

    environment:
      - NODE_ENV=production
      - PSITRANSFER_ADMIN_PASS=q1w2e3r4        # 生产请替换为强口令
      - PSITRANSFER_UPLOAD_PASS=q1w2e3r4       # 生产请替换为强口令
      - PSITRANSFER_FILE_DOWNLOADED_WEBHOOK=http://192.168.1.172:9000/hooks/psitransfer-download

模板要点解读：

1. 大小限制（maxFileSize/maxBucketSize）双管齐下，防单请求与累计两种撑爆路径；
2. maxAge 缩到 30 天，控制孤儿 partial 与滞留文件的磁盘占用；
3. 上传口令 + 管理口令都启用，管理页提供 bucket 巡检视图；
4. 下载 Webhook 指向内部接收端，便于把「文件已被下载」事件接进工单/IM 通知流。

修改后复核：

cd /opt/psitransfer && docker compose up -d
curl -s http://localhost:8130/config.json | python3 -m json.tool

实测回显（节选）：

    "maxFileSize": 10737418240,
    "maxBucketSize": 21474836480

七、常见问题

Q1：改了 retentions 后老文件还能正常下载吗？

能。retentions 只在上传时校验新请求的合法性，存量文件的保留档按其元数据继续生效；但集合整体替换会让「集合外档位」的老文件在界面显示上失去档位名。不建议缩小官方默认集合，如需自定义在官方 9 档基础上增补。

Q2：PSITRANSFER_RETENTIONS 用了非 JSON 字符串会怎样？

对象类型走 JSON.parse，非法 JSON 会在启动加载环境变量阶段抛异常导致服务起不来。修正环境变量值后 docker compose up -d 重建即可；这也是「环境变量优先级高」的双刃剑——排查启动失败先看环境变量里 JSON 类参数的合法性。

Q3：日志里周期性出现 NotFoundError: Not Found at Store.info (/app/lib/store.js:65)？

实测完整堆栈：

NotFoundError: Not Found
    at Store.info (/app/lib/store.js:65:26)
    at async /app/lib/db.js:80:20

这是清理扫描对「元数据仍在、文件本体已不存在」的记录（如从未传完的 partial，或 one-time 下载完成瞬间）做信息读取时抛出的噪音报错，服务主流程不受影响（监听与上传下载均正常）。消除思路：缩短 maxAge 让 partial 记录尽快被回收，或按部署指南「常见问题 Q5」手动清理孤儿文件。

Q4：defaultRetention 设成了 retentions 里没有的键会怎样？

/config.json 会把该值原样下发给前端，但前端在下拉框中匹配不到对应档位，表现为上传页默认档显示异常。务必保证 defaultRetention ∈ Object.keys(retentions)，改完用 3.3 的接口复核。

Q5：forceHttps 与反向代理如何配合？

forceHttps 生效时服务自动启用 trust proxy，按 X-Forwarded-Proto 判断请求是否已安全。反代终止 TLS 时：反代侧需正确传递 X-Forwarded-Proto 头，服务侧 forceHttps 设为跳转目标 URL；若反代已强制 HTTPS，服务端可不启用 forceHttps 以省一次跳转。

八、参考链接

• 官方仓库：https://github.com/psi-4ward/psitransfer （README 配置章节，2026-11-01 查询）
• 镜像内置配置源码：/app/config.js、/app/lib/endpoints.js（2.4.5 版实测读取）
• 保留时长说明：https://github.com/psi-4ward/psitransfer/tree/master/docs （官方文档目录）
• 本专栏配套：《PsiTransfer 2.4.5 Docker Compose 部署指南》、《PsiTransfer 2.4.5 介绍与选型指南》、《PsiTransfer 2.4.5 常用 CLI 命令与工具详解》