MoviePilot/docs/secrets.md

使用 Docker / Kubernetes Secrets

MoviePilot V3 支持把部署配置作为 UTF-8 文件挂载到 /run/secrets/，例如 /run/secrets/API_TOKEN、/run/secrets/GITHUB_TOKEN 或 /run/secrets/DB_POSTGRESQL_PASSWORD。文件内容直接进入配置解析，不导出为进程环境变量， 不复制到 app.env。此能力针对主程序的部署配置，不读取插件数据库配置。

配置优先级为：显式构造参数 > 进程环境变量 > <CONFIG_DIR>/app.env > secret 文件 > 字段默认值。 Web 设置通常写入 app.env；环境变量管理的项仍拒绝界面写回。 只要目录中存在同名 secret 项（包括无效文件、目录或被高优先级来源遮蔽的项）， 界面与自动修正都不会为它写入 app.env，并提示修改文件后重启。原值不变的提交无需更新。

目录与格式

• 默认读取 /run/secrets，目录不存在时静默使用其他来源与默认值。
• 在进程环境变量中设置 MOVIEPILOT_SECRETS_DIR 可更换目录，兼容 SECRETS_DIR；前者优先。 显式设为空字符串、false、off 或 0 可关闭 secrets。目录开关在模块导入时确定， 不从 app.env 或 secret 文件读取。CONFIG_DIR 仍应在进程环境中设置。
• 文件名必须与配置项大小写完全一致，例如 API_TOKEN，不能写成 api_token。
• 文件写裸值，不要照搬 app.env 的外层引号；引号属于文件内容。
• 内容使用 UTF-8，允许 UTF-8 BOM；首尾空白和末尾换行会去除，内部换行保留。
• list / dict 字段使用 JSON，例如 ALLOWED_HOSTS 的内容为 ["https://mp.example.com"]， DB_CONNECT_ARGS 的内容为 {"connect_timeout": 10}。
• 空文件、非法 UTF-8、非法 JSON、类型或字段约束错误、过短的 API_TOKEN 会按项跳过， 日志只提示字段名。API_TOKEN 需至少 16 个字符；无其他有效来源时保持未配置， 不为无效的外部令牌生成另一份密钥。错误目录或读取权限也会告警，请修正挂载和运行用户权限。
• 支持 K8s 投影文件的符号链接。轮换文件内容后必须重启 MoviePilot；现有进程不会热加载。
• 当前不支持 XXX_FILE 约定。单项任意路径可通过挂载到 secrets 目录中的同名文件实现。

Compose 示例

services:
  moviepilot:
    image: jxxghp/moviepilot-v3:latest
    volumes:
      - ./config:/config
    secrets:
      - source: moviepilot_api_token
        target: API_TOKEN
      - source: moviepilot_github_token
        target: GITHUB_TOKEN

secrets:
  moviepilot_api_token:
    file: ./private/api_token
  moviepilot_github_token:
    file: ./private/github_token

把实际密钥放到 ./private/ 对应文件并从版本管理中排除；Compose 文件只引用路径。 Docker Swarm 可将顶层声明改为已有的外部 secret；Kubernetes 可把 Secret 的 key 按配置名投影到 /run/secrets。按部署平台提供合适的只读权限，确保 MoviePilot 运行用户能够读取。

从旧配置迁移

先准备 secret 文件，再从编排环境变量和 app.env 中移除同名值，最后重启。 高优先级值仍存在时会继续生效，轮换 secret 无法覆盖它。已经写在 app.env 里的历史值 需要手工删除整行；界面“清空”可能写入字段默认值，不代表删除覆盖项。 外部管理的配置不能通过 Web 或 CLI 改为本地配置；需要先移除 secret 挂载并重启。