Lingarr反向代理部署教程：Nginx/Caddy配置、子路径托管与HTTPS安全加固

Lingarr反向代理部署教程：Nginx/Caddy配置、子路径托管与HTTPS安全加固

【免费下载链接】lingarr Lingarr is an application that supports both local and SaaS translation services to translate subtitle files into a specified target language. With automated translation options, Lingarr simplifies translating subtitles. 项目地址: https://gitcode.com/gh_mirrors/li/lingarr

Lingarr 是一款开源的本地字幕翻译应用，支持接入 LibreTranslate、DeepL、OpenAI 等十余种翻译服务，自动把字幕文件翻译成你指定的目标语言。部署好 Lingarr 后，通过 Nginx 或 Caddy 配置反向代理，就能为它启用域名访问、子路径托管与 HTTPS 加密。本文是一份完整的 Lingarr 反向代理部署教程，从端口与环境变量讲起，手把手带你完成 Nginx、Caddy 反代配置和 HTTPS 安全加固，新手也能轻松上手。🚀

---

为什么需要给 Lingarr 配置反向代理？

Lingarr 默认监听本机 9876 端口，直接访问 http://服务器IP:9876 虽然能用，但存在几个痛点：

痛点	反向代理的解决方案
🔒 没有加密，字幕与 API Key 明文传输	统一在代理层启用 HTTPS 证书
🌐 端口号难记、多服务难以统一管理	用域名 + 80/443 标准端口访问
🗂️ 想和 Radarr、Sonarr 等工具同域共存	通过子路径（如 /lingarr）隔离
⚙️ 需要集中限流、加安全头	在代理层统一配置、统一加固

一句话总结：反向代理 = 给 Lingarr 加上域名、HTTPS 和统一入口，是自托管服务走向"正规军"的第一步。

---

部署前准备：Lingarr 端口、环境变量与数据目录

开始配代理前，先确认以下三件事，缺一不可。

1. 确认服务端口（默认 9876）

Lingarr 容器内部通过环境变量 ASPNETCORE_URLS=http://+:9876 指定监听端口，宿主机映射为 9876:9876。之后所有反代配置都指向 http://127.0.0.1:9876。

2. 确认数据目录挂载

/path/to/media/movies  → /movies   （电影字幕目录）
/path/to/media/tv      → /tv       （剧集字幕目录）
/path/to/config        → /app/config（配置、数据库、加密密钥）

其中 /app/config 保存了 API Key 加密密钥（/app/config/keys）和数据库文件，务必做好持久化。

3. 子路径场景需要 BASE_PATH

如果你打算用 https://你的域名/lingarr 这种子路径访问，必须在容器环境变量中加入：

BASE_PATH=/lingarr

Lingarr 启动时通过 app.UsePathBase(basePath) 识别子路径前缀，并把前端资源的基础路径写进 HTML 的 <base> 标签（见 ApplicationBuilderExtensions.cs），前端再通过 baseUrl.ts 读取它来拼接所有 API 请求。前后端的前缀必须一致，否则会出现白屏或接口 404。

---

Nginx 反向代理配置步骤：从 HTTP 到 HTTPS

Nginx 是使用最广的反代方案，配置也最灵活。假设你的 Lingarr 已经跑在 127.0.0.1:9876，域名是 lingarr.example.com。

第一步：配置 HTTPS 站点（推荐直接用 HTTPS）

server {
    listen 80;
    server_name lingarr.example.com;
    return 301 https://$host$request_uri;   # 强制跳转 HTTPS
}

server {
    listen 443 ssl http2;
    server_name lingarr.example.com;

    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    client_max_body_size 100m;              # 字幕文件可能较大，按需调整

    location / {
        proxy_pass http://127.0.0.1:9876;
        proxy_http_version 1.1;

        proxy_set_header Host              $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;

        # 关键：SignalR 实时进度需要 WebSocket 升级
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        "upgrade";
    }
}

⚠️ 划重点：Lingarr 的翻译进度、任务通知依赖 SignalR 长连接（Hub 路径为 /signalr/TranslationRequests 等），必须转发 Upgrade 和 Connection 头，否则页面会一直转圈、进度不刷新。

第二步：验证配置并重载

nginx -t                 # 检查配置语法
nginx -s reload          # 平滑重载

浏览器打开 https://lingarr.example.com，能正常进入登录页即成功。

---

Caddy 反向代理配置：自动 HTTPS 的更简方案

如果你不想手动申请证书、续期证书，Caddy 是首选——它内置自动 HTTPS，配置只有三行。

根路径托管（域名直接访问）

在 Caddyfile 中写入：

lingarr.example.com {
    reverse_proxy 127.0.0.1:9876
}

Caddy 会自动申请 Let's Encrypt 证书并启用 HTTPS，WebSocket 升级也默认支持，无需任何额外指令。执行 caddy reload 即可生效，这是目前 最快配置方法，全程不到一分钟。⚡

---

Lingarr 子路径托管：BASE_PATH 配置与代理前缀

当一台服务器要同时跑多个服务时，子路径托管是最优雅的方案。例如让 Lingarr 通过 https://example.com/lingarr 访问。

环境变量设置

容器环境变量中加入：

BASE_PATH=/lingarr

Nginx 子路径反代

注意 proxy_pass 后面不要加斜杠，这样 /lingarr 前缀会原样传给后端，由 UsePathBase 自动剥离：

location /lingarr/ {
    proxy_pass http://127.0.0.1:9876;

    proxy_http_version 1.1;
    proxy_set_header Host              $host;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /lingarr;   # 告诉后端真实前缀

    proxy_set_header Upgrade           $http_upgrade;
    proxy_set_header Connection        "upgrade";
}

Caddy 子路径反代

handle 指令只做路由、不剥离前缀，正好匹配 Lingarr 的子路径机制：

example.com {
    handle /lingarr/* {
        header_up X-Forwarded-Prefix /lingarr
        reverse_proxy 127.0.0.1:9876
    }
}

💡 项目自带的 docker-compose.dev.yml 里也有一段 Traefik 子路径示例（Host + PathPrefix + X-Forwarded-Prefix），原理与本教程一致，可对照参考。

---

HTTPS 安全加固清单：让 Lingarr 访问更安全

完成反代后，再做以下几项加固，你的 Lingarr 才算"毕业"：

• ✅ 强制 HTTPS：80 端口一律 301 跳转到 443（Nginx 配置见上文；Caddy 默认全站 HTTPS，无需处理）
• ✅ 开启 HSTS 等安全响应头：

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

• ✅ 不要直接暴露 9876 端口：只在反向代理内部访问 127.0.0.1:9876，公网只开 80/443
• ✅ 数据库不映射公网：MySQL/PostgreSQL 仅在内网 Docker 网络中使用，不要像开发配置那样映射 1433:3306 到宿主机
• ✅ 修改默认密码：数据库、Lingarr 管理员账号务必使用强密码
• ✅ 持久化加密密钥：确保 /app/config 卷存在且可写，否则 API Key 加密密钥（ENCRYPTION_KEYS，默认 /app/config/keys）丢失后需重新录入密钥
• ✅ TLS 版本：Nginx 建议 ssl_protocols TLSv1.2 TLSv1.3;，禁用老旧的 TLS 1.0/1.1

---

常见问题排查：反向代理报错怎么办

现象	可能原因	解决办法
🔴 502 Bad Gateway	Lingarr 未启动或端口不对	检查 9876 是否监听：curl http://127.0.0.1:9876
🔴 进度条不更新、任务不刷新	SignalR WebSocket 未转发	补上 Upgrade/Connection 头，确认代理支持 WS
🔴 页面白屏、静态资源 404	子路径前缀不一致	检查 BASE_PATH 与 Nginx location /lingarr/ 是否完全一致
🔴 登录后反复跳回登录页	Cookie 的 SameSite/Secure 冲突	确认反代正确传递了 X-Forwarded-Proto，保证 HTTPS 下 Cookie 行为正常
🔴 接口 404、前端找不到 API	前缀剥离错误	子路径场景 proxy_pass 末尾不要加 /

排查时记得看 Lingarr 日志：docker logs lingarr，代理层日志则看 Nginx /var/log/nginx/error.log 或 Caddy 的标准输出。

---

结语

到这里，你已经完成了 Lingarr 的完整反向代理部署：Nginx 与 Caddy 两种方案任选其一，子路径托管与 HTTPS 安全加固也一并到位。🎉

• 追求可控与灵活 → 选 Nginx，配置透明、生态成熟；
• 追求省心与自动 HTTPS → 选 Caddy，三行配置秒上线。

配置完成后，就可以放心地把 Lingarr 的翻译任务交给它了——无论是接入 DeepL、OpenAI 还是本地 AI，在安全加密的访问通道下，字幕翻译都会更安心、更高效。如果你还想了解翻译服务接入、自动翻译任务等进阶玩法，欢迎继续探索 Lingarr 的更多能力。

【免费下载链接】lingarr Lingarr is an application that supports both local and SaaS translation services to translate subtitle files into a specified target language. With automated translation options, Lingarr simplifies translating subtitles. 项目地址: https://gitcode.com/gh_mirrors/li/lingarr