1. 为什么要用 Secret以及它在 Docker 里的位置先说个很现实的场景某运维同学把数据库密码直接写进了环境变量代码里再读环境变量。结果一次不小心把docker inspect的输出贴到了群里整条连接串连密码全部曝光。这种事儿在团队协作里太常见了尤其当镜像被推到公共仓库、配置被同步到版本库时密码、Token、证书这类东西只要出现一次基本就等于泄露。Docker 官方其实很早就意识到了这个问题所以提供了 Config 和 Secret 两类资源来管理配置。简单区分Config 用来存非敏感配置比如 nginx.conf、日志级别任何人能读没关系Secret 是专门给敏感信息准备的比如数据库密码、API Key、TLS 私钥默认不会明文出现在镜像层里也不会轻松被 inspect 扫出来。这一篇我主要讲 Secret 的核心机制、实操用法和我在真实部署中踩过的坑。如果你已经在用 Docker Compose 管理服务但对 Swarm 模式还停留在“听说过”的阶段这篇文章同样适用因为 Secret 的很多设计思路和管理方式即便在单机开发环境里也有很强的参考价值。2. 拆开看 Docker Secret它到底解决了什么问题2.1 Secret 的核心设计思路很多人第一次接触 Secret 时的第一反应是“这不就是把文件挂载进容器吗”确实Secret 在容器内的呈现方式就是一个文件默认挂在/run/secrets/xxx但它的价值体现在“密钥怎么到达这里”的过程上。Docker Secret 的管理和分发由 Swarm 管理器完成。当你创建一条 Secret 时它会被加密存储在 Swarm 的内部存储里注意这里不是明文塞进某个目录而是经过加密处理的。当你把一个 Secret 指派给某个服务时管理器只把对应的密钥下发到运行在那个节点上的任务容器里节点上的其他容器、其他服务是看不到的。这个“最小化暴露”的设计非常关键。它意味着密钥不会进入镜像构建层镜像可以安心推到仓库密钥不会进入容器环境变量列表docker inspect看不到明文密钥只在需要它的容器里短暂存在容器停止或删除后密钥文件随之销毁。2.2 Secret 与 Config 的分工我刚接触时也搞混过 Secret 和 Config后来在项目里用了几个月才算摸清楚边界。下表是我自己的理解方式对比项Docker ConfigDocker Secret适用内容nginx.conf、应用配置文件、非敏感的公共数据密码、私钥、Token、证书等敏感信息是否加密存储不加密Swarm 内明文存储加密存储管理节点间传输走加密通道挂载位置默认/xxx可指定绝对路径默认/run/secrets/xxx目标用途让容器读到统一的最新配置提供满足最小权限原则的密钥下发是否支持 Compose支持支持但依赖 Swarm 模式注意Secret 只有在 Swarm 模式下才会真正发挥加密分发的作用。单机docker run或普通 Compose 启动的服务无法生成 Swarm 加密存储链路所以很多人刚开始在本地测试 Secret 时会发现“能用但总觉得哪里不对劲”其实是运行模式不一样导致的。2.3 为什么说环境变量放密钥是反面教材环境变量之所以不能存密钥主要有三个问题第一环境变量对所有进程可见。容器启动后PID 为 1 的进程可以拿到全部环境变量如果应用里有一个子进程被攻击者利用环境变量里的密钥就等于拱手送人。文件形式的 Secret 则可以通过权限位限制默认只有 root 或指定 UID 可读缩小暴露面。第二环境变量会被docker inspect输出。只要有人能执行 docker 命令或访问 Docker API环境变量里的所有值都是一览无余的。第三环境变量难以审计和轮换。你想改一个密码得重新创建容器再把新环境变量注入而 Secret 可以独立更新服务重新部署一条命令就能挂上新的密钥不需要动镜像。3. Secret 实测上手从创建到挂载全流程3.1 先把 Swarm 跑起来Secret 的底层依赖 Swarm 模式所以第一步不是创建 Secret而是初始化 Swarm。无论你是一台机器还是多台机器只要想用 Secret就得先执行docker swarm init执行成功后你的当前机器会成为 Swarm 管理器节点。如果是多节点环境其他机器可以用docker swarm join加入到集群里这里就不展开了。验证一下节点状态docker node ls看到管理器角色正常显示就可以继续了。3.2 创建 Secret 的三种方式Docker 创建 Secret 主要支持三种数据来源我一个个说。方式一从标准输入创建。这是最常用的方式适合在脚本或终端里快速创建echo my-db-password-2025 | docker secret create db_pass -末尾的-表示从 stdin 读取内容。这个方式的好处是不会在 shell 历史里留下明显的密码痕迹当然 echo 命令本身还是会出现在历史里敏感环境建议用方式二。方式二从文件创建。如果密钥内容本来就保存在文件里比如 TLS 私钥、证书、或者一个稍长的 Tokendocker secret create tls_key /path/to/private.key需要注意Docker 会读取该文件的完整内容作为 Secret 值文件里如果带换行符换行也会被存进去。很多人在证书密钥上踩过这个坑应用读取后解密失败折腾半天发现是多了一个换行。方式三用 docker secret create 配合管道生成随机密码。比如生成一个随机串作为 MySQL 密码openssl rand -base64 24 | docker secret create mysql_pass -这里的 openssl 命令生成的随机串包含/等字符如果目标应用对密码有字符集限制建议用tr -d过滤一下我后面在常见问题里会具体说。3.3 把 Secret 挂到服务里创建好的 Secret 不会自动出现在容器里必须要显式指定给某个服务。以下是一个完整的创建流程我用一个 Nginx 示例来讲# 创建密钥文件 echo supersecret | docker secret create nginx_token - # 创建服务指定挂载 secret docker service create \ --name web \ --secret nginx_token \ --publish 8080:80 \ nginx:latest服务创建后进入容器验证docker service ps web # 找到运行中的容器 ID docker exec -it container_id /bin/sh # 在容器内查看 cat /run/secrets/nginx_token正常情况下你会看到supersecret原文。如果只想给容器内的某个用户读可以指定 UID、GID 和权限模式docker service create \ --name web \ --secret sourcenginx_token,targetapp_token,mode0440,uid1000,gid1000 \ nginx:latest这里每个参数都值得解释一下source是 Docker 侧的 Secret 名字target是容器内呈现的文件名默认与 source 同名mode是文件权限0440 表示只有 owner 和 group 可读uid、gid指定文件所属用户和组适合以非 root 运行的容器。3.4 更新与轮换改密码的正确姿势应用密码定期轮换是运维基本功Docker Secret 对轮换的支持是所有设计里我觉得最舒服的部分。假如你想更换数据库密码操作分两步# 第一步创建新的 Secret echo new-db-pass-2025 | docker secret create db_pass_v2 - # 第二步更新服务挂载新 Secret docker service update \ --secret-rm db_pass \ --secret-add sourcedb_pass_v2,targetdb_pass \ web这里有个细节很多人没注意--secret-rm和--secret-add可以同时执行在一条命令里完成替换。你不需要先移除再添加也不需要重建整个服务Docker 会滚动更新任务逐个替换容器。新容器挂载的是db_pass_v2但容器内目标文件名仍然是db_pass所以应用代码完全不用改。这个“源名称可变、目标名称稳定”的设计是我觉得 Secret 比环境变量优雅得多的原因之一。3.5 删除 Secret删除操作同样直接docker secret rm db_pass但有一个限制如果某个正在运行的服务还在使用这条 Secret删除会报错。必须先更新服务把它从挂载列表里去掉再执行删除docker service update --secret-rm db_pass web docker secret rm db_pass警告删除操作是不可逆的。Secret 不像 Config 那样可以重新拉取一旦误删只能重新创建然后重新更新服务。我建议在生产环境把 Secret 的创建命令沉淀成脚本统一纳入发布流程不要依赖人工记忆。4. 进阶用法与服务间共享4.1 多个服务共享同一个 Secret实际项目中数据库密码往往需要同时提供给 API 服务和定时任务服务。Secret 不像容器文件系统那样属于某个容器它属于 Swarm所以天然支持多服务挂载docker service update --secret-add db_pass api_service docker service update --secret-add db_pass cron_service两个服务挂的是同一条 Secret但每个服务内部的呈现方式完全独立。你可以在 api_service 里把db_pass映射为db/password在 cron_service 里映射为db_pass完全不影响对方。4.2 在 Compose 文件中使用 Secret虽然 Secret 依赖 Swarm但 Compose 文件里同样可以声明。以下是一个简化示例version: 3.8 services: app: image: myapp:latest secrets: - db_pass environment: - DB_PASS_FILE/run/secrets/db_pass secrets: db_pass: external: trueexternal: true表示这条 Secret 已经通过docker secret create提前创建好不在 Compose 文件里定义内容。这样做的好处是Secret 的创建和应用的启动解耦方便统一管理密钥生命周期。如果你的环境允许在 Compose 里直接定义文件来源通常是 Docker Swarm 的新版本特性也可以这样写secrets: db_pass: file: ./secrets/db_pass.txt这条方式会由 Swarm 在部署时自动读取文件内容创建 Secret。不过我个人不太建议把密钥文件放进项目仓库除非你确定仓库是私有且加密的。4.3 用文件方式间接解决“环境变量太长”的问题有些场景其实不是在存密码而是要往容器里注入大量非结构化数据比如 JSON Web Token 的公钥、AWS 凭证文件、证书链。这些内容塞进环境变量一是太长二是换行符处理麻烦。用 Secret 文件挂载就很自然应用侧统一从/run/secrets/xxx读取代码里只需要写一行secret_path /run/secrets/aws_credentials with open(secret_path, r) as f: credentials f.read()对比环境变量方式这种读取方式还多了路径可追踪的好处日志里能明确看到密钥文件来源排障时很容易定位。5. 官方文档不会明说的坑问题排查与避坑心得5.1 非 Swarm 环境下把 Secret 当 Config 用我在本地开发机测试 Secret 时一度以为它和普通文件挂载等价后来在生产环境才发现差异巨大。具体来说如果只是用docker-compose up启动没有经过docker swarm initCompose 里声明的secrets其实不会真正走加密下发链路它在宿主机上还是普通明文文件。这时候你如果觉得“Secret 也没啥特别的”那就被表象骗了。真正要发挥 Secret 价值必须在 Swarm 模式部署。本地开发时为了模拟我的做法是服务端代码把密钥读取路径抽象成常量开发环境用普通文件挂载模拟/run/secrets/;生产环境走真正的 Secret。这样既能保证本地快速迭代又不牺牲生产安全性。5.2 文件里多出来的换行符这条坑专治“为什么密码明明是对的应用却报认证失败”。echo默认会输出换行符也就是说echo mypassword | docker secret create db_pass -实际存进去的字符串是mypassword\n而不是mypassword。如果你的应用读取 Secret 后不主动 trim那么这个看不见的换行符就会让你折腾半小时。解决办法有两个创建时用printf而不是echoprintf mypassword | docker secret create db_pass -或者应用读取后strip()但总归是代码层补救不如源头做好。5.3 Secret 在容器内的可见性细节还有两个小细节容易被忽略第一Secret 文件在 Linux 容器里默认挂载为 tmpfs不会被写入容器的可写层。这意味着即使容器被 commit 成新镜像Secret 也不会混进镜像里。这一点对于安全审计非常重要。第二不是所有基础镜像都有/run/secrets目录但 Docker 会自动创建所以不需要手动 mkdir。第三如果你在docker service create时同时指定了 username 和 Secret 的 uid要注意权限匹配。默认情况下 Secret 文件属于 root如果你的容器以非 root 用户运行读取时可能会遇到 Permission denied。解决方法是创建服务时显式指定 iddocker service create \ --name app \ --secret sourcedb_pass,targetdb_pass,uid1000,gid1000,mode0400 \ myapp:latest这属于那种“文档里写了但没强调踩坑了才记得”的细节。5.4 轮换时的滚动更新时序docker service update执行后旧任务并不会瞬间全部消失而是按滚动更新的策略逐个替换。如果你在服务里把 Secret 用于数据库连接池旧容器在销毁前可能还在用旧密码连接数据库而数据库侧已经切到新密码这会导致一小段时间内的连接失败。我的经验是做密码轮换时先在目标服务挂载新 Secret确认新容器正常、旧容器退出再切换数据库侧的实际密码。顺序反了就会看到几十秒的报错潮。简单来说先改应用侧再改数据侧。5.5 Secret 大小限制单条 Docker Secret 的大小默认限制在 500KB 左右这是一个容易被忽略的隐形上限。如果你要存放一个比较大的证书链或加密密钥文件超过限制就需要考虑拆分或者改用 Config。虽然绝大多数密码、Token 都在 KB 级别以内但我在一次挂载 CSR 相关文件时踩过这个上限所以列出来提醒一下。6. 一份可以直接抄的完整示例把上面的内容串起来我给你一个完整的、生产可用的集成示例。假设我们要部署一个 Node.js 应用需要访问 MySQL密码通过 Secret 管理。宿主机准备阶段# 1. 初始化 Swarm docker swarm init # 2. 创建 MySQL 密码 Secret printf S3cure_Pass_2025 | docker secret create mysql_pass - # 3. 创建 API Token openssl rand -base64 32 | tr -d / | docker secret create api_token -服务部署阶段docker service create \ --name myapp \ --network mynet \ --secret sourcemysql_pass,targetmysql/password,mode0400 \ --secret sourceapi_token,targetapi/token,mode0400 \ --env DB_HOSTmysql \ --env DB_PASS_FILE/run/secrets/mysql/password \ --publish 3000:3000 \ myapp:latest应用代码里读取密码const fs require(fs); const dbPassword fs.readFileSync(process.env.DB_PASS_FILE, utf8).trim();这个示例中我把 Secret 的目标文件名指向了一个包含路径的层级目录Docker 会自动创建目录结构不需要额外 mkdir。应用代码也从DB_PASS_FILE环境变量拿到路径代码本身不硬编码 Secret 路径方便不同环境切换。整个过程中docker inspect 查看服务时只能看到 Secret 的 ID 和名字看不到明文内容。而容器内文件权限被锁定为 0400只有容器内 root 可读符合最小权限原则。7. 把 Secret 纳入你的发布流程Secret 用起来不复杂但难在把它纳入到规范化的发布流程里。我的个人习惯是每个项目维护一个secrets.sh脚本里面定义所有 Secret 的创建命令脚本内容不进入公开仓库由运维或 CI 系统在受控环境执行。举个例子脚本里长这样#!/usr/bin/env bash set -euo pipefail create_or_update_secret() { local name$1 local file_path$2 if docker secret inspect $name /dev/null 21; then echo Secret $name already exists, skipping... else docker secret create $name $file_path fi } create_or_update_secret mysql_pass ./secrets/mysql_pass.txt create_or_update_secret redis_pass ./secrets/redis_pass.txt create_or_update_secret api_token ./secrets/api_token.txt部署时先执行脚本确保 Secret 存在再跑docker stack deploy。后期更换密码时也只需要在脚本里新增一个带版本号的新 Secret然后更新服务的挂载引用。整个过程可重复、可审计。结合我个人踩过的坑有两点建议第一密钥轮换要形成机制不要临时手动操作。每次手机敲一条命令创建 Secret 都会增加犯错概率我后来统一改成脚本化之后再也没有因为手滑把密钥漏到终端日志里。第二Secret 的名字里建议带上环境标识。同一套配置在开发、测试、生产之间迁移时db_pass_dev、db_pass_prod这样的命名能避免跨环境串值。这套方式我用了大半年至少在“密码如何安全传给容器”这个问题上再也没操过心。如果你目前还在用环境变量存密码强烈建议找一个空闲窗口把这套机制切过去。