docker-minecraft-server 环境变量配置完全指南4 个场景实现零改镜像的动态部署【免费下载链接】docker-minecraft-serverDocker image that provides a Minecraft Server for Java Edition that automatically installs/upgrades versions, modloaders, modpacks and more at startup项目地址: https://gitcode.com/GitHub_Trending/do/docker-minecraft-server改一次插件的数据库地址就要重新构建一次镜像或者手动进容器改文件——这个循环谁都不想经历。docker-minecraft-server 自带的环境变量改造配置文件能力就是为此准备的容器启动时它会扫描/data下的配置文件把${CFG_DB_HOST}这样的占位符替换成你传入的环境变量值。数据库地址、服务器名、密钥都在部署阶段注入镜像一行不动。这套机制只依赖两样东西配置文件里按${变量名}语法写好的占位符和容器启动时传入的环境变量。下面按 4 个真实部署场景走一遍每个场景给出最小可运行的配置片段。REPLACE_ENV_IN_PLACE 的工作方式扫描 /data 并替换${变量}REPLACE_ENV_IN_PLACE为true默认值时启动脚本会遍历容器内/data路径下的所有文件把与容器环境变量匹配的${...}占位符就地替换。因为只有带前缀的变量名才参与替换——前缀由REPLACE_ENV_VARIABLE_PREFIX控制默认是CFG_——所以${CFG_DB_HOST}会被替换而${DB_HOST}不会把前缀设为空字符串则允许匹配任意变量名。替换发生在服务器进程启动之前Minecraft 首次读到的配置就已经是替换后的内容。测试服与生产服共用一套配置切换数据库连接的写法Paper 服务器上常挂 Essentials、LuckPerms 这类需要连外部数据库的插件而测试服和生产服的数据库地址不同。把地址写死在配置文件里换环境就得手动改写进镜像更不行因为数据库连接本属于部署信息。做法是在database.yml里用占位符host: ${CFG_DB_HOST}、name: ${CFG_DB_NAME}、password: ${CFG_DB_PASSWORD}然后把真实值放在 compose 文件里声明services: minecraft: image: itzg/minecraft-server ports: - 25565:25565 volumes: - mc:/data environment: EULA: TRUE REPLACE_ENV_VARIABLES: TRUE ENV_VARIABLE_PREFIX: CFG_ CFG_DB_HOST: db.internal:3306 CFG_DB_NAME: minecraft volumes: mc: {}这段配置做了什么开启替换、声明前缀、传入两个环境相关的值。效果是同一份仓库文件测试服把CFG_DB_HOST指到测试库、生产服指到生产库改一个值重启容器即生效世界数据完全不受影响。把密钥文件注入配置_FILE后缀引用容器 secrets 密码和上面的主机名不同它不该以明文出现在 compose 文件或 Git 仓库里。docker-minecraft-server 为此提供了_FILE约定占位符照常声明环境变量改成同名加_FILE后缀值指向一个文件路径替换时取的是文件内容而非路径本身。下面这段配置把宿主机上的密钥文件挂载为容器 secret再让占位符${CFG_DB_PASSWORD}取到它的值secrets: db_password: file: ./db_password services: minecraft: image: itzg/minecraft-server secrets: - db_password environment: EULA: TRUE CFG_DB_PASSWORD_FILE: /run/secrets/db_password效果compose 文件里只有路径没有任何明文密码容器启动后/data里的配置已被替换成真实密码但密码的源始终留在宿主机的文件里换密码只需要改文件再重启。用 JSON 补丁修改 paper.yml 的深层嵌套字段有些修改用文本替换表达不了。Paper 的paper.yml是三层嵌套结构比如settings.velocity-support.enabled这种路径而且文件在服务器首次启动前根本不存在占位符替换无从下手。PATCH_DEFINITIONS指向一个补丁 JSON 文件或存放多个补丁文件的目录按 JSON 路径精准设置深层字段value里还能再写${...}占位符。挂载补丁并声明变量{ patches: [ { file: /data/paper.yml, ops: [ { $set: { path: $.settings[velocity-support].enabled, value: ${CFG_VELOCITY_ENABLED}, value-type: bool } } ] } ] }services: minecraft: image: itzg/minecraft-server volumes: - ./patches:/patches:ro environment: EULA: TRUE TYPE: PAPER PATCH_DEFINITIONS: /patches/paper-patch.json CFG_VELOCITY_ENABLED: true效果补丁在每次启动时都会执行即使插件或服务器重新生成了配置文件深层字段也能被稳定覆盖补丁内的占位符同样受CFG_前缀约束。补丁文件支持 JSON、JSON5、YAML、TOML 格式不只局限于改 YAML。同步 /config 挂载目录时触发占位符替换很多部署会把宿主机的./config只读挂载到容器/config首次启动时镜像会把其中的插件默认配置复制进/data。复制动作发生在启动早期所以这里由REPLACE_ENV_DURING_SYNC控制模板文件在同步阶段就完成占位符替换复制进/data的已经是成品配置。services: minecraft: image: itzg/minecraft-server volumes: - ./config:/config:ro environment: EULA: TRUE REPLACE_ENV_DURING_SYNC: true CFG_LP_PREFIX: test这段配置做了什么挂载插件配置模板目录并显式开启同步替换该变量默认为开启写出来是为了明确意图不需要时可设false关闭。效果/config里的 LuckPerms 模板带${CFG_LP_PREFIX}占位符同步到/data/plugins时前缀已被替换测试服和生产服共用同一份模板各取各的环境值。环境变量替换的文件范围、排除路径与生效时机几个边界信息提前知道能省掉不少排查时间扩展名范围就地替换默认处理.yml、.yaml、.txt、.cfg、.conf、.properties这些扩展名的文件其他扩展名不会被动到。排除文件REPLACE_ENV_VARIABLES_EXCLUDES按文件名排除不带路径REPLACE_ENV_VARIABLES_EXCLUDE_PATHS按目录排除且递归生效例如REPLACE_ENV_VARIABLES_EXCLUDE_PATHS/data/plugins/Essentials/userdata可以跳过插件的用户数据目录。排除的时机是每次启动替换只发生在启动阶段、服务器进程拉起之前。如果插件运行期间把真实值写回了配置文件下次启动时占位符已不存在替换自然不会再动它——这是设计使然不是 bug。前缀别乱设空REPLACE_ENV_VARIABLE_PREFIX设为空字符串后容器里任意环境变量都成为替换候选包括PATH这类系统变量。日常使用保持默认CFG_即可。把占位符写进配置、把值通过环境变量传入替换工作由 docker-minecraft-server 在启动时自动完成——这就是环境变量改造配置文件的全部机制数据库地址、服务器名、密钥都在部署阶段注入镜像字节不动。完整变量清单见 docs/variables.md更多组合示例参考 examples/docker-compose.yml替换与补丁的细节在 docs/configuration/interpolating.md。【免费下载链接】docker-minecraft-serverDocker image that provides a Minecraft Server for Java Edition that automatically installs/upgrades versions, modloaders, modpacks and more at startup项目地址: https://gitcode.com/GitHub_Trending/do/docker-minecraft-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
docker-minecraft-server 环境变量配置完全指南：4 个场景实现零改镜像的动态部署
docker-minecraft-server 环境变量配置完全指南4 个场景实现零改镜像的动态部署【免费下载链接】docker-minecraft-serverDocker image that provides a Minecraft Server for Java Edition that automatically installs/upgrades versions, modloaders, modpacks and more at startup项目地址: https://gitcode.com/GitHub_Trending/do/docker-minecraft-server改一次插件的数据库地址就要重新构建一次镜像或者手动进容器改文件——这个循环谁都不想经历。docker-minecraft-server 自带的环境变量改造配置文件能力就是为此准备的容器启动时它会扫描/data下的配置文件把${CFG_DB_HOST}这样的占位符替换成你传入的环境变量值。数据库地址、服务器名、密钥都在部署阶段注入镜像一行不动。这套机制只依赖两样东西配置文件里按${变量名}语法写好的占位符和容器启动时传入的环境变量。下面按 4 个真实部署场景走一遍每个场景给出最小可运行的配置片段。REPLACE_ENV_IN_PLACE 的工作方式扫描 /data 并替换${变量}REPLACE_ENV_IN_PLACE为true默认值时启动脚本会遍历容器内/data路径下的所有文件把与容器环境变量匹配的${...}占位符就地替换。因为只有带前缀的变量名才参与替换——前缀由REPLACE_ENV_VARIABLE_PREFIX控制默认是CFG_——所以${CFG_DB_HOST}会被替换而${DB_HOST}不会把前缀设为空字符串则允许匹配任意变量名。替换发生在服务器进程启动之前Minecraft 首次读到的配置就已经是替换后的内容。测试服与生产服共用一套配置切换数据库连接的写法Paper 服务器上常挂 Essentials、LuckPerms 这类需要连外部数据库的插件而测试服和生产服的数据库地址不同。把地址写死在配置文件里换环境就得手动改写进镜像更不行因为数据库连接本属于部署信息。做法是在database.yml里用占位符host: ${CFG_DB_HOST}、name: ${CFG_DB_NAME}、password: ${CFG_DB_PASSWORD}然后把真实值放在 compose 文件里声明services: minecraft: image: itzg/minecraft-server ports: - 25565:25565 volumes: - mc:/data environment: EULA: TRUE REPLACE_ENV_VARIABLES: TRUE ENV_VARIABLE_PREFIX: CFG_ CFG_DB_HOST: db.internal:3306 CFG_DB_NAME: minecraft volumes: mc: {}这段配置做了什么开启替换、声明前缀、传入两个环境相关的值。效果是同一份仓库文件测试服把CFG_DB_HOST指到测试库、生产服指到生产库改一个值重启容器即生效世界数据完全不受影响。把密钥文件注入配置_FILE后缀引用容器 secrets 密码和上面的主机名不同它不该以明文出现在 compose 文件或 Git 仓库里。docker-minecraft-server 为此提供了_FILE约定占位符照常声明环境变量改成同名加_FILE后缀值指向一个文件路径替换时取的是文件内容而非路径本身。下面这段配置把宿主机上的密钥文件挂载为容器 secret再让占位符${CFG_DB_PASSWORD}取到它的值secrets: db_password: file: ./db_password services: minecraft: image: itzg/minecraft-server secrets: - db_password environment: EULA: TRUE CFG_DB_PASSWORD_FILE: /run/secrets/db_password效果compose 文件里只有路径没有任何明文密码容器启动后/data里的配置已被替换成真实密码但密码的源始终留在宿主机的文件里换密码只需要改文件再重启。用 JSON 补丁修改 paper.yml 的深层嵌套字段有些修改用文本替换表达不了。Paper 的paper.yml是三层嵌套结构比如settings.velocity-support.enabled这种路径而且文件在服务器首次启动前根本不存在占位符替换无从下手。PATCH_DEFINITIONS指向一个补丁 JSON 文件或存放多个补丁文件的目录按 JSON 路径精准设置深层字段value里还能再写${...}占位符。挂载补丁并声明变量{ patches: [ { file: /data/paper.yml, ops: [ { $set: { path: $.settings[velocity-support].enabled, value: ${CFG_VELOCITY_ENABLED}, value-type: bool } } ] } ] }services: minecraft: image: itzg/minecraft-server volumes: - ./patches:/patches:ro environment: EULA: TRUE TYPE: PAPER PATCH_DEFINITIONS: /patches/paper-patch.json CFG_VELOCITY_ENABLED: true效果补丁在每次启动时都会执行即使插件或服务器重新生成了配置文件深层字段也能被稳定覆盖补丁内的占位符同样受CFG_前缀约束。补丁文件支持 JSON、JSON5、YAML、TOML 格式不只局限于改 YAML。同步 /config 挂载目录时触发占位符替换很多部署会把宿主机的./config只读挂载到容器/config首次启动时镜像会把其中的插件默认配置复制进/data。复制动作发生在启动早期所以这里由REPLACE_ENV_DURING_SYNC控制模板文件在同步阶段就完成占位符替换复制进/data的已经是成品配置。services: minecraft: image: itzg/minecraft-server volumes: - ./config:/config:ro environment: EULA: TRUE REPLACE_ENV_DURING_SYNC: true CFG_LP_PREFIX: test这段配置做了什么挂载插件配置模板目录并显式开启同步替换该变量默认为开启写出来是为了明确意图不需要时可设false关闭。效果/config里的 LuckPerms 模板带${CFG_LP_PREFIX}占位符同步到/data/plugins时前缀已被替换测试服和生产服共用同一份模板各取各的环境值。环境变量替换的文件范围、排除路径与生效时机几个边界信息提前知道能省掉不少排查时间扩展名范围就地替换默认处理.yml、.yaml、.txt、.cfg、.conf、.properties这些扩展名的文件其他扩展名不会被动到。排除文件REPLACE_ENV_VARIABLES_EXCLUDES按文件名排除不带路径REPLACE_ENV_VARIABLES_EXCLUDE_PATHS按目录排除且递归生效例如REPLACE_ENV_VARIABLES_EXCLUDE_PATHS/data/plugins/Essentials/userdata可以跳过插件的用户数据目录。排除的时机是每次启动替换只发生在启动阶段、服务器进程拉起之前。如果插件运行期间把真实值写回了配置文件下次启动时占位符已不存在替换自然不会再动它——这是设计使然不是 bug。前缀别乱设空REPLACE_ENV_VARIABLE_PREFIX设为空字符串后容器里任意环境变量都成为替换候选包括PATH这类系统变量。日常使用保持默认CFG_即可。把占位符写进配置、把值通过环境变量传入替换工作由 docker-minecraft-server 在启动时自动完成——这就是环境变量改造配置文件的全部机制数据库地址、服务器名、密钥都在部署阶段注入镜像字节不动。完整变量清单见 docs/variables.md更多组合示例参考 examples/docker-compose.yml替换与补丁的细节在 docs/configuration/interpolating.md。【免费下载链接】docker-minecraft-serverDocker image that provides a Minecraft Server for Java Edition that automatically installs/upgrades versions, modloaders, modpacks and more at startup项目地址: https://gitcode.com/GitHub_Trending/do/docker-minecraft-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考