Firmiana
  • 简体中文

      • 架构概览

      Firmiana 遵循典型的 Micronaut 分层架构模式。

      分层图

      ┌──────────────────────────────────────────────────────┐
│                  HTTP 客户端                          │
│         (Element, Cinny, Element X, curl)             │
└──────────────────┬───────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────┐
│              控制器 (43+)                             │
│  Matrix Client-Server API 路由                        │
│  /_matrix/client/v3, /_matrix/federation/v1 等        │
├──────────────────────────────────────────────────────┤
│              安全层                                   │
│  MatrixAccessTokenValidator → Bearer Token 认证       │
│  CurrentUserService → 提取已认证用户                   │
├──────────────────────────────────────────────────────┤
│              服务层                                   │
│  RoomEventService, SyncNotifier, MatrixTokenService   │
│  FederationRequestSigningService 等                   │
├──────────────────────────────────────────────────────┤
│              仓储层                                   │
│  Micronaut Data JDBC 接口 (@JdbcRepository)           │
├──────────────────────────────────────────────────────┤
│              数据库                                   │
│  H2 内嵌（文件模式）+ Flyway 迁移                      │
└──────────────────────────────────────────────────────┘

      核心组件

      控制器

      控制器按功能组织在 com.firmiana.matrix.controller 下：

      包用途示例
      controller/顶层 Matrix 端点V3Controller, V3SyncController
      controller/auth/认证V3LoginController, V3RegisterController
      controller/room/房间操作V1RoomController, V3RoomController
      controller/user/用户资料/账户V3ProfileController
      controller/device/设备管理V3DeviceController
      controller/media/媒体上传/下载MediaController, V1MediaController
      federation/Server-Server APIFederationTransactionController

      服务

      服务包含业务逻辑。最重要的几个：

      服务职责行数
      RoomEventService房间事件、成员关系、关系、撤回、联邦 EDU~1175
      SyncNotifier/sync 长轮询、流令牌、过滤器评估~800
      MatrixTokenService令牌生命周期（创建、验证、刷新、撤销）~400
      FederationRequestSigningService请求签名、签名验证~230
      FederationDestinationQueue出站事务队列（含退避）~200
      FederationKeyCache远程服务器密钥缓存（含 TTL）~150

      仓储

      所有仓储都是 Micronaut Data JDBC 接口，使用 @JdbcRepository(dialect = Dialect.H2) 注解。遵循 Micronaut Data 命名约定进行查询推导。

      实体

      实体使用 Lombok @Data / @Getter / @Setter 注解，通过 @MappedEntity 映射到 H2 表。关键实体：User、Room、Event、RoomMember、UserAccessToken、MediaMetadata、EventRelations、DeviceInbox。

      请求生命周期

      1. HTTP 请求到达 Netty
      2. Micronaut 将请求路由到对应的控制器方法
      3. MatrixAccessTokenValidator 根据 user_access_tokens 表验证 Bearer Token
      4. CurrentUserService 将用户身份提取到请求上下文
      5. 控制器委托给服务层
      6. 服务执行业务逻辑，调用仓储
      7. 仓储通过 Micronaut Data JDBC 查询 H2
      8. 响应按照 Matrix 规范序列化为 JSON

      横切关注点

      • 错误处理：MatrixExceptionHandler 将异常转换为 Matrix 错误响应
      • 限流：RateLimiter 基于滑动窗口的按 IP 限流
      • 日志：Logback，控制台 + 滚动文件输出（logs/app.log）
      • 安全头：CSP、nosniff、DENY frame、HSTS
      • CORS：可配置的跨域策略（开发环境为宽松模式）