198 lines
3.2 KiB
Markdown
198 lines
3.2 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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 和代码维护两套不同的字段定义
|