biliup-next/docs/config-system.md

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

• provider
• min_duration_seconds
• ffprobe_bin
• yt_dlp_cmd
• allowed_extensions

transcribe

• provider
• groq_api_key
• max_file_size_mb
• ffmpeg_bin

song_detect

• provider
• codex_cmd
• qwen_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 和代码维护两套不同的字段定义