第十一章：环境变量与部署配置

DocuTranslate 支持通过环境变量（或 .env 文件）为后端预置默认配置。这对服务化部署、Docker 部署、MCP 集成尤其重要——可以避免在每次请求 / 每个客户端里重复填写模型信息。本章系统整理所有环境变量，并给出部署建议。

11.1 环境变量的作用与优先级

环境变量设置的是后端参数的默认值：当前端 / API 调用没有传该参数时，才使用环境变量的值。使用方式：把仓库中的 .env.example 复制为 .env，取消注释并填写需要的项；或在启动前 export（Docker 用 -e）。

两个控制优先级的关键开关：

用 FORCE_OVERRIDE=true 可以在多人 / 对外服务时锁定统一的模型配置，防止调用方乱传。

11.2 LLM 基础配置

11.3 LLM 高级参数

注意：环境变量里的默认值（如 CONCURRENT=30、TEMPERATURE=0.7、CHUNK_SIZE=4000）与 SDK 代码默认值（如 concurrent=10、temperature=0.3、chunk_size=3000）可能不同，具体以你的使用入口为准。

11.4 Markdown 工作流配置

11.5 MinerU Cloud 配置（convert_engine=mineru 时）

11.6 MinerU Deploy 配置（convert_engine=mineru_deploy 时）

11.7 Text 工作流配置

11.8 系统配置

11.9 部署示例

.env 文件（本地 / 源码部署）

DOCUTRANSLATE_API_KEY=sk-xxxx
DOCUTRANSLATE_BASE_URL=https://api.deepseek.com/v1
DOCUTRANSLATE_MODEL_ID=deepseek-chat
DOCUTRANSLATE_TO_LANG=中文
DOCUTRANSLATE_CONCURRENT=16
DOCUTRANSLATE_ENV_FORCE_OVERRIDE=false

放在启动目录下，docutranslate -i 启动时会自动读取。

Docker 部署（注入环境变量）

docker run -d -p 8010:8010 \
  -e DOCUTRANSLATE_API_KEY=sk-xxxx \
  -e DOCUTRANSLATE_BASE_URL=https://api.deepseek.com/v1 \
  -e DOCUTRANSLATE_MODEL_ID=deepseek-chat \
  -e DOCUTRANSLATE_TO_LANG=中文 \
  -e DOCUTRANSLATE_ENV_FORCE_OVERRIDE=true \
  -v /data/docutranslate/output:/app/output \
  xunbu/docutranslate:latest

• 用 -e 注入模型配置；
• 用 -v 挂载 output 目录持久化译文；
• 生产环境建议前置 Nginx/Caddy 反向代理，加上 HTTPS 与访问认证。

11.10 小结

• 环境变量为后端设默认值，ENV_FORCE_OVERRIDE / WEB_SKIP_VALIDATION 控制与请求参数的优先级。
• 变量分组：LLM 基础 / LLM 高级 / Markdown 工作流 / MinerU Cloud / MinerU Deploy / Text 工作流 / 系统。
• 服务化 / Docker 部署时用环境变量锁定统一配置，挂载 output 持久化，反向代理加认证。
• 下一章汇总最佳实践与常见问题排障。