biss
712bd1a3a2
原生接口：context、dashboard、schools、school-organization、admins、exams 保持超级、校级、班级管理员的数据范围及权限隔离 其余管理写入、审批流和考务编排仍由 Node 转发 新增 ADMIN_NATIVE_READS_ENABLED=true 开关，并强制要求原生认证和共享 Redis
71 lines
3.3 KiB
Markdown
71 lines
3.3 KiB
Markdown
# ASP.NET Core 10 迁移
|
||
|
||
迁移采用兼容优先的渐进式方案：ASP.NET Core 作为统一入口，尚未迁移的 `/api/*` 请求暂时转发给运行在 `4174` 端口的 Node.js 服务。每完成一个功能域，就在 ASP.NET Core 中注册对应原生端点并停止转发该路径。
|
||
|
||
## 当前阶段
|
||
|
||
- [x] ASP.NET Core 10 解决方案与分层项目
|
||
- [x] 原前端静态资源无修改托管
|
||
- [x] 旧 API 兼容转发，包含 Cookie、请求体、文件下载和状态码
|
||
- [x] 存活与迁移就绪检查
|
||
- [x] 公开首页与已发布通知（原生 SQLite / MySQL 读取）
|
||
- [x] 招生公示与 HMAC 文书验真公开接口
|
||
- [x] 登录、自主注册、Session 与 TOTP（兼容开关默认关闭）
|
||
- [x] 考生业务
|
||
- [ ] 管理后台、审批流和考务编排（第一批管理端只读接口已原生化）
|
||
- [x] 考生志愿填报与招生录取查询
|
||
- [ ] Excel、文书和缓存
|
||
- [ ] 容器入口切换及 Node.js 后端移除
|
||
|
||
## 本地运行
|
||
|
||
先在一个终端运行旧 API：
|
||
|
||
```powershell
|
||
$env:PORT = '4174'
|
||
npm start
|
||
```
|
||
|
||
再在另一个终端运行 ASP.NET Core 入口：
|
||
|
||
```powershell
|
||
dotnet run --project .\src\Eis.Web\Eis.Web.csproj
|
||
```
|
||
|
||
浏览器仍访问 <http://127.0.0.1:4173>。
|
||
|
||
- `GET /health/live`：只检查 ASP.NET Core 宿主。
|
||
- `GET /health/migration`：检查迁移宿主和旧 API 转发链路。
|
||
|
||
可通过配置 `LegacyNode:Enabled=false` 禁用兼容转发；此时尚未迁移的 API 会返回 `501`。
|
||
|
||
认证域的 ASP.NET Core 原生实现已经覆盖 `/api/auth/*`，包括现有 PBKDF2 密码、`hz_session` Cookie、登录挑战、TOTP、防重放、恢复码和自主注册。迁移期间默认仍由 Node 处理认证；显式设置以下变量后切换到原生实现：
|
||
|
||
```powershell
|
||
$env:AUTH_NATIVE_ENABLED = 'true'
|
||
```
|
||
|
||
开发环境未配置 Redis 时可以使用进程内状态独立验证原生认证。生产环境以及仍需访问 Node 受保护接口的联调环境必须配置 `REDIS_URL` 或 `REDIS_SESSION_URL`；两个运行时会复用相同逻辑库和 `exam-information:auth` 键前缀，从而共享登录会话。`GET /health/migration` 会报告 `authentication.nativeEnabled`、状态后端和跨运行时会话共享能力。
|
||
|
||
考生域全部端点（首页、通知、个人资料读取与提交、可报名考试、我的报名读取与提交、成绩与总分排名、成绩单防伪码、成绩复议、准考证下载、志愿填报与录取查询）可通过以下开关原生运行；该开关必须与原生认证及共享 Redis 同时启用：
|
||
|
||
```powershell
|
||
$env:AUTH_NATIVE_ENABLED = 'true'
|
||
$env:CANDIDATE_NATIVE_ENABLED = 'true'
|
||
```
|
||
|
||
管理后台第一批只读接口（管理上下文、仪表盘、学校、学校组织、管理员和考试列表）已经原生化，并保留超级、校级、班级管理员的权限与数据作用域。其余管理端写入、审批流和考务编排接口仍转发给 Node，因此该开关同样要求原生认证和共享 Redis：
|
||
|
||
```powershell
|
||
$env:AUTH_NATIVE_ENABLED = 'true'
|
||
$env:ADMIN_NATIVE_READS_ENABLED = 'true'
|
||
```
|
||
|
||
`GET /health/migration` 的 `administration.nativeReadsEnabled` 和 `administration.routes` 会报告这一批端点是否已切换。
|
||
|
||
完整的宿主、静态资源、JSON 转发和 Session Cookie 冒烟测试：
|
||
|
||
```powershell
|
||
pwsh.exe -NoLogo -NoProfile -NonInteractive -File .\scripts\smoke-dotnet-migration.ps1
|
||
```
|