第34章 配置反向代理与 URL 前缀
反向代理
Stash 支持使用反向代理。
### 通用说明 通常，你需要设置以下几个请求头（请查阅你的代理文档了解具体配置方法）：
* Host (http host) * X-Real-IP * X-Forwarded-For * X-Forwarded-Proto
更多信息请参阅 issue 134。
### 使用 URL 前缀 Stash 也支持在 URL 前缀下运行。在这种情况下，还需设置 `X-Forwarded-Prefix` 请求头。代理还需要从请求的 URL 中移除该前缀。例如，如果你希望主页能通过 `http://example.domain.com/stash` 访问，则需设置 `X-Forwarded-Prefix: /stash`。
### 设置外部 URL 你也可以手动设置 Stash 将提供服务的域名。在 Stash 的 `config.yml` 中添加 `external_host:` 配置项，并分配一个可公开访问的主机名（包含 `http://` 或 `https://`）。如果使用了前缀，仍需要设置 `X-Forwarded-Prefix`。
```yaml external_host: http://example.domain.com ```
服务器配置示例
#### Nginx ```nginx location / { proxy_pass http://127.0.0.1:9999;
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 60000s; } ```
#### Nginx + Docker (Linuxserver Letsencrypt) 如果你使用的是 linuxserver 的 letsencrypt docker，可以在 proxy-confs 文件夹中创建一个 `stash.subdomain.conf` 文件，并采用以下配置：
```nginx # 请确保你的 DNS 已为 stash 设置了 CNAME 记录
server { listen 443 ssl; listen [::]:443 ssl;
server_name stash.*;
include /config/nginx/ssl.conf;
client_max_body_size 0;
# 如需启用 LDAP 认证，请在 ldap.conf 中填写 LDAP 详细信息 #include /config/nginx/ldap.conf;
location / { # 如需启用 HTTP 认证，请取消下面两行的注释 #auth_basic "Restricted"; #auth_basic_user_file /config/nginx/.htpasswd;
# 如需启用 LDAP 认证，请取消下面两行的注释 #auth_request /auth; #error_page 401 =200 /login;
include /config/nginx/proxy.conf; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; resolver 127.0.0.11 valid=30s; set $upstream_app stash; set $upstream_port 9999; set $upstream_proto http; proxy_pass $upstream_proto://$upstream_app:$upstream_port; proxy_set_header Host $http_host; proxy_read_timeout 60000s; } } ```
#### Nginx 使用前缀 以下是 Nginx 使用 `/stash` 前缀的示例：
```nginx location /stash/ { # 注意末尾的斜杠 - 这会让 nginx 从请求 URL 中移除 /stash 前缀 proxy_pass http://192.168.0.1:9999/;
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Port $server_port; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Prefix /stash; proxy_read_timeout 60000s; } ```
#### Nginx 使用 external_host 另一个 Nginx 示例： 在这个例子中，我们将使用 `stash.home` 作为域名，且 `192.168.0.1` 是 Stash 的 IP 地址，请根据实际情况编辑。 还应设置 `external_host` 配置项，在此例中为 `external_host: http://stash.home`。更多细节请参考 external_host 章节。
```nginx server { listen 80; listen [::]:80;
server_name stash.home; client_max_body_size 0;
location / { proxy_pass http://192.168.0.1:9999;
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Port $server_port; proxy_set_header X-Forwarded-Proto $scheme; } } ```
#### Apache ```apache # 如果使用 apache < 2.4.47，请移除 upgrade=websocket ProxyPass "/stash" "http://127.0.0.1:9999" upgrade=websocket ProxyPassReverse "/stash" "http://127.0.0.1:9999" RequestHeader setIfEmpty X-Forwarded-Prefix "/stash" ProxyPreserveHost on
# 用于名称解析 ServerAdmin admin@example.com ServerName example.com ServerAlias stash.example.com
# 对于 apache < 2.4.47，如需启用 websockets #RewriteEngine on #RewriteCond %{HTTP:Upgrade} websocket [NC] #RewriteCond %{HTTP:Connection} upgrade [NC] #RewriteRule ^/?stash/(.*) "ws://127.0.0.1:9999/$1" [P,L]
# 用于启用 SSL SSLEngine on SSLCertificateFile /path/to/cert.pem SSLCertificateKeyFile /path/to/cert.key ```
前置条件 ```bash sudo a2enmod proxy sudo a2enmod proxy_http sudo a2enmod proxy_balancer sudo a2enmod lbmethod_byrequests
sudo a2enmod rewrite sudo a2enmod headers
# 用于 SSL sudo a2enmod ssl ```
#### Caddy v2 ```caddy stash.example.com { reverse_proxy 127.0.0.1:9999 { header_up Host {host} header_up X-Real-IP {remote_host} header_up X-Forwarded-Port {server_port} } } ```
还应设置 `external_host` 配置项，在此例中为 `external_host: http://stash.home`。更多细节请参考 external_host 章节。
故障排除
#### 504 错误 在某些情况下，如果数据库文件较大，在进行 stash db 迁移时可能会因超时而遇到 504 错误。请调整 `proxy_read_timeout` 的值（例如 Letsencrypt/Swag docker 容器中的 `proxy.conf` 文件）。
#### 422 错误 为了使 websocket 正常工作，你可能需要在你的 server 块中添加以下几行代码（例如 Letsencrypt Unraid docker 容器中的 `proxy.conf` 文件）。如本文提到的方法，这应该能解决问题。
```nginx proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; ```
#### Cloudflare Tunnel 不建议使用 Cloudflare Tunnels，因为它们会对非 HTML 流量进行限流（视频流量属于此类）。 更多细节请参阅 Cloudflare 博客文章。
