业务逻辑安全专项扫描

范围: 聊天菜单返回键、资源泄漏、文件名安全校验

一、背景与动机

1.1 问题溯源

在前期开发过程中，我们发现了一些容易被忽视的”边边角角”的业务逻辑硬性问题：

文件名处理缺失 - 上传文件时未对文件名进行校验和清理，可能包含非法字符
缩略图加载导致全文件下载 - 之前的缩略图加载逻辑存在问题，在某些情况下会触发整个原始文件的下载，造成不必要的流量消耗

这些问题的共同特点是：

不影响主流程功能的正常使用
在特定条件下才会暴露
可能导致安全风险或资源浪费
容易在常规功能测试中被遗漏

1.2 专项扫描目标

基于历史经验，本次专项扫描的目标是：

主动发现并修复类似的”隐性”问题
重点关注非 UI 层面的业务逻辑缺陷
借鉴互联网通用的移动端开发经验

二、发现的问题清单

问题总览

#	问题	严重程度	状态
1	聊天菜单返回键不关闭	中	✅ 已修复
2	音频播放器订阅泄漏	高	✅ 已修复
3	后端文件名未校验非法字符	高	✅ 已修复
4	磁盘缓存无上限	低	⏸ 取消（优化项）
5	Future.delayed 后 mounted 检查	低	⏸ 取消（低优先级）

三、问题详细分析与修复

3.1 聊天菜单返回键不关闭

问题现象

在聊天界面长按消息气泡后，会弹出一个上下文菜单（复制、转发、删除等选项）。此时按下系统返回键，菜单不会关闭，仍然停留在屏幕上。

根因分析

查看 context_menu.dart 的实现：

class _ContextMenuOverlayState extends State<_ContextMenuOverlay>
    with SingleTickerProviderStateMixin {
  OverlayEntry? _overlayEntry;
  
  void _show() {
    _overlayEntry = OverlayEntry(
      builder: (context) => Material(
        color: Colors.transparent,
        child: Stack(...)
      ),
    );
    Overlay.of(context).insert(_overlayEntry!);
  }
}

问题的核心是 OverlayEntry 直接插入到 Overlay，不经过 Navigator 路由。

Flutter 的返回键处理机制是通过 Navigator 的路由栈来实现的：

按返回键时，Navigator 会 pop 栈顶的 Route
OverlayEntry 不是 Route，不在 Navigator 管理范围内
因此返回键事件不会触发 OverlayEntry 的关闭

方案选型

方案	优点	缺点	评估
A. 改用 showDialog	自动处理返回键	动画效果受限，需要重写布局逻辑	❌ 改动大
B. 改用自定义 Route	完整的路由管理	需要继承 OverlayRoute，实现复杂	❌ 过度工程
C. 用 PopScope 拦截	改动最小，精准解决问题	需要理解 PopScope 机制	✅ 采用

实现方案

使用 Flutter 3.x 的 PopScope 组件包裹 Overlay 内容：

@override
Widget build(BuildContext context) {
  return PopScope(
    canPop: false,  // 阻止默认的 pop 行为
    onPopInvokedWithResult: (didPop, result) {
      if (!didPop) {
        _dismiss();  // 自定义处理：关闭菜单
      }
    },
    child: Material(
      color: Colors.transparent,
      child: Stack(
        children: [
          // 原有的菜单内容...
        ],
      ),
    ),
  );
}

PopScope 机制解析

PopScope 是 Flutter 3.12 引入的新组件，用于控制返回导航行为：

canPop = false: 阻止 Navigator 的默认 pop 操作
onPopInvokedWithResult: 在 pop 请求发生时回调
didPop 参数: 表示是否已执行 pop（false 表示被我们拦截了）

这样，当我按返回键时：

Flutter 框架检测到 PopScope
因为 canPop = false，不执行默认 pop
触发 onPopInvokedWithResult 回调
我们在回调中调用 _dismiss() 关闭菜单

修改的文件

client/lib/ui/widgets/chat/context_menu.dart

3.2 音频播放器订阅泄漏

问题现象

在聊天页面播放语音消息时，如果连续播放多条语音，会产生内存泄漏，且可能出现多次回调导致的状态异常。

根因分析

查看 chat_page.dart 中的语音播放逻辑：

Future<void> _playVoice(SendMessage message, String localPath) async {
  // ...
  _audioPlayer.play();
 
  // 问题：每次播放都创建新的订阅，但从不取消旧订阅
  _audioPlayer.playerStateStream.listen((state) {
    if (state.processingState == ProcessingState.completed) {
      if (mounted) setState(() => _playingMessageId = null);
    }
  });
}

问题分析：

订阅累积: 每次调用 _playVoice 都会创建一个新的 StreamSubscription
永不取消: 旧的订阅没有被取消，会一直存活
内存泄漏: 订阅持有对 State 的引用，阻止垃圾回收
多次回调: 多个订阅同时存在，播放完成时会触发多次 setState

问题危害程度

这是一个 高严重度 问题：

我每播放一次语音，就增加一个订阅
长时间使用后，可能有数十甚至上百个订阅累积
内存占用持续增长
可能导致应用变慢或崩溃

实现方案

添加订阅变量：在类级别保存订阅引用

class _ChatPageState extends State<ChatPage>
    with WidgetsBindingObserver, TickerProviderStateMixin {
  // === 音频播放状态 ===
  final AudioPlayer _audioPlayer = AudioPlayer();
  String? _playingMessageId;
  StreamSubscription<PlayerState>? _playerStateSubscription;  // 新增

播放前取消旧订阅：

Future<void> _playVoice(SendMessage message, String localPath) async {
  // ...
  _audioPlayer.play();
 
  // 取消之前的订阅，避免内存泄漏
  await _playerStateSubscription?.cancel();
 
  // 创建新订阅
  _playerStateSubscription = _audioPlayer.playerStateStream.listen((state) {
    if (state.processingState == ProcessingState.completed) {
      if (mounted) setState(() => _playingMessageId = null);
    }
  });
}

dispose 时清理：

@override
void dispose() {
  // ...
  _audioRecorder.dispose();
  _playerStateSubscription?.cancel();  // 新增
  _audioPlayer.dispose();
  super.dispose();
}

需要导入的包

import 'dart:async';  // 提供 StreamSubscription 类型

修改的文件

client/lib/ui/chat_page.dart

3.3 后端文件名未校验非法字符

问题现象

上传文件时，如果文件名包含特殊字符（如 /\:*?"<>| 或 ..），可能导致：

Windows 平台文件操作失败
路径遍历攻击风险
元数据解析异常

风险分析

字符	风险
`/` `\`	路径分隔符，可能造成路径注入
`..`	路径遍历，可能访问上级目录
`:`	Windows 驱动器分隔符/NTFS 流标识
`*` `?`	通配符，可能被 shell 展开
`"` `<` `>` `\|`	Windows 禁止的文件名字符

虽然我们的系统并不直接用文件名作为存储路径（S3 使用 UUID），但文件名会：

在前端显示
存储在元数据中
可能在导出时使用

为了防御性编程，应该在入口处统一清理。

实现方案

创建统一清理函数（utils.go）：

// sanitizeFileName 清理文件名中的非法字符
// 移除 Windows 禁用字符: / \ : * ? " < > |
// 移除路径遍历字符: ..
func sanitizeFileName(name string) string {
	if name == "" {
		return name
	}
 
	// 禁用字符替换为下划线
	invalidChars := []string{"/", "\\", ":", "*", "?", "\"", "<", ">", "|"}
	result := name
	for _, c := range invalidChars {
		result = strings.ReplaceAll(result, c, "_")
	}
 
	// 移除路径遍历字符串
	for strings.Contains(result, "..") {
		result = strings.ReplaceAll(result, "..", "_")
	}
 
	// 移除前导/尾部空格和点（Windows 禁止）
	result = strings.TrimSpace(result)
	result = strings.TrimRight(result, ".")
 
	// 如果全部被清理掉了，返回默认名
	if result == "" {
		return "unnamed"
	}
 
	return result
}

应用点汇总：

文件	位置	说明
files.go	uploadFileByPath	文件路径上传
files.go	HTTP 上传处理	表单文件上传
send.go	创建 SendMessage	发送消息时
send.go	saveSendFileToNetdisk	保存到网盘时
orphan.go	adoptChunkedOrphan	收养分块游离文件
orphan.go	adoptLegacyOrphan	收养旧版游离文件

修改示例（files.go）：

// uploadFileByPath
fileName := req.FileName
if fileName == "" {
    fileName = filepath.Base(req.FilePath)
}
fileName = sanitizeFileName(fileName)  // 新增：清理非法字符

// HTTP 上传
fileName = sanitizeFileName(header.Filename)  // 新增：清理非法字符

设计决策

Q: 为什么用替换而不是拒绝？

A: 使用体验优先。大多数情况下，一般并不知道文件名中包含非法字符（可能是从其他系统复制来的）。直接拒绝会容易困惑。替换为下划线是一个合理的降级策略。

Q: 为什么在后端处理而不是前端？

A: 防御性编程原则。前端的校验可以被绕过（如直接调用 API），后端作为最后一道防线必须保证数据安全。

Q: 为什么不使用更复杂的白名单策略？

A: 保持简单。黑名单方式已经覆盖了主要风险字符，且对国际化友好（不会误伤 Unicode 字符）。

修改的文件

core/internal/api/utils.go - 新增 sanitizeFileName 函数
core/internal/api/files.go - 文件上传入口
core/internal/api/send.go - 发送消息入口
core/internal/api/orphan.go - 游离文件收养入口

四、取消的修复项

4.1 磁盘缓存无上限

问题描述：缩略图缓存没有容量限制，长期使用可能占用大量磁盘空间。

取消原因：

这是一个优化项，不是硬性 bug
可以通过系统设置清除应用缓存
实现 LRU 缓存需要较大改动，投入产出比低
当前阶段优先关注核心功能

后续计划：加入产品 backlog，后续版本考虑实现缓存管理策略。

4.2 Future.delayed 后 mounted 检查

问题描述：某些 Future.delayed 后的 setState 调用缺少 mounted 检查。

取消原因：

大部分延迟时间较短（100-300ms）
我在此期间离开页面的概率很低
即使发生，Flutter 框架会捕获异常，不会崩溃
属于低优先级优化

五、扫描方法论

5.1 使用的扫描手段

Web 搜索：搜索 Flutter/移动端常见陷阱和最佳实践
代码 grep：
- .listen( - 查找流订阅
- Timer.periodic - 查找定时器
- StreamSubscription - 查找订阅变量
- dispose() - 检查资源清理
代码审查：逐一检查关键入口点

5.2 扫描发现统计

扫描项	检查数量	发现问题
流订阅	12处	1处泄漏
定时器	3处	0处问题
文件名处理	6处入口	全部未校验
Overlay 返回键	1处	1处未处理

六、验证结果

6.1 静态分析

# Go 代码检查
go vet ./...
# 结果: 通过
 
# Flutter 代码检查
flutter analyze
# 结果: 3 个 info（非本次引入，是历史遗留）

6.2 运行测试

所有修改均为防御性增强，不影响现有功能行为：

聊天菜单正常弹出，返回键可关闭
语音播放功能正常
文件上传功能正常

七、经验总结

7.1 高危模式识别

通过本次扫描，识别出以下需要特别注意的代码模式：

裸订阅：stream.listen((e) {...}) 没有保存 subscription
Overlay 组件：直接使用 OverlayEntry 而不是 Dialog/Route
输入内容直接使用：文件名、路径等输入内容未经校验
资源创建无对应释放：在方法中创建资源但无处释放

7.2 防御性编程原则

入口校验：在接收外部数据的第一时间进行校验和清理
资源配对：每个资源创建都要有对应的释放
生命周期感知：异步操作完成后检查组件是否仍然存活
最小信任：不信任任何来自外部的数据

7.3 后续改进方向

考虑引入静态分析工具自动检测资源泄漏
建立代码审查 checklist
对关键路径添加单元测试
定期进行安全扫描

八、附录：修改代码汇总

A. context_menu.dart

// 修改前
@override
Widget build(BuildContext context) {
  return Material(
    color: Colors.transparent,
    child: Stack(...),
  );
}
 
// 修改后
@override
Widget build(BuildContext context) {
  return PopScope(
    canPop: false,
    onPopInvokedWithResult: (didPop, result) {
      if (!didPop) {
        _dismiss();
      }
    },
    child: Material(
      color: Colors.transparent,
      child: Stack(...),
    ),
  );
}

B. chat_page.dart

// 新增 import
import 'dart:async';
 
// 新增变量
StreamSubscription<PlayerState>? _playerStateSubscription;
 
// 修改 _playVoice
await _playerStateSubscription?.cancel();
_playerStateSubscription = _audioPlayer.playerStateStream.listen((state) {
  if (state.processingState == ProcessingState.completed) {
    if (mounted) setState(() => _playingMessageId = null);
  }
});
 
// 修改 dispose
_playerStateSubscription?.cancel();

C. utils.go

// 新增函数
func sanitizeFileName(name string) string {
    // ... 见上文完整实现
}

D. files.go, send.go, orphan.go

在所有接收文件名的入口点添加 sanitizeFileName() 调用。

扫描完成时间: 2026-01-01 21:00
修复验证: 通过
影响范围: 聊天菜单交互、语音播放、文件上传全链路

业务逻辑安全专项扫描

Table of Contents

一、背景与动机

1.1 问题溯源

1.2 专项扫描目标

二、发现的问题清单

问题总览

三、问题详细分析与修复

3.1 聊天菜单返回键不关闭

问题现象

根因分析

方案选型

实现方案

PopScope 机制解析

修改的文件

3.2 音频播放器订阅泄漏

问题现象

根因分析

问题危害程度

实现方案

需要导入的包

修改的文件

3.3 后端文件名未校验非法字符

问题现象

风险分析

实现方案

设计决策

修改的文件

四、取消的修复项

4.1 磁盘缓存无上限

4.2 Future.delayed 后 mounted 检查

五、扫描方法论

5.1 使用的扫描手段

5.2 扫描发现统计

六、验证结果

6.1 静态分析

6.2 运行测试

七、经验总结

7.1 高危模式识别

7.2 防御性编程原则

7.3 后续改进方向

八、附录：修改代码汇总

A. context_menu.dart

B. chat_page.dart

C. utils.go

D. files.go, send.go, orphan.go