Lingarr环境变量与Docker Secrets：安全配置与密钥管理的最佳实践

【免费下载链接】lingarrLingarr 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 是一款强大的字幕翻译工具，支持本地与 SaaS 翻译服务，可将字幕文件自动翻译成目标语言。作为自托管应用，Lingarr 需要管理数据库密码、OpenAI 与 DeepL 等翻译服务的 API 密钥，这些敏感信息一旦泄露，轻则被刷爆额度，重则危及整台服务器。本文将为你完整梳理Lingarr 环境变量的分类与用法，并给出Docker Secrets 密钥管理的最佳实践，让字幕翻译服务在安全的前提下稳定运行。

为什么密钥安全配置如此重要？

很多用户习惯直接把 API Key 写死在docker-compose.yml或.env文件中。一旦仓库被公开、文件被误分享或容器日志被查看，密钥就全部暴露。对于 Lingarr 这类需要接入多个 AI 翻译服务（OpenAI、Anthropic、Gemini、DeepSeek、Mistral 等）的字幕翻译工具，密钥即金钱，安全配置绝不是可选项。

好消息是，Lingarr 原生支持Docker Secrets机制，任何环境变量都可以通过追加_FILE后缀改为从文件中读取，这正是官方推荐的安全配置方式。

Lingarr 环境变量全景图

Lingarr 的配置以环境变量为主，完整清单见项目文档 Settings.MD 与 configuration.md。下面按类别整理最常用的变量：

数据库类环境变量

数据库连接串由 DatabaseConfiguration.cs 根据上述变量动态拼装，其中DB_PASSWORD默认值是Secret1234，生产环境务必修改。

翻译服务类环境变量

集成与其他变量

• RADARR_URL/RADARR_API_KEY：Radarr 集成
• SONARR_URL/SONARR_API_KEY：Sonarr 集成
• AUTH_ENABLED：是否启用登录认证
• ENCRYPTION_KEYS：加密密钥存储路径
• TELEMETRY_ENABLED：是否开启匿名遥测

环境变量与文件读取的优先级规则

Lingarr 在启动时通过 StartupService.cs 的ApplySettingsFromEnvironment方法，将所有环境变量写入数据库设置：

1. 先检查<变量名>_FILE指向的文件；
2. 文件不存在或为空时，回退到同名环境变量；
3. 当两者同时存在时，_FILE优先。

这意味着你可以在 compose 文件中同时保留变量与 secrets 引用，程序会自动选择更安全的文件来源。

Docker Secrets 配置步骤（最快配置方法）

下面以 OpenAI API Key 为例，演示完整的 Docker Secrets 配置流程。

第一步：创建密钥文件

在宿主机创建 secrets 目录，写入密钥内容（文件内不要有多余换行）：

mkdir -p ./secrets printf '%s' 'sk-your-openai-key' > ./secrets/openai_api_key.txt

第二步：编写安全的 docker-compose 配置

services: lingarr: image: lingarr/lingarr:latest container_name: lingarr restart: unless-stopped environment: - ASPNETCORE_URLS=http://+:9876 - DB_CONNECTION=mysql - DB_HOST=lingarr-db - DB_PORT=3306 - DB_DATABASE=lingarr - DB_USERNAME=lingarr # 通过 secrets 文件注入，避免明文 - DB_PASSWORD_FILE=/run/secrets/db_password - OPENAI_API_KEY_FILE=/run/secrets/openai_api_key - SERVICE_TYPE=openai secrets: - db_password - openai_api_key ports: - "9876:9876" volumes: - /path/to/media:/media - /path/to/config:/app/config depends_on: lingarr-db: condition: service_healthy lingarr-db: image: mariadb:latest restart: unless-stopped environment: - MYSQL_DATABASE=lingarr - MYSQL_USER=lingarr # 数据库侧同样使用 secrets - MYSQL_PASSWORD_FILE=/run/secrets/db_password - MYSQL_ROOT_PASSWORD_FILE=/run/secrets/db_root_password secrets: - db_password - db_root_password volumes: - /path/to/db:/var/lib/mysql healthcheck: test: "mariadb $$MYSQL_DATABASE -u$$MYSQL_USER -p$$MYSQL_PASSWORD -e 'SELECT 1;'" secrets: db_password: file: ./secrets/db_password.txt db_root_password: file: ./secrets/db_root_password.txt openai_api_key: file: ./secrets/openai_api_key.txt

第三步：启动并验证

docker compose up -d

启动后进入容器确认密钥已正确加载：

docker exec -it lingarr ls -l /run/secrets/

哪些变量适合用 Docker Secrets？

根据 Lingarr 的环境变量体系，建议将以下高敏变量全部改为_FILE注入：

更多安全加固技巧

1. 以非 root 用户运行容器

Docker 支持指定运行用户，减少容器逃逸风险：

services: lingarr: user: "1000:1000" # UID:GID

2. 妥善管理宿主机密钥文件

• secrets 目录权限收紧：chmod 600 ./secrets/*
• .gitignore中排除secrets/和.env
• 定期轮换密钥并重启容器

3. 启用 Lingarr 内置认证

设置AUTH_ENABLED=true，并通过ENCRYPTION_KEYS指定加密密钥存储路径，为 Web 界面加一道锁。

4. 参考开发环境配置

项目自带的 docker-compose.dev.yml 展示了完整的变量写法（注意其中的密码仅为开发占位符，切勿照搬到生产）。

常见问题

Q：_FILE变量和普通变量同时设置了怎么办？A：Lingarr 优先读取_FILE指向的文件内容，普通变量被忽略。

Q：secrets 文件内容带换行会影响配置吗？A：不会。Lingarr 读取时会自动去掉首尾换行（见ReadFromFileEnv实现）。

Q：不升级 Docker 版本能使用 secrets 吗？A：Docker Compose v2 及以上均支持，本地部署建议使用docker compose子命令而非旧的docker-compose。

总结

通过环境变量 + Docker Secrets 的组合，Lingarr 的字幕翻译服务可以做到"配置即代码、密钥不入库"。记住三个要点：所有 API 密钥和数据库密码改用_FILE注入、宿主密钥文件严格限权、定期轮换。按照本文的最佳实践配置，你就能在享受 Lingarr 自动化字幕翻译便利的同时，守住安全底线。

【免费下载链接】lingarrLingarr 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