UBAA.Server 是 BUAASubnet/UBAA 后端的 Go 重写版本，目标是在不重写前端的前提下，用 Go、Fiber、FreeCache 和 SQLite 提供与原 Ktor 后端兼容的 API 行为。
它保留了现有 Compose Multiplatform 前端依赖的路由、DTO 字段名、鉴权方式和错误结构，同时把服务端会话、Cookie、缓存和上游请求逻辑迁移到 Go 实现中。
- 前端零改动：继续使用
/api/v1/...路由和Authorization: Bearer <token>鉴权。 - 单文件数据库：使用 SQLite 保存会话、刷新令牌、登录统计和上游 Cookie。
- 内存缓存：使用 FreeCache 缓存活跃会话，减少持久化读取。
- 兼容原行为：错误响应、JWT claims、默认端口和主要 JSON 字段保持兼容。
- 覆盖真实查询链路：课表、成绩、考试、图书馆、SPOC、博雅等接口均按前端契约暴露。
.
├── cmd/server/ # 服务入口
├── internal/app/ # Fiber app、指标和中间件装配
├── internal/auth/ # 登录、JWT、会话与鉴权
├── internal/features/ # 课表、成绩、图书馆等业务功能
├── internal/storage/ # SQLite 持久化
├── internal/upstream/ # 上游 HTTP 客户端和 WebVPN 适配
├── internal/dto/ # 前端兼容 DTO
└── docs/compatibility.md # 兼容性说明
cp .env.example .env
go run ./cmd/server默认监听地址与原后端一致：
SERVER_BIND_HOST=0.0.0.0
SERVER_PORT=5432
SQLITE_PATH=data/ubaa-server.db启动后检查服务状态：
curl http://127.0.0.1:5432/health/readygo build -trimpath -ldflags "-s -w" -o bin/ubaa-server ./cmd/server
./bin/ubaa-server发布构建可以把 Git 信息写入二进制；默认版本号已与 BUAASubnet/UBAA 当前主分支对齐为 1.7.3 / 26：
go build -trimpath \
-ldflags "-s -w \
-X github.com/BUAASubnet/UBAA.Server/internal/buildinfo.Commit=$(git rev-parse --short HEAD) \
-X github.com/BUAASubnet/UBAA.Server/internal/buildinfo.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-o bin/ubaa-server ./cmd/server| 模块 | 路由前缀 | 状态 |
|---|---|---|
| 鉴权与会话 | /api/v1/auth |
已实现 |
| 用户信息 | /api/v1/user |
已实现 |
| 课表查询 | /api/v1/schedule |
已实现 |
| 考试查询 | /api/v1/exam |
已实现 |
| 成绩查询 | /api/v1/grade |
已实现 |
| 空闲教室 | /api/v1/classroom |
已实现 |
| 博雅课程 | /api/v1/bykc |
已实现 |
| SPOC 作业 | /api/v1/spoc |
已实现 |
| Judge 作业 | /api/v1/judge |
已实现 |
| 评教 | /api/v1/evaluation |
已实现 |
| 图书馆座位 | /api/v1/libbook |
已实现 |
| 场馆预约 | /api/v1/cgyy |
已实现 |
| 阳光打卡 | /api/v1/ygdk |
已实现 |
| 签到 | /api/v1/signin |
已实现 |
| 健康检查 | /health/live, /health/ready |
已实现 |
| Prometheus 指标 | /metrics |
已实现 |
更多兼容性细节见 docs/compatibility.md。
UBAA.Server 启动时会读取进程环境变量，也会自动加载仓库根目录的 .env.example 同格式 .env 文件。本地开发建议先执行：
cp .env.example .env.env、SQLite 数据库、日志和 token 不应提交到仓库。
与原 BUAASubnet/UBAA 后端相比，Go 版保留了仍适用的 .env 能力：监听地址、更新地址、JWT、WebVPN、BYKC 调试、CORS、令牌/会话生命周期、认证超时和登录并发控制。原后端的 Redis 相关配置，如 REDIS_URI、REDIS_HEALTH_TIMEOUT_MS、SESSION_COOKIE_SYNC_INTERVAL_MS、AUTH_DISTRIBUTED_LOCK_*，在本仓库中不再使用；对应能力由 SQLite 持久化、FreeCache 和单进程登录并发阀门承担。
HTTP_PROXY / HTTPS_PROXY 仍可通过 Go 标准库的 http.ProxyFromEnvironment 生效，不需要写入专门配置项。
安装依赖并运行测试：
go mod tidy
go test ./...常用开发命令：
go run ./cmd/server
go test ./...
go test ./internal/features -run Test为了让 BUAASubnet/UBAA 中的桌面端和多平台前端无需重写，本服务遵循以下约定：
- 路由路径保持
/api/v1/...。 - JSON 字段名对齐原 shared Kotlin DTO。
- 鉴权方式保持
Authorization: Bearer <token>。 - JWT issuer/audience 与原后端保持一致。
- 常见错误码和错误响应结构保持一致。
- 默认端口保持
5432。
注意：课表、成绩、考试、图书馆、SPOC 等接口会访问 BUAA 上游系统。端到端耗时会受到学校网络、上游响应、登录态、限流和风控策略影响。
- 不要提交
.env、SQLite 数据库、日志、token 或 Cookie。 - 生产环境必须设置强
JWT_SECRET。 - 不要用错误账号密码反复尝试 SSO 登录，可能触发风控。
- 预约、签到、评教提交等写入接口不适合做压测。
- 压测只应覆盖查询接口，并设置合理的并发和 RPS 上限。
BUAASubnet/UBAA：原项目、前端和 Kotlin 后端。BUAASubnet/UBAA.Server：本仓库，Go 后端重写。- Go：本仓库主要开发语言。
- Fiber：HTTP Web 框架。
- FreeCache：内存缓存。
- SQLite：本地持久化数据库。
- Ktor：原后端使用的 Kotlin Web 框架。
本项目与上游 BUAASubnet/UBAA 保持同一项目体系。使用和分发前请确认上游仓库的许可证与合规要求。