Module Server

server 模块指南

server 是 Ktor + Netty 网关，把北航多个下游系统统一成 /api/v1/* 接口，不是传统本地数据库 CRUD 服务。

这一层负责什么

• CAS / SSO 登录编排、JWT 发行和 refresh token 轮换
• 服务端会话、Cookie、上游客户端实例和 Redis 持久化
• 对课表、考试、BYKC、签到、空教室、CGYY、评教、SPOC、YGDK 的统一适配
• 健康检查、指标、版本检查和启动时清理

文件清单

启动与运行时

文件	作用
Application.kt	入口，安装插件、注册路由、启动清理任务、关闭全局资源
ServerRuntimeConfig.kt	运行时配置读取，来自 .env / 环境变量
metrics/Observability.kt	业务操作观测与指标埋点辅助
metrics/LoginMetrics.kt	登录相关指标
metrics/GaugeBindings.kt	gauge 指标绑定
metrics/FunctionCounterBindings.kt	function counter 绑定
health/HealthSupport.kt	/health/live、/health/ready，含 Redis readiness
version/AppVersionService.kt	服务端版本来源和 release notes 拉取
version/AppVersionRoutes.kt	/api/v1/app/version 路由
utils/HttpClients.kt	上游 HttpClient 创建与代理 / TLS 设置
utils/UpstreamTimeouts.kt	上游 deadline 包装与超时异常
utils/JwtUtil.kt	JWT 签发、验证和辅助函数
utils/VpnCipher.kt	USE_VPN 开启时的 WebVPN URL 转写
utils/HeadlessImageSupport.kt	无头环境下的图片处理辅助

认证、会话与上游门户

文件	作用
auth/api/AuthRoutes.kt	登录、预加载、刷新、状态、注销等认证路由
auth/api/AuthService.kt	认证编排、会话恢复、状态核验
auth/api/Exceptions.kt	认证域异常
auth/api/UserFacingErrors.kt	统一错误码到用户可读文案的映射
auth/config/AuthConfig.kt	token TTL、会话 TTL、分布式锁预算校验
auth/jwt/JwtAuth.kt	JWT 验证与会话查找
auth/infra/RedisRuntime.kt	Redis 连接与共享运行时
auth/infra/DistributedLockManager.kt	登录 / 预登录分布式锁
auth/session/SessionManager.kt	会话生命周期、恢复、清理中心
auth/session/RedisSessionStore.kt	会话元数据持久化，含 generation / revision / portal_type
auth/session/RefreshTokenStore.kt	refresh token 哈希、存储、轮换、失效
auth/session/RedisCookieStorage.kt	上游 Cookie 持久化
auth/session/RedisCookieStorageFactory.kt	Cookie 存储工厂
auth/session/PreLoginPersistence.kt	预登录状态持久化
auth/upstream/CasParser.kt	CAS 表单、captcha、execution 等页面解析
auth/upstream/ByxtService.kt	上游学工门户会话 bootstrap
auth/portal/AcademicPortalSupport.kt	门户辅助函数
auth/portal/AcademicPortalWarmupCoordinator.kt	门户预热和会话提升协调

业务域

领域	文件
schedule	ScheduleRoutes.kt, ScheduleService.kt
exam	ExamRoutes.kt, ExamService.kt
bykc	BykcRoutes.kt, BykcService.kt, BykcClient.kt, BykcCrypto.kt, BykcModels.kt, BykcExceptions.kt
signin	SigninRoutes.kt, SigninService.kt, SigninClient.kt
classroom	ClassroomRoutes.kt, ClassroomClient.kt
cgyy	CgyyRoutes.kt, CgyyService.kt, CgyyZhjsClient.kt, CgyySigner.kt, CgyyCaptchaSolver.kt
spoc	SpocRoutes.kt, SpocService.kt, SpocClient.kt, SpocSupport.kt
evaluation	EvaluationRoutes.kt, EvaluationService.kt, EvaluationClient.kt
ygdk	YgdkRoutes.kt, YgdkService.kt, YgdkClient.kt, YgdkException.kt
user	UserRoutes.kt, UserService.kt

路由边界

• 匿名接口：/api/v1/auth/*
• JWT 保护接口：/api/v1/user/*、/api/v1/schedule/*、/api/v1/exam/*、/api/v1/bykc/*、/api/v1/signin/*、/api/v1/classroom/*、/api/v1/evaluation/*、/api/v1/spoc/*、/api/v1/cgyy/*、/api/v1/ygdk/*
• 运维接口：/health/*、/metrics
• 版本接口：/api/v1/app/version

认证和会话模型

• 认证不是纯无状态 JWT；服务端还需要维护每个用户的上游会话、Cookie 和客户端实例
• SessionManager 是预登录会话、正式会话提升、access token 到会话映射、TTL 管理、恢复和清理的中心
• Redis 中会保存会话元数据、refresh token 和 Cookie，彼此独立但互相关联
• AuthConfig 会在启动时校验分布式锁 TTL，必须覆盖登录和预登录超时预算并额外留出安全余量

上游调用约定

• 服务层负责编排上游请求，路由层只做参数校验和错误响应
• 上游调用统一用 withUpstreamDeadline(...) 包裹超时预算
• 不吞错误；领域异常要显式抛出并转换成统一错误响应
• 路由层用 observeBusinessOperation 记录业务指标

领域实现特点

• BykcCrypto.kt 负责 BYKC 的 RSA + AES 加密和请求封装
• SigninService.kt 会缓存 SigninClient，并对闲置实例做清理
• CgyyService.kt 依赖 CgyyZhjsClient、CgyySigner 和 CgyyCaptchaSolver，处理 SSO、签名和验证码重试
• SpocService.kt 以客户端缓存 + 上游 deadline 的方式批量拉取作业和详情
• EvaluationService.kt 负责评教任务获取和逐题提交编排
• YgdkService.kt 会在没有用户图片时生成占位图/默认图像路径

运维与启动

• Application.kt 安装 Metrics、CallLogging、CORS、JSON、JWT、ForwardedHeaders 等插件，并注册清理逻辑
• ServerRuntimeConfig.kt 从 .env / 环境变量读取运行时开关与 Redis 相关配置
• HealthSupport.kt 的 ready 检查会把 Redis 可用性纳入判断
• AppVersionService.kt 会从系统属性、环境变量、构建信息等位置解析当前服务端版本
• logs/server.log 是默认日志落点

新增受保护业务域的顺序

1. 先新增 XxxClient.kt / XxxService.kt
2. 再新增 XxxRoutes.kt
3. 在 Application.kt 的受保护路由块中挂载
4. 在 docs/API-Contracts.md 补上路径和请求/响应
5. 最后补测试