mirror of
https://github.com/jxxghp/MoviePilot.git
synced 2026-10-29 03:18:14 +08:00
61 lines
3.4 KiB
Markdown
61 lines
3.4 KiB
Markdown
# 使用 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 示例
|
||
|
||
```yaml
|
||
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 挂载并重启。
|