theshy/biliup-next
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
862db502b08418ebbcf3234d5393393a54750c0c
biliup-next/docs/config-system.md
theshy d0cf1fd0df init biliup-next
2026-04-01 00:44:58 +08:00

3.1 KiB
Raw Blame History

Config System

Design Goal

配置系统不是辅助功能，而是新系统的控制面基础设施。

目标：

  • 所有运行参数有统一来源
  • 配置可被严格校验
  • 配置可被 UI、CLI、文件三种方式修改
  • 配置变更可审计
  • 无效配置不得直接污染运行态

Design Principles

借鉴 OpenClaw 的做法，配置系统采用 schema-first 设计。

核心原则：

  • 所有配置项必须先声明在 schema 中
  • 所有模块只能通过配置服务读取配置
  • UI 表单由 schema 驱动渲染
  • 保存前必须校验
  • 校验失败不允许生效
  • 配置有版本和变更记录

Config Sources

1. Default Config

系统默认值，由代码内置或默认配置文件提供。

2. Active Config

当前生效的正式配置。

建议位置：

  • biliup-next/config/settings.json

3. Staged Config

用户在 UI 或 CLI 中提交、但尚未生效的待校验配置。

建议位置：

  • biliup-next/config/settings.staged.json

4. Schema

定义配置结构、类型、默认值、枚举范围、校验规则和 UI 元信息。

建议位置：

  • biliup-next/config/settings.schema.json

Config Flow

User edits config
  -> Write staged config
  -> Validate against schema
  -> Run dependency checks
  -> If valid: promote to active
  -> If invalid: keep current active config

Validation Layers

1. Schema Validation

检查：

  • 类型
  • 必填字段
  • 枚举值
  • 数值范围
  • 字段格式

2. Semantic Validation

检查：

  • 路径是否存在
  • 可执行文件是否可用
  • season id 是否合法
  • 依赖组合是否冲突

3. Runtime Validation

检查：

  • provider 是否可初始化
  • 凭证是否存在
  • 外部连接是否可用

Suggested Config Groups

runtime

  • workspace_dir
  • database_path
  • log_level
  • scan_interval_seconds

paths

  • stage_dir
  • backup_dir
  • session_dir
  • cookies_file
  • upload_config_file

ingest

  • min_duration_seconds
  • allowed_extensions

transcribe

  • provider
  • groq_api_key
  • max_file_size_mb
  • ffmpeg_bin

song_detect

  • provider
  • codex_cmd
  • poll_interval_seconds

split

  • ffmpeg_bin
  • poll_interval_seconds

publish

  • provider
  • biliup_path
  • cookie_file
  • retry_count
  • retry_schedule_minutes
  • retry_backoff_seconds

comment

  • enabled
  • max_retries
  • base_delay_seconds
  • poll_interval_seconds

collection

  • enabled
  • season_id_a
  • season_id_b
  • allow_fuzzy_full_video_match
  • append_collection_a_new_to_end
  • append_collection_b_new_to_end

UI Strategy

管理台不手写业务表单，而是由 schema 驱动生成配置界面。

每个配置项除了类型信息，还应有：

  • title
  • description
  • group
  • ui:widget
  • ui:secret
  • ui:order

这样可以让配置页面和底层配置保持同源。

Audit Trail

每次配置变更都应记录：

  • 修改人
  • 修改时间
  • 修改前值
  • 修改后值
  • 校验结果
  • 是否已生效

Non-Goals

  • 不追求兼容任意格式的配置文件
  • 不允许模块私自定义一份独立配置入口
  • 不允许 UI 和代码维护两套不同的字段定义