前言
tusd是个好东西，天生支持浏览器断点续传。我们这个系列讲的是如何搭建server端，并且应用到Nginx 反代中的subpath 级别。网上关于单独的搭建教程很多，但是放到nginx反向代理后的location的文章很少，且看且珍惜。
小玩模式 - 本地运行tusd 服务端
这个可以用二进制方式运行，也可能方便的用docker形式。
最简单的运行命令为
docker run -p 8080:8080 docker.imgdb.de/tusproject/tusd:latest
这时可以在tus-js-client 中指定endpoint 为 ‘http://127.0.0.1/files/’ 这样是完全没问题的。
上线生产 - 以子路径方式部署到nginx后方
这里我们没有单独的子域名去部署了，因此，官方的文档只是部分适用。
首先，反代对于tusd来说，一定要加上参数 -behind-proxy ，然后需要配置 X-Forwarded-Host 和 X-Forwarded-Proto，以及禁用nginx buffering。
并且我们这里替换掉默认的 url basepath，就需要加上参数 -base-path 。
那么，docker run命令变成了
docker run -p 8080:8080 docker.imgdb.de/tusproject/tusd:latest -behind-proxy -base-path '/tusfiles/'
nginx 完整配置如下：
location /tusfiles/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
if ($request_method = OPTIONS) {
return 204;
}
# Disable request and response buffering
proxy_request_buffering off;
proxy_buffering off;
proxy_http_version 1.1;
proxy_cache off;
add_header Cache-Control "no-store";
add_header 'Access-Control-Allow-Origin' '*';
add_header 'Access-Control-Allow-Methods' 'OPTIONS, GET, POST, HEAD, PATCH';
add_header 'Access-Control-Allow-Headers' 'Content-Type, Upload-Length, Upload-Offset, Tus-Resumable, Upload-Metadata, X-Requested-With, Location, Authorization';
add_header 'Access-Control-Expose-Headers' 'Location, Upload-Offset, Upload-Length, Tus-Version, Tus-Resumable';
add_header 'Access-Control-Allow-Credentials' 'true';
# Add X-Forwarded-* headers so that response can reference https and
# originating host:port
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
# Allow proxying of websockets if required
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
client_max_body_size 0;
# 确保 NGINX 不会隐藏 TUS 头部
proxy_pass_header Upload-Offset;
proxy_pass_header Upload-Length;
proxy_pass_header Tus-Resumable;
}
遇到的问题
浏览器控制台报错 Reason: CORS Multiple Origin Not Allowed
可以看到response header中响应了两个 Access-Control-Allow-Origin 。但是奇怪的是，用httpie 或者curl时候无法复现这双头的响应。
开始以为是vite 自动添加的，配置了一通都没效果。查资料也没查到合适的，还是在 tusd -h 查看帮助时发现是tuds默认添加的，根据官方文档，这种情况需要给tusd 加上 -disable-cors 参数。
完整的docker 运行 tusd 命令
docker run -p 8080:8080 docker.imgdb.de/tusproject/tusd:latest -behind-proxy -disable-cors -base-path '/tusfiles/'
nginx报错 could not build optimal proxy_headers_hash
you should increase either proxy_headers_hash_max_size: 512 or proxy_headers_hash_bucket_size: 64; ignoring proxy_headers_hash_bucket_size
解决方案
你需要在 http 配置块中增加 proxy_headers_hash_max_size 或 proxy_headers_hash_bucket_size。
- 修改 NGINX 配置
打开 nginx.conf 文件，找到 http 块，添加：
http {
proxy_headers_hash_max_size 1024;
proxy_headers_hash_bucket_size 128;
}
解释：
proxy_headers_hash_max_size 1024; → 增大哈希表最大大小（默认为 512）。
proxy_headers_hash_bucket_size 128; → 增加桶大小（默认为 64）。
浏览器控制台报错 tus: invalid or missing Location header
这个情况是由于配置了错误的nginx location，请记住配置为
location /tusfiles/ {
proxy_pass http://127.0.0.1:8080;
}
tusd存储的文件默认路径
在容器内的data 目录中，不过不是原始文件名。
tusd 不会直接存储文件的原始名称，而是使用 UUID 作为文件名。你可以检查 data/ 目录下是否有类似这样的文件：
ls -lh ./data/
示例：
-rw-r--r-- 1 user user 50M Mar 19 16:00 e2f1a5c1e3de4e6cb5d26bafe3bb4a41
-rw-r--r-- 1 user user 2K Mar 19 16:00 e2f1a5c1e3de4e6cb5d26bafe3bb4a41.info
这里：
e2f1a5c1e3de4e6cb5d26bafe3bb4a41 → 上传的文件内容
e2f1a5c1e3de4e6cb5d26bafe3bb4a41.info → 元数据（metadata）文件
浏览器控制台报错 tus: invalid or missing offset value
确保你的tus-js-client 相关前端代码中是正常的，不要有任何报错。
附上Usage of tusd 参数全列表
Listening options:
-base-path string
Basepath of the HTTP server (default "/files/")
-behind-proxy
Respect X-Forwarded-* and similar headers which may be set by proxies
-enable-h2c
Allow for HTTP/2 cleartext (h2c) connections (non-encrypted)
-host string
Host to bind HTTP server to (default "0.0.0.0")
-port string
Port to bind HTTP server to (default "8080")
-unix-sock string
If set, will listen to a UNIX socket at this location instead of a TCP socket
TLS options:
-tls-certificate string
Path to the file containing the x509 TLS certificate to be used. The file should also contain any intermediate certificates and the CA certificate.
-tls-key string
Path to the file containing the key for the TLS certificate.
-tls-mode string
Specify which TLS mode to use; valid modes are tls13, tls12, and tls12-strong. (default "tls12")
Upload protocol options:
-disable-download
Disable the download endpoint
-disable-termination
Disable the termination endpoint
-enable-experimental-protocol
Enable support for the new resumable upload protocol draft from the IETF's HTTP working group, next to the current tus v1 protocol. (experimental and may be removed/changed in the future)
-max-size int
Maximum size of a single upload in bytes
CORS options:
-cors-allow-credentials
Allow credentials by setting Access-Control-Allow-Credentials: true
-cors-allow-headers string
Comma-separated list of headers that are included in Access-Control-Allow-Headers in addition to the ones required by tusd
-cors-allow-methods string
Comma-separated list of request methods that are included in Access-Control-Allow-Methods in addition to the ones required by tusd
-cors-allow-origin string
Regular expression used to determine if the Origin header is allowed. If not, no CORS headers will be sent. By default, all origins are allowed. (default ".*")
-cors-expose-headers string
Comma-separated list of headers that are included in Access-Control-Expose-Headers in addition to the ones required by tusd
-cors-max-age string
Value of the Access-Control-Max-Age header to control the cache duration of CORS responses. (default "86400")
-disable-cors
Disable CORS headers
File storage option:
-filelock-acquirer-poll-interval duration
The acquirer of a lock polls regularly to see if the lock has been released. This flag specifies the poll interval. (default 2s)
-filelock-holder-poll-interval duration
The holder of a lock polls regularly to see if another request handler needs the lock. This flag specifies the poll interval. (default 5s)
-upload-dir string
Directory to store uploads in (default "./data")
AWS S3 storage options:
-s3-bucket string
Use AWS S3 with this bucket as storage backend (requires the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION environment variables to be set)
-s3-concurrent-part-uploads int
Number of concurrent part uploads to S3 (experimental and may be removed in the future) (default 10)
-s3-disable-content-hashes
Disable the calculation of MD5 and SHA256 hashes for the content that gets uploaded to S3 for minimized CPU usage (experimental and may be removed in the future)
-s3-disable-ssl
Disable SSL and only use HTTP for communication with S3 (experimental and may be removed in the future)
-s3-endpoint string
Endpoint to use S3 compatible implementations like minio (requires s3-bucket to be pass)
-s3-max-buffered-parts int
Size in bytes of the individual upload requests made to the S3 API. Defaults to 50MiB (experimental and may be removed in the future) (default 20)
-s3-min-part-size int
Minimum size in bytes of the individual upload requests made to the S3 API. Must not be lower than S3's limit. Defaults to 5MiB. (default 5242880)
-s3-object-prefix string
Prefix for S3 object names
-s3-part-size int
Preferred size in bytes of the individual upload requests made to the S3 API. Defaults to 50MiB (experimental and may be removed in the future) (default 52428800)
-s3-transfer-acceleration
Use AWS S3 transfer acceleration endpoint (requires -s3-bucket option and Transfer Acceleration property on S3 bucket to be set)
Google Cloud Storage options:
-gcs-bucket string
Use Google Cloud Storage with this bucket as storage backend (requires the GCS_SERVICE_ACCOUNT_FILE environment variable to be set)
-gcs-object-prefix string
Prefix for GCS object names
Azure Storage options:
-azure-blob-access-tier string
Blob access tier when uploading new files (possible values: archive, cool, hot, '')
-azure-container-access-type string
Access type when creating a new container if it does not exist (possible values: blob, container, '')
-azure-endpoint string
Custom Endpoint to use for Azure BlockBlob Storage (requires azure-storage to be pass)
-azure-object-prefix string
Prefix for Azure object names
-azure-storage string
Use Azure BlockBlob Storage with this container name as a storage backend (requires the AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_KEY environment variable to be set)
General hook options:
-hooks-enabled-events string
Comma separated list of enabled hook events (e.g. post-create,post-finish). Leave empty to enable default events (default "pre-create,post-create,post-receive,post-terminate,post-finish")
-progress-hooks-interval duration
Interval at which the post-receive progress hooks are emitted for each active upload (default 1s)
File hook options:
-hooks-dir string
Directory to search for available hooks scripts
HTTP hook options:
-hooks-http string
An HTTP endpoint to which hook events will be sent to
-hooks-http-backoff duration
Wait period before retrying each retry (default 1s)
-hooks-http-forward-headers string
List of HTTP request headers to be forwarded from the client request to the hook endpoint
-hooks-http-retry int
Number of times to retry on a 500 or network timeout (default 3)
gRPC hook options:
-hooks-grpc string
An gRPC endpoint to which hook events will be sent to
-hooks-grpc-backoff duration
Wait period before retrying each retry (default 1s)
-hooks-grpc-client-tls-certificate string
Path to the file containing the client certificate for mTLS
-hooks-grpc-client-tls-key string
Path to the file containing the client key for mTLS
-hooks-grpc-forward-headers string
List of HTTP request headers to be forwarded from the client request to the hook endpoint
-hooks-grpc-retry int
Number of times to retry on a server error or network timeout (default 3)
-hooks-grpc-secure
Enables secure connection via TLS certificates to the specified gRPC endpoint
-hooks-grpc-server-tls-certificate string
Path to the file containing the TLS certificate of the remote gRPC server
Plugin hook options:
-hooks-plugin string
Path to a Go plugin for loading hook functions
Monitoring, profiling, logging options:
-expose-metrics
Expose metrics about tusd usage (default true)
-expose-pprof
Expose the pprof interface over HTTP for profiling tusd
-log-format string
Logging format (text or json) (default "text")
-metrics-path string
Path under which the metrics endpoint will be accessible (default "/metrics")
-pprof-block-profile-rate int
Fraction of goroutine blocking events that are reported in the blocking profile
-pprof-mutex-profile-rate int
Fraction of mutex contention events that are reported in the mutex profile
-pprof-path string
Path under which the pprof endpoint will be accessible (default "/debug/pprof/")
-show-greeting
Show the greeting message for GET requests to the root path (default true)
-show-startup-logs
Print details about tusd's configuration during startup (default true)
-verbose
Enable verbose logging output (default true)
-version
Print tusd version information
Timeout options:
-acquire-lock-timeout duration
Timeout for a request handler to wait for acquiring the upload lock. (default 20s)
-network-timeout duration
Timeout for reading the request and writing the response. If the tusd does not receive data for this duration, it will consider the connection dead. (default 1m0s)
-request-completion-timeout duration
Period after which all request operations are cancelled when the request is stopped by the client. (default 10s)
-shutdown-timeout duration
Timeout for closing connections gracefully during shutdown. After the timeout, tusd will exit regardless of any open connection. (default 10s)
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
