缓存与 Redis

热路径（Resolve / LoadCatalog）缓存。目录快照含签名材料，生产 Redis 必须设密码，禁止与不可信租户共享。

参数	类型	默认	说明	何时改
cache.driver	memory | redis	memory	进程内或 Redis	多进程或要求跨进程缓存时改 redis
cache.redis.addr	string	127.0.0.1:6379	Redis 地址	driver=redis 时必填；连 Docker / 远程实例时改
cache.redis.password	string	""	生产必填；KIRIVERS_CACHE_REDIS_PASSWORD	生产必须设；目录快照含签名材料
cache.redis.db	int	0	Redis 逻辑库	与其它应用共用实例时隔离库号
cache.redis.reconnect_interval_minutes	int	10	运行中回退后的重连间隔；<1 按 1 分钟	缩短以更快切回 Redis；拉长以减少抖动

启动 vs 运行时

阶段	memory	redis
启动	不连 Redis	必须 Ping 成功，否则非 0 退出、不监听（与 Postgres 宕机仍可能监听不同：Postgres 连不上是 fatal；Redis 仅在 driver=redis 时 fail-closed）
运行中断开	不适用	回退进程内内存，按间隔重连；成功后清空 kirivers: 前缀再切回

GET /api/v1/health 的 ready 不含 Redis。Redis 运行时回退不会把 health 打成未就绪。

单机安装可跳过 Redis。多 KiriVers 进程必须 Redis，且 cluster.download 仅在 storage.driver=s3 且 cache.driver=redis 时生效。

# 进程级系统配置。监听地址与 TLS 在 admin.yaml / client.yaml，本文件不含 addr。
# -config 可指向本文件或其所在目录；同目录还需 admin.yaml 与 client.yaml。
# 环境变量前缀 KIRIVERS_（例：postgres.dsn → KIRIVERS_POSTGRES_DSN）。
# 控制台为 Zerolog ConsoleWriter（stderr，默认着色）；文件为 JSON + 按大小滚动。

log:
  # 非法级别回退 info。示例用 debug 便于本机；Viper 默认 info。
  level: debug
  console:
    enabled: true
    no_color: false
  file:
    enabled: true
    dir: ./logs
    filename: kirivers.log
    max_size_mb: 100
    max_backups: 10
    max_age_days: 28
    compress: true
    local_time: true

# 与 dev/docker/compose.yml 中 PostgreSQL 服务一致，供本机开发。
# 生产环境请用环境变量 KIRIVERS_POSTGRES_DSN 覆盖，勿提交真实密钥到 config.yaml。
postgres:
  dsn: "host=127.0.0.1 user=kirivers password=8WdeOilkFYo6OcBE3bdmg2 dbname=kirivers port=5432 sslmode=disable TimeZone=Asia/Shanghai"

storage:
  driver: local
  local:
    root: ./data/storage
  s3:
    endpoint: ""
    region: auto
    bucket: ""
    access_key: ""
    secret_key: ""
    use_path_style: true
    # 公共产物 CDN 前缀；空则按 endpoint+bucket 拼匿名 GET URL。环境变量 KIRIVERS_STORAGE_S3_PUBLIC_BASE_URL。
    public_base_url: ""
  # 私有后端桶（GeoIP MMDB）。driver=s3 且未配 bucket 时 GeoIP 上传失败，不得写入公共桶。
  # 环境变量 KIRIVERS_STORAGE_PRIVATE_*。
  # private:
  #   endpoint: ""
  #   region: auto
  #   bucket: kirivers-private
  #   access_key: ""
  #   secret_key: ""
  #   use_path_style: true

# 本节点可选显示名（仅管理台节点列表；空则显示 UUID）。环境变量 KIRIVERS_NODE_DISPLAY_NAME。
node:
  display_name: ""

# 多节点下载方式，仅 storage.driver=s3 且 cache.driver=redis 时生效。s3=公共直链，local=本机代拉。
# 环境变量 KIRIVERS_CLUSTER_DOWNLOAD。
cluster:
  download: s3

security:
  # 完整管理会话空闲滑动 TTL；每次命中按当前时刻续期。管理员鉴权查缓存中的会话 Token（不透明随机串）。
  session_idle_hours: 72
  # 密码成功后的受限 token（强制绑定 / 第二因素），到期须重新密码登录。
  login_pending_ttl_seconds: 600
  # 同一 TOTP 时间步（30s）内允许的校验次数；超限返回 TOTP_RATE_LIMITED。
  totp_max_attempts_per_period: 10
  # WebAuthn 依赖方。rp_id 为空时 Passkey 接口返回 NOT_READY，TOTP 登录仍可用。
  webauthn_rp_id: ""
  webauthn_origins: []

# 私有存储短时签名 URL 的实例级 HMAC 密钥（docs/app-init.md 13.7 / C15-1）。
# 未配置时进程启动生成临时随机值并告警——重启即全部已签发 URL 失效；
# 生产环境必须显式配置（或使用环境变量 KIRIVERS_URL_SIGNING_SECRET）。
url_signing_secret: ""

jobs:
  workers: 2

# 多文件客户端 fileset 动态打包未压缩硬顶（D6）。差异路径 Manifest size 去重合计
# ≥ 该值则不入队、立即 full_package。环境变量 KIRIVERS_DYNAMIC_PACK_MAX_BYTES。
dynamic_pack:
  max_bytes: 536870912

# 原生 file_list 待下载条数平台天花板。项目可下调（0=继承），不得超出。
# 环境变量 KIRIVERS_FILE_LIST_MAX_FILES。加载后 <1 回退 16。
file_list:
  max_files: 16

# 原生 changelog 条数窗口。无 from_version 用 default_entries；有 from_version 用 max_entries 截断。
# 加载后 <1 回退 5 / 50。若 default_entries > max_entries，config.Load 失败，进程不监听。
# 环境变量 KIRIVERS_CHANGELOG_DEFAULT_ENTRIES / KIRIVERS_CHANGELOG_MAX_ENTRIES。
changelog:
  default_entries: 5
  max_entries: 50

# 热路径（Resolve / LoadCatalog）缓存。默认 memory，不连接 Redis，便于无 Redis 本机启动。
# driver=redis 时启动必须 Ping 成功，否则进程以非 0 退出且不监听（与 Postgres 宕机仍监听不同）。
# 运行中 Redis 失败会回退到进程内内存，并按 reconnect_interval_minutes 重连；成功后清空 kirivers: 前缀再切回。
# 目录快照含签名私钥，生产 Redis 必须设密码，禁止对不可信租户共享。
# 本地 docker Redis：docker compose -f dev/docker/compose.yml up -d
# 密码用环境变量覆盖，勿把 dev/docker/redis.conf 的 requirepass 当作生产密钥写进本文件：
#   KIRIVERS_CACHE_REDIS_PASSWORD
cache:
  driver: memory  # memory | redis
  redis:
    addr: "127.0.0.1:6379"
    password: ""
    db: 0
    reconnect_interval_minutes: 10