2026-07-05 09:11:05 +08:00
""" Settings schema and current configuration service. """
from __future__ import annotations
import json
from pathlib import Path
from typing import Any , Mapping
2026-07-05 14:56:48 +08:00
from uuid import uuid4
2026-07-05 09:11:05 +08:00
from backend . dto . common import ApiError , ErrorCode
from core . config_service import ConfigService
2026-07-11 21:50:34 +08:00
from core . config_writer import config_file_lock , dump_yaml , write_text_atomic
2026-07-05 10:49:14 +08:00
from core . audit_service import AuditService
from core . identity import RequestContext
2026-07-11 21:50:34 +08:00
from core . runtime_paths import is_default_config_path , resolve_plugin_path
from database . db_helper import (
Database ,
DatabaseSettings ,
get_runtime_config_overrides ,
load_config_file_payload ,
load_config_payload ,
2026-07-15 23:01:07 +08:00
persist_runtime_config_values ,
2026-07-11 21:50:34 +08:00
)
2026-07-05 09:11:05 +08:00
SENSITIVE_KEY_PARTS = ( " password " , " token " , " secret " , " api_key " , " apikey " , " key " , " dsn " )
DATABASE_BACKENDS = { " auto " , " sqlite " , " postgresql " , " postgres " , " pg " }
class SettingsService :
def __init__ (
self ,
config_service : ConfigService | None = None ,
schema_path : str | Path = " _conf_schema.json " ,
2026-07-05 10:49:14 +08:00
audit_service : AuditService | None = None ,
2026-07-05 09:11:05 +08:00
) :
self . config_service = config_service or ConfigService ( )
self . schema_path = _resolve_path ( schema_path )
2026-07-05 10:49:14 +08:00
self . audit_service = audit_service
2026-07-05 09:11:05 +08:00
def get_schema ( self ) - > dict [ str , Any ] :
return {
" schema_version " : " 3.0 " ,
" raw_schema " : self . _load_raw_schema ( ) ,
" sections " : [
{
" key " : " plugin " ,
2026-07-06 10:59:28 +08:00
" title " : " 插件 " ,
2026-07-05 09:11:05 +08:00
" fields " : [
2026-07-06 10:59:28 +08:00
_field ( " name " , " string " , label = " 插件名 " , readonly = True ) ,
_field ( " display_name " , " string " , label = " 显示名称 " ) ,
_field ( " version " , " string " , label = " 版本 " , readonly = True ) ,
2026-07-05 09:11:05 +08:00
] ,
} ,
{
" key " : " features " ,
2026-07-06 10:59:28 +08:00
" title " : " 功能 " ,
2026-07-05 09:11:05 +08:00
" fields " : [
2026-07-06 10:59:28 +08:00
_field ( " quick_profile " , " bool " , label = " 快速建档 " ) ,
_field ( " workspace " , " bool " , label = " 工作台 " ) ,
_field ( " material_library " , " bool " , label = " 素材库 " ) ,
_field ( " wardrobe " , " bool " , label = " 衣橱 " ) ,
_field ( " api_discovery " , " bool " , label = " 能力探测 " ) ,
_field ( " private_companion_integration " , " bool " , label = " 私伴插件集成 " ) ,
2026-07-05 09:11:05 +08:00
] ,
} ,
2026-07-11 21:50:34 +08:00
{
" key " : " generation " ,
" title " : " 生图提供方 " ,
" fields " : [
_field ( " default_model " , " string " , label = " 默认路由名 " ) ,
_field ( " provider.provider_id " , " string " , label = " 提供方 ID " ) ,
_field ( " provider.base_url " , " string " , label = " API 根地址 " ) ,
_field ( " provider.image_endpoint " , " string " , label = " 生图 endpoint " ) ,
_field ( " provider.model_id " , " string " , label = " 模型 ID " ) ,
_field ( " provider.route_name " , " string " , label = " 路由名 " ) ,
_field ( " provider.api_key_env_var " , " string " , label = " API Key 环境变量 " ) ,
_field ( " provider.timeout_seconds " , " number " , label = " 超时秒数 " ) ,
] ,
} ,
{
" key " : " vision " ,
" title " : " 素材视觉识别 " ,
" fields " : [
_field ( " default_route " , " string " , label = " 默认 Vision 路由名 " ) ,
_field ( " provider.provider_id " , " string " , label = " Vision 提供方 ID( 留空复用生图) " ) ,
_field ( " provider.base_url " , " string " , label = " Vision API 根地址(留空复用生图) " ) ,
_field ( " provider.vision_endpoint " , " string " , label = " Vision endpoint " ) ,
_field ( " provider.model_id " , " string " , label = " Vision 模型 ID " ) ,
_field ( " provider.route_name " , " string " , label = " Vision 路由名 " ) ,
_field (
" provider.api_key_env_var " ,
" string " ,
label = " Vision API Key 环境变量(留空复用生图) " ,
) ,
_field ( " provider.timeout_seconds " , " number " , label = " Vision 超时秒数 " ) ,
_field ( " provider.enabled " , " bool " , label = " 启用 Vision 路由 " ) ,
] ,
} ,
2026-07-11 23:48:36 +08:00
{
" key " : " model_assignments " ,
" title " : " 模型分工 " ,
" fields " : [
_field ( " material_recognition " , " string " , label = " 素材解析路由 " ) ,
2026-07-18 23:20:06 +08:00
_field ( " advanced_material_recognition " , " string " , label = " 进阶素材识别路由 " ) ,
2026-07-20 18:22:56 +08:00
_field ( " advanced_style_consensus " , " string " , label = " 进阶画风交叉归纳路由 " ) ,
2026-07-18 23:20:06 +08:00
_field ( " advanced_material_validation_generation " , " string " , label = " 进阶素材验证生图路由 " ) ,
2026-07-11 23:48:36 +08:00
_field ( " profile_parse " , " string " , label = " 角色导入解析路由 " ) ,
_field ( " persona_split " , " string " , label = " 人设拆解路由 " ) ,
_field ( " prompt_planning " , " string " , label = " 提示词规划路由 " ) ,
2026-07-15 23:01:07 +08:00
_field ( " visual_review_routes " , " list " , label = " 视觉质量审核路由列表 " ) ,
_field ( " cross_review_primary " , " string " , label = " 兼容视觉主审核路由 " ) ,
_field ( " cross_review_secondary " , " string " , label = " 兼容视觉复核路由 " ) ,
_field ( " cross_review_routes " , " list " , label = " 兼容视觉审核路由列表 " ) ,
_field ( " generation_cross_review_primary " , " string " , label = " 生成式交叉审查主生图路由 " ) ,
_field ( " generation_cross_review_secondary " , " string " , label = " 生成式交叉审查复核生图路由 " ) ,
_field ( " generation_cross_review_routes " , " list " , label = " 生成式交叉审查生图路由列表 " ) ,
2026-07-11 23:48:36 +08:00
_field ( " quick_generation " , " string " , label = " 快速生图路由 " ) ,
_field ( " portrait_generation " , " string " , label = " 头像生成路由 " ) ,
_field ( " halfbody_generation " , " string " , label = " 半身生成路由 " ) ,
_field ( " fullbody_generation " , " string " , label = " 全身生成路由 " ) ,
_field ( " sheet_generation " , " string " , label = " 设定图生成路由 " ) ,
_field ( " hires_fix " , " string " , label = " 高清修复路由 " ) ,
] ,
} ,
{
" key " : " recognition_prompts " ,
" title " : " 识别提示词 " ,
" fields " : [
_field ( " default_instruction " , " text " , label = " 默认素材识别指令 " ) ,
_field ( " category_requirements " , " list " , label = " 分类附加要求 " ) ,
] ,
} ,
2026-07-18 23:20:06 +08:00
{
" key " : " advanced_materials " ,
" title " : " 进阶素材 " ,
" fields " : [
_field ( " cost_budget.enabled " , " bool " , label = " 启用验证预算守卫 " ) ,
_field ( " cost_budget.days " , " number " , label = " 用量统计窗口(天) " ) ,
_field ( " cost_budget.max_task_count " , " number " , label = " 窗口内最大验证任务数 " ) ,
_field ( " cost_budget.max_image_count " , " number " , label = " 窗口内最大验证图片数 " ) ,
_field ( " cost_budget.max_estimated_cost " , " number " , label = " 窗口内最大估算费用 " ) ,
_field ( " cost_budget.price_key " , " string " , label = " 计价键( Provider 或模型 ID) " ) ,
_field ( " cost_budget.per_request " , " number " , label = " 每次请求单价 " ) ,
_field ( " cost_budget.per_image " , " number " , label = " 每张图片单价 " ) ,
_field ( " cost_budget.per_1k_tokens " , " number " , label = " 每千 Token 单价 " ) ,
] ,
} ,
2026-07-12 02:54:45 +08:00
{
" key " : " prompt_governance " ,
" title " : " 提示词与内容分流 " ,
" fields " : [
_field ( " translation.enabled " , " bool " , label = " 启用 LLM 提示词转译 " ) ,
_field ( " translation.model_route " , " string " , label = " 提示词转译模型路由 " ) ,
_field ( " translation.template_version " , " string " , label = " 转译模板版本 " ) ,
_field ( " translation.entrypoints.web " , " bool " , label = " Web 允许转译 " ) ,
_field ( " translation.entrypoints.qq " , " bool " , label = " QQ 允许转译 " ) ,
_field ( " translation.entrypoints.telegram " , " bool " , label = " Telegram 允许转译 " ) ,
_field ( " translation.entrypoints.discord " , " bool " , label = " Discord 允许转译 " ) ,
_field ( " moderation.llm_review_enabled " , " bool " , label = " 启用 LLM 内容复核 " ) ,
_field ( " moderation.model_route " , " string " , label = " 内容审核模型路由 " ) ,
_field ( " moderation.failure_policy " , " select " , label = " 审核失败策略 " , options = [ " fail_closed " , " confirm " ] ) ,
_field ( " routing.safe_route " , " string " , label = " 普通生图路由 " ) ,
_field ( " routing.nsfw_route " , " string " , label = " NSFW 生图路由 " ) ,
_field ( " routing.adult_auto_route_enabled " , " bool " , label = " 允许成人内容自动分流 " ) ,
_field ( " routing.entrypoints.web " , " bool " , label = " Web 允许成人路由 " ) ,
_field ( " routing.entrypoints.qq " , " bool " , label = " QQ 允许成人路由 " ) ,
_field ( " routing.entrypoints.telegram " , " bool " , label = " Telegram 允许成人路由 " ) ,
_field ( " routing.entrypoints.discord " , " bool " , label = " Discord 允许成人路由 " ) ,
_field ( " image_moderation.enabled " , " bool " , label = " 启用生成后图片审核 " ) ,
_field ( " image_moderation.model_route " , " string " , label = " 图片审核模型路由 " ) ,
_field ( " retention.raw_prompt_days " , " number " , label = " 原始提示词保留天数 " ) ,
_field ( " retention.translated_prompt_days " , " number " , label = " 转译提示词保留天数 " ) ,
_field ( " retention.moderation_record_days " , " number " , label = " 审核记录保留天数 " ) ,
_field ( " retention.redact_sensitive_logs " , " bool " , label = " 日志默认脱敏 " ) ,
] ,
} ,
2026-07-12 00:59:06 +08:00
{
" key " : " chat_access " ,
" title " : " 聊天权限 " ,
" fields " : [
_field ( " group_allowlist " , " list " , label = " 群聊白名单 " ) ,
_field ( " user_allowlist " , " list " , label = " 用户白名单 " ) ,
2026-07-12 02:54:45 +08:00
_field ( " adult_group_allowlist " , " list " , label = " 成人内容群聊白名单 " ) ,
_field ( " adult_user_allowlist " , " list " , label = " 成人内容用户白名单 " ) ,
2026-07-12 00:59:06 +08:00
_field ( " user_concurrency_limit " , " number " , label = " 用户并发任务上限 " ) ,
_field ( " group_concurrency_limit " , " number " , label = " 群聊并发任务上限 " ) ,
_field ( " daily_user_generation_limit " , " number " , label = " 用户每日生成上限 " ) ,
_field ( " daily_group_generation_limit " , " number " , label = " 群聊每日生成上限 " ) ,
_field ( " allow_2k " , " bool " , label = " 允许聊天命令使用 2K " ) ,
_field ( " allow_4k " , " bool " , label = " 允许聊天命令使用 4K " ) ,
] ,
} ,
2026-07-05 09:11:05 +08:00
{
" key " : " storage " ,
2026-07-06 10:59:28 +08:00
" title " : " 存储 " ,
2026-07-05 09:11:05 +08:00
" fields " : [
2026-07-06 10:59:28 +08:00
_field ( " images_path " , " path " , label = " 图片目录 " ) ,
_field ( " thumbnails_path " , " path " , label = " 缩略图目录 " ) ,
_field ( " materials_path " , " path " , label = " 素材目录 " ) ,
2026-07-18 23:20:06 +08:00
_field ( " advanced_materials_path " , " path " , label = " 进阶素材独立目录 " ) ,
2026-07-06 10:59:28 +08:00
_field ( " styles_path " , " path " , label = " 风格目录 " ) ,
_field ( " archives_path " , " path " , label = " 归档目录 " ) ,
_field ( " temp_path " , " path " , label = " 临时目录 " ) ,
2026-07-05 09:11:05 +08:00
] ,
} ,
{
" key " : " database " ,
2026-07-06 10:59:28 +08:00
" title " : " 数据库 " ,
2026-07-05 09:11:05 +08:00
" fields " : [
2026-07-06 10:59:28 +08:00
_field ( " backend " , " select " , label = " 后端 " , options = [ " auto " , " sqlite " , " postgresql " ] ) ,
_field ( " sqlite.path " , " path " , label = " SQLite 路径 " ) ,
_field ( " postgresql.enabled " , " bool " , label = " 启用 PostgreSQL " ) ,
_field ( " postgresql.dsn " , " string " , label = " PG DSN " , sensitive = True ) ,
_field ( " postgresql.host " , " string " , label = " PG 主机 " ) ,
_field ( " postgresql.port " , " number " , label = " PG 端口 " ) ,
_field ( " postgresql.database " , " string " , label = " PG 数据库 " ) ,
_field ( " postgresql.user " , " string " , label = " PG 用户 " , sensitive = True ) ,
_field ( " postgresql.password " , " string " , label = " PG 密码 " , sensitive = True ) ,
2026-07-05 09:11:05 +08:00
] ,
} ,
{
" key " : " security " ,
2026-07-06 10:59:28 +08:00
" title " : " 安全 " ,
2026-07-05 09:11:05 +08:00
" fields " : [
2026-07-06 10:59:28 +08:00
_field ( " integration_token_set " , " bool " , label = " 集成令牌已设置 " , readonly = True ) ,
_field ( " allowed_integration_plugins " , " string_list " , label = " 允许集成的插件 " ) ,
2026-07-05 09:11:05 +08:00
] ,
} ,
] ,
}
def get_current ( self ) - > dict [ str , Any ] :
raw = self . _load_current_mapping ( )
return {
2026-07-05 13:13:00 +08:00
" config_path " : " ***PATH*** " ,
2026-07-05 09:11:05 +08:00
" config " : _mask_sensitive ( raw ) ,
}
def validate ( self , candidate : Mapping [ str , Any ] ) - > dict [ str , Any ] :
config = candidate . get ( " config " , candidate )
if not isinstance ( config , Mapping ) :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " config must be an object " , { " field " : " config " } )
errors : list [ dict [ str , Any ] ] = [ ]
warnings : list [ dict [ str , Any ] ] = [ ]
2026-07-11 21:50:34 +08:00
generation = config . get ( " generation " , { } )
generation_provider : Mapping [ str , Any ] = { }
if isinstance ( generation , Mapping ) :
provider = generation . get ( " provider " , { } )
provider = provider if isinstance ( provider , Mapping ) else { }
generation_provider = provider
2026-07-13 00:13:37 +08:00
adapters = generation . get ( " adapters " )
if isinstance ( adapters , list ) :
for index , adapter in enumerate ( adapters ) :
if not isinstance ( adapter , Mapping ) or adapter . get ( " enabled " ) is False :
continue
base_url = str ( adapter . get ( " base_url " ) or " " ) . strip ( )
if not base_url :
warnings . append (
{
" field " : f " generation.adapters. { index } .base_url " ,
" message " : " enabled adapter has no base URL and cannot be probed yet " ,
}
)
else :
route_name = str ( provider . get ( " route_name " ) or generation . get ( " default_model " ) or " " ) . strip ( )
model_id = str ( provider . get ( " model_id " ) or generation . get ( " default_model " ) or " " ) . strip ( )
base_url = str ( provider . get ( " base_url " ) or " " ) . strip ( )
if any ( ( route_name , model_id , base_url ) ) :
for field , value in (
( " generation.default_model " , route_name ) ,
( " generation.provider.model_id " , model_id ) ,
( " generation.provider.base_url " , base_url ) ,
) :
if not value :
errors . append ( { " field " : field , " message " : " configured generation provider field is required " } )
2026-07-11 21:50:34 +08:00
vision = config . get ( " vision " , { } )
if isinstance ( vision , Mapping ) :
provider = vision . get ( " provider " , { } )
provider = provider if isinstance ( provider , Mapping ) else { }
route_name = str ( provider . get ( " route_name " ) or vision . get ( " default_route " ) or " " ) . strip ( )
model_id = str ( provider . get ( " model_id " ) or " " ) . strip ( )
base_url = str ( provider . get ( " base_url " ) or generation_provider . get ( " base_url " ) or " " ) . strip ( )
explicitly_configured = any (
str ( provider . get ( key ) or " " ) . strip ( )
for key in (
" provider_id " ,
" base_url " ,
" model_id " ,
" api_key_env_var " ,
" api_key_secret_ref " ,
)
)
if explicitly_configured :
for field , value in (
( " vision.default_route " , route_name ) ,
( " vision.provider.model_id " , model_id ) ,
( " vision.provider.base_url " , base_url ) ,
) :
if not value :
errors . append ( { " field " : field , " message " : " configured vision provider field is required " } )
2026-07-05 09:11:05 +08:00
database = config . get ( " database " , { } )
if isinstance ( database , Mapping ) :
backend = str ( database . get ( " backend " , " auto " ) ) . lower ( )
if backend not in DATABASE_BACKENDS :
errors . append (
{
" field " : " database.backend " ,
" message " : " unsupported database backend " ,
" allowed " : sorted ( DATABASE_BACKENDS ) ,
}
)
postgresql = database . get ( " postgresql " , { } )
if backend in { " postgresql " , " postgres " , " pg " } and isinstance ( postgresql , Mapping ) :
if not postgresql . get ( " dsn " ) and not (
postgresql . get ( " host " ) and postgresql . get ( " database " ) and postgresql . get ( " user " )
) :
warnings . append (
{
" field " : " database.postgresql " ,
" message " : " postgresql backend is selected but connection fields are incomplete " ,
}
)
2026-07-12 02:54:45 +08:00
governance = config . get ( " prompt_governance " , { } )
if isinstance ( governance , Mapping ) :
routing = governance . get ( " routing " , { } )
if isinstance ( routing , Mapping ) :
safe_route = str ( routing . get ( " safe_route " ) or " " ) . strip ( )
nsfw_route = str ( routing . get ( " nsfw_route " ) or " " ) . strip ( )
if routing . get ( " adult_auto_route_enabled " ) and not nsfw_route :
errors . append ( { " field " : " prompt_governance.routing.nsfw_route " , " message " : " NSFW route is required when adult auto routing is enabled " } )
if safe_route and nsfw_route and safe_route == nsfw_route :
errors . append ( { " field " : " prompt_governance.routing " , " message " : " safe and NSFW routes must use different configured routes " } )
translation = governance . get ( " translation " , { } )
if isinstance ( translation , Mapping ) and translation . get ( " enabled " ) and not str ( translation . get ( " model_route " ) or " " ) . strip ( ) :
warnings . append ( { " field " : " prompt_governance.translation.model_route " , " message " : " translation is enabled without a dedicated model route; runtime will safely use the original prompt " } )
retention = governance . get ( " retention " , { } )
if isinstance ( retention , Mapping ) :
for key in ( " raw_prompt_days " , " translated_prompt_days " , " moderation_record_days " ) :
try :
days = int ( retention . get ( key , 0 ) )
except ( TypeError , ValueError ) :
days = - 1
if days < 0 :
errors . append ( { " field " : f " prompt_governance.retention. { key } " , " message " : " retention days must be zero or greater " } )
2026-07-18 23:20:06 +08:00
advanced_materials = config . get ( " advanced_materials " , { } )
if isinstance ( advanced_materials , Mapping ) :
budget = advanced_materials . get ( " cost_budget " , { } )
if isinstance ( budget , Mapping ) :
for key in ( " days " , " max_task_count " , " max_image_count " ) :
value = budget . get ( key )
if value in ( None , " " ) :
continue
try :
normalized = int ( value )
except ( TypeError , ValueError ) :
normalized = - 1
if normalized < 0 :
errors . append ( { " field " : f " advanced_materials.cost_budget. { key } " , " message " : " value must be zero or greater " } )
for key in ( " max_estimated_cost " , " per_request " , " per_image " , " per_1k_tokens " ) :
value = budget . get ( key )
if value in ( None , " " ) :
continue
try :
normalized_cost = float ( value )
except ( TypeError , ValueError ) :
normalized_cost = - 1
if normalized_cost < 0 :
errors . append ( { " field " : f " advanced_materials.cost_budget. { key } " , " message " : " value must be zero or greater " } )
2026-07-05 09:11:05 +08:00
return { " valid " : not errors , " errors " : errors , " warnings " : warnings }
def diff ( self , candidate : Mapping [ str , Any ] ) - > dict [ str , Any ] :
current = self . _load_current_mapping ( )
incoming = candidate . get ( " config " , candidate )
if not isinstance ( incoming , Mapping ) :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " config must be an object " , { " field " : " config " } )
before = _flatten ( current )
2026-07-11 21:50:34 +08:00
after = _flatten ( _merge_masked ( current , incoming ) )
2026-07-05 09:11:05 +08:00
keys = sorted ( set ( before ) | set ( after ) )
changes = [ ]
for key in keys :
before_value = before . get ( key )
after_value = after . get ( key )
if before_value == after_value :
continue
if _is_sensitive_key ( key ) :
changes . append (
{
" path " : key ,
" before_set " : bool ( before_value ) ,
" after_set " : bool ( after_value ) ,
" sensitive " : True ,
}
)
2026-07-05 13:13:00 +08:00
elif _is_path_key ( key ) :
changes . append (
{
" path " : key ,
" before " : _mask_path_value ( before_value ) ,
" after " : _mask_path_value ( after_value ) ,
" sensitive " : False ,
}
)
2026-07-05 09:11:05 +08:00
else :
changes . append (
{
" path " : key ,
" before " : before_value ,
" after " : after_value ,
" sensitive " : False ,
}
)
return { " has_changes " : bool ( changes ) , " changes " : changes }
2026-07-05 10:49:14 +08:00
def save ( self , candidate : Mapping [ str , Any ] , ctx : RequestContext ) - > dict [ str , Any ] :
validation = self . validate ( candidate )
if not validation [ " valid " ] :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " config validation failed " , validation )
incoming = candidate . get ( " config " , candidate )
if not isinstance ( incoming , Mapping ) :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " config must be an object " , { " field " : " config " } )
2026-07-11 21:50:34 +08:00
with config_file_lock ( self . config_service . config_path ) :
before = self . _load_current_mapping ( )
before_file = load_config_file_payload ( self . config_service . config_path )
merged_effective = _merge_masked ( before , incoming )
2026-07-15 23:01:07 +08:00
runtime_changes = _runtime_override_changes (
before ,
merged_effective ,
self . config_service . config_path ,
)
persistence = persist_runtime_config_values ( runtime_changes ) if runtime_changes else { }
if runtime_changes and not persistence . get ( " available " ) :
2026-07-11 21:50:34 +08:00
raise ApiError (
ErrorCode . VALIDATION_FAILED ,
2026-07-15 23:01:07 +08:00
" AstrBot-managed settings could not be persisted from this runtime " ,
{ " runtime_managed_fields " : sorted ( runtime_changes ) } ,
2026-07-11 21:50:34 +08:00
)
merged = _restore_runtime_managed_fields (
merged_effective ,
before_file ,
get_runtime_config_overrides ( ) if is_default_config_path ( self . config_service . config_path ) else { } ,
)
_initialize_database_if_changed ( before_file , merged )
self . _record_snapshot ( before_file , ctx , " before_save " )
write_text_atomic ( self . config_service . config_path , dump_yaml ( merged ) )
after = self . _load_current_mapping ( )
2026-07-05 10:49:14 +08:00
if self . audit_service :
self . audit_service . record (
ctx = ctx ,
action = " save_settings " ,
target_type = " config " ,
2026-07-05 13:13:00 +08:00
target_id = " ***PATH*** " ,
2026-07-05 10:49:14 +08:00
before_snapshot = _mask_sensitive ( before ) ,
after_snapshot = _mask_sensitive ( after ) ,
)
return { " saved " : True , " config " : _mask_sensitive ( after ) }
def reload ( self ) - > dict [ str , Any ] :
return { " reloaded " : True , " config " : self . get_current ( ) [ " config " ] }
def export ( self ) - > dict [ str , Any ] :
return {
" redacted " : True ,
" config " : self . get_current ( ) [ " config " ] ,
}
def import_config ( self , payload : Mapping [ str , Any ] , ctx : RequestContext ) - > dict [ str , Any ] :
config = payload . get ( " config " , payload )
if not isinstance ( config , Mapping ) :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " config must be an object " , { " field " : " config " } )
return self . save ( { " config " : config } , ctx )
2026-07-05 14:56:48 +08:00
def list_snapshots ( self , limit : int = 20 ) - > list [ dict [ str , Any ] ] :
if not self . audit_service :
return [ ]
placeholder = self . audit_service . database . _placeholder
2026-07-05 19:57:17 +08:00
normalized_limit = _limit ( limit , default = 20 , maximum = 100 )
2026-07-05 14:56:48 +08:00
conn = self . audit_service . database . connect ( )
try :
rows = conn . execute (
f """
SELECT snapshot_id , reason , actor_id , config_json , created_at
FROM config_snapshots
ORDER BY created_at DESC
LIMIT { placeholder }
""" ,
( normalized_limit , ) ,
) . fetchall ( )
finally :
conn . close ( )
snapshots = [ ]
for row in rows :
config = json . loads ( row [ " config_json " ] or " {} " )
snapshots . append (
{
" snapshot_id " : row [ " snapshot_id " ] ,
" reason " : row [ " reason " ] ,
" actor_id " : row [ " actor_id " ] ,
" config " : _mask_sensitive ( config ) ,
" created_at " : row [ " created_at " ] ,
}
)
return snapshots
2026-07-05 15:28:28 +08:00
def get_snapshot ( self , snapshot_id : str ) - > dict [ str , Any ] :
if not self . audit_service :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " config snapshots are unavailable " , { } )
normalized_snapshot_id = str ( snapshot_id or " " ) . strip ( )
if not normalized_snapshot_id :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " snapshot_id is required " , { " field " : " snapshot_id " } )
row = self . _load_snapshot_row ( normalized_snapshot_id )
if row is None :
raise ApiError (
ErrorCode . RESOURCE_NOT_FOUND ,
" config snapshot not found " ,
{ " snapshot_id " : normalized_snapshot_id } ,
)
config = json . loads ( row [ " config_json " ] or " {} " )
return {
" snapshot_id " : row [ " snapshot_id " ] ,
" reason " : row [ " reason " ] ,
" actor_id " : row [ " actor_id " ] ,
" config " : _mask_sensitive ( config ) ,
" created_at " : row [ " created_at " ] ,
}
2026-07-05 14:56:48 +08:00
def rollback ( self , payload : Mapping [ str , Any ] , ctx : RequestContext ) - > dict [ str , Any ] :
if not self . audit_service :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " config snapshots are unavailable " , { } )
snapshot_id = str ( payload . get ( " snapshot_id " ) or " " ) . strip ( )
if not snapshot_id :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " snapshot_id is required " , { " field " : " snapshot_id " } )
2026-07-05 15:28:28 +08:00
row = self . _load_snapshot_row ( snapshot_id )
2026-07-05 14:56:48 +08:00
if row is None :
raise ApiError ( ErrorCode . RESOURCE_NOT_FOUND , " config snapshot not found " , { " snapshot_id " : snapshot_id } )
config = json . loads ( row [ " config_json " ] or " {} " )
validation = self . validate ( { " config " : config } )
if not validation [ " valid " ] :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " snapshot config validation failed " , validation )
2026-07-11 21:50:34 +08:00
with config_file_lock ( self . config_service . config_path ) :
before = self . _load_current_mapping ( )
before_file = load_config_file_payload ( self . config_service . config_path )
conflicts = _runtime_override_conflicts ( config , self . config_service . config_path )
if conflicts :
raise ApiError (
ErrorCode . VALIDATION_FAILED ,
" snapshot changes settings managed by AstrBot " ,
{ " runtime_managed_fields " : conflicts } ,
)
rollback_config = _restore_runtime_managed_fields (
config ,
before_file ,
get_runtime_config_overrides ( ) if is_default_config_path ( self . config_service . config_path ) else { } ,
)
_initialize_database_if_changed ( before_file , rollback_config )
self . _record_snapshot ( before_file , ctx , " before_rollback " )
write_text_atomic ( self . config_service . config_path , dump_yaml ( rollback_config ) )
after = self . _load_current_mapping ( )
2026-07-05 14:56:48 +08:00
self . audit_service . record (
ctx = ctx ,
action = " rollback_settings " ,
target_type = " config " ,
target_id = " ***PATH*** " ,
before_snapshot = _mask_sensitive ( before ) ,
after_snapshot = _mask_sensitive ( after ) ,
metadata = { " snapshot_id " : snapshot_id } ,
)
return { " rolled_back " : True , " snapshot_id " : snapshot_id , " config " : _mask_sensitive ( after ) }
2026-07-05 15:28:28 +08:00
def _load_snapshot_row ( self , snapshot_id : str ) :
if not self . audit_service :
return None
placeholder = self . audit_service . database . _placeholder
conn = self . audit_service . database . connect ( )
try :
return conn . execute (
f """
SELECT snapshot_id , reason , actor_id , config_json , created_at
FROM config_snapshots
WHERE snapshot_id = { placeholder }
""" ,
( snapshot_id , ) ,
) . fetchone ( )
finally :
conn . close ( )
2026-07-05 09:11:05 +08:00
def _load_raw_schema ( self ) - > dict [ str , Any ] :
if not self . schema_path . exists ( ) :
return { }
return json . loads ( self . schema_path . read_text ( encoding = " utf-8 " ) )
def _load_current_mapping ( self ) - > dict [ str , Any ] :
2026-07-11 21:50:34 +08:00
return load_config_payload ( self . config_service . config_path )
2026-07-05 09:11:05 +08:00
2026-07-05 14:56:48 +08:00
def _record_snapshot ( self , config : Mapping [ str , Any ] , ctx : RequestContext , reason : str ) - > str | None :
if not self . audit_service :
return None
snapshot_id = f " cfgsnap_ { uuid4 ( ) . hex } "
placeholder = self . audit_service . database . _placeholder
conn = self . audit_service . database . connect ( )
try :
conn . execute (
f """
INSERT INTO config_snapshots (
snapshot_id , reason , actor_id , config_json
) VALUES (
{ placeholder } , { placeholder } , { placeholder } , { placeholder }
)
""" ,
(
snapshot_id ,
reason ,
ctx . actor_id ,
json . dumps ( dict ( config ) , ensure_ascii = False , sort_keys = True ) ,
) ,
)
conn . commit ( )
finally :
conn . close ( )
return snapshot_id
2026-07-05 09:11:05 +08:00
def _field (
key : str ,
field_type : str ,
* ,
2026-07-06 10:59:28 +08:00
label : str = " " ,
2026-07-05 09:11:05 +08:00
options : list [ str ] | None = None ,
sensitive : bool = False ,
readonly : bool = False ,
) - > dict [ str , Any ] :
return {
" key " : key ,
2026-07-06 10:59:28 +08:00
" label " : label or key ,
2026-07-05 09:11:05 +08:00
" type " : field_type ,
" options " : options or [ ] ,
" sensitive " : sensitive ,
" readonly " : readonly ,
}
def _mask_sensitive ( value : Any , path : str = " " ) - > Any :
if isinstance ( value , Mapping ) :
masked : dict [ str , Any ] = { }
for key , child in value . items ( ) :
child_path = f " { path } . { key } " if path else str ( key )
2026-07-05 09:24:00 +08:00
if _is_sensitive_key ( child_path ) and child :
masked [ str ( key ) ] = " ***MASKED*** "
elif _is_path_key ( child_path ) and _is_absolute_path_value ( child ) :
masked [ str ( key ) ] = " ***PATH*** "
else :
masked [ str ( key ) ] = _mask_sensitive ( child , child_path )
2026-07-05 09:11:05 +08:00
return masked
if isinstance ( value , list ) :
return [ _mask_sensitive ( item , path ) for item in value ]
return value
2026-07-05 19:57:17 +08:00
def _limit ( value : Any , * , default : int , maximum : int ) - > int :
try :
limit = int ( value )
except ( TypeError , ValueError ) :
limit = default
return min ( max ( limit , 1 ) , maximum )
2026-07-05 09:11:05 +08:00
def _flatten ( value : Mapping [ str , Any ] , prefix : str = " " ) - > dict [ str , Any ] :
flattened : dict [ str , Any ] = { }
for key , child in value . items ( ) :
path = f " { prefix } . { key } " if prefix else str ( key )
if isinstance ( child , Mapping ) :
flattened . update ( _flatten ( child , path ) )
else :
flattened [ path ] = child
return flattened
def _is_sensitive_key ( path : str ) - > bool :
lowered = path . lower ( )
if lowered . endswith ( " _set " ) :
return False
return any ( part in lowered for part in SENSITIVE_KEY_PARTS )
2026-07-05 09:24:00 +08:00
def _is_path_key ( path : str ) - > bool :
lowered = path . lower ( )
return lowered . endswith ( " _path " ) or lowered . endswith ( " .path " )
def _is_absolute_path_value ( value : Any ) - > bool :
return isinstance ( value , str ) and Path ( value ) . is_absolute ( )
2026-07-05 13:13:00 +08:00
def _mask_path_value ( value : Any ) - > Any :
return " ***PATH*** " if _is_absolute_path_value ( value ) else value
2026-07-05 09:11:05 +08:00
def _resolve_path ( path : str | Path ) - > Path :
2026-07-11 21:50:34 +08:00
return resolve_plugin_path ( path )
2026-07-05 10:49:14 +08:00
def _merge_masked ( current : Mapping [ str , Any ] , incoming : Mapping [ str , Any ] ) - > dict [ str , Any ] :
result : dict [ str , Any ] = dict ( current )
for key , value in incoming . items ( ) :
if isinstance ( value , str ) and value in { " ***MASKED*** " , " ***PATH*** " } :
continue
if isinstance ( value , Mapping ) and isinstance ( result . get ( key ) , Mapping ) :
result [ str ( key ) ] = _merge_masked ( result [ key ] , value )
2026-07-13 01:49:00 +08:00
elif isinstance ( value , list ) and isinstance ( result . get ( key ) , list ) :
result [ str ( key ) ] = _merge_masked_list ( result [ key ] , value )
2026-07-05 10:49:14 +08:00
else :
result [ str ( key ) ] = value
return result
2026-07-13 01:49:00 +08:00
def _merge_masked_list ( current : list [ Any ] , incoming : list [ Any ] ) - > list [ Any ] :
merged : list [ Any ] = [ ]
for index , item in enumerate ( incoming ) :
if isinstance ( item , Mapping ) :
2026-07-15 23:01:07 +08:00
clean_item = dict ( item )
copy_source_id = clean_item . pop ( " __copy_from_adapter_id " , None )
existing = _matching_list_mapping ( current , clean_item , index )
if not isinstance ( existing , Mapping ) and copy_source_id not in ( None , " " ) :
existing = _list_mapping_by_adapter_id ( current , str ( copy_source_id ) )
merged . append ( _merge_masked ( existing if isinstance ( existing , Mapping ) else { } , clean_item ) )
2026-07-13 01:49:00 +08:00
elif isinstance ( item , str ) and item in { " ***MASKED*** " , " ***PATH*** " } and index < len ( current ) :
merged . append ( current [ index ] )
else :
merged . append ( item )
return merged
2026-07-15 23:01:07 +08:00
def _list_mapping_by_adapter_id ( current : list [ Any ] , adapter_id : str ) - > Mapping [ str , Any ] | None :
for item in current :
if not isinstance ( item , Mapping ) :
continue
if str ( item . get ( " id " ) or item . get ( " provider_id " ) or " " ) == adapter_id :
return item
return None
2026-07-13 01:49:00 +08:00
def _matching_list_mapping ( current : list [ Any ] , incoming : Any , index : int ) - > Mapping [ str , Any ] | None :
if not isinstance ( incoming , Mapping ) :
return None
for identity_key in ( " id " , " provider_id " , " route_id " , " category_id " , " category " , " key " ) :
identity = incoming . get ( identity_key )
if identity in ( None , " " ) :
continue
for item in current :
if isinstance ( item , Mapping ) and item . get ( identity_key ) == identity :
return item
if index < len ( current ) and isinstance ( current [ index ] , Mapping ) :
return current [ index ]
return None
2026-07-11 21:50:34 +08:00
def _runtime_override_conflicts ( incoming : Mapping [ str , Any ] , config_path : Path ) - > list [ str ] :
if not is_default_config_path ( config_path ) :
return [ ]
overrides = _flatten ( get_runtime_config_overrides ( ) )
if not overrides :
return [ ]
candidate = _flatten ( incoming )
2026-07-13 01:49:00 +08:00
generation = incoming . get ( " generation " ) if isinstance ( incoming . get ( " generation " ) , Mapping ) else { }
uses_plugin_adapters = isinstance ( generation . get ( " adapters " ) , list )
def is_plugin_adapter_compatibility_field ( path : str ) - > bool :
if not uses_plugin_adapters :
return False
return path == " generation.default_model " or path . startswith ( " generation.provider. " )
return sorted (
path
for path , value in overrides . items ( )
if path in candidate
and candidate [ path ] != value
and not is_plugin_adapter_compatibility_field ( path )
)
2026-07-11 21:50:34 +08:00
2026-07-15 23:01:07 +08:00
def _runtime_override_changes (
before : Mapping [ str , Any ] ,
incoming : Mapping [ str , Any ] ,
config_path : Path ,
) - > dict [ str , Any ] :
""" Return only user-changed values that are owned by AstrBot ' s plugin config. """
if not is_default_config_path ( config_path ) :
return { }
managed = _flatten ( get_runtime_config_overrides ( ) )
if not managed :
return { }
previous = _flatten ( before )
candidate = _flatten ( incoming )
generation = incoming . get ( " generation " ) if isinstance ( incoming . get ( " generation " ) , Mapping ) else { }
uses_plugin_adapters = isinstance ( generation . get ( " adapters " ) , list )
def is_plugin_adapter_compatibility_field ( path : str ) - > bool :
if not uses_plugin_adapters :
return False
return path == " generation.default_model " or path . startswith ( " generation.provider. " )
return {
path : candidate [ path ]
for path in managed
if path in candidate
and candidate [ path ] != previous . get ( path )
and not is_plugin_adapter_compatibility_field ( path )
}
2026-07-11 21:50:34 +08:00
def _restore_runtime_managed_fields (
candidate : Mapping [ str , Any ] ,
file_config : Mapping [ str , Any ] ,
runtime_overrides : Mapping [ str , Any ] ,
) - > dict [ str , Any ] :
result = _copy_mapping ( candidate )
file_values = _flatten ( file_config )
for path in _flatten ( runtime_overrides ) :
if path in file_values :
_set_nested_value ( result , path . split ( " . " ) , file_values [ path ] )
else :
_delete_nested_value ( result , path . split ( " . " ) )
return result
def _copy_mapping ( value : Mapping [ str , Any ] ) - > dict [ str , Any ] :
copied : dict [ str , Any ] = { }
2026-07-05 10:49:14 +08:00
for key , child in value . items ( ) :
if isinstance ( child , Mapping ) :
2026-07-11 21:50:34 +08:00
copied [ str ( key ) ] = _copy_mapping ( child )
2026-07-05 10:49:14 +08:00
elif isinstance ( child , list ) :
2026-07-11 21:50:34 +08:00
copied [ str ( key ) ] = [
_copy_mapping ( item ) if isinstance ( item , Mapping ) else item
for item in child
]
2026-07-05 10:49:14 +08:00
else :
2026-07-11 21:50:34 +08:00
copied [ str ( key ) ] = child
return copied
def _set_nested_value ( target : dict [ str , Any ] , parts : list [ str ] , value : Any ) - > None :
cursor = target
for part in parts [ : - 1 ] :
child = cursor . get ( part )
if not isinstance ( child , dict ) :
child = { }
cursor [ part ] = child
cursor = child
if parts :
cursor [ parts [ - 1 ] ] = value
def _delete_nested_value ( target : dict [ str , Any ] , parts : list [ str ] ) - > None :
if not parts :
return
cursor : dict [ str , Any ] = target
parents : list [ tuple [ dict [ str , Any ] , str ] ] = [ ]
for part in parts [ : - 1 ] :
child = cursor . get ( part )
if not isinstance ( child , dict ) :
return
parents . append ( ( cursor , part ) )
cursor = child
cursor . pop ( parts [ - 1 ] , None )
for parent , key in reversed ( parents ) :
child = parent . get ( key )
if isinstance ( child , dict ) and not child :
parent . pop ( key , None )
else :
break
def _initialize_database_if_changed ( before : Mapping [ str , Any ] , after : Mapping [ str , Any ] ) - > None :
before_database = before . get ( " database " ) if isinstance ( before . get ( " database " ) , Mapping ) else { }
after_database = after . get ( " database " ) if isinstance ( after . get ( " database " ) , Mapping ) else { }
if dict ( before_database ) == dict ( after_database ) :
return
Database ( DatabaseSettings . from_mapping ( after ) ) . initialize ( )
# Compatibility alias for existing tests and services that imported the
# previous private serializer. New code should import core.config_writer.
_dump_yaml = dump_yaml