配置参考

Wippy 通过 .wippy.yaml 文件进行配置。所有选项都有合理的默认值。

下面的任何值都可以在启动时通过 wippy run --set section.path=value 覆盖（可重复使用，优先级高于文件）。如需覆盖单个注册表入口而非这些配置区段，请使用 override: 区段或 -o——参见覆盖入口。

配置组合

--config 可重复使用；文件按相同的 schema 从左到右组合：

wippy run --config .wippy.yaml --config .wippy.local.yaml

• 后面的文件覆盖匹配的值并保留其余内容。
• 每个显式指定的文件都必须存在。不带 --config 时，默认的 .wippy.yaml 是可选的。
• 第一个文件锚定用于解析相对路径的目录。
• 文件名不带任何保留含义；除默认文件外不会自动发现任何文件。

配置按顺序应用：文件组合，然后是 --profile 选择，最后是 --set 覆盖。对于从包运行的应用，打包的运行时默认值位于所有这些之下（参见发布运行时默认值）。

Profiles

配置文件可以在 profiles: 下声明具名的覆盖层。每个 profile 主体与普通配置区段的结构相同；通过 --profile <name> 选择后，这些值会叠加到合并后的基础配置之上：

version: "1.0"

vars:
  port: 8085

override:
  app:db:kind: db.sql.sqlite

disable:
  namespaces: ["legacy.**"]

profiles:
  pg:
    vars:
      port: 18085
    override:
      app:db:kind: db.sql.postgres
    disable:
      namespaces.add: ["experimental.**"]

wippy run --profile pg

• --profile 可重复使用；profile 从左到右组合，在文件组合之后、--set 之前应用。未知名称会报错。
• 值按叶子合并（后写者胜出）。profiles: 区段本身会从解析后的配置中剥离。
• disable 区段在 profile 内支持列表操作 — namespaces.add、namespaces.remove、entries.add、entries.remove — 因此 profile 可以调整基础列表而不是整体替换。
• ${name} 引用从合并后的 vars: 区段插值。profile 的 vars 中不允许引用 OS 环境变量；请在基础配置中使用 ${env:NAME}，在文件加载时解析。

wippy run、test 和 pack 接受 --profile；run list、install、update、lint 和 registry 同样接受它用于工作区 profile（连同 --set）。应用可以在包内附带 profile — 参见发布 Profile。

Logger

控制 zap logger 编码器。CLI 参数（-v、-c、-s）会覆盖级别/输出；唯一由 yaml 驱动的选项是编码。

logger:
  encoding: json

日志管理器

控制运行时日志路由。控制台输出通过 CLI 参数（-v、-c、-s）配置。

logmanager:
  propagate_downstream: true
  stream_to_events: false

参见：Logger 模块

性能分析器

Go pprof HTTP 服务器，用于 CPU/内存分析。通过 -p 参数或配置启用。

profiler:
  enabled: true
  address: "localhost:6060"

访问地址：http://localhost:6060/debug/pprof/

安全

全局安全行为。单独的策略定义为 security.policy 入口。

security:
  strict_mode: false

参见：安全系统、Security 模块

注册表

入口存储和版本历史。注册表保存所有配置入口。

registry:
  history_type: sqlite
  history_path: /var/lib/wippy/registry.db

registry:
  history_type: postgres
  history_dsn: ${env:WIPPY_REGISTRY_HISTORY_DSN}
  history_schema: wippy_registry

参见：注册表概念、Registry 模块

制品

已物化的构建期制品的输出根目录。

artifact:
  materialization_root: build/wippy

参见：构建期制品

工作区

本地模块替换，以 org/module 为键。取值为目录；相对路径相对于第一个 --config 文件所在目录解析，而 null 会禁用从更早的配置层或配置档继承来的替换。

workspace:
  replacements:
    acme/http: ../local-http
    acme/sql: null

替换项从不写入 wippy.lock。参见使用替换进行本地开发。

中继

跨节点的进程间消息路由。

relay:
  node_name: worker-1

参见：进程模型

监督器

服务生命周期管理。控制监督器用于派发生命周期事件的内部控制邮箱。

supervisor:
  host:
    buffer_size: 2048
    worker_count: 32

参见：监督指南

Lua 运行时

Lua 虚拟机缓存和表达式求值。

lua:
  cache:
    enabled: true
    dir: .cache/lua
  type_system:
    enabled: true

参见：Lua 概览

调度器

WASM 运行时的核心分区。启用后，会为 WASM 执行预留 reserved_cores 个 CPU，其余的服务于 actor 调度器；无效的划分（例如预留核心数超过可用核心数）会被记录日志并忽略。

scheduler:
  wasm_isolation:
    enabled: true
    reserved_cores: 2

查找器

注册表搜索缓存。内部用于入口查找。

finder:
  query_cache_size: 2000

OpenTelemetry

通过 OTLP 导出分布式追踪和指标。

otel:
  enabled: true
  endpoint: "http://jaeger:4318"
  traces_enabled: true
  process:
    trace_lifecycle: true

标准 OTEL 环境变量（OTEL_SDK_DISABLED、OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_PROTOCOL、OTEL_EXPORTER_OTLP_INSECURE、OTEL_SERVICE_NAME、OTEL_SERVICE_VERSION、OTEL_TRACES_SAMPLER、OTEL_TRACES_SAMPLER_ARG、OTEL_PROPAGATORS）会覆盖对应字段。

参见：可观测性指南

关闭

优雅关闭行为。

shutdown:
  timeout: 60s

指标

内部指标收集缓冲区。

metrics:
  buffer:
    size: 20000
  interceptor:
    enabled: true

参见：Metrics 模块、可观测性指南

Prometheus

Prometheus 指标端点。

prometheus:
  enabled: true
  address: "0.0.0.0:9090"

暴露 /metrics 端点供 Prometheus 抓取，同时还有 /livez。

参见：可观测性指南

集群

多节点集群：gossip 成员发现加上有界 Raft 共识核心。架构和运维模型参见集群指南；本节为配置键参考。

顶层配置

成员（gossip）

通过 memberlist 实现 SWIM gossip。用于节点发现、故障检测和元数据传播。

必须提供 gossip 密钥。设置 membership.secret_key 或 membership.secret_file（两者都给出时以文件为准）；两者都未设置时，集群组件无法启动。该值经 base64 编码。

四个探测键未设置时继承 memberlist 面向局域网的默认值；高延迟链路应调高它们（例如 probe_interval: 2s、probe_timeout: 500ms、suspicion_mult: 5）。

节点间（传输）

承载节点间中继和 Raft 流量的 TCP 网格。Raft 通过节点间的 request/reply 在此网格上传输；没有独立的 Raft 端口。

advertise_addr/advertise_port 在节点元数据中发布一个附加端点，同时绑定端点保持原样继续广播，因此混合版本集群在滚动升级期间仍能保持连接。

只要启用了集群，节点间身份就是必需的。identity_key 和 identity_key_file 互斥且必须提供其中之一；该值（标准或原始 base64）解码后为 32 字节的 ed25519 种子或 64 字节的 ed25519 私钥。trusted_peer_keys 把每个节点名映射到该节点的 32 字节 ed25519 公钥，并且必须包含与本地 cluster.name 对应的条目，其值与本地身份匹配——否则启动失败。参见集群指南。

Raft（共识）

有界的 Raft。Raft 状态默认在文件系统持久化，存储于 raft.data_dir（默认 ~/.wippy/store）下；重启后的节点仍会从对等节点重新加入 quorum。store.kv.raft entry 通过它进行复制。引导通过 gossip 驱动（Consul/Nomad bootstrap_expect 风格）。

单节点（开发环境）——集群开启，立即自举：

cluster:
  enabled: true
  name: dev
  membership:
    secret_key: "d2lwcHktZG9jcy1nb3NzaXAtc2VjcmV0LTMyYnl0ZXM="
  internode:
    identity_key: "d2lwcHktZG9jcy1kZXYtbm9kZS1leGFtcGxlc2VlZCE="
    trusted_peer_keys:
      dev: "rNqImcjOzef28dzvma80mSrCW1px5LBAc5TbaYqAgm0="
  raft:
    bootstrap_expect: 1

三节点投票集群——每个节点列出其他节点作为种子，等待三个节点全部就绪后组成 quorum。每个节点都携带相同的 trusted_peer_keys 映射和各自的私钥：

cluster:
  enabled: true
  name: node-1
  failure_domain: us-east-1a
  membership:
    bind_port: 7946
    join_addrs: "node-2:7946,node-3:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/node-1.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
  raft:
    bootstrap_expect: 3
    max_voters: 5

仅 gossip 客户端——加入集群用于命名/消息传递，但从不运行 Raft。它同样需要自己的身份，并且必须出现在每个节点的信任映射中：

cluster:
  enabled: true
  name: edge-7
  membership:
    join_addrs: "node-1:7946,node-2:7946"
    secret_file: /etc/wippy/cluster.key
  internode:
    identity_key_file: /etc/wippy/edge-7.key
    trusted_peer_keys:
      node-1: "okmamN3PKkMpPwPBurknHy2Wi3dwp/rz+uTM2fF9aD0="
      node-2: "PWX+oOYrFdtjUxbgmTkXCFI0KEvG++ZM52HOWfDkqP8="
      node-3: "QfP0fgllbj4s95VAztTORhy3bv9mst1l0lwuUNvO/hE="
      edge-7: "7lzP4jBAkC3P+0jq4vtMsC45571BlVXk3mSlOD/Z0SA="
  raft:
    role: client

LSP

用于编辑器集成的语言服务器协议（Language Server Protocol）服务器。

lsp:
  enabled: true
  address: ":7777"
  http_enabled: true

参见：LSP 指南

网络服务

覆盖网络管理器（SOCKS5、I2P、Tailscale 驱动）。

network_service:
  state_dir: /var/lib/wippy/net
  default_network: app:tailscale

参见：网络覆盖

HTTP 调度器

HTTP 调度函数和出站请求所用的共享 HTTP 客户端池的调优参数。

dispatcher:
  http:
    timeout: 30s
    max_idle_per_host: 32

模块

wippy install/update 使用的模块注册表客户端。

modules:
  registry_url: https://internal-registry.example.com

扩展

启动时加载的原生 Go 插件扩展（仅 Unix）。

extensions:
  enabled: true
  paths:
    - ./extensions/myplugin.so

环境变量

节点间 TLS

在 cluster.internode.tls 下启用节点间 TCP mesh 的双向 TLS。它也保护通过该 mesh 传输的 relay 和 Raft 流量。将以下设置添加到现有集群配置中：

cluster:
  internode:
    tls:
      enabled: true
      cert_file: /etc/wippy/node.crt
      key_file: /etc/wippy/node.key
      ca_file: /etc/wippy/cluster-ca.pem

TLS 默认禁用。设置 enabled: true 时，必须提供三个非空文件路径：PEM 证书、匹配的私钥，以及用于验证服务器和客户端证书的 PEM CA bundle。最低协议版本为 TLS 1.2。所有连接的 peer 都应配置兼容的证书和信任根。ed25519 身份和受信任 peer 公钥映射仍然是必需的。

未知的 TLS 设置、无效类型、缺失或无效的凭据、格式错误的 CA bundle，以及未设置 enabled: true 却提供的凭据路径，都会导致启动失败。无效的显式配置绝不会静默回退到明文通信。

另请参阅

• CLI 参考 - 命令行选项
• 集群指南 - 集群架构与运维
• 入口类型 - 所有入口类型
• 可观测性指南 - 日志、指标、追踪