Как безопасно передавать секреты при сборке и запуске
На этой странице
Секрет нельзя «запекать» в образ: всё, что попало в слой, ENV или историю сборки, увидит любой, кто сможет скачать образ, а отозвать его оттуда невозможно. Секреты сборки (токен приватного npm-registry) передают через BuildKit: RUN --mount=type=secret монтирует файл только на время инструкции. Секреты запуска (пароль БД, ключи API) передают в рантайме: secret manager платформы, Kubernetes Secrets, Compose secrets (файл в /run/secrets/...) или переменные окружения из защищённого хранилища CI.
Вопрос
Как передать секреты при сборке и при запуске контейнера, не оставив их в образе?
Что делать нельзя
ENV DATABASE_PASSWORD=super-secret # виден в docker inspect
ARG NPM_TOKEN # может остаться в истории сборки
RUN echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > .npmrc && npm ci
COPY .env . # файл в слое образаДаже если удалить .npmrc следующей инструкцией, файл останется в нижнем слое и извлекается через docker save.
Секреты сборки: BuildKit secret mount
# syntax=docker/dockerfile:1
FROM node:24-alpine
WORKDIR /app
COPY package.json package-lock.json .npmrc ./
RUN --mount=type=secret,id=npm_token,env=NPM_TOKEN \
npm ci# .npmrc в репозитории — без самого токена
//registry.npmjs.org/:_authToken=${NPM_TOKEN}docker build --secret id=npm_token,env=NPM_TOKEN -t app .
# или из файла: --secret id=npm_token,src=./npm_token.txtСекрет доступен только во время этой RUN и не попадает ни в слой, ни в кэш. Без env= он монтируется файлом /run/secrets/npm_token.
Для приватных git-зависимостей есть аналог — RUN --mount=type=ssh с docker build --ssh default.
Секреты запуска
Compose secrets — секрет монтируется файлом:
services:
api:
image: ghcr.io/team/api:1.4.0
secrets:
- db_password
environment:
DB_PASSWORD_FILE: /run/secrets/db_password
secrets:
db_password:
file: ./secrets/db_password.txt # файл не в gitimport { readFileSync } from "node:fs";
const password = process.env.DB_PASSWORD_FILE
? readFileSync(process.env.DB_PASSWORD_FILE, "utf8").trim()
: process.env.DB_PASSWORD;Соглашение *_FILE поддерживают официальные образы (POSTGRES_PASSWORD_FILE).
Переменные окружения — самый распространённый способ, но значения видны через docker inspect и в /proc процесса, наследуются дочерними процессами и легко попадают в логи ошибок. Файл чуть безопаснее.
Внешние хранилища — AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Doppler. Платформа подставляет секрет при запуске, ротация не требует пересборки.
Frontend: секретов нет
VITE_* и runtimeConfig.public / NUXT_PUBLIC_* попадают в браузер и видны всем. Токены сторонних API используют только на сервере (серверный маршрут Nuxt в server/api, backend), а браузер обращается к своему серверу.
Если секрет утёк
- Отозвать и перевыпустить секрет — удаление образа из registry недостаточно, копии могли скачать.
- Пересобрать образ без секрета.
- Добавить сканер секретов в CI (gitleaks, trufflehog) и проверку образов.
Частые ошибки
ARGилиENVдля токенов и паролей.COPY .envв образ.- Логирование
process.envпри старте. - Секреты в
VITE_*илиNUXT_PUBLIC_*. - Production
.envв git.
Что важно помнить
- Слой образа нельзя «почистить» — только пересобрать и отозвать секрет.
- Build-секреты —
--mount=type=secret, runtime-секреты — платформа или файлы/run/secrets. - Переменная окружения — допустимый, но не самый безопасный транспорт.
Мини-шпаргалка
- Сборка:
RUN --mount=type=secret,id=x+docker build --secret id=x,.... - Git:
--mount=type=ssh. - Запуск: Compose
secrets,*_FILE, secret manager. - Утечка: отозвать → пересобрать → сканировать.