Nexus/docs/changelog/2026-05-30-settings-inspection.md

Changelog — Settings 页面巡检 + Telegram Bot Token 脱敏

日期: 2026-05-30
类型: 安全修复 + 功能验证
涉及文件:

• server/api/settings.py — SENSITIVE_KEYS 加入 telegram_bot_token + reveal-token 端点
• web/app/settings.html — Telegram 区域独立渲染 + Bot Token 脱敏 UI

变更摘要

1. Telegram Bot Token 脱敏 (安全修复)

问题: GET /api/settings/ 以明文返回 Bot Token 8743165040:AAH_YGffcj2mdqSAx1sHXjspvUFzJ_kVC2I，违反安全铁律（API 响应不得返回敏感凭据明文）。

修复:

• 后端 SENSITIVE_KEYS 新增 telegram_bot_token，GET 响应返回脱敏值 87431650...
• 新增 POST /api/settings/telegram/reveal-token 端点（密码验证 + 审计日志）
• 前端 Telegram 区域从通用 SECTIONS 循环中分离，单独渲染：
  • Bot Token 默认脱敏显示 + 「显示」按钮（需密码验证）
  • 验证后切换为 password 类型输入框 + 显示/隐藏切换
  • Chat ID 保持正常编辑（非敏感信息）

2. Settings 页面功能巡检结果

功能	状态	备注
品牌设置保存	✅ 正常	PUT system_name → 200
告警阈值保存	✅ 正常	PUT cpu_alert_threshold → 200 + 热更新
通知 toggle 开关	✅ 正常	乐观 UI 更新 + API 同步
手动 IP 添加/删除	✅ 正常	POST + DELETE → 200
IP 白名单开关	✅ 正常	confirm 弹窗 + toggle
订阅地址保存	✅ 正常	触发后台刷新
Telegram Chat ID 检测	✅ 正常	getUpdates → 2 个对话
不可变 Key 拒绝	✅ 正常	PUT api_key → 403
TOTP 状态显示	✅ 正常	已启用卡片 + 重新绑定/禁用按钮
Bot Token 脱敏	✅ 正常	87431650... + 显示按钮
API Key 脱敏+复制	✅ 正常	de3a155d... + 显示/复制
订阅 IP 显示	✅ 正常	6 个节点 IP
手动 IP 空状态	✅ 正常	显示「（空）」
告警通知 8 项 toggle	✅ 正常	全部可切换

3. 已排除的假问题

• heartbeat_timeout 映射: 已存在于 DB_OVERRIDE_MAP (config.py:115)，Task 2 关闭
• 手动 IP 与订阅 IP 重叠: 旧页面缓存（ip-allowlist 路由修复前），刷新后正常
• 「等待首次刷新...」: 服务重启后时序问题，refresh 完成后刷新页面正常显示

动机

安全审计发现 Telegram Bot Token 明文暴露，需要与 API_KEY/SECRET_KEY 同等级别保护。

是否需迁移/重启

• 需要重启后端服务（新增 API 端点 + SENSITIVE_KEYS 变更）

验证方式

1. GET /api/settings/ → telegram_bot_token 值为 87431650...
2. POST /api/settings/telegram/reveal-token + 密码 → 返回完整 token
3. 前端 settings 页面 → Bot Token 显示脱敏 + 「显示」按钮可正常揭示
4. ruff check → 0 errors