基础设施配置
本页只描述 Wow 自己拥有的配置。连接池、TLS、认证、超时等后端客户端属性仍由 Spring Boot 或原生客户端拥有；请对照应用实际使用的 Spring Boot 版本，而不是把外部属性复制进 Wow 参考页。
capability 与属性是两个门禁
wow.*.enabled=true 不会把实现加入 classpath。应用必须先请求对应的 Starter capability；反过来，capability 在 classpath 上时这些集成默认启用。未使用的 capability 不要提前引入。
Kafka
配置类：KafkaProperties、KafkaReceiverProperties；所需 capability：kafka-support。
| 属性 | 类型 | 默认值 | 含义 |
|---|---|---|---|
wow.kafka.enabled | Boolean | true | 启用 Kafka 自动配置 |
wow.kafka.bootstrap-servers | List<String> | 无，必填 | 发送端和接收端 bootstrap 地址 |
wow.kafka.topic-prefix | String | wow. | Command/DomainEvent/StateEvent topic 前缀 |
wow.kafka.properties | Map<String, String> | {} | 生产者与消费者公共 Kafka 属性 |
wow.kafka.producer | Map<String, String> | {} | 生产者覆盖；优先级高于公共属性 |
wow.kafka.consumer | Map<String, String> | {} | 消费者覆盖；优先级高于公共属性 |
wow.kafka.receiver.prefetch-batches | Int | 1 | Reactor Kafka 预取的 poll 批次数 |
wow.kafka.receiver.max-deferred-commits | Int | 1 | 为乱序提交保留的最大 deferred commit 数 |
wow.kafka.receiver.retry-attempts | Long | 3 | 一次连续 receive failure burst 的最大尝试次数 |
wow.kafka.receiver.retry-backoff | Duration | 10s | 接收重试的最小退避 |
wow.kafka.receiver.decode-failure-strategy | Enum | fail | fail 或 acknowledge |
wow:
kafka:
bootstrap-servers: ${KAFKA_BOOTSTRAP_SERVERS}
producer:
acks: all
receiver:
decode-failure-strategy: failfail 让无效记录终止当前接收并进入 receiver retry；acknowledge 确认并跳过无效记录。后者会放弃该记录，只有在已有隔离、审计和人工恢复路径时才应使用。Wow 创建 Bus 客户端，但 topic/partition、ACL、retention、consumer lag、备份和位点恢复仍由应用平台负责。
MongoDB
配置类：MongoProperties、MongoEventStoreBatchProperties、MongoSnapshotStoreBatchProperties；所需 capability：mongo-support。
| 属性 | 类型 | 默认值 | 含义 |
|---|---|---|---|
wow.mongo.enabled | Boolean | true | 启用 Mongo 自动配置 |
wow.mongo.auto-init-schema | Boolean | true | 启动时初始化 Wow collection/index schema |
wow.mongo.event-stream-database | String? | null | EventStore 数据库；空值使用 Spring 主数据库 |
wow.mongo.snapshot-database | String? | null | SnapshotStore/查询数据库；空值使用 Spring 主数据库 |
wow.mongo.prepare-database | String? | null | PrepareKey 数据库；空值使用 Spring 主数据库 |
连接由 Spring Boot 的 spring.mongodb.* 属性拥有：
spring:
mongodb:
uri: ${MONGODB_URI}两个批处理器默认关闭；启用后才按 collection 聚合并发写入。
| 精确属性 | 默认值 |
|---|---|
wow.mongo.event-store-batch.enabled | false |
wow.mongo.event-store-batch.max-size | 128 |
wow.mongo.event-store-batch.max-delay | 1ms |
wow.mongo.event-store-batch.max-pending-items | 4096 |
wow.mongo.event-store-batch.lane-count | 1 |
wow.mongo.snapshot-store-batch.enabled | false |
wow.mongo.snapshot-store-batch.max-size | 128 |
wow.mongo.snapshot-store-batch.max-delay | 1ms |
wow.mongo.snapshot-store-batch.max-pending-items | 4096 |
wow.mongo.snapshot-store-batch.lane-count | 1 |
max-size 必须在 2 到 536870911 之间（Reactor 预取计算上限），max-delay 必须为正数，pending 上限不得小于 max-size，lane-count 必须在 1 到 max-pending-items 之间。同一聚合始终进入同一 lane；Writer 忙碌时保留单项积压，恢复写入需求后按不超过 max-size 重新合批，不足一批时也可能立即发出，无需再等待一个 max-delay；增加 lane 只能在有吞吐证据时进行。auto-init-schema=true 负责 Wow schema 初始化，不替代数据库备份、分片设计或业务查询索引验证。
MongoDB/Elasticsearch 的四个 Store 构造器统一使用 me.ahoo.wow.infra.batch.BatchOptions；batchOptions = null 表示禁用批处理。Spring 默认仍为 enabled=false。容量字段统一为 max-pending-items，原 max-pending-appends 和 max-pending-saves 不再受支持。批处理溢出、已关闭和关闭超时统一使用核心异常类型。
Redis
配置类：RedisProperties、RedisStreamRecoveryProperties；所需 capability：redis-support。
| 属性 | 类型 | 默认值 | 含义 |
|---|---|---|---|
wow.redis.enabled | Boolean | true | 启用 Redis 自动配置 |
wow.redis.message-bus.recovery.enabled | Boolean | true | 恢复 Redis Streams consumer group 中遗留的 pending 消息 |
wow.redis.message-bus.recovery.min-idle-time | Duration | 5m | pending 消息可被 claim 前的最小 idle 时间 |
wow.redis.message-bus.recovery.interval | Duration | 30s | recovery sweep 间隔 |
wow.redis.message-bus.recovery.batch-size | Long | 100 | 每页 pending 记录数 |
min-idle-time、interval 至少为 1ms，batch-size 必须大于零。连接由 Spring Boot 的 spring.data.redis.* 属性拥有。
spring:
data:
redis:
url: ${REDIS_URL}pending recovery 只处理 Wow Redis Streams Bus 的 consumer-group pending entries；它不是 Redis EventStore/SnapshotStore 备份，也不会恢复已经被裁剪或删除的 Stream 记录。平台仍需负责持久化模式、容量、Stream trimming、consumer group 与备份恢复。
Elasticsearch
配置类：ElasticsearchProperties、ElasticsearchQueryProperties 及两个 batch properties；所需 capability：elasticsearch-support。
| 属性 | 类型 | 默认值 | 含义 |
|---|---|---|---|
wow.elasticsearch.enabled | Boolean | true | 启用 Elasticsearch 自动配置 |
wow.elasticsearch.auto-init-template | Boolean | true | 创建/确认 Wow event 与 snapshot index template |
wow.elasticsearch.compatibility-version | Int? | null | 配置后为 REST client 添加兼容媒体类型 header |
wow.elasticsearch.query.batch-size | Int | 10000 | PIT + search_after 的单批大小 |
wow.elasticsearch.query.keep-alive | Duration | 1m | 每次全量查询请求刷新的 PIT keep-alive |
query.batch-size 必须在 1..10000，且不能高于目标索引的 index.max_result_window；keep-alive 必须至少 1ms。连接由 spring.elasticsearch.* 拥有：
spring:
elasticsearch:
uris: ${ELASTICSEARCH_URIS}compatibility-version 没有默认值。只有部署拓扑确实要求 Elasticsearch REST compatibility header 时才设置，并由应用验证该值与服务端兼容；文档不固定某个服务端主版本。
| 精确属性 | 默认值 |
|---|---|
wow.elasticsearch.event-store-batch.enabled | false |
wow.elasticsearch.event-store-batch.max-size | 128 |
wow.elasticsearch.event-store-batch.max-delay | 1ms |
wow.elasticsearch.event-store-batch.max-pending-items | 4096 |
wow.elasticsearch.event-store-batch.lane-count | 1 |
wow.elasticsearch.snapshot-store-batch.enabled | false |
wow.elasticsearch.snapshot-store-batch.max-size | 128 |
wow.elasticsearch.snapshot-store-batch.max-delay | 1ms |
wow.elasticsearch.snapshot-store-batch.max-pending-items | 4096 |
wow.elasticsearch.snapshot-store-batch.lane-count | 1 |
批处理校验与 MongoDB 相同。EventStore batch 使用 Bulk create；SnapshotStore 的 direct/batch 两条路径都以 _source.version 做原子保护更新，避免旧快照覆盖新版本。auto-init-template=true 时，模板请求失败、空响应或未确认会让启动失败；仅在外部平台明确拥有模板时关闭它，并保留模板版本与验证证据。
当 Elasticsearch 被选为 SnapshotStore 或 EventStore 时，Wow 还会查找 META-INF/wow/elasticsearch/{indexName}.json 或 config/wow/elasticsearch/{indexName}.json 下的具体索引资源（wow.{context}.{aggregate}.snapshot、wow.{context}.{aggregate}.es）。具体资源在通用模板之后、对应存储创建之前处理；已有索引保持不变，其 mapping 与资源不同时记录警告。该机制独立于 auto-init-template；资源缺失时不执行任何操作。
查询
配置类：QueryProperties（前缀 wow.query）；启用 Wow 即绑定，不需要单独的 capability。wow.query.http.* 预算作用于入口为 HTTP 的查询：Gateway 在准入时、任何存储 I/O 之前检查它，WebFlux 适配器也用同样的 list 与 page 大小作为响应行数上限。
| 属性 | 类型 | 默认值 | 含义 |
|---|---|---|---|
wow.query.http.max-list-size | Int | 1000 | list/aggregation limit；0 关闭上限并允许 limit 0 |
wow.query.http.max-page-size | Int | 100 | page size 上限；0 关闭 |
wow.query.http.max-page-window | Long | 10000 | page.index * page.size 上限；0 关闭 |
wow.query.http.max-filter-nodes | Int | 128 | FilterExpression 节点数上限；0 关闭 |
wow.query.http.max-filter-values | Int | 1000 | 集合型过滤条件的值数量上限；0 关闭 |
wow.query.http.allow-expensive-operators | Boolean | true | 允许 expensive filters、Elements、metric 排序/算术、表达式分组、DATE_PART 分组、dense 补齐、FIRST/LAST 指标及 match-all count/paged |
wow.query.http.max-residual-groups | Integer | 10000 | 存储无法原生执行 HAVING 或按指标排序、由查询服务计算时（例如 Elasticsearch），一次 HTTP 聚合最多处理的分组数（dense 补齐的行也计入）；0 关闭上限 |
wow.query.require-explicit-entry | Boolean | false | 拒绝未声明查询入口（HTTP 或 IN_PROCESS）的 Gateway 查询；wow.query.http.* 预算作用于入口为 HTTP 的查询 |
wow.query.require-authenticated-scope | Boolean | false | 拒绝已认证范围未固定 tenantId 的 Snapshot 或 EventStream HTTP 查询（403 IllegalAccessQueryScope）；从请求头或路径变量读取的范围是自报的，不算已认证。加载、State 与 tracing 路由只在开启 wow.webflux.state.point-read-admission 时遵循此开关，所以只开此开关、不开点读准入时启动失败。见范围来源 |
wow.query.abac.require-principal-tags | Boolean | false | 拒绝主体没有 ABAC 标签的 HTTP 快照查询（403 IllegalAccessQueryScope）；作用于以 AbacQueryOptions Bean 构造的 AbacQueryPolicy |
wow.query.abac.match-missing-tag-key | Boolean | true | 资源缺少主体的某个标签键时仍作为公开资源匹配；false 要求资源带有该键且取值落在主体的值中 |
wow.query.schema.revalidate-interval | Duration | 5m | 每个实例定期重新加载查询 schema 以发现存储变化的间隔；0s 关闭。wowQuerySchema actuator 端点可按需立即重新校验 |
wow.query.schema.legacy-declarations | warn | fail | warn | 某模型没有任何 9.2 声明、却有 9.1 声明文件（wow-query-schema/{context}/{aggregate}/{model}.json）时的处理：warn 使用推断的 schema，并在日志中写明 9.2 文件应放在哪里；fail 让该模型的 schema 不可用。见迁移 9.1 的声明文件 |
wow.query.sensitivity.display-comparable | Boolean | true | 是否允许过滤与分页排序比较 DISPLAY 敏感字段的原值；false 时与 CONFIDENTIAL 字段一样拒绝（见字段脱敏） |
9.2 之前这些上限的键是 wow.webflux.query.{max-list-size, max-page-size, max-page-window, max-filter-nodes, max-filter-values, allow-expensive-operators}。旧键已弃用（10.0.0 删除），对未设置对应 wow.query.http.* 键的上限仍然生效，启动时告警。9.1 与 9.2 节点共用的配置可以继续用旧键，所有节点升到 9.2 后再改为新键。
所有数值型查询上限必须非负；普通 page size 仍至少为 1，page offset 仍不得超过 Int.MAX_VALUE。allow-expensive-operators=true 是兼容性默认值，不是容量证明；收紧前需验证现有请求和升级路径。
WebFlux
配置类：WebFluxProperties；所需 capability：webflux-support。
| 属性 | 类型 | 默认值 | 含义 |
|---|---|---|---|
wow.webflux.enabled | Boolean | true | 启用内置 Wow HTTP route 装配 |
wow.webflux.global-error.enabled | Boolean | true | 注册 Wow 全局 WebExceptionHandler |
wow.webflux.batch.concurrency | Int | 128 | 批量快照重建与 StateEvent 重发任务并发度 |
wow.webflux.batch.prefetch | Int | 4 | 批量任务 prefetch |
wow.webflux.query.default-list-size | Int | 100 | HTTP list 查询省略 limit 或传 0 时套用的默认值；不超过 wow.query.http.max-list-size；0 关闭默认值并恢复拒绝 limit 0 |
wow.webflux.query.idle-timeout | Duration | 10s | 等待下一结果或完成的最长空闲时间；0s 关闭 |
wow.webflux.query.strict-count-filter | Boolean | false | 拒绝根对象既无 op 也无 operator 的 count 请求体（400，绑定错误 op/INVALID_REQUEST）。关闭时这样的请求体按旧版条件读取，其操作符默认为 ALL，写错的过滤会统计全部行 |
wow.webflux.state.point-read-admission | Boolean | false | State 路由读取的每个状态都像查询一样准入：执行入口策略（含 wow.query.require-authenticated-scope），并在内存中判定调用方范围、QueryPolicy 与快照默认范围，不满足视为不存在（已删除的状态视为不存在；tracing 包含已删除的版本）；响应按查询 schema 脱敏，并限制 tracing。wow.query.require-authenticated-scope 依赖此开关：只开前者、不开此开关时启动失败；见 State 点读 |
wow.webflux.state.tracing-max-versions | Integer | 1000 | 点读准入下一次 tracing 最多返回的版本数；0 关闭上限 |
wow.webflux.command.request.appender.agent.enabled | Boolean | true | 把 User-Agent 写入命令上下文 |
wow.webflux.command.request.appender.ip.enabled | Boolean | true | 把解析出的远端 IP 写入命令上下文 |
批量并发度按请求生效，并由快照重建与 StateEvent 重发共享；多个并发请求会叠加下游负载，应按应用与存储容量下调。
webflux-support 注册命令、事件、快照查询以及重建/补偿等内置 route，但不自动提供业务认证、授权或管理面隔离。应用必须从运行时 OpenAPI 取得实际路径，并为修改性运维 route 配置鉴权、审计、限流和受控网络入口。