SpringOpen
搜索 K

外观

配置说明 ​

受众：开发者 摘要：项目常用配置来源和目录约定。.env / application.yml / 静态资源 / 私有持久化目录。

本文档说明项目常用配置来源和目录约定。

配置优先级 ​

基础原则：

  1. 管理后台配置优先。
  2. 本地 application.yml / application-*.yml / .env 兜底。
  3. 默认值保证本地开发尽量开箱即用。

涉及第三方服务商的能力，例如 Mail、SMS、Storage、Translate、Notification、Payment，通常支持数据库配置同名 key 覆盖本地文件配置。

配置命名 ​

  • Spring 配置前缀：spring.open.*
  • 自定义 Starter 的环境变量前缀：SPRING_OPEN_*
  • 数据库连接环境变量使用简洁风格：DB_HOST、DB_PORT、DB_DATABASE、DB_USERNAME、DB_PASSWORD；Docker 初始化 MySQL root 密码使用 DB_ROOT_PASSWORD
  • Redis 使用：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_DATABASE
  • 应用基础变量使用：APP_NAME、APP_PORT、APP_VERSION、APP_SECRET

application.yml 不为每个配置项都预置环境变量占位符。只有应用元信息、数据库、Redis、应用共享密钥、第三方账号密钥、RPC 地址、对象存储和 Webhook 等部署差异值，才保留环境变量入口。普通开关、TTL、容量、线程数和默认资源选择等配置，直接在 application.yml、application-*.yml 或后台配置中修改。

部署差异项如果没有安全的通用默认值，应保持空值，例如收款钱包、私钥、证书、第三方 API key。不要在运行配置里写 REPLACE_*、假钱包地址或假密钥；后台配置页面可以用字段说明提示管理员填写。

.env ​

.env 只保留本地启动必须的基础配置，避免把所有可选能力都堆进去。

Config Starter 会在 Spring Boot 读取 application.yml 前自动加载 .env，不需要在 application.yml 中显式配置 spring.config.import。默认读取顺序如下，后面的文件会覆盖前面的同名 key：

text
./.env
./.env.properties
../.env
../.env.properties
./config/.env
./config/.env.properties
./config/*/.env
./config/*/.env.properties
../config/.env
../config/.env.properties
../config/*/.env
../config/*/.env.properties
./docker/.env
./docker/.env.properties
../docker/.env
../docker/.env.properties

.env 的优先级低于命令行参数、JVM 参数和系统环境变量，高于 application.yml 中的默认值。因此生产环境显式声明的环境变量会覆盖本地 .env。

可通过启动参数或系统环境变量调整 Dotenv 加载行为：

dotenv
SPRING_OPEN_CONFIG_DOTENV_ENABLED=false
SPRING_OPEN_CONFIG_DOTENV_INCLUDE_DEFAULT_LOCATIONS=false
SPRING_OPEN_CONFIG_DOTENV_LOCATIONS=/etc/spring-open,/run/secrets/spring-open.env

对应 Spring 配置项为：

yaml
spring:
  open:
    config:
      dotenv:
        enabled: true
        include-default-locations: true
        locations:
          - /etc/spring-open
          - /run/secrets/spring-open.env

由于 Dotenv 加载发生在 application.yml 之前，用于控制 Dotenv 自身的 spring.open.config.dotenv.* 通常应来自系统环境变量、JVM 参数或命令行参数。 locations 支持普通文件、目录、通配文件模式和 [.properties] 可选后缀；目录路径会按 .env、.env.properties 顺序读取。

典型内容：

dotenv
APP_NAME=spring-open
APP_PORT=8000
# APP_SECRET=

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=spring_open
DB_USERNAME=spring_open
DB_PASSWORD=spring_open
# DB_TYPE=com.zaxxer.hikari.HikariDataSource
# DB_DRIVER_CLASS_NAME=com.mysql.cj.jdbc.Driver
# DB_ROOT_PASSWORD=root

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DATABASE=0

# PostgreSQL configuration
# DB_PORT=5432
# DB_URL=jdbc:postgresql://127.0.0.1:5432/spring_open
# DB_DRIVER_CLASS_NAME=org.postgresql.Driver

常用环境变量：

变量默认值说明
APP_NAMEspring-open应用名；站点展示名和 OpenAPI 标题会从它派生
APP_PORT8000HTTP 端口
APP_SECRET空应用共享密钥；留空时本地会用应用名和设备标识派生，数据库配置中心可播种共享值
APP_STORAGE_DIR${user.dir}/storage私有持久化根目录；不配置时使用当前工作目录下的 storage/；本地从 spring-open-application 模块目录启动时会自动回退到仓库根目录
APP_PUBLIC_DIR${user.dir}/public公开静态资源目录；不配置时使用当前工作目录下的 public/；本地从 spring-open-application 模块目录启动时会自动回退到仓库根目录
LOG_FILE_NAMEstorage/runtime/logs/app.logSpring Boot 日志文件路径；默认固定为 app.log，多实例部署可显式覆盖
SPRING_PROFILES_ACTIVEMaven profile 默认值运行环境：dev、test、prod、lite
SPRING_OPEN_INSTALL_ENABLEDdev 为 false，prod 为 true是否启用安装向导和安装流程
SPRING_OPEN_INSTALL_QUICKSTART_CLEANUP_ENABLEDtrue是否启用后台演示数据清理；独立于安装向导开关
SPRING_OPEN_INSTALL_TOKEN空安装令牌；配置后安装接口要求输入匹配令牌

应用配置 ​

应用主配置位于：

text
spring-open-application/src/main/resources/application.yml

环境配置位于：

text
spring-open-application/src/main/resources/application-dev.yml
spring-open-application/src/main/resources/application-test.yml
spring-open-application/src/main/resources/application-prod.yml
spring-open-application/src/main/resources/application-lite.yml

application.yml 放基础兜底配置，各环境文件只保留必要差异。不要把所有 spring.open.* 都搬进 .env；.env 更适合存放本机数据库、Redis 和敏感凭证。

启动模式 ​

默认配置遵循“最小配置先启动，再按生产要求收紧”的原则：

模式外部依赖用途验证护栏
devMySQL + Redis日常本地开发，按 .env 提供数据库和 Redis 连接与 application.yml 默认装配一致
lite无外部依赖，测试中使用 H2兼容诊断、最小启动和快速 smokespring-open-application/src/test/java/com/springopen/application/StartupApplicationSmokeTest.java
testTestcontainers MySQL + Redis近生产基础设施 smokespring-open-application/src/test/java/com/springopen/application/ApplicationInfrastructureIT.java
prod生产 MySQL / Redis / 外部 Provider正式部署参见 生产部署样板 与 安全与依赖基线

真实外部 Provider（真实支付、真实短信、真实邮件、真实 AI 上游、真实链上出款、数据库备份等）不因主模块启用而自动产生真实外呼或真实资金动作，必须显式配置 Provider 凭据、开关、回调和验收记录。AI 商家 realtime 能力矩阵、外部 payout Provider、数据库备份、Knowledge 持久向量库、i18n 数据库覆盖等属于有成本、安全或暗启动语义的例外，默认保持关闭或无 Provider。

模块开关矩阵 ​

全量应用默认装配业务模块；需要裁剪运行面时，优先使用模块开关。表中默认值均为 true，未配置即启用；关闭后要求模块自身入口 backoff，跨模块消费者通过 ObjectProvider、条件 Bean 或空实现降级。

模块开关 key关闭效果
Advertisingspring.open.advertising.enabled关闭广告位、素材、投放和结算运营面
AIspring.open.ai.enabled关闭 AI 平台、模型网关和商家工作台业务面
Blogspring.open.blog.enabled关闭博客文章、分类、评论、订阅和知识来源贡献
Chatspring.open.conversation.enabled关闭聊天会话用户入口和客服支持入口
CMSspring.open.cms.enabled关闭内容、轮播、导航、公告和审核治理入口
Distributionspring.open.distribution.enabled关闭分销关系、佣金生成和结算入口
Formspring.open.form.enabled关闭表单定义、提交和后台管理入口
Forumspring.open.forum.enabled关闭论坛板块、主题、回复和通知绑定入口
Installspring.open.install.enabled关闭安装向导和安装状态写入口
Livespring.open.live.enabled关闭直播间、预约、聊天、录制和运营入口
Live Codespring.open.live-code.enabled关闭活码公开解析、跳转和后台管理入口
Mallspring.open.mall.enabled关闭商城商品、购物车、订单、售后和商家入口
Marketingspring.open.marketing.enabled关闭签到、抽奖、营销活动和奖励发放入口
Marketplacespring.open.marketplace.enabled关闭交易市场商品、订单、推广和结算入口
Meetingspring.open.meeting.enabled关闭会议、RTC、套餐和开放 API 入口
Open Platformspring.open.open-platform.enabled关闭开放平台应用、Key、Web3 开放 API 和控制台入口
Payment Platformspring.open.payment-platform.enabled关闭聚合支付商户、商户应用、支付和结算入口
Readingspring.open.reading.enabled关闭阅读内容、书架、书源同步和版权投诉入口
Searchspring.open.search.enabled关闭统一搜索聚合入口和模块搜索 Provider
Short Linkspring.open.short-link.enabled关闭短链接公开跳转和后台管理入口
Videospring.open.video.enabled关闭视频内容、互动、创作者结算和推荐入口

核心能力也按同一口径提供可裁剪开关；spring.open.config.enabled 和 spring.open.iam.enabled 属常驻底座，不建议关闭整域，只关闭其子能力或移除对应依赖。

能力开关 key关闭效果
Notificationspring.open.notification.enabled关闭通知发送、通知消息和用户通知偏好入口
Knowledgespring.open.knowledge.enabled关闭知识库切片、索引、检索和问答底座
Content Safetyspring.open.content-safety.enabled关闭内容安全检测 Manager 和默认 Provider
Reportingspring.open.reporting.enabled关闭报表定义、查询和导出运行时
Riskspring.open.risk.enabled关闭风控规则、限额和风险运维入口
Feature Flagspring.open.feature-flag.enabled关闭 Feature Flag 运行时和管理入口
Moneyspring.open.money.enabled关闭余额账户、台账、充值、提现和资产兑换入口
Web3 Starterspring.open.web3.enabled关闭 Web3 钱包、RPC、价格、DEX 和地址簿 starter 能力
Money Web3spring.open.money.web3.enabled关闭 Money Web3 充值、提现、桥和结算业务能力
Queuespring.open.queue.enabled关闭队列 Manager、失败任务和后台运维入口
Schedulerspring.open.scheduler.enabled关闭调度 Manager、执行日志和后台运维入口
Rate Limitspring.open.rate-limit.enabled关闭限流 Manager 和注解限流入口
Pluginspring.open.plugin.enabled关闭插件元数据发现和生命周期执行入口

静态资源 ​

公开文件默认放在：

text
public/

目标效果：

text
public/test.txt -> http://localhost:8000/test.txt

私有持久化文件放在：

text
storage/

临时运行文件放在：

text
storage/runtime/

缓存文件默认放在：

text
storage/runtime/cache/

Spring Boot 日志默认放在：

text
storage/runtime/logs/

storage/.gitignore 直接覆盖 storage/database/、storage/runtime/、storage/runtime/cache/ 和 storage/runtime/logs/，即使这些子目录被删除，忽略规则也仍然保留；实际数据库文件、运行文件、缓存文件和日志文件默认不进入 Git。storage/database/、私有文件和密钥不应随意清理。

Released under the Apache License 2.0.

Copyright © SpringOpen