登录与两步验证

登录页标题 登录 KiriVers。流程：密码 → 待绑定或第二因素（pending TTL：security.login_pending_ttl_seconds）→ 完整会话。空闲滑动 TTL：security.session_idle_hours。管理员鉴权使用缓存会话 Token（服务端 Authorization: Bearer 携带的不透明随机串）。

谁能打开：任何能访问管理平面（默认 http://127.0.0.1:8081）的浏览器。首次账号须先用管理员初始化创建。

首次登录

输入 用户名、密码，点登录。
首次须 绑定身份验证器：扫码或手动输入密钥，填写 6 位验证码，点 确认绑定。
保存恢复码（只显示一次）。勾选 我已安全保存这些恢复码，再点继续。
出现 添加 Passkey（可选）。可点 注册 Passkey，或点跳过。之后在右上角 账号安全 添加。

同一 30s 周期验证码次数用尽：TOTP_RATE_LIMITED。

配置 Passkey（WebAuthn）

Passkey 依赖系统 YAML 里两个键。security.webauthn_rp_id 或 security.webauthn_origins 任一为空，Passkey 接口返回 NOT_READY（HTTP 503）。TOTP 与恢复码仍可用。

界面此时显示：「服务器未配置 WebAuthn，暂时无法添加 Passkey。仍可用 TOTP 或恢复码登录。」

参数	类型	默认	含义	何时改	失败
`security.webauthn_rp_id`	string	`""`	依赖方 ID：主机名，不含 scheme 与端口	启用 Passkey	空 → `NOT_READY`
`security.webauthn_origins`	string[]	`[]`	完整 Origin 列表（含 scheme 与端口）	必须与浏览器地址栏 Origin 一致	空或与浏览器不一致 → 浏览器拒绝或 `NOT_READY`

示例（本机管理平面 http://localhost:8081）：

yaml

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

改完后把 webauthn_rp_id 设为 localhost（或公网主机名 updates.example.com），把 webauthn_origins 设为完整 Origin，例如 http://localhost:8081。改 YAML 后必须重启进程。

HTTPS

非 localhost 需要 HTTPS 安全上下文，否则浏览器不允许 WebAuthn。localhost 可用 http://localhost:8081。

localhost公网

yaml

security:
  webauthn_rp_id: localhost
  webauthn_origins:
    - http://localhost:8081

yaml

security:
  webauthn_rp_id: updates.example.com
  webauthn_origins:
    - https://updates.example.com

YAML 细节：安全相关配置。

账号安全（后续添加 / 删除 Passkey）

右上角用户菜单 账号安全（/security），不是抽屉项。页内说明：不会踢掉其他已登录会话。

打开 账号安全。
在 Passkey 区域点 添加 Passkey，填写 Passkey 名称，完成浏览器提示。
删除：点 删除 Passkey，确认。不会退出已登录会话，也不会移除 TOTP。
轮换 TOTP / 重新生成 恢复码同样不踢会话。

若服务器未配置 WebAuthn，添加 Passkey 不可用，并显示上面那句界面提示。仍可用 TOTP 或恢复码登录。

`clear-2fa`

本机 CLI：

bash

kirivers admin clear-2fa alice

清除该账号的 TOTP、Passkey 与恢复码。不吊销已有会话。对方下次登录会重新绑定身份验证器。见管理员初始化。

登录与两步验证 ​

首次登录 ​

配置 Passkey（WebAuthn） ​

账号安全（后续添加 / 删除 Passkey） ​

clear-2fa ​

登录与两步验证

首次登录

配置 Passkey（WebAuthn）

账号安全（后续添加 / 删除 Passkey）

`clear-2fa`