摘要：本文记录了 WebMusic 项目在一天内的架构演进过程。通过引入多租户数据隔离、RBAC 权限控制及审计日志中间件，项目从一个个人使用的音乐播放器升级为具备企业级安全特性的私有云服务。

在 v2.7.0 版本的迭代中，我们主要关注系统的安全性、多用户隔离以及可维护性。以下是本次重构的核心技术点复盘。

1. 核心架构升级：多租户数据隔离 (Multi-Tenancy)

为了支持演示账号（Demo User）和普通多用户场景，仅仅在前端隐藏入口是远远不够的。我们对后端核心控制器进行了基于 UserId 的物理级隔离改造。

• 挑战：如何确保 Admin 用户配置的敏感 SMB 存储凭据不被其他用户扫描或访问？
• 方案：
  • 在 ScanSource 和 MediaFile 实体中引入 Ownership 概念。
  • 重构 MediaController 的查询逻辑，从早期的 Navigation Property 过滤升级为更严谨的 Where(m => allowedSourceIds.Contains(m.SourceId))，杜绝了通过 ID 遍历可能导致的数据越权。

2. 资产风控与权限控制 (RBAC)

随着项目集成了 Gemini AI 用于歌词生成和自动标签，API 调用成本成为需要考虑的因素。针对 Demo 账户甚至未来的普通订阅用户，必须严格限制其对高成本接口的访问。

我们实施了基于 JWT Claims 的角色权限控制（RBAC）：

• Token 升级：在 auth/login 颁发 Token 时，根据用户身份注入 ClaimTypes.Role (如 “Admin” 或 “User”)。
• 后端拦截：TagsController 和 LyricsController 全面通过 [Authorize(Roles = "Admin")] 属性进行保护。这比传统的在代码中判断 UserId == 1 更具扩展性和维护性。
• 前端适配：UI 层根据 isAdmin 状态自动禁用 AI 相关功能按钮，并提供 “Restricted Mode” 的视觉反馈，优化用户体验。

3. 可观测性：审计日志中间件 (Audit Logging)

为了增强系统的可维护性和安全性，我们引入了自定义的审计机制。

• 中间件实现：开发了 ApiLoggingMiddleware，拦截关键 API 请求。
• 记录维度：记录操作者身份（User）、请求路径、HTTP 方法、响应状态码及耗时。
• 降噪策略：针对 /stream (流媒体分片) 和 /cover (封面图片) 等高频且低敏感度的请求进行了过滤，确保日志文件聚焦于核心业务操作（如数据修改、用户管理）。

4. 完整的用户生命周期管理

为了闭环多用户功能，我们补全了用户管理模块。

• 新增 UsersController，提供用户列表查询、创建用户、删除用户及管理员重置密码接口。
• 前端新增 AdminPage，提供可视化的用户管理面板。

总结

通过这次重构，WebMusic 不仅在功能上得到了补全，更在架构的健壮性上迈出了重要一步。从简单的 CRUD 到包含权限、审计、隔离的完整系统，这一过程验证了现代 Web 开发技术栈（.NET 8 + React）的高效性。

本文档基于项目 Git Commit Log (v2.6.x - v2.7.0) 自动生成，由 Gemini 辅助整理。