Docker Compose 怎样把敏感配置注入服务而不写进镜像

如果密码、API Key 直接写进 Dockerfile，或者把完整值放进普通环境变量，镜像层、日志和进程环境都可能留下不必要的暴露面。Docker Compose 的 secrets 适合把敏感值作为文件交给指定服务：先声明来源，再在服务下显式授权，容器内默认挂载到 /run/secrets/。

Docker 官方地址：https://docs.docker.com/compose/how-tos/use-secrets/

最小可靠配置是“顶层声明 + 服务级授权 + 文件路径核对”三件事。只声明 secret 而不在目标服务下授权，服务不会自动获得访问权；只写服务授权而没有顶层来源，也无法完成挂载。

先准备独立的 secret 文件

在 Compose 文件旁准备 api_token.txt，文件只保存敏感值，不把它复制到镜像，也不要把真实值写进下面的文章示例。配置工作区中的路径应是项目内的相对路径，实际项目要把这个文件加入合适的忽略规则，并按团队权限管理。

1. 打开原创配置工作区的项目配置 → 外部文件。
2. 选择新增敏感文件，填写文件名 api_token.txt，来源类型选本地文件。
3. 看到文件摘要只显示“已准备”，不要把敏感值展示在界面或日志中，再进入 Compose 映射。

声明来源并授权目标服务

进入项目配置 → Compose 映射 → secrets。这里要填两个位置：顶层 secrets 定义来源，services.api.secrets 决定谁能访问。把它们混在一起，是最常见的“配置看起来有值但服务读不到”原因。

services:
  api:
    image: example/api:stable
    secrets:
      - api_token # 只给 api 服务授权，不让其它服务自动获得

secrets:
  api_token:
    file: ./api_token.txt # 来源是项目文件，不把值写进镜像层

在界面中依次选择secret 来源 → api_token → file → ./api_token.txt，再点击服务授权 → api → 添加。保存前，字段映射区域应该同时出现“file 来源”和“api 服务授权”。

保存后核对挂载路径和访问范围

点击映射配置 → 保存配置后，打开服务摘要 → api → 挂载摘要。Compose 会把 secret 作为文件挂载到 /run/secrets/api_token；摘要应显示“仅 api 可见”，而不是把 secret 自动列到所有服务。

1. 检查状态栏是否显示配置已保存。
2. 检查挂载路径是否为 /run/secrets/api_token，名称要和授权项 api_token 一致。
3. 打开访问范围，确认只有 api，并确认摘要没有展示 secret 内容。

不生效时按四个字段排查

先看文件路径，再看顶层名称，再看服务授权，最后看容器类型。路径写错会导致来源文件找不到；api_token 在顶层和服务下拼写不一致，会导致映射断开；只写顶层 secrets 而未写 services.api.secrets，服务没有访问权。Docker 文档还说明，Compose secrets 的这种文件挂载方式面向 Linux 容器；Windows 容器的挂载能力不同，不能只看配置文件保存状态就推断运行时一定可用。

# 用项目配置检查最终字段，不把 secret 内容打印出来
docker compose config --quiet

# 进入目标服务后只检查文件是否存在，避免把敏感值输出到日志
docker compose exec api sh -c 'test -r /run/secrets/api_token && echo secret-file-ready'

如果应用只接受环境变量，先确认它是否支持类似 API_TOKEN_FILE 的文件路径约定；不要为了迁就应用而把 secret 原值重新写回普通环境变量。构建阶段需要读取的令牌属于 build secret，和运行时挂载给服务的 secret 是两条配置路径，也不要混用。

常见疑问

只写顶层 secrets 就能让所有服务读取吗？

不能。服务必须在自己的 secrets 字段中显式列出名称，Compose 才会授予访问权。

secret 会变成镜像中的文件吗？

本文讨论的是运行时挂载，目标是让服务在容器内读取挂载文件；它不等于把敏感值复制进 Dockerfile 或镜像层。构建阶段若要使用令牌，应按 Docker 的 build secrets 规则单独配置。

为什么保存成功但服务仍然读不到？

优先核对 file 相对路径、顶层名称、服务授权名称和容器平台支持范围。保存状态只能说明配置文件接受了字段，不能代替运行环境的实际支持判断。

把这套操作记成一条短路径：准备文件，顶层声明来源，服务级授权，核对 /run/secrets/，再根据容器平台与应用的文件读取约定处理兼容性。这样才能减少敏感配置进入镜像和普通环境变量的机会。