Module Server

server 模块指南

server 是 Ktor + Netty 网关，把北航多个下游系统统一成 /api/v1/* 接口。它不是传统本地数据库 CRUD 服务；核心职责是认证编排、上游会话托管、业务适配、错误归一和观测。

这一层负责什么

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

启动与路由注册

Application.kt 当前注册顺序：

1. 初始化 PrometheusMeterRegistry、登录指标、全局版本服务。
2. 安装 Metrics、CallLogging、CORS、ContentNegotiation、JWT、ForwardedHeaders 等插件。
3. 校验认证分布式锁预算。
4. 初始化 SessionManager、BYKC/CGYY/SPOC/Judge/YGDK 等全局服务。
5. 启动 15 秒 Redis readiness 轮询和 5 分钟清理任务。
6. 注册 /metrics、/health/*、/api/v1/app/version 和认证相关路由。
7. 在 authenticate(JwtAuth.JWT_AUTH) 中注册 user/schedule/bykc/exam/grade/signin/classroom/cgyy/evaluation/spoc/judge/ygdk。
8. 注册根路径 /。

关闭时会取消清理任务并释放全局资源：SessionManager、Redis runtime、refresh token store、分布式锁、CGYY/SPOC/Judge/YGDK 缓存、观测指标等。

文件清单

启动与运行时

文件	作用
Application.kt	入口，安装插件、注册路由、启动 readiness/cleanup、关闭全局资源
ServerRuntimeConfig.kt	运行时配置读取，支持 .env 和系统环境变量；监听地址/端口例外见配置文档
metrics/Observability.kt	业务操作、上游请求、重试、fallback、清理和 readiness 指标
metrics/LoginMetrics.kt	登录相关指标
metrics/GaugeBindings.kt	gauge 指标绑定
metrics/FunctionCounterBindings.kt	function counter 绑定
health/HealthSupport.kt	/health/live、/health/ready，ready 会检查 Redis
version/AppVersionService.kt	服务端版本来源、GitHub 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	认证编排、会话恢复、状态核验、上游 SSO 交互
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	会话生命周期、恢复、清理、touch、失效中心
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
grade	GradeRoutes.kt, GradeService.kt
bykc	BykcRoutes.kt, BykcService.kt, BykcClient.kt, BykcCrypto.kt, BykcModels.kt, BykcExceptions.kt, BykcDebugConfig.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
judge	JudgeRoutes.kt, JudgeService.kt, JudgeClient.kt, JudgeSupport.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/preload、/api/v1/auth/login、/api/v1/auth/login-stats、/api/v1/auth/refresh、/api/v1/auth/captcha/{captchaId}、/api/v1/app/version
• 有效会话接口：/api/v1/auth/status、/api/v1/auth/logout
• JWT 保护接口：/api/v1/user/*、/api/v1/schedule/*、/api/v1/exam/*、/api/v1/grade/*、/api/v1/bykc/*、/api/v1/signin/*、/api/v1/classroom/*、/api/v1/evaluation/*、/api/v1/spoc/*、/api/v1/judge/*、/api/v1/cgyy/*、/api/v1/ygdk/*
• 运维接口：/health/*、/metrics、/

认证和会话模型

• 认证不是纯无状态 JWT；服务端还维护每个用户的上游会话、Cookie 和客户端实例。
• JwtAuth 验签后会用 SessionManager 以 read-only 方式确认服务端会话存在。
• 业务请求通过当前用户会话继续 touch 活跃时间，必要时标记上游认证失效。
• SessionManager 是预登录会话、正式会话提升、access token 到会话映射、TTL 管理、恢复和清理的中心。
• Redis 中会保存会话元数据、refresh token、Cookie 和预登录上下文，彼此独立但互相关联。
• RedisSessionStore 的会话元数据包含 generation、revision 和 portal_type，用于多节点恢复与版本推进。
• AuthConfig 会在启动时校验分布式锁 TTL，必须覆盖登录和预登录超时预算并额外留出 2 秒安全余量。

上游调用约定

• 服务层负责编排上游请求，路由层只做参数校验、会话提取、错误响应和指标记录。
• 上游调用统一用 withUpstreamDeadline(...) 包裹超时预算。
• 不吞错误；领域异常要显式抛出并转换成统一错误响应。
• 路由层用 observeBusinessOperation 记录业务指标。
• 如果上游认证失效，路由应调用对应 scope 的 markUnauthenticated()，让客户端得到明确的重新登录信号。

领域实现特点

• GradeService.kt 使用北航成绩接口，按 termCode 查询并返回 GradeData；错误统一映射为 grade_error。
• BykcCrypto.kt 负责 BYKC 的 RSA + AES 加密和请求封装；BykcDebugConfig.kt 可临时打开原始响应/解析日志。
• SigninService.kt 会缓存 SigninClient，并对闲置实例做清理。
• CgyyService.kt 依赖 CgyyZhjsClient、CgyySigner 和 CgyyCaptchaSolver，处理 SSO、签名、验证码重试和目的类型 fallback。
• SpocService.kt 以客户端缓存 + 上游 deadline 的方式拉取作业和详情。
• JudgeService.kt 和 JudgeClient.kt 先取课程/作业摘要，再按需取详情；不要把所有详情拉取放进初始列表请求。
• EvaluationService.kt 负责评教任务获取和逐题提交编排。
• YgdkService.kt 会在没有用户图片时生成占位图/默认图像路径。

观测与运维

• /health/live 只表示进程可响应。
• /health/ready 会检查 Redis；Redis 不可用返回 503。
• /metrics 暴露 Prometheus 文本。
• 重要指标包括 ubaa.business.operations、ubaa.upstream.requests、ubaa.retry.events、ubaa.fallback.events、ubaa.cleanup.removals、ubaa.readiness.check。
• 关键 gauge 包括 ubaa.sessions.active、ubaa.sessions.prelogin、ubaa.signin.cache、ubaa.bykc.cache、ubaa.cgyy.cache、ubaa.spoc.cache、ubaa.judge.cache、ubaa.ygdk.cache、ubaa.redis.ready。
• logs/server.log 是默认日志落点。

测试地图

常见 server 验证入口：

类型	示例
启动/指标/健康	ApplicationTest, ApplicationMetricsTest, HealthSupportTest
认证/会话	AuthRoutesTest, AuthServiceConcurrencyTest, AuthConfigTest, JwtTest, SessionManagerMetricsTest
业务路由	ScheduleRoutesTest, ExamRoutesTest, GradeRoutesTest, BykcRoutesTest, CgyyRoutesTest, SpocRoutesTest, JudgeRoutesTest, YgdkRoutesTest
上游客户端/服务	BykcClientTest, GradeServiceTest, CgyyServiceTest, SpocClientTest, JudgeClientTest, YgdkServiceTest
真实上游可选测试	JudgeRealIntegrationTest，需显式设置真实测试开关和凭据

新增受保护业务域的顺序

1. 新增或调整 shared/model/dto
2. 在 shared/api 增加接口、Relay backend 和必要的 Local backend
3. 在 server 新增 XxxClient.kt / XxxService.kt
4. 新增 XxxRoutes.kt
5. 在 Application.kt 的受保护路由块中挂载
6. 在 Application.kt 的清理和 gauge 中处理缓存型服务
7. 在 docs/API-Contracts.md 补路径、请求、响应和错误码
8. 补 route/service/shared/composeApp 测试