Docker Compose configs 怎样把只读配置挂载到服务

Docker Compose 里的 configs 适合把非敏感配置文件从镜像中拆出来，再按服务授权挂载到容器。处理“配置文件没有进服务”这类问题时，顺序要固定：先在顶层声明配置来源，再在目标服务下显式授予它，最后确认容器内的目标路径。它不是密钥存储，也不是用来保存运行时写入数据的 volume。

官方地址：https://docs.docker.com/reference/compose-file/configs/

最小可用写法是“顶层定义 + 服务授权 + 目标路径”三件套；只写顶层 configs，服务仍然拿不到配置文件。

步骤一：先分清 configs 的使用边界

如果问题表现为“镜像不想重新构建，但服务需要换一份普通配置”，configs 是合适的入口。它把配置内容作为文件投影给容器，服务只能访问自己被授予的配置。Docker 文档说明，Linux 容器的默认挂载位置是 /，默认权限为 0444；需要固定路径时，应在服务侧使用长语法明确写出 target。

先按数据用途做判断：

步骤二：声明配置来源

最容易维护的方式是把现有文件声明为 config。下面的配置把宿主机项目目录中的 config/app.conf 注册为 app_config；这一层只负责说明“配置从哪里来”，还没有把它交给任何服务。

configs:
  app_config:
    # 从项目目录读取普通应用配置文件
    file: ./config/app.conf

services:
  api:
    image: example/api:1.0
    # 服务侧的 configs 授权会在下一步补上

如果配置很短，也可以使用 content 或 environment；需要查找部署环境中已经创建好的对象时，则使用 external: true。不要把 file、content 和 external 混成一套：external 配置的职责是查找已有对象，Compose 不会替你创建它。

步骤三：把 config 授予服务并指定挂载点

配置文件真正进入服务，关键在服务下面的 configs 列表。短语法适合直接使用默认目标路径；为了让应用始终读取固定文件名，建议使用长语法写出 source、target 和权限。

services:
  api:
    image: example/api:1.0
    configs:
      - source: app_config
        target: /etc/demo/app.conf
        # 只读配置文件使用默认的 0444 权限语义
        mode: 0444

configs:
  app_config:
    # 配置来源仍然是项目内的普通文件
    file: ./config/app.conf

这里有三个需要同时核对的名字：顶层定义的 app_config、服务授权中的 source，以及应用真正打开的 target。如果应用仍然读取 /etc/demo/default.conf，仅修改 Compose 的挂载路径并不会自动改变应用参数；要么让 target 对齐应用约定，要么同步调整应用的配置入口。

步骤四：处理 external 与更新边界

开发环境常用 file，由 Compose 根据项目文件创建配置；某些部署环境则把配置的创建交给外部流程，此时可以这样写：

configs:
  app_config:
    # 部署前必须已经存在名为 app_config 的外部配置
    external: true
    # name 可用于指定引擎中实际查找的名称
    name: app_config

使用 external 时，Compose 不会创建缺失的 config；找不到它就会报错。并且除了 name 以外的属性都没有意义，因此不要同时保留 file，否则配置文件会变得含糊或被判为无效。

更新普通文件后，重新执行部署流程并检查服务是否重新获得新配置。不要把容器内目标文件当成编辑入口：configs 的目标是向服务提供配置，而不是给应用提供可写工作目录。若程序需要运行中修改并在重启后保留内容，应把写入目录设计成 volume，并把只读初始配置与运行时数据分开。

步骤五：用配置展开结果核对问题

发布前先让 Compose 展开最终配置，重点看服务侧是否真的有 configs 映射、source 是否拼写一致，以及目标路径是否符合应用约定：

# 展开当前项目的最终 Compose 配置，先检查结构再启动服务
docker compose config

# 启动目标服务，让配置授权随服务定义生效
docker compose up -d api

排查可以按下面的顺序进行：

1. 顶层是否存在与 source 完全一致的 app_config。
2. 服务下是否写了 configs，而不是只写顶层声明。
3. 应用读取的路径是否与 target 一致，特别是文件名和大小写。
4. 如果用了 external: true，部署环境中是否已经创建同名 config。
5. 如果数据包含密码或私钥，是否应该改为 secrets，而不是继续放进 configs。

常见问题

只写顶层 configs，为什么容器里没有文件？

顶层声明只定义配置对象，服务还必须在自己的 configs 字段中显式授权；缺少这一步，服务不会获得配置。

configs 和 secrets 可以互换吗？

不建议。普通应用配置可以用 configs，密码、API Key 或私钥应按 secrets 的语义管理；两者都需要服务显式授权，但用途和风险边界不同。

如何让配置挂载到应用指定的文件名？

使用服务侧长语法设置 target，例如把 app_config 映射到 /etc/demo/app.conf，并确认应用读取的路径与它一致。

记住这条判断链即可：configs 顶层定义来源，服务侧决定谁能读，target 决定应用从哪里读，external 决定配置由谁提前创建。把普通配置、敏感信息和可写数据分别放进 configs、secrets、volumes，Compose 文件就更容易维护，也更容易定位“配置没有进容器”的问题。