Docker 目录编排规范

总体原则docker/目录用于集中存放项目部署相关内容成员进入后能快速找到启动方式、配置位置、脚本位置、构建产物位置。标准目录结构docker/ README.md docker-compose.yml .env.example .env # 本地使用不提交 scripts/ images/ container-name/各目录和文件职责docker/README.md仅包含 Docker 部署相关内容建议包括启动方式、环境变量准备方式、构建与导出方式、升级方式、常用排障命令。docker/docker-compose.yml定义整体编排主要放置 services、networks、volumes、depends_on、healthcheck、ports、env_file、volumes 挂载。原则复杂配置应拆分到对应容器的子目录避免大段配置堆砌在此文件。支持按需启动单个或多个容器docker compose up container-name。docker/.env.example环境变量模板包含镜像名、端口、数据库连接参数、中间件连接参数、服务运行参数。要求只放示例值、不放真实密钥、只保留当前实际使用的变量。docker/.env实际使用的配置文件不提交 Git由.env.example复制而来仅运行时使用。docker/scripts/存放 Docker 相关脚本适合放置镜像构建脚本、导出脚本、一键启动辅助脚本、初始化脚本、健康检查脚本。原则只放部署相关脚本不放业务代码脚本。脚本语言推荐使用 Python原因避免 PowerShell.ps1在不同 Windows 版本或执行策略下出现兼容性问题Python 跨平台一致性更好交互体验更强如input()实现菜单选择、argparse处理命令行参数、rich或colorama实现彩色输出。推荐脚本结构每个脚本应包含if __name__ __main__入口支持命令行参数如--container指定容器、--stage指定构建阶段和交互式选择两种模式。交互式脚本示例# scripts/build.py import subprocess, sys from datetime import datetime CONTAINERS [gateway, mysql, redis, app] STAGES [build, export, buildexport] def ask_choice(prompt, options): print(prompt) for i, opt in enumerate(options, 1): print(f {i}. {opt}) idx int(input(请选择: )) - 1 return options[idx] def main(): if len(sys.argv) 1: container sys.argv[1] stage sys.argv[2] if len(sys.argv) 2 else buildexport else: container ask_choice(选择容器:, CONTAINERS) stage ask_choice(选择阶段:, STAGES) timestamp datetime.now().strftime(%Y%m%dT%H%M%S) if stage in [build, buildexport]: subprocess.run([docker, build, -t, f{container}:latest, -t, f{container}:{timestamp[:8]}, .]) if stage in [export, buildexport]: subprocess.run([docker, save, f{container}:latest, f{container}:{timestamp[:8]}, -o, f../images/{container}_{timestamp}.tar]) print(f完成: {container} {stage}) if __name__ __main__: main()支持的构建阶段build仅构建镜像、export仅导出已构建的镜像为 tar、buildexport构建并导出默认。支持的选择维度全量构建所有容器、选择单个容器、选择多个容器如通过逗号分隔或多选。docker/images/存放导出的镜像包等产物适合放置docker save生成的*.tar。要求作为构建产物目录不提交 tar 文件通过.gitignore忽略。每个容器独立打包不合并为单个项目 tar。镜像包命名规范ISO 风格格式container-name_YYYYMMDDTHHMMSS.tar示例gateway_20260410T143022.tar、mysql_20260410T143022.tar、redis_20260410T143022.tar。其中container-name与docker-compose.yml中的容器名保持一致使用小写字母和连字符YYYYMMDD为构建日期T为日期时间分隔符HHMMSS为构建时间24小时制。按时间后缀自然排序。镜像 Tag 规范每个容器导出时打两个 tagcontainer-name:latest和container-name:YYYYMMDD日期版本号如gateway:20260410。latest始终指向最新构建的镜像覆盖自己即可。版本号使用日期而非手动递增的数字版本优点是无需额外维护、天然有序、与文件名对应。如需更细粒度同一天多次构建可扩展为container-name:YYYYMMDD-HHMMSS或container-name:YYYYMMDD-serial。示例构建命令docker build -t gateway:latest -t gateway:20260410 .导出命令docker save gateway:latest gateway:20260410 -o gateway_20260410T143022.tar。加载命令docker load -i gateway_20260410T143022.tar然后通过docker compose up gateway启动。独立打包的优势支持按需加载和启动单个容器无需整体替换每个容器独立版本管理升级回滚互不影响减小传输和存储体积。建议在 README.md 中说明当前推荐的镜像包版本和 tag 对应关系可选维护images.txt记录各容器最新包信息。docker/container-name/存放每个容器的专属运行配置例如docker/gateway/nginx.conf、docker/mysql/init.sql、docker/redis/redis.conf、docker/app/application-docker.yml。适用场景需要独立配置文件的容器配置不适合直接写进docker-compose.yml。每个容器单独一个子目录配置不散落在docker/根目录。推荐的最小结构docker/ README.md docker-compose.yml .env.example scripts/ images/有容器专属配置时扩展为docker/ README.md docker-compose.yml .env.example scripts/ images/ gateway/ mysql/ redis/ app/简单约定docker/根目录只放入口文件和通用文件每个容器专属配置放container-name/脚本统一放scripts/推荐使用 Python跨平台、交互性强、避免 PowerShell 兼容问题脚本应支持交互式选择全量/单个/多个容器构建阶段和命令行参数两种模式构建阶段包括build仅构建镜像、export仅导出 tar、buildexport构建并导出构建产物统一放images/每个容器独立打包不支持整体项目 tar镜像包命名采用 ISO 风格container-name_YYYYMMDDTHHMMSS.tar镜像 tag 规范每个容器同时打latest和日期版本号YYYYMMDD两个 taglatest始终指向最新构建覆盖自身即可按需启动docker compose up container-name配合docker load使用实际环境配置.env不入库示例配置.env.example入库