设置页面（Settings）¶

📎 引用文件

本文引用的文件 - agent/src/api/settings_routes.py - frontend/src/pages/Settings.tsx - agent/src/config/accessor.py - agent/src/config/migrate.py - agent/src/providers/llm_providers.json - agent/src/api/security.py - frontend/src/lib/apiAuth.ts - README_zh.md - README.md

简介¶

本章节面向 Vibe-Trading 的“设置”页面，系统性说明系统配置管理能力，包括： - 模型提供商设置、API 密钥管理、连接配置、生成参数与推理强度等偏好设置 - 数据源凭据（如 Tushare Token）管理 - IM 通道运行状态查看与控制（启动/停止） - QVeris 集成设置（独立面板） - 配置验证机制、热重载支持、配置持久化与迁移 - 安全性考虑、权限控制、版本兼容性与前后端同步机制 - 配置文件格式规范、最佳实践与常见问题排查

该页面同时提供本地 API 访问密钥设置（非桌面模式），以及数据源加载器可用性提示。

章节来源 - README_zh.md:1003-1005 - README.md:1036-1044

项目结构¶

设置功能由前端页面与后端路由共同实现： - 前端：React 页面负责表单交互、错误提示、轮询通道状态、调用 API - 后端：FastAPI 路由暴露 /settings/* 接口，负责读取/写入 .env、校验参数、同步运行时环境变量、返回结构化响应 - 配置层：通过 accessor 模块提供线程安全的配置缓存与重置能力；迁移模块负责历史状态迁移 - 提供商元数据：JSON 驱动，新增/修改提供商无需改代码 - 安全：基于 Bearer 令牌或回环信任的鉴权策略，敏感字段脱敏与白名单校验

graph TB UI["前端设置页面 Settings.tsx"] --> API["后端设置路由 settings_routes.py"] API --> ENV[".env 配置读写 ENV_PATH/LEGACY_ENV_PATH"] API --> RUNTIME["运行时环境变量 os.environ + reset_env_config()"] API --> PROVIDERS["提供商元数据 llm_providers.json"] API --> SEC["鉴权与安全 security.py"] UI --> AUTH["浏览器本地存储 API Key apiAuth.ts"]

图表来源 - frontend/src/pages/Settings.tsx:62-120 - agent/src/api/settings_routes.py:497-674 - agent/src/config/accessor.py:52-93 - agent/src/providers/llm_providers.json:1-200 - agent/src/api/security.py:343-483 - frontend/src/lib/apiAuth.ts:1-21

章节来源 - frontend/src/pages/Settings.tsx:1-777 - agent/src/api/settings_routes.py:1-674 - agent/src/config/accessor.py:1-149 - agent/src/config/migrate.py:1-153 - agent/src/providers/llm_providers.json:1-200 - agent/src/api/security.py:343-483 - frontend/src/lib/apiAuth.ts:1-21

核心组件¶

设置页面（前端）
并行拉取 LLM 设置、数据源设置、IM 通道状态
提供商切换时应用默认模型与基础 URL
动态刷新可用模型列表（支持 OAuth 与 API Key 两种认证类型）
保存 LLM 设置与数据源凭据，桌面模式下将凭据写入系统安全存储并重启后端
本地 API 访问密钥设置（非桌面模式）
设置路由（后端）
GET/PUT /settings/llm：获取/更新 LLM 设置
POST /settings/llm/models：按提供商与基础 URL 列出可用模型
GET/PUT /settings/data-sources：获取/更新数据源凭据
配置校验：温度范围、推理强度枚举、Base URL 合法性、OAuth 专用校验
持久化：合并旧版 .env，写入用户配置路径，必要时清空敏感字段
热重载：写入后同步到 os.environ 并重置配置缓存
配置访问器
单例 EnvConfig 缓存，线程安全
reset_env_config 用于热重载后刷新
提供商元数据
JSON 驱动，声明每个提供商的默认模型、基础 URL、是否必需 API Key、认证类型、登录命令等
安全与鉴权
读操作要求本地或已认证；写操作要求更强认证
开发模式下未配置 API_AUTH_KEY 时仅允许回环客户端
敏感信息脱敏显示，禁止在 Base URL 中嵌入凭据

章节来源 - frontend/src/pages/Settings.tsx:62-120 - frontend/src/pages/Settings.tsx:178-208 - frontend/src/pages/Settings.tsx:217-286 - agent/src/api/settings_routes.py:497-674 - agent/src/config/accessor.py:52-93 - agent/src/providers/llm_providers.json:1-200 - agent/src/api/security.py:343-483

架构总览¶

设置页面的请求-响应流程如下：

sequenceDiagram participant U as "用户" participant F as "前端设置页面" participant A as "后端设置路由" participant E as ".env 配置" participant R as "运行时环境" participant P as "提供商元数据" U->>F : 打开设置页面 F->>A : GET /settings/llm A->>E : 读取当前配置 A->>P : 加载提供商选项 A-->>F : 返回 LLM 设置与提供商列表 U->>F : 修改提供商/模型/参数/密钥 F->>A : PUT /settings/llm A->>E : 持久化更新合并旧版.env A->>R : 同步环境变量并重置配置缓存 A-->>F : 返回最新设置 U->>F : 点击“刷新模型” F->>A : POST /settings/llm/models A->>P : 根据提供商与基础URL查询模型 A-->>F : 返回模型列表与警告码

图表来源 - frontend/src/pages/Settings.tsx:62-120 - frontend/src/pages/Settings.tsx:178-208 - frontend/src/pages/Settings.tsx:217-286 - agent/src/api/settings_routes.py:497-674 - agent/src/config/accessor.py:52-93 - agent/src/providers/llm_providers.json:1-200

详细组件分析¶

模型提供商设置与 API 密钥管理¶

提供商选择与应用默认值
切换提供商时自动应用默认模型与基础 URL
支持 OAuth 与 API Key 两种认证类型
API 密钥处理
非桌面模式：输入框直接提交密钥；桌面模式：通过系统安全存储写入
支持“清除密钥”选项，清空对应环境变量
密钥有效性校验：拒绝占位符或无效格式
模型列表发现
按提供商与基础 URL 调用 OpenAI 兼容的 /models 接口
若失败或未提供密钥，退回默认模型并给出警告码
对 OAuth 提供商禁用模型发现（返回不支持警告）

flowchart TD Start(["开始"]) --> SelectProvider["选择提供商"] SelectProvider --> ApplyDefaults["应用默认模型与基础URL"] ApplyDefaults --> NeedKey{"需要API Key?"} NeedKey --> |是| InputKey["输入或复用已配置密钥"] NeedKey --> |否| SkipKey["跳过密钥输入"] InputKey --> ValidateKey["校验密钥格式"] SkipKey --> ListModels["请求模型列表"] ValidateKey --> ListModels ListModels --> Success{"成功?"} Success --> |是| UpdateUI["更新模型下拉框"] Success --> |否| ShowHint["显示警告提示"] UpdateUI --> Save["保存设置"] ShowHint --> Save Save --> End(["结束"])

图表来源 - frontend/src/pages/Settings.tsx:163-208 - agent/src/api/settings_routes.py:589-633 - agent/src/api/settings_routes.py:279-328

章节来源 - frontend/src/pages/Settings.tsx:163-208 - agent/src/api/settings_routes.py:589-633 - agent/src/api/settings_routes.py:279-328

连接配置与生成参数¶

连接配置
基础 URL 校验：必须为 HTTP(S)，不允许嵌入用户名/密码
OAuth 提供商使用专用校验函数限制合法端点
生成参数
温度：0~2 范围校验
超时秒数：1~3600 范围校验
最大重试次数：0~20 范围校验
推理强度：空或 none/low/medium/high/max 枚举校验
保存与热重载
写入 .env 后同步到 os.environ 并重置配置缓存，使后续组件立即生效

flowchart TD S(["提交设置"]) --> ValidateURL["校验基础URL"] ValidateURL --> ValidateParams["校验温度/超时/重试/推理强度"] ValidateParams --> Persist["写入.env并合并旧配置"] Persist --> SyncEnv["同步到运行时环境变量"] SyncEnv --> ResetCache["重置配置缓存"] ResetCache --> Return["返回最新设置"]

图表来源 - agent/src/api/settings_routes.py:506-587 - agent/src/api/settings_routes.py:403-431 - agent/src/config/accessor.py:79-93

章节来源 - agent/src/api/settings_routes.py:506-587 - agent/src/api/settings_routes.py:403-431 - agent/src/config/accessor.py:79-93

数据源凭据管理（Tushare Token）¶

读取与更新
支持输入新 Token 或清空现有 Token
桌面模式：通过系统安全存储写入 TUSHARE_TOKEN
状态展示
显示是否已配置、BaoStock 加载器是否可用与安装状态
热重载
更新后同步到运行时环境变量并重置配置缓存

章节来源 - frontend/src/pages/Settings.tsx:254-286 - agent/src/api/settings_routes.py:635-674

IM 通道运行状态与控制¶

状态轮询
页面加载时并行获取通道状态，展示启用/加载/运行/不可用计数
控制操作
支持启动/停止通道运行时，刷新状态
恢复提示
显示适配器恢复建议与错误信息

章节来源 - frontend/src/pages/Settings.tsx:122-144 - frontend/src/pages/Settings.tsx:359-472

QVeris 集成设置¶

独立面板，用于配置 QVeris 服务（启用/禁用、基础 URL、API Key、模式、预算额度等）
与主设置页面并列展示，遵循相同的安全与持久化策略

章节来源 - frontend/src/pages/Settings.tsx:329-330 - agent/src/api/qveris_routes.py:1-55

本地 API 访问密钥设置（非桌面模式）¶

在浏览器本地存储中保存 API_AUTH_KEY
提交后刷新页面以应用新的鉴权头

章节来源 - frontend/src/pages/Settings.tsx:288-319 - frontend/src/lib/apiAuth.ts:1-21

依赖关系分析¶

前端依赖
Settings.tsx 依赖 ModelPicker、QVerisSettings 子组件
通过 api 模块调用后端接口，使用 i18n 进行多语言提示
后端依赖
settings_routes.py 依赖 accessor（配置缓存）、security（鉴权）、providers JSON（提供商元数据）
通过 httpx 异步调用提供商模型列表接口
配置层依赖
accessor.py 提供线程安全的配置单例与重置
migrate.py 负责历史状态迁移，确保升级不丢失数据

graph LR FE["前端 Settings.tsx"] --> BE["后端 settings_routes.py"] BE --> ACC["配置访问器 accessor.py"] BE --> SEC["鉴权 security.py"] BE --> PROV["提供商 llm_providers.json"] BE --> MIG["迁移 migrate.py"]

图表来源 - frontend/src/pages/Settings.tsx:1-777 - agent/src/api/settings_routes.py:1-674 - agent/src/config/accessor.py:1-149 - agent/src/config/migrate.py:1-153 - agent/src/providers/llm_providers.json:1-200 - agent/src/api/security.py:343-483

性能与可靠性¶

并发读取
前端并行拉取 LLM 设置、数据源设置、通道状态，提升首屏速度
热重载
后端写入后立即同步环境变量并重置配置缓存，避免重启进程
健壮性
模型列表请求失败时退回默认模型并提示
配置写入失败返回明确错误信息（权限/路径问题）
安全
读操作不创建 .env，仅返回相对路径
写操作需更强认证，防止未授权更新
敏感字段脱敏，禁止在 Base URL 中嵌入凭据

[本节为通用指导，不直接分析具体文件]

故障排除指南¶

无法加载设置
检查网络与鉴权头是否正确
确认后端服务正常运行
模型列表为空或失败
确认基础 URL 正确且可访问
如需 API Key，请提供有效密钥或使用受信任的基础 URL
保存设置失败
检查 .env 文件权限与路径
确认无其他进程锁定文件
通道状态异常
尝试刷新状态，检查适配器安装与依赖
查看恢复提示与错误信息
本地 API 访问密钥无效
在非桌面模式下重新设置并刷新页面
确认浏览器本地存储未被清理

章节来源 - frontend/src/pages/Settings.tsx:62-120 - frontend/src/pages/Settings.tsx:178-208 - frontend/src/pages/Settings.tsx:217-286 - agent/src/api/settings_routes.py:506-587 - agent/src/api/settings_routes.py:635-674

结论¶

设置页面提供了完整的系统配置管理能力，涵盖模型提供商、API 密钥、连接参数、数据源凭据与 IM 通道控制。通过严格的参数校验、热重载机制与安全的鉴权策略，确保配置变更即时生效且安全可靠。结合 JSON 驱动的提供商元数据与配置迁移工具，系统具备良好的可扩展性与兼容性。

[本节为总结性内容，不直接分析具体文件]

附录：配置项与默认值¶

LLM 设置
提供商：从 llm_providers.json 加载
模型名称：必填，默认使用提供商默认模型
基础 URL：HTTP(S)，不允许嵌入凭据；OAuth 提供商使用专用校验
API Key：可选，支持清空；桌面模式写入系统安全存储
温度：0~2，默认 0.0
超时秒数：1~3600，默认 120
最大重试次数：0~20，默认 2
推理强度：空或 none/low/medium/high/max
SSE 超时秒数：默认 90
数据源设置
Tushare Token：可选，支持清空；桌面模式写入系统安全存储
BaoStock：显示是否支持与安装状态
安全与权限
读操作：本地或已认证
写操作：更强认证；开发模式下未配置 API_AUTH_KEY 仅允许回环
敏感字段脱敏，禁止在 Base URL 中嵌入凭据
配置文件与迁移
目标路径：用户配置路径（ENV_PATH），兼容旧版 LEGACY_ENV_PATH
迁移：历史状态目录迁移至运行时根目录，原子移动与恢复

章节来源 - agent/src/api/settings_routes.py:46-120 - agent/src/api/settings_routes.py:336-400 - agent/src/api/settings_routes.py:506-587 - agent/src/api/settings_routes.py:635-674 - agent/src/config/migrate.py:1-153 - agent/src/providers/llm_providers.json:1-200 - agent/src/api/security.py:343-483 - README_zh.md:1003-1005 - README.md:1036-1044

← 实时监控页面（Runtime）运行详情页面（RunDetail） →