前言微服务项目里数据库密码、大模型 API Key 等敏感信息如果写在application.properties并提交到 Git极易造成泄露。本文介绍一种轻量方案用.env文件 做环境隔离配合 Java 生态的dotenv-java库安全加载配置。一、需求背景1.1 硬编码配置的问题// 反例配置直接写在代码里String dbUrl jdbc:mysql://localhost:3306/db;问题说明违反开闭原则改配置就要改代码、重新部署多人协作冲突每人本地环境不同容易互相覆盖环境切换困难开发、测试、生产要频繁改代码1.2 敏感信息暴露的风险application.properties中常包含数据库账号密码大模型 API KeyOSS 密钥第三方服务 Token一旦误提交 Git后果严重风险说明安全泄露公开仓库可被爬取密钥黑客攻击密钥被滥用产生费用或数据泄露合规风险金融、医疗等行业有严格安全要求协作混乱多人项目应各自维护本地密钥不能外传二、解决方案.env 文件2.1 什么是 .env 文件.env是一种轻量配置格式用 KEYVALUE 键值对存储配置将配置与代码分离集中管理环境变量跨环境、跨语言通用语法简单无需像.properties那样转义也不像.yaml那样严格要求缩进2.2 .env 文件示例# .env 文件内容 DB_URLjdbc:mysql://localhost:3306/mydb DB_USERroot DB_PASS123456 # 数据库密码支持注释 APP_PORT8080 # AI 相关配置示例 LLM_API_KEYsk-xxxxxxxxxxxxxxxx LLM_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 EMBEDDING_API_KEYsk-xxxxxxxxxxxxxxxx2.3 .env 的核心优势优势说明无侵入独立文件存在改配置不动代码跨语言通用Java、Python、Node.js、Go 都有对应库关注点分离配置与业务代码解耦安全隔离.env加入.gitignore敏感信息不进版本库2.4 各语言对应库语言库名Javadotenv-javaNode.jsdotenvPythonpython-dotenvGogodotenv三、Java 实现dotenv-java 库3.1 为什么用 dotenv-java传统FileReader手动读取配置要自己处理空格、空行、注释容易出错没有类型安全和默认值缺少必填校验dotenv-java可以自动完成这些事。3.2 Maven 依赖dependency groupIdio.github.cdimascio/groupId artifactIddotenv-java/artifactId version3.0.0/version /dependency3.3 核心特性① 环境变量兼容优先读取系统环境变量没有再读.env文件方便 Docker/K8s 部署。② 类型安全与默认值// 获取配置不存在时使用默认值String port dotenv.get(APP_PORT, 8080);③ 自动加载默认从项目根目录加载.env文件。④ 自定义路径// 加载指定环境的配置文件 Dotenv dotenv Dotenv.configure() .directory(./config) .filename(.env.dev) .load();⑤ 必填校验// 关键配置缺失时直接报错防止带病启动 String dbPass dotenv.get(DB_PASS); // 或使用 required 强制校验 dotenv.entries().forEach(entry - { // 启动时检查必要配置 });四、项目目录结构建议project-root/├── src/├── config/│ ├── .env.dev # 开发环境不提交 Git│ ├── .env.test # 测试环境不提交 Git│ └── .env.prod # 生产环境不提交 Git├── .env.example # 配置模板提交 Git无真实密钥├── .gitignore # 忽略 .env 文件└── pom.xml.gitignore 配置# 忽略所有真实环境配置 .env .env.* !.env.example # 或者精确忽略 config/.env.dev config/.env.test config/.env.prod.env.example 模板可提交 Git# 数据库配置 DB_URLjdbc:mysql://localhost:3306/mydb DB_USERyour_username DB_PASSyour_password # 应用配置 APP_PORT8080 # AI 大模型配置 LLM_API_KEYyour_api_key_here LLM_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 LLM_MODELqwen-plus # Embedding 配置 EMBEDDING_API_KEYyour_embedding_key_here EMBEDDING_MODELtext-embedding-v4 # OSS 配置 OSS_ENDPOINTyour_endpoint OSS_ACCESS_KEYyour_access_key OSS_SECRET_KEYyour_secret_key五、与 Spring Boot 集成思路5.1 加载时机在 Spring Boot 启动类或配置类中早于application.yml加载.env将值注入系统属性或自定义配置源。5.2 配置优先级建议系统环境变量最高↓.env 文件↓application-{profile}.yml↓application.yml最低5.3 典型使用场景配置项存放位置原因数据库密码.env敏感大模型 API Key.env敏感OSS 密钥.env敏感服务端口.env或 yml环境相关业务开关application.yml非敏感日志级别application.yml非敏感六、多环境隔离方案6.1 按环境分文件环境文件部署位置本地开发config/.env.dev开发者本机测试环境config/.env.test测试服务器生产环境config/.env.prod生产服务器6.2 启动时指定环境# 开发环境 java -jar app.jar --spring.profiles.activedev # 通过环境变量指定 dotenv 文件 export DOTENV_FILEconfig/.env.prod java -jar app.jar6.3 Docker 部署# docker-compose.yml services: app: image: my-app:latest env_file: - config/.env.prod # 生产配置不入镜像 ports: - 8080:8080七、安全最佳实践实践说明.env永不提交 Git加入.gitignore提供.env.example只含字段名和占位符生产密钥独立管理每台服务器单独配置定期轮换密钥API Key、数据库密码定期更换最小权限原则数据库账号只给必要权限启动时校验必填项缺关键配置直接失败日志脱敏打印配置时屏蔽密码和 Key八、常见问题Q1.env 和 application.yml 有什么区别.env放敏感、环境相关配置不进 Gitapplication.yml放非敏感、业务相关配置可进 GitQ2团队新人如何知道要配哪些项提供.env.exampleREADME 中说明复制为.env.dev并填写。Q3生产环境怎么用服务器上放config/.env.prod或通过 K8s Secret / 云平台密钥管理注入不要把生产密钥打进 Docker 镜像Q4已有 application.yml 还要 .env 吗建议敏感项迁到.env非敏感项保留在 yml两者配合使用。九、知识点总结要点内容核心问题硬编码配置 敏感信息进 Git解决方案.env文件 dotenv-java关键原则配置与代码分离、敏感信息不进版本库Java 工具dotenv-java自动加载、默认值、必填校验多环境.env.dev/.env.test/.env.prod安全实践.gitignore.env.example 密钥轮换
配置信息防泄露方案：.env 环境隔离详解（dotenv-java）
前言微服务项目里数据库密码、大模型 API Key 等敏感信息如果写在application.properties并提交到 Git极易造成泄露。本文介绍一种轻量方案用.env文件 做环境隔离配合 Java 生态的dotenv-java库安全加载配置。一、需求背景1.1 硬编码配置的问题// 反例配置直接写在代码里String dbUrl jdbc:mysql://localhost:3306/db;问题说明违反开闭原则改配置就要改代码、重新部署多人协作冲突每人本地环境不同容易互相覆盖环境切换困难开发、测试、生产要频繁改代码1.2 敏感信息暴露的风险application.properties中常包含数据库账号密码大模型 API KeyOSS 密钥第三方服务 Token一旦误提交 Git后果严重风险说明安全泄露公开仓库可被爬取密钥黑客攻击密钥被滥用产生费用或数据泄露合规风险金融、医疗等行业有严格安全要求协作混乱多人项目应各自维护本地密钥不能外传二、解决方案.env 文件2.1 什么是 .env 文件.env是一种轻量配置格式用 KEYVALUE 键值对存储配置将配置与代码分离集中管理环境变量跨环境、跨语言通用语法简单无需像.properties那样转义也不像.yaml那样严格要求缩进2.2 .env 文件示例# .env 文件内容 DB_URLjdbc:mysql://localhost:3306/mydb DB_USERroot DB_PASS123456 # 数据库密码支持注释 APP_PORT8080 # AI 相关配置示例 LLM_API_KEYsk-xxxxxxxxxxxxxxxx LLM_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 EMBEDDING_API_KEYsk-xxxxxxxxxxxxxxxx2.3 .env 的核心优势优势说明无侵入独立文件存在改配置不动代码跨语言通用Java、Python、Node.js、Go 都有对应库关注点分离配置与业务代码解耦安全隔离.env加入.gitignore敏感信息不进版本库2.4 各语言对应库语言库名Javadotenv-javaNode.jsdotenvPythonpython-dotenvGogodotenv三、Java 实现dotenv-java 库3.1 为什么用 dotenv-java传统FileReader手动读取配置要自己处理空格、空行、注释容易出错没有类型安全和默认值缺少必填校验dotenv-java可以自动完成这些事。3.2 Maven 依赖dependency groupIdio.github.cdimascio/groupId artifactIddotenv-java/artifactId version3.0.0/version /dependency3.3 核心特性① 环境变量兼容优先读取系统环境变量没有再读.env文件方便 Docker/K8s 部署。② 类型安全与默认值// 获取配置不存在时使用默认值String port dotenv.get(APP_PORT, 8080);③ 自动加载默认从项目根目录加载.env文件。④ 自定义路径// 加载指定环境的配置文件 Dotenv dotenv Dotenv.configure() .directory(./config) .filename(.env.dev) .load();⑤ 必填校验// 关键配置缺失时直接报错防止带病启动 String dbPass dotenv.get(DB_PASS); // 或使用 required 强制校验 dotenv.entries().forEach(entry - { // 启动时检查必要配置 });四、项目目录结构建议project-root/├── src/├── config/│ ├── .env.dev # 开发环境不提交 Git│ ├── .env.test # 测试环境不提交 Git│ └── .env.prod # 生产环境不提交 Git├── .env.example # 配置模板提交 Git无真实密钥├── .gitignore # 忽略 .env 文件└── pom.xml.gitignore 配置# 忽略所有真实环境配置 .env .env.* !.env.example # 或者精确忽略 config/.env.dev config/.env.test config/.env.prod.env.example 模板可提交 Git# 数据库配置 DB_URLjdbc:mysql://localhost:3306/mydb DB_USERyour_username DB_PASSyour_password # 应用配置 APP_PORT8080 # AI 大模型配置 LLM_API_KEYyour_api_key_here LLM_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 LLM_MODELqwen-plus # Embedding 配置 EMBEDDING_API_KEYyour_embedding_key_here EMBEDDING_MODELtext-embedding-v4 # OSS 配置 OSS_ENDPOINTyour_endpoint OSS_ACCESS_KEYyour_access_key OSS_SECRET_KEYyour_secret_key五、与 Spring Boot 集成思路5.1 加载时机在 Spring Boot 启动类或配置类中早于application.yml加载.env将值注入系统属性或自定义配置源。5.2 配置优先级建议系统环境变量最高↓.env 文件↓application-{profile}.yml↓application.yml最低5.3 典型使用场景配置项存放位置原因数据库密码.env敏感大模型 API Key.env敏感OSS 密钥.env敏感服务端口.env或 yml环境相关业务开关application.yml非敏感日志级别application.yml非敏感六、多环境隔离方案6.1 按环境分文件环境文件部署位置本地开发config/.env.dev开发者本机测试环境config/.env.test测试服务器生产环境config/.env.prod生产服务器6.2 启动时指定环境# 开发环境 java -jar app.jar --spring.profiles.activedev # 通过环境变量指定 dotenv 文件 export DOTENV_FILEconfig/.env.prod java -jar app.jar6.3 Docker 部署# docker-compose.yml services: app: image: my-app:latest env_file: - config/.env.prod # 生产配置不入镜像 ports: - 8080:8080七、安全最佳实践实践说明.env永不提交 Git加入.gitignore提供.env.example只含字段名和占位符生产密钥独立管理每台服务器单独配置定期轮换密钥API Key、数据库密码定期更换最小权限原则数据库账号只给必要权限启动时校验必填项缺关键配置直接失败日志脱敏打印配置时屏蔽密码和 Key八、常见问题Q1.env 和 application.yml 有什么区别.env放敏感、环境相关配置不进 Gitapplication.yml放非敏感、业务相关配置可进 GitQ2团队新人如何知道要配哪些项提供.env.exampleREADME 中说明复制为.env.dev并填写。Q3生产环境怎么用服务器上放config/.env.prod或通过 K8s Secret / 云平台密钥管理注入不要把生产密钥打进 Docker 镜像Q4已有 application.yml 还要 .env 吗建议敏感项迁到.env非敏感项保留在 yml两者配合使用。九、知识点总结要点内容核心问题硬编码配置 敏感信息进 Git解决方案.env文件 dotenv-java关键原则配置与代码分离、敏感信息不进版本库Java 工具dotenv-java自动加载、默认值、必填校验多环境.env.dev/.env.test/.env.prod安全实践.gitignore.env.example 密钥轮换
