Docker Compose 模块化多环境配置规范指南：示例搭建Directus 12.4.0

Docker Compose 模块化多环境配置规范指南示例搭建Directus 12.4.0Docker Compose 模块化多环境配置规范指南示例Directus 12.4.0额外说明Directus 可以干什么目录结构规范配置文件详解与完整注释1. 全局公共环境配置dev/.env2. 服务私有环境配置dev/directus_V12.4.0/.env3. 服务编排配置dev/directus_V12.4.0/docker-compose.yml4. 创建数据库5. 服务启动6. 浏览器访问Docker Compose 模块化多环境配置规范指南服务的版本、端口、密码以及项目的环境网络这些要怎么放置标准的规范做法是双层配置隔离根目录公共.env仅保留全局通用变量ENV、COMPOSE_PROJECT_NAME、NETWORK_NAME等。服务私有.env与服务的docker-compose.yml同级放置仅维护该服务独有的参数如版本、密码、端口、JVM 配置等。示例Directus 12.4.0额外说明Directus 可以干什么GitHub 官网https://github.com/directus/directus介绍Directus是构建项目的后端平台。将其连接到数据库、资产存储和外部服务即可立即获得REST和GraphQL API、SDK、实时功能、身份验证、文件管理、自动化以及用于处理数据的 Web 应用程序。精细的访问控制意味着用户只能查看、交互和创建其角色允许的数据。Docker 构建官网说明https://directus.com/docs/self-hosting/deploying目录结构规范以下为标准的工程目录结构。不同环境如dev/test/prod通过顶层文件夹进行物理隔离.env按照双层变量隔离的方式dev/ ├── .env # 全局公共环境配置文件仅定义共享基础设施变量 └── directus_V12.4.0/ # 独立服务单元 ├── .env # 服务私有环境配置文件仅定义服务专属变量 ├── docker-compose.yml # Docker Compose 编排文件 └── volumes/ # 持久化数据与日志挂载目录配置文件详解与完整注释1. 全局公共环境配置dev/.env# # Docker Compose 全局公共环境配置文件# 作用管理跨服务的全局基础设施配置如网络、环境标识等# ############################################################# 环境基础配置############################################################# 当前运行环境标识# 可选值dev开发、test测试、prod生产ENVdev# Docker Compose 全局项目名称影响容器默认命名前缀COMPOSE_PROJECT_NAMEdev############################################################# Docker 公共网络配置############################################################# 跨服务通信的 Docker 共享网络名称NETWORK_NAMEnetwork-${ENV}# 自定义 Docker bridge 网络子网掩码确保网段不与宿主机冲突NETWORK_SUBNET10.10.0.0/242. 服务私有环境配置dev/directus_V12.4.0/.env# # Directus 服务专属环境配置文件# 作用管理 Directus 独享的版本、密钥、管理员账号及暴露端口# 位置与服务自身的 docker-compose.yml 同级# ############################################################# Directus 配置############################################################# 镜像版本例如11.0.0 / 10.13.0DIRECTUS_VERSION11.0.0# 暴露端口配置宿主机访问端口容器内部默认端口8055DIRECTUS_PORT8055############################################################# Directus 安全密钥配置############################################################# 系统 Session 签名与敏感数据加密 Key建议使用 standard UUID v4# 用于管理后台 Cookie 校验、内部 Session 加密及敏感字段哈希派生# 在线网址https://uuidgen.org/v/4DIRECTUS_SECURITY_KEYc7ac2c39-3e63-4780-8d87-1aba2d683d91# JWT 令牌签名私钥建议使用强随机 Base64/Hex 字符串# 用于对外 API 接口响应中 Access Token 与 Refresh Token 的生成与验签# 在线网址https://secretkeygenerator.com/zh/jwt-secret-key-generatorDIRECTUS_JWT_SECRET63jYs2S94dhgpB88oqBYZRICnBOIeK7FTGCeYcUtiU4############################################################# Directus 管理员初始化账号############################################################# 初始超级管理员邮箱登录 Web UI 管理后台凭证DIRECTUS_ADMIN_EMAILhaokai163.com# 初始超级管理员密码DIRECTUS_ADMIN_PASSWORDPass8520############################################################# 目标 MySQL 数据库连接凭证############################################################# 数据库连接用户与密码连接同一网络中已部署的 MySQL 服务DIRECTUS_DB_USERrootDIRECTUS_DB_PASSWORDPass8520DIRECTUS_DB_DATABASEdirectus配置属性说明DIRECTUS_SECURITY_KEY主要用于 Directus 内部 Session 签名、Cookie 加密及敏感字段的哈希派生推荐使用标准的 UUID v4 结构。在线网址https://uuidgen.org/v/4DIRECTUS_JWT_SECRET是用于签发与验签 REST API 接口 JWT TokenAccess Token / Refresh Token的 HMAC 秘钥要求具备极高的随机熵值。在线网址https://secretkeygenerator.com/3. 服务编排配置dev/directus_V12.4.0/docker-compose.yml可以参考官网提供的https://directus.com/docs/self-hosting/deploying# # Directus Docker Compose 配置## 目录结构# dev/# ├── .env# └── directus_V11.0.0/# ├── .env# ├── docker-compose.yml# └── volumes/# ├── uploads/ # 用户上传的媒体与文件资产/directus/uploads# └── extensions/ # 自定义扩展与插件目录/directus/extensions## 说明## 1. 环境配置# 全局基础参数ENV、NETWORK等由根目录公共 .env 管理# Directus 专属参数版本、密钥、端口等由服务同级 .env 管理。## 2. 持久化目录# Directus 的文件资产与扩展插件统一存放于# directus_V11.0.0/volumes/ 目录下。## 3. 路径规则# 所有宿主机挂载目录均采用相对路径# 相对路径以当前 docker-compose.yml 所在目录为基准。# 例如 ./volumes/uploads 对应# 当前环境/directus_V11.0.0/volumes/uploads。## 4. 环境隔离# 挂载路径不使用 ${ENV} 拼接。# 不同环境通过上层目录进行隔离例如# dev/directus_V11.0.0、test/directus_V11.0.0。## 5. 数据迁移# directus_V11.0.0/ 目录包含 Compose 配置及静态文件# 结合底层 MySQL 数据库可作为当前环境数据字典服务的整体备份和迁移单元。## 6. 依赖关系# 依赖外部已拉起的 MySQL 实例如果后续有依赖 Directus 的微服务# 请在下游服务中使用 depends_on: directus: condition: service_healthy。## ############################################################# 网络配置############################################################networks:# Compose 内部网络名称。env_network:# 使用 Docker Bridge 网络。driver:bridge# Docker 实际网络名称由上层公共 .env 管理。name:${NETWORK_NAME}# 自定义网络地址范围。ipam:config:-subnet:${NETWORK_SUBNET}############################################################# 服务配置############################################################services:########################################################### Directus##########################################################directus:# Directus 镜像及版本。# 版本由私有 .env 中的 DIRECTUS_VERSION 管理。image:directus/directus:${DIRECTUS_VERSION}# 容器名称自动拼接环境与版本号。# 例如directus_dev_V11.0.0container_name:directus_${ENV}_V${DIRECTUS_VERSION}# 加入当前环境的 Docker 网络。networks:-env_network# 端口映射。## Directus# 宿主机 ${DIRECTUS_PORT} - 容器 8055ports:-${DIRECTUS_PORT}:8055# Directus 运行参数。environment:# 系统 Session 签名与敏感数据加密 Key映射内部定义的 DIRECTUS_SECURITY_KEY。KEY:${DIRECTUS_SECURITY_KEY}# JWT 令牌签名私钥映射内部定义的 DIRECTUS_JWT_SECRET。SECRET:${DIRECTUS_JWT_SECRET}# 初始超级管理员账号信息。ADMIN_EMAIL:${DIRECTUS_ADMIN_EMAIL}ADMIN_PASSWORD:${DIRECTUS_ADMIN_PASSWORD}# 数据库客户端类型指定为 MySQL。DB_CLIENT:mysql# 同一网络中连接 MySQL 服务名例如mysql。DB_HOST:mysqlDB_PORT:3306DB_DATABASE:${DIRECTUS_DB_DATABASE}DB_USER:${DIRECTUS_DB_USER}DB_PASSWORD:${DIRECTUS_DB_PASSWORD}# CORS 跨域配置开启全量允许便于外部 API 正常调用。CORS_ENABLED:trueCORS_ORIGIN:true######################################################### 持久化目录########################################################## 所有宿主机挂载目录均采用相对路径。## 相对路径以当前 docker-compose.yml 所在目录为基准。## 当前 Compose 文件路径示例## 当前环境/directus_V11.0.0/docker-compose.yml## 因此## ./volumes/uploads# ./volumes/extensions## 分别对应## 当前环境/directus_V11.0.0/volumes/uploads# 当前环境/directus_V11.0.0/volumes/extensions## 不使用 ${ENV} 拼接挂载路径# 环境隔离由上层目录完成。#########################################################volumes:# 用户上传的媒体文件、文档及资产目录。## 宿主机# ./volumes/uploads## 容器# /directus/uploads-./volumes/uploads:/directus/uploads# 自定义扩展、 Hook 脚本及第三方接口插件目录。## 宿主机# ./volumes/extensions## 容器# /directus/extensions-./volumes/extensions:/directus/extensions######################################################### 健康检查严格遵照官方标准的 /server/ping 探针########################################################healthcheck:# 使用 wget 访问内部 HTTP Ping 端点探测服务可用性。test:[CMD-SHELL,wget --spider -q http://localhost:8055/server/ping || exit 1]# 正常运行阶段每 10 秒检查一次。interval:10s# 单次健康检查超时时间。timeout:5s# 连续失败 5 次后标记为 unhealthy。retries:5# 启动阶段的高频探测间隔加快探测容器就绪速度。start_interval:5s# 启动阶段给予 30 秒宽限时间用于数据库 Schema 校验与初始化。start_period:30s# 容器异常退出后自动重启。restart:unless-stopped######################################################### 容器标签########################################################labels:# 当前环境。env:${ENV}# Directus 版本。version:${DIRECTUS_VERSION}# 服务名称自动拼接环境与版本号。service:directus_${ENV:-dev}_V${DIRECTUS_VERSION}4. 创建数据库注意需要先创建数据库Directus 的数据库驱动mysql2在启动时只会连接指定的数据库并自动建表初始化系统 Schema但不会自动帮你执行CREATE DATABASE建库操作。如果目标数据库不存在MySQL 就会抛出ER_BAD_DB_ERROR (1049): Unknown database directus_db错误。如果一开始使用docker-compose.yml启动之后修改docker-compose.yml换一个管理账号那么除了删除volumes文件夹还要清空对应的数据库数据才能生效。5. 服务启动在directus_V12.4.0/目录下执行命令时显式同时加载父级和当前目录的.env文件dockercompose --env-file../.env --env-file .env up-d注意必须同时写上--env-file ../.env和--env-file .env这样 Compose 才能在语法解析阶段同时获取到父级的ENV、NETWORK_NAME以及子级的ES_VERSION。出现这个警告是因为 Docker Compose 在同一个项目名称Project Name下检测到了不属于当前docker-compose.yml文件定义的其他容器。警告原因分析出现该警告的核心原因在于多个子服务共享了同一个 Docker Compose 项目名称Project Name项目名称统一由于公共配置文件中统一指定了固定的COMPOSE_PROJECT_NAME例如devDocker Compose 会将该项目下的所有服务如容器 A、容器 B 等归入同一个逻辑项目集中管理。局部文件读取当在某个独立的服务子目录下执行部署命令时Docker Compose 仅会加载当前目录下的docker-compose.yml配置文件。识别为孤儿容器Compose 在检查全局项目状态时发现该项目下存在其他已经在运行、但未定义在当前docker-compose.yml文件中的容器因此将其标记为“孤儿容器orphan containers”并发出提醒。影响说明无负面影响这仅是 Docker Compose 的正常提示信息不会影响当前服务的启动与运行也不会自动删除或干预其他正在运行的容器。符合预期将多个组件放在同一个大项目名下属于合理的管理方式只要已运行的其他服务仍需继续提供服务完全忽略此警告即可。6. 浏览器访问注意这里要加/login否则edge会识别有问题。http://localhost:8055设置中可以选择中文