config.yaml

File: config.yaml. Prefix KIRIVERS_. Listen addresses are not in this file.

PostgreSQL

Key	Type	Meaning	When to change
postgres.dsn	string	libpq DSN	Always change the password in production; KIRIVERS_POSTGRES_DSN is valid

Startup fatals if the database cannot be opened. A runtime database outage makes business /api return 404 while GET /api/v1/health stays 200 with ready=false.

Process log log

Key	Type	Typical default	Meaning	When to change
log.level	string	example debug, Viper default info	Invalid levels fall back to info	Production info/warn; debug while diagnosing
log.console.enabled	bool	true	stderr ConsoleWriter	Off when there is no TTY or you only keep journald
log.file.enabled	bool	true	JSON rolling file	Off if you only want stderr
log.file.dir	string	./logs	Relative to process CWD	Absolute path in production; include in backups

The four plane log streams live in the plane YAML files. See Configuration.

Jobs and ceilings

Key	Type	Default	Meaning	When to change
jobs.workers	int	2	Job workers	Delta / pack / cleanup concurrency
dynamic_pack.max_bytes	int	536870912	Uncompressed hard cap for dynamic multi-file packs	Oversize → HTTP 200 full_package
file_list.max_files	int	16	Instance ceiling; values <1 become 16	Projects may lower, never exceed
changelog.default_entries	int	5	Count without from_version; <1 → 5	Shorten the default window; must be ≤ max_entries
changelog.max_entries	int	50	Truncation with from_version; <1 → 50	default_entries > max_entries refuses to listen

# 进程级系统配置。监听地址与 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

Other keys

• Cache: Cache and Redis
• Storage: S3 and local disk
• cluster.download / node.display_name: cluster
• security.* / url_signing_secret: security