transfer.sh 1.6.1 配置参数详解
逐项讲解 transfer.sh v1.6.1 全部 40 余个启动参数与环境变量：flag 与环境变量两种传参方式及同设优先级、全量参数总览、监听/存储/限流/访问控制/TLS/自动清理/日志观测分类详解与实测验证，附 systemd 生产配置模板与常见问题排障，全部行为已在 Ubuntu 22.04 实测。
transfer.sh 1.6.1 配置参数详解
> 目标：逐项讲清 transfer.sh v1.6.1 服务端 transfersh 的全部启动参数与环境变量——两种传参方式与同设时的优先级、全量参数总览、按监听/存储/限流/访问控制/TLS/自动清理/日志观测分类的实测验证，最后给出 systemd 生产配置模板与常见问题。全部行为均已在下述环境实测验证。
一、环境信息
本文所有实测在以下环境完成：
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- 组件版本：transfer.sh v1.6.1（单文件静态编译的 Go 二进制，
transfersh一个文件即服务端本体） - 二进制来源：官方 GitHub Releases 的
transfersh-v1.6.1-linux-amd64，sha256 校验值46fb5ac519769bae8a626cc3f79e2101013ff13beb75d5a613b8df6970d9e27c - 二进制路径：
/opt/transfer.sh/bin/transfersh - 数据目录：
/opt/transfer.sh/data - 服务器地址：
192.168.1.172（下文示例端口均为实测端口，可按需替换）
版本验证命令与实测回显：
grep PRETTY_NAME /etc/os-release; uname -m
PRETTY_NAME="Ubuntu 22.04.5 LTS"
x86_64
/opt/transfer.sh/bin/transfersh version
transfer.sh version v1.6.1
部署方式（Compose 编排）见《transfer.sh 1.6.1 Docker Compose 部署指南》；组件本身的定位与选型背景见《transfer.sh 介绍与选型指南》。本文聚焦服务端参数本身，与部署载体无关，直接在服务器上运行二进制的方式讲解。
二、前置条件
transfersh二进制已下载并校验（官方 Releases 页面获取，sha256sum比对），放置于/opt/transfer.sh/bin/并赋予执行权限：chmod +x /opt/transfer.sh/bin/transfersh- 数据目录已创建（local 存储后端的落盘位置，属主为运行服务的用户）：
mkdir -p /opt/transfer.sh/data - 规划服务端口并确认未占用（
ss -ltn | grep <端口>应无输出）； - 如使用 systemd 托管，准备运行用户（本文用
transfersh）：useradd -r -s /sbin/nologin transfersh chown -R transfersh:transfersh /opt/transfer.sh/data
三、参数查看与修改方式
3.1 用 --help 查看全量参数
/opt/transfer.sh/bin/transfersh --help
实测完整回显见第四章参数总览（原文照抄）。
3.2 两种传参方式：命令行 flag 与环境变量
--help 里每个参数末尾都标注了对应的环境变量名（如 [$LISTENER]、[$PROVIDER]），两者完全等价，选一种即可。实测用环境变量方式启动（等价于 --provider local --listener :8143 --rate-limit 3 --temp-path /tmp --basedir /opt/transfer.sh/data）：
PROVIDER=local LISTENER=:8143 RATE_LIMIT=3 TEMP_PATH=/tmp BASEDIR=/opt/transfer.sh/data \
/opt/transfer.sh/bin/transfersh
[transfer.sh]2026/11/01 06:56:52 Transfer.sh server started.
using temp folder: /tmp/
using storage provider: local
[transfer.sh]2026/11/01 06:56:52 starting to listen on: :8143
[transfer.sh]2026/11/01 06:56:52 ---------------------------
启动日志会回显实际生效的临时目录、存储后端与监听地址，可用于确认参数生效。
3.3 flag 与环境变量同时设置时的优先级
同一参数既有环境变量又有 flag 时，flag 优先。实测验证：环境变量 RATE_LIMIT=100 配合 flag --rate-limit 2 启动，随后连续下载同一文件：
RATE_LIMIT=100 /opt/transfer.sh/bin/transfersh \
--provider local --basedir /opt/transfer.sh/data --listener :8142 --rate-limit 2 &
for i in 1 2 3 4; do curl -s -o /dev/null -w "dl$i: HTTP %{http_code}\n" http://127.0.0.1:8142/fzsvVtAgMe/prio.txt; done
dl1: HTTP 200
dl2: HTTP 200
dl3: HTTP 429
dl4: HTTP 429
第 3 个请求即被限流，证明生效的是 flag 的 2（每分钟 2 个请求）而非环境变量的 100。排查"限流没生效"类问题时优先检查是否有 flag 被环境变量覆盖（或反之）。
四、参数总览
以下是 transfersh --help 的完整实测回显（v1.6.1），即全部可配置参数的一手清单：
NAME:
transfer.sh - transfer.sh
DESCRIPTION:
Easy file sharing from the command line
USAGE:
transfer.sh [flags] command [arguments...]
COMMANDS:
version
help, h Shows a list of commands or help for one command
FLAGS:
--listener value 127.0.0.1:8080 (default: "127.0.0.1:8080") [$LISTENER]
--profile-listener value 127.0.0.1:6060 [$PROFILE_LISTENER]
--force-https (default: false) [$FORCE_HTTPS]
--tls-listener value 127.0.0.1:8443 [$TLS_LISTENER]
--tls-listener-only (default: false) [$TLS_LISTENER_ONLY]
--tls-cert-file value [$TLS_CERT_FILE]
--tls-private-key value [$TLS_PRIVATE_KEY]
--temp-path value path to temp files (default: "/tmp") [$TEMP_PATH]
--web-path value path to static web files [$WEB_PATH]
--proxy-path value path prefix when service is run behind a proxy [$PROXY_PATH]
--proxy-port value port of the proxy when the service is run behind a proxy [$PROXY_PORT]
--email-contact value email address to link in Contact Us (front end) [$EMAIL_CONTACT]
--ga-key value key for google analytics (front end) [$GA_KEY]
--uservoice-key value key for user voice (front end) [$USERVOICE_KEY]
--provider value s3|gdrive|local [$PROVIDER]
--s3-endpoint value [$S3_ENDPOINT]
--s3-region value (default: "eu-west-1") [$S3_REGION]
--aws-access-key value [$AWS_ACCESS_KEY]
--aws-secret-key value [$AWS_SECRET_KEY]
--bucket value [$BUCKET]
--s3-no-multipart Disables S3 Multipart Puts (default: false) [$S3_NO_MULTIPART]
--s3-path-style Forces path style URLs, required for Minio. (default: false) [$S3_PATH_STYLE]
--gdrive-client-json-filepath value [$GDRIVE_CLIENT_JSON_FILEPATH]
--gdrive-local-config-path value [$GDRIVE_LOCAL_CONFIG_PATH]
--gdrive-chunk-size value (default: 16) [$GDRIVE_CHUNK_SIZE]
--storj-access value Access for the project [$STORJ_ACCESS]
--storj-bucket value Bucket to use within the project [$STORJ_BUCKET]
--rate-limit value requests per minute (default: 0) [$RATE_LIMIT]
--purge-days value number of days after uploads are purged automatically (default: 0) [$PURGE_DAYS]
--purge-interval value interval in hours to run the automatic purge for (default: 0) [$PURGE_INTERVAL]
--max-upload-size value max limit for upload, in kilobytes (default: 0) [$MAX_UPLOAD_SIZE]
--lets-encrypt-hosts value host1, host2 [$HOSTS]
--log value /var/log/transfersh.log [$LOG]
--basedir value path to storage [$BASEDIR]
--clamav-host value clamav-host [$CLAMAV_HOST]
--perform-clamav-prescan perform-clamav-prescan (default: false) [$PERFORM_CLAMAV_PRESCAN]
--virustotal-key value virustotal-key [$VIRUSTOTAL_KEY]
--profiler enable profiling (default: false) [$PROFILER]
--http-auth-user value user for http basic auth [$HTTP_AUTH_USER]
--http-auth-pass value pass for http basic auth [$HTTP_AUTH_PASS]
--http-auth-htpasswd value htpasswd file http basic auth [$HTTP_AUTH_HTPASSWD]
--http-auth-ip-whitelist value comma separated list of ips allowed to upload without being challenged an http auth [$HTTP_AUTH_IP_WHITELIST]
--ip-whitelist value comma separated list of ips allowed to connect to the service [$IP_WHITELIST]
--ip-blacklist value comma separated list of ips not allowed to connect to the service [$IP_BLACKLIST]
--cors-domains value comma separated list of domains allowed for CORS requests [$CORS_DOMAINS]
--random-token-length value (default: 10) [$RANDOM_TOKEN_LENGTH]
--help, -h show help
--version, -v print the version
VERSION:
v1.6.1
按用途分组索引（详见第五章）：
| 分组 | 参数 |
|---|---|
| 监听与网络入口 | --listener、--tls-listener、--tls-listener-only、--force-https、--lets-encrypt-hosts、--proxy-path、--proxy-port |
| 存储后端与数据 | --provider、--basedir、--temp-path、--s3-*、--gdrive-*、--storj-* |
| 上传限制与令牌 | --max-upload-size、--random-token-length、--rate-limit |
| 自动清理 | --purge-days、--purge-interval |
| 访问控制 | --ip-whitelist、--ip-blacklist、--http-auth-user、--http-auth-pass、--http-auth-htpasswd、--http-auth-ip-whitelist、--cors-domains |
| 安全扫描 | --clamav-host、--perform-clamav-prescan、--virustotal-key |
| TLS | --tls-listener、--tls-cert-file、--tls-private-key、--force-https、--lets-encrypt-hosts |
| 日志与观测 | --log、--profiler、--profile-listener |
| 前端与反代 | --web-path、--proxy-path、--proxy-port、--email-contact、--ga-key、--uservoice-key |
五、核心参数分类详解
5.1 监听与网络入口（--listener）
--listener 是主服务监听地址，默认 127.0.0.1:8080——只监听本机回环，对外提供服务必须显式改为 :端口 或 0.0.0.0:端口，否则外部无法访问。这是"服务起了但连不上"的头号原因。
--tls-listener 默认 127.0.0.1:8443，配置证书文件后成为独立的 HTTPS 监听口，与 --listener 可并存（同一进程双端口），实测同时启动两个监听：
/opt/transfer.sh/bin/transfersh --provider local --basedir /opt/transfer.sh/data \
--listener :8141 --tls-listener :8146 \
--tls-cert-file /etc/transfer.sh/tls.crt --tls-private-key /etc/transfer.sh/tls.key
[transfer.sh]2026/11/01 04:39:18 Transfer.sh server started.
using temp folder: /tmp/
using storage provider: local
[transfer.sh]2026/11/01 04:39:18 starting to listen on: :8141
[transfer.sh]2026/11/01 04:39:18 starting to listen for TLS on: :8146
[transfer.sh]2026/11/01 04:39:18 ---------------------------
两个监听口的服务能力完全一致（上传/下载均可），TLS 口的行为验证见 5.7。
5.2 存储后端与数据目录（--provider、--basedir、--temp-path）
--provider 支持四种存储后端：local（本地磁盘）、s3（含 MinIO，配合 --s3-path-style）、gdrive（Google Drive）、storj。注意 --help 文案只写了 s3|gdrive|local，v1.6.1 实际已支持 storj（--storj-access/--storj-bucket 参数存在，配置不完整时的启动报错也可证，见下）。
--provider local 时 --basedir 必填，缺失直接拒绝启动：
/opt/transfer.sh/bin/transfersh --provider local --listener :8144
2026/11/01 07:08:35 basedir not set.
--provider 取值非法或对应凭据缺失时同样拒绝启动，实测三次不完整配置的启动报错（三条来自三次独立启动尝试）：
2026/11/01 04:25:51 storj-access not set.
2026/11/01 04:25:51 gdrive-client-json-filepath not set.
2026/11/01 04:25:51 Provider not set or invalid.
--temp-path（默认 /tmp）用于上传过程中的临时落盘，启动日志 using temp folder: /tmp/ 即其回显。大文件上传时确保该分区有足够空间。
local 后端的落盘结构为「--basedir 下每个上传一个以随机 token 命名的一级子目录，目录内是文件本体 + 同名 .metadata 元数据文件」，元数据是单行 JSON，实测内容示例：
{"ContentType":"","ContentLength":50,"Downloads":0,"MaxDownloads":-1,"MaxDate":"2026-11-02T06:49:47.761965554Z","DeletionToken":"eR4MJDEL5aY7ElAoVGz0","Encrypted":false,"DecryptedContentType":""}
了解该结构有助于排查过期、下载数等行为（它们的真实状态都记录在这里）。
5.3 上传限制与链接令牌（--max-upload-size、--random-token-length、--rate-limit）
--max-upload-size：单文件上传上限，单位 KB，默认 0（不限制）。实测设为 5（即 5KB）后：10KB 文件上传被拒、3KB 文件正常：
curl -s -w '\nHTTP:%{http_code}\n' --upload-file big.bin http://127.0.0.1:8137/big.bin # 10KB
Request Entity Too Large
HTTP:413
http://127.0.0.1:8137/cdNNrlEEnW/small.bin
HTTP:200
--random-token-length：下载链接中随机 token 的长度，默认 10（如 fYdpkLW5X8）。实测改为 4 后链接明显变短（X-Url-Delete 响应头可见 token 部分）：
X-Url-Delete: http://192.168.1.172:8139/Bmqj/short.txt/6MtryP1N
token 越短链接越好记，但被碰撞/穷举的风险越高，公网服务建议保持默认 10。
--rate-limit：全站每分钟请求数上限，默认 0（不限制）。实测环境变量 RATE_LIMIT=3 启动后，连续下载同一文件 5 次：
dl1: HTTP 200
dl2: HTTP 200
dl3: HTTP 200
dl4: HTTP 429
dl5: HTTP 429
计数按分钟滑动窗口对所有请求生效（含下载与上传），触发后返回 429。与环境变量同设时 flag 优先（实证见 3.3）。
5.4 自动清理（--purge-days、--purge-interval）
两个参数必须同时配置且都大于 0 才启用自动清理（只配其一不生效）：
--purge-days：上传文件保留天数，超过即被清理；--purge-interval：清理巡检的间隔，单位小时。
源码实现语义（v1.6.1）：清理器用固定间隔的 ticker 驱动——第一次巡检发生在服务启动后 --purge-interval 小时，之后每隔同样时间一次；local 后端的清理判定依据是文件修改时间（mtime），早于"当前时间减 --purge-days 天"的文件被删除。注意两点推论：
- 改完参数不会立刻清理，最多要等一个完整 interval 周期；
- 清理看的是文件系统 mtime，不是元数据里的 MaxDate——手工搬动过数据目录会改变清理结果。
实测验证（--purge-days 1 --purge-interval 1，独立数据目录）：上传后把数据目录内该文件的 mtime 回拨到 2 天前：
-rw------- 1 root root 186 Oct 30 06:53 /tmp/purge-data/Fblmxc2i6a/purgetest.txt.metadata
-rw------- 1 root root 13 Oct 30 06:53 /tmp/purge-data/Fblmxc2i6a/purgetest.txt
等待启动后第一个巡检周期（实测首跳时刻=启动时间+interval，本例约 1 小时）后检查数据目录，超期的文件本体与 .metadata 均被删除，空目录会保留（清理只删文件），实测结论与源码语义一致。
另一种"过期"是单次上传级别的 Max-Days / Max-Downloads（在 curl 上传时通过请求参数指定，不属于启动参数），与本章的服务级 purge 互不冲突：前者只影响单个链接的可用性（过期后下载返回 404，实测见《transfer.sh 1.6.1 curl 上传下载命令详解》），后者批量清理磁盘文件。
5.5 访问控制（ip 白/黑名单、HTTP Basic 认证、CORS）
--ip-whitelist / --ip-blacklist：按客户端源 IP 精确匹配的连接级放行/拒绝名单（逗号分隔，不能写网段）。实测 --ip-whitelist 127.0.0.1：
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8144/ # 白名单内
HTTP 200
curl -s -w "\nHTTP %{http_code}\n" http://10.89.58.3:8144/ | tail -2 # 本机另一网络接口地址，白名单外
HTTP 403
非白名单源一律 403 Forbidden（黑名单同理拒绝）。两个要点：
- 匹配是逐 IP 精确匹配，多网卡服务器要放行本机访问需把每个接口地址都写进去；
- 客户端 IP 取值信任
X-Forwarded-For请求头——实测对黑名单 IP 的请求伪造X-Forwarded-For: 8.8.8.8后上传成功（HTTP 200）。因此 ip 黑白名单只应在服务前没有不可信访问者能直连时使用，或部署在会清洗 XFF 的可信反代之后（配合--proxy-path/--proxy-port）。
--http-auth-user / --http-auth-pass：全局 HTTP Basic 认证（上传/下载都要带凭据）。实测 admin/q1w2e3r4 三种请求结果：
无凭据 → Not authorized / HTTP 401
admin:badpass → Not authorized / HTTP 401
admin:q1w2e3r4 → HTTP 200
--http-auth-htpasswd：改用 htpasswd 文件认证（支持多用户，apr1/bcrypt 等哈希由 go-htpasswd 库解析）。生成方式：
openssl passwd -apr1 -salt ts161salt q1w2e3r4
文件每行一条 用户名:哈希，实测内容：
admin:$apr1$ts161sal$6CNCex5SESDLSuqclsqZ50
配置后实测：无凭据 401、正确凭据 200、错误凭据 401。user/pass 与 htpasswd 可以同时配置，校验时两者任一通过即放行。
--http-auth-ip-whitelist：认证白名单——名单内的源 IP 完全免认证。实测对 --http-auth-user admin --http-auth-pass q1w2e3r4 --http-auth-ip-whitelist 127.0.0.1 的实例，本机回环地址不带任何凭据上传成功（HTTP 200），外部地址仍要求凭据。适合"本机脚本免认证、外部需密码"的场景。
--cors-domains：允许跨域的域名列表。关键细节：必须写完整 Origin（含协议，如 http://example.com），且精确匹配。实测 --cors-domains 'http://example.com,http://192.168.1.172:8134' 后：
匹配 Origin 的上传响应头：
HTTP/1.1 100 Continue
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://example.com
OPTIONS 预检请求响应：
HTTP/1.1 200 OK
Access-Control-Allow-Methods: PUT
Access-Control-Allow-Origin: http://example.com
不匹配的 Origin（如 http://evil.com）请求本身仍 200，但响应中不会出现 Access-Control-Allow-Origin 头，浏览器侧会被拦截。常见错误是只写裸域名 example.com（无协议）——永远不会匹配，浏览器报 CORS 错误。
5.6 TLS 与 HTTPS（--tls-listener、--tls-cert-file、--tls-private-key、--force-https、--lets-encrypt-hosts）
5.1 已展示双监听配置。HTTPS 口验证（自签证书场景 curl 加 -k）：
curl -sk -w '\nHTTP:%{http_code}\n' --upload-file hello.txt https://192.168.1.172:8146/tlsfile.txt
https://192.168.1.172:8146/ordcqqgQ2V/tlsfile.txt
HTTP:200
--force-https 把 HTTP 口的所有请求 308 重定向到 HTTPS 口（所以两者要一起配置）：
HTTP/1.1 308 Permanent Redirect
Location: https://192.168.1.172:8146/plain.txt
Content-Length: 0
--tls-listener-only 让服务只保留 TLS 监听、关闭明文口。--lets-encrypt-hosts 提供 ACME 自动证书（填域名，如 share.example.com），要求域名能解析到本机且 80/443 可达，实测用假域名时服务正常启动、证书签发会在 ACME 环节失败——生产使用需真实域名与公网可达性。
5.7 安全扫描（--virustotal-key、--clamav-host、--perform-clamav-prescan）
transfer.sh 内置对 /<文件名>/virustotal 与 /<文件名>/clamav 两类扫描上传端点的支持（把文件提交给第三方扫描服务，按结果决定是否存储）。
VirusTotal：需配置 --virustotal-key（官网申请的 API key）。未配 key 时调用该端点实测返回 500：
invalid character '<' looking for beginning of value
HTTP:500
服务端日志同步记录了提交动作（无 key 时提交失败）：
[transfer.sh]2026/11/01 06:49:48 Submitting to VirusTotal: hello.txt 50
[transfer.sh]2026/11/01 06:49:50 scanid: , resource: , permalink: , md5:
[transfer.sh]2026/11/01 06:49:50 192.168.1.172:35964 - - [2026-11-01T06:49:50Z] "PUT /hello.txt/virustotal HTTP/1.1" 500 "" "curl/8.5.0"
ClamAV：--clamav-host 指向 clamd 的 TCP 地址（如 127.0.0.1:3310），--perform-clamav-prescan 开启后对所有上传先扫描再入库，检出病毒即拒绝。需要环境内已有 clamd 服务，本文未单独实测该链路。
普通上传（不带 virustotal/clamav 后缀）不受这两个参数影响。
5.8 日志与观测（--log、--profiler、--profile-listener）
--log：日志落盘文件路径（默认 /var/log/transfersh.log）。日志包含启动信息与每条请求的访问记录（含来源 IP、方法、路径、状态码、UA），排障时直接定位问题请求，实测片段：
[transfer.sh]2026/11/01 06:49:47 Error metadata: maxDate expired
[transfer.sh]2026/11/01 06:49:47 192.168.1.172:35948 - - [2026-11-01T06:49:47Z] "GET /usvdNeBMoS/expired.txt HTTP/1.1" 404 "" "curl/8.5.0"
注意运行用户需对该路径有写权限，否则日志不落盘（服务本身不受影响）。
--profiler：开启 Go pprof 性能剖析端点。这里有一个 v1.6.1 的实现细节需要特别提醒：剖析端点固定监听 :6060，--profile-listener 参数实际上不生效。实测 --profiler --profile-listener :8148 启动日志明确写着：
[transfer.sh]2026/11/01 07:09:34 Profiled listening at: :6060
随后 :8148 无任何监听，而 :6060 的 pprof 端点正常工作：
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:6060/debug/pprof/
HTTP 200
两个结论：想用 pprof 就按 :6060 访问；--profile-listener 想改端口是改不动的（防暴露考虑，不要把 6060 暴露到公网）。
5.9 前端与反代（--web-path、--proxy-path、--proxy-port 等）
--web-path：自定义静态页面目录（替换内置的网页界面），用于品牌定制；不配置时使用二进制内置页面。--proxy-path/--proxy-port：服务部署在反向代理之后时，告知真实对外路径前缀与端口，服务据此生成正确的绝对链接（如 X-Url-Delete 头）；同时反代需正确传递X-Forwarded-For，ip 黑白名单的判定才会基于真实客户端 IP（见 5.5 的伪造风险提醒）。--email-contact/--ga-key/--uservoice-key：纯前端展示项——页面 Contact Us 链接邮箱、Google Analytics、UserVoice 挂件，不影响服务功能，按需配置。
六、生产配置模板（systemd 托管 + 参数组合建议）
推荐用 systemd 托管 transfersh 进程。/etc/systemd/system/transfersh.service 模板：
[Unit]
Description=transfer.sh file sharing service
After=network.target
[Service]
User=transfersh
Group=transfersh
ExecStart=/opt/transfer.sh/bin/transfersh \
--listener :8080 \
--provider local \
--basedir /opt/transfer.sh/data \
--temp-path /tmp \
--log /var/log/transfersh.log \
--max-upload-size 102400 \
--rate-limit 120 \
--random-token-length 10 \
--purge-days 14 \
--purge-interval 6
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
参数选值依据（均对应第五章实测行为）：
| 参数 | 建议值 | 理由 |
|---|---|---|
--listener :8080 | 显式监听全部地址 | 默认 127.0.0.1:8080 对外不可访问（5.1） |
--provider local --basedir | local + 专用数据目录 | 单机自托管最简形态，目录属主给 transfersh 用户 |
--max-upload-size | 按需（示例 100MB） | 防止磁盘被单次大上传打满，单位 KB |
--rate-limit | 按负载设定 | 全站每分钟请求上限，超限 429（5.3） |
--random-token-length | 保持 10 | 链接不可枚举，缩短有穷举风险（5.3） |
--purge-days + --purge-interval | 成对配置（14 天/6 小时） | 只配其一不生效；首跳在启动后一个 interval（5.4） |
--log | 落盘到专用路径 | 访问日志排障依赖（5.8） |
启用与验证：
systemctl daemon-reload
systemctl enable --now transfersh
systemctl status transfersh --no-pager | head -5
如需认证再追加 --http-auth-user admin --http-auth-pass q1w2e3r4（或 --http-auth-htpasswd），如需 HTTPS 追加 TLS 三件套参数（5.6/5.5）。本文参数与部署载体无关，若采用其他部署形态，参数传入口径见《transfer.sh 1.6.1 Docker Compose 部署指南》第四章。
七、常见问题
Q1：启动直接退出，报 basedir not set.
--provider local 必须同时给 --basedir（5.2）。补上即可。
Q2：启动报 Provider not set or invalid.
--provider 没传或拼写错误；传了 s3/gdrive/storj 但对应凭据参数缺失也会得到类似的 xxx not set. 报错（5.2）。
Q3：设置了 --rate-limit 但好像没生效
检查是否被环境变量与 flag 同设干扰——flag 优先（3.3）。另外限流按"每分钟全站请求数"计数，单发请求测不出来，需连发复现。
Q4：--profile-listener 指定的端口没有监听
v1.6.1 的 pprof 端点固定 :6060，--profile-listener 不生效（5.8）。
Q5：ip-blacklist 拉黑了某 IP 但它还能上传
该客户端可能伪造了 X-Forwarded-For 头——IP 判定信任 XFF（5.5）。把服务放进会清洗 XFF 的可信反代之后，或改用认证方案。
Q6：Max-Days 传了负数报 400，传超大值却不报错？
负值返回 400 Invalid MaxDate, make sure Max-Days is smaller than 290 years；数值大到溢出 int64 时会被静默忽略（上传仍 200，但过期限制实际未设置，X-Remaining-Days 显示 n/a）。这是 v1.6.1 对参数解析边界的真实行为，业务上需对 Max-Days 取值做前置校验。请求级 Max-Days/Max-Downloads 的完整行为见《transfer.sh 1.6.1 curl 上传下载命令详解》。
Q7：配了 --cors-domains 浏览器仍报 CORS 错误
域名必须带协议完整写出（如 http://example.com），裸域名不匹配（5.5）。
Q8：配了 --purge-days 文件没被清理
确认 --purge-interval 也已配置且大于 0（两者缺一不生效）；确认已等待至少一个完整 interval 周期（首跳在启动后 N 小时，5.4）。
Q9：服务起了但外部访问不通
检查 --listener 是否还是默认 127.0.0.1:8080（5.1），改为 :端口 后重启。
八、参考链接
- 本系列：《transfer.sh 介绍与选型指南》
https://www.quzuo.net/document/nn7i2cwAAhTV、《transfer.sh 1.6.1 Docker Compose 部署指南》https://www.quzuo.net/document/k8d8smHJIjJx、《transfer.sh 1.6.1 curl 上传下载命令详解》https://www.quzuo.net/document/izkelRSBTntz - 官方仓库：
https://github.com/dutchcoders/transfer.sh（README 含参数表） - 版本发布页：
https://github.com/dutchcoders/transfer.sh/releases/tag/v1.6.1