Skip to Content
TSLinkTSLink 文档

让别人往我的 Mac 传大文件

在本机运行 copyparty 这类上传应用,调高 TSLink 默认 32 MiB 的请求上限,再发一个会到期的访客链接。照片和文档没问题,几十 GB 走 Funnel 太慢。

最后更新于

查看 Markdown

TSLink 不提供上传页面,所以要先在 Mac 上运行一个能接收上传的 Web 应用(比如 copyparty),让它只监听本机,再在前面挂一个 TSLink 访客链接。上传方用浏览器打开链接,不需要任何账号,到你设定的截止时间或你撤销为止。TSLink 的请求上限要比应用的最大单个请求还大,否则大一些的请求会收到 HTTP 413。 假设上传应用已经在 127.0.0.1:3923 上监听:

bash
tslink add uploads --proxy localhost:3923 --max-request-body 128MiB --request-read-timeout 2m
tslink guest create uploads --for 3d --label "Footage from Sam" --public --print-link

需要 TSLink v0.4.0 或更新版本;在新安装上,第一条访客链接还会把应用从 home gateway 上摘下来。文件写到上传应用指定的磁盘位置。TSLink 是独立项目,并非由 Tailscale 出品。

这里的大文件指几个 GB,不是几十 GB。 访客链接经 Tailscale Funnel 传输,Tailscale 说明 Funnel 有不可配置的带宽限制。2026-11-11 我们经 Funnel 做的上传测试里,单个 curl 上传是 0.65 到 0.84 MB/s,浏览器持续上传是 0.8 到 1.5 MB/s,同一路径走 tailnet 大约 35 MB/s;按约 1 MB/s 算,1 GB 大约 15 到 20 分钟,10 GB 大约 3 小时,40 GB 要 11 小时以上。这只是一天的结果,不是保证。特别大的传输,请用传输服务或者走私有路径:发送方装上 Tailscale,你给他按人授权的访问,授权对象是指向同一个上传服务的第二个私有应用:

bash
tslink add uploads-private --proxy localhost:3923 --max-request-body 128MiB --request-read-timeout 2m
tslink people add sam@example.com --apps uploads-private --for 3d --print-links

访客 gate 生效期间,应用不能新增人员授权(people_service_unsupported),所以要另起一个名字。people add 会对照 tailnet 的用户目录核对登录名,对 tailnet 之外的人还会创建设备邀请;这两步都需要已保存的用户级 Tailscale API token(tslink login),否则会报告设置未完成。发送方装上 Tailscale、登录,再接受你发过去的邀请。

设定请求上限

没有单独设置的 TSLink HTTP 应用,单个请求体上限是 32 MiB,读取空闲窗口 30 秒,请求头超时 10 秒。超出上限的请求收到 HTTP 413,停滞的上传收到 HTTP 408。上限针对每个请求,不针对整次传输:

  • 分块上传器每个分块发一个请求。copyparty 默认分块目标 64 MiB、最大 96 MiB,它的 u2sz 说明建议把代理的请求上限调到至少 96 MiB,或者用 --u2sz 调小分块(它认为 32 仍然可以接受)。默认分块下,128MiB 是合理的上限,它限制的是访客单个请求能发多少。上面那次测试里,用 TSLink 默认的 32 MiB 时,每个分块都收到 413:页面一直显示有传输速度,服务器上却什么都没存下。调高上限,或者把 --u2sz 设到上限以下。
  • 普通 HTML 表单把整个文件放在一个请求里,上限要大于最大的文件加上表单元数据。
  • --request-read-timeout 2m 给停顿超过 30 秒的手机留出余量。它计算的是没有进展的时间,不是总上传时长。
  • 去掉上限要同时写 --max-request-body unlimited --ack-unlimited-request-body。

能在 tslink add 里定好就先定好。链接建好以后要改上限,用 tslink limits set,它只改上限,目标、访问权限、路由、健康检查、--preserve-host、访客 gate 和已入网节点都不变:

bash
tslink limits set uploads --max-request-body 256MiB
tslink url uploads --wait

它会重启这个应用的节点:进行中的上传会中断,上传方要重新打开链接(设了 PIN 的话再输一次)。命令在重启完成前就返回,等 tslink url 有输出后再让对方重试。TSLink 会拒绝对带访客链接的应用执行 tslink add。guest create 会打印应用当前的上限;超出上限的上传会收到写明上限的 JSON 413,tslink status 和 tslink doctor 会统计拒绝次数,并给出调高上限的命令。详见健康检查与请求上限。

选择并配置上传应用

TSLink 只负责转发请求;接收文件、决定存放位置、处理中断的传输,都是上传应用的事。copyparty 是一个选择:单个程序,按它的上传文档,浏览器上传器会把文件切成带校验的分块,网络中断后可以续传。

我们测试过的 copyparty 配置和实测数据见接收大文件。简单说,配置成下面这样:

  • 只监听本机。 copyparty 的 -i 指定监听地址,默认是所有 IPv4 和 IPv6 网卡(见 --help 源码);设为 127.0.0.1 后,同一网络里的其他设备就无法绕过 TSLink 直接访问。
  • 只能上传,不能浏览。 copyparty 的 w 权限允许访客往文件夹里上传,但看不到其中的内容(见账号与卷)。
  • 隐藏机器信息。 -nih 去掉界面上的主机名,-nid 隐藏磁盘用量,效果等同 --du-who no(单横线,见 --help 源码)。

copyparty 会拒绝 Origin 头与服务器域名不一致、又没带密码头的上传(见 cors 说明),而 TSLink 默认转发的是后端自己的 Host。我们用 copyparty 1.20.26 和 v0.3.1 之后不久的一个 main 分支构建测试时,不加 --preserve-host,经访客链接的浏览器上传也能成功:TSLink 会把公网域名放进 X-Forwarded-Host,copyparty 的日志显示它从这个头读取域名。测试中偶尔出现的 HTTP 400 是 copyparty 对重复分块的回应(日志写 already got that),客户端重发了服务器已经收到的分块,不影响上传结果。如果上传被拒,给 tslink add 加上 --preserve-host,它会把应用节点自己的外部域名作为 Host 转发。它和上限不同,应用有了访客链接后就改不了:执行 tslink remove uploads(会撤销它的链接),带上这个参数重新添加,再创建新链接。

开始之前

  • 已安装 TSLink(见安装),以及开启了 MagicDNS 和 HTTPS 的 Tailscale 账号。
  • Funnel 权限。 Tailscale Funnel 要求 tailnet 策略文件里有 funnel 节点属性。对明确公开的服务,TSLink 默认会在拥有可用 API 权限和策略权限的情况下自动写入;否则自己加上。
  • 第一次运行要让节点入网。 tslink add 可能返回带 auth_url 的 needs_login,在 guest create 之前打开一次,否则它会停在 enrollment_required。guest create 最多等 8 秒拿到应用地址;仍然报 url_not_ready 的话,什么都没有保存,执行 tslink url uploads --wait=30s 后把同一条命令再跑一次。
  • PIN 在创建时设置。 只有一个上传方时加 PIN 比较合适:给 guest create 加上 --pin,在隐藏提示符下输入 6 到 64 位数字,再单独发给对方。之后再加 PIN 就要创建一个新链接,第一个链接还有效时也可以创建。
  • 发送前先检查。 guest create 只保存配置,用 tslink status 和 tslink doctor 确认 Funnel 已生效。新的公网名字最多可能要 10 分钟才出现在公网 DNS 里。测试链接要用 tailnet 之外的设备,比如关掉 Tailscale、走蜂窝数据的手机;在 tailnet 内部打开访客链接只会跳转到 /,不会建立访客会话。
  • 足够的磁盘空间,以及在整个上传期间保持唤醒的 Mac。

查看、撤销与清理

bash
tslink guest list
tslink access log --app uploads --since 24h
tslink guest revoke <id>
tslink remove uploads

撤销对这个链接 ID 永久生效,并取消进行中的上传。tslink remove 会撤销这个应用剩下的全部链接,之后用同一个名字重新添加的应用也不会让它们复活。访客链接默认最长 7d,不接受 never。

旧版本上的新链接

在 v0.3.1 及更早版本里,guest create 不会去掉 gateway 路由(要先执行 tslink portal route remove <app>),带访客链接的应用改不了请求上限,访客 gate 生效期间对同一应用再执行 guest create --print-link 会报 url_not_ready。直接升级,不用把应用从头来一遍。任何版本上,guest create 失败后都不要去掉 --print-link 重试:那样会成功,但保存下来的链接谁也拿不到,遇到这种授权要撤销。

需要知道的限制

  • TSLink 不负责续传。 连接断了能否续上取决于上传应用,copyparty 的上传器可以,普通 HTML 表单不行。撤销和截止时间也会中断进行中的上传,应用要能处理不完整的文件。
  • 链接公开且可转发。 截止前,拿到链接(以及设置了的 PIN)的人都能上传,所以文件夹应该设成只写。label 不能说明上传者是谁。
  • 访客链接只支持 HTTP proxy 应用。 用 tslink add --dir 注册的文件夹只在 tailnet 内可见,没有应用在后面,TSLink 收不了文件。
  • Funnel 吞吐有限,见本页开头。

这些情况换别的工具更合适

方案适合什么情况代价
单独用 copyparty你接受 copyparty 自己的账号,以及它自带的分享链接(--shr,可以设密码、到期时间并允许上传),还有按卷设置的上传文件寿命;清理过期分享需要开启 e2d。公网访问要自己想办法。TSLink 提供经 Funnel 的 ts.net 地址,不用在路由器上开端口,并在应用前面执行截止时间和撤销,进行中的请求也会被切断。
Tailscale Serve 或在单独的无 gate 应用上做 TSLink 人员授权上传方是你自己的设备,已经在 tailnet 里,或者愿意装 Tailscale(给外部人员授权还需要你保存了 API token)。不会有任何东西公开,tailnet 路径也快得多。上传方要装 Tailscale。
Cloudflare Quick Tunnel没有 Tailscale 账号;--allowed-mail 只放行在交互式浏览器里验证过的邮箱。只面向测试和开发,最多 200 个并发请求,cloudflared 一停访问就结束,每次运行主机名都会变。
命名的 Cloudflare Tunnel要一个长期公开的上传地址。账号、域名和访问策略都要自己管,没有内置到期。
Dropbox 文件请求或传输服务上传方方便或速度最重要,或者 Mac 撑不了一直在线。Dropbox 上传方不需要 Dropbox 账号。文件进入服务商的存储。Dropbox Basic、Plus 和 Family 单个文件最大 2 GB,更高的方案最大 250 GB,并且可以设截止时间。

交给编程 agent

把下面这段贴进 Claude Code、Codex 或 Cursor:

代码
通过一个 TSLink 访客链接,让一位外部人员在 3 天内往这台 Mac 上传文件(照片或文档,不是几十 GB)。按以下规则执行:
1. 使用现成的上传应用,不要自己写上传服务器。优先用 copyparty,按它的官方 README 配置:只监听 127.0.0.1,端口 3923,只开放一个文件夹 ~/incoming,访客可以写入但不能浏览,用 -nih 和 -nid 隐藏主机名和磁盘用量。让它在后台持续运行。
2. 确认 tslink --version 显示 v0.4.0 或更新版本。注册应用:tslink add uploads --proxy localhost:3923 --max-request-body 128MiB --request-read-timeout 2m。如果结果是 needs_login,把 auth_url 给我并等待。不要自己去掉 gateway 路由,第一条访客链接会处理。
3. 创建之前先问我要不要 PIN,PIN 只能在这一步设置。公开任何东西之前,先把访客命令给我看,等我同意。如果我要 PIN,让我自己加 --pin 执行这条命令,在隐藏提示符下输入,不要把 PIN 写进任何命令参数;否则执行:tslink guest create uploads --for 3d --label "<上传方>" --public --print-link --json。期限不得超过 7d,也不能用 never。
4. 用 tslink status 和 tslink doctor 确认 Funnel 已生效,然后把链接、grant id、到期时间和撤销命令 tslink guest revoke <id> 一起给我。从 tailnet 之外测试一次上传;如果上传被拒,告诉我,解决办法是执行 tslink remove uploads,再加上 --preserve-host 重新添加并创建新链接。
5. 如果上传收到 HTTP 413,用 tslink limits set uploads --max-request-body <大小> 调高上限,并告诉我上传方要重新打开链接。要新链接时,再执行一次 guest create。如果 guest create 报 url_not_ready,执行 tslink url uploads --wait=30s 后再试一次,不要去掉 --print-link 重试。
6. 我说结束时:先执行 tslink guest revoke <id>,再停掉上传应用,最后执行 tslink remove uploads。不要删除 ~/incoming 里的任何东西。

相关页面

以上 Tailscale、Cloudflare、Dropbox 与 copyparty 官方来源访问日期:2026-11-11(copyparty README 与源码固定在提交 1af7efe)。TSLink 行为按 v0.4.0 核对;吞吐与 copyparty 相关的观察来自一次测试,使用 copyparty 1.20.26 和 v0.3.1 之后不久的一个 main 分支构建。TSLink 是 anydoor7 的独立项目,并非由 Tailscale 制作或背书。

目录