Table of Contents

快速开始

1. 准备开发环境
2. 创建本地配置
3. 安装前端依赖并构建
4. 恢复并启动后端
5. 前后端联调模式
6. 首次登录后的基础配置
7. Docker 快速启动
8. 最小验证

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

快速开始

本页用于在 Windows PowerShell 环境中快速启动完整开发环境。项目根目录以下均以仓库根目录为当前目录。

1. 准备开发环境

需要安装：

.NET 10 SDK。仓库 global.json 指定 10.0.302，允许使用同一特性带中的更高补丁版本。
Node.js 20.19 或更高版本，推荐 Node.js 24。
npm。
Git。
可选：Docker Desktop，用于容器方式运行。
可选：MySQL 8.4 和 Redis，用于验证生产拓扑。

检查版本：

dotnet --version
node --version
npm --version
git --version

2. 创建本地配置

复制环境变量模板：

Copy-Item -LiteralPath .\.env.example -Destination .\.env

默认模板使用：

Development 环境；
http://127.0.0.1:4173；
SQLite；
./data/exam.sqlite；
初始超级管理员 admin。

首次本地启动可直接使用模板。若数据库是空库，应用会自动创建 v20 结构、系统基础配置、默认审批流程和一个初始超级管理员。

开发环境默认账号取自 .env：

账号：INITIAL_ADMIN_USERNAME
密码：INITIAL_ADMIN_PASSWORD

模板中的密码只适合本地开发，部署前必须更换。

3. 安装前端依赖并构建

Set-Location .\src\Eis.Web\ClientApp
npm ci
npm run build
Set-Location ..\..\..

构建产物写入 src/Eis.Web/wwwroot/vue-app。该目录由 Vite 管理，不要直接编辑其中的 app.js 或 app.css。

4. 恢复并启动后端

dotnet restore .\Eis.slnx
dotnet run --project .\src\Eis.Web\Eis.Web.csproj

打开：

系统首页：http://127.0.0.1:4173
登录页：http://127.0.0.1:4173/auth/login
存活检查：http://127.0.0.1:4173/health/live
组件状态：http://127.0.0.1:4173/health/migration

/health/live 返回宿主是否存活；/health/migration 会展示原生模块、认证状态后端和缓存状态。

5. 前后端联调模式

后端继续运行在 4173。另开一个 PowerShell 终端：

Set-Location .\src\Eis.Web\ClientApp
npm run dev

访问 http://127.0.0.1:5173。Vite 会把以下路径代理到 ASP.NET Core：

/api
/health
/js

前端使用 Vue Router History 模式。直接刷新 /candidate/...、/admin/... 或 /admission/... 时，由 ASP.NET Core 的前端资源回退逻辑返回 SPA 入口。

6. 首次登录后的基础配置

推荐按以下顺序建立可用业务环境：

使用初始超级管理员登录。
在“账户安全”中修改管理员密码；需要时绑定 TOTP。
在“学校管理”中建立学校并标记生源校或招生校职责。
建立校级和班级管理员。
在“报名号规则”中确认号码段组合。
在“流程设计”中确认资料、报名、复议和档案变更审批步骤。
建立考试、科目、时间、费用和合格规则。
由校级管理员批量申领考生账号，或由超级管理员临时开启自主注册。

如果只需要查看完整样例流程，可使用数据库工具导入内置演示数据。该操作会改写目标数据库，请先阅读数据库与数据工具，不要未经确认直接对现有数据库执行。

7. Docker 快速启动

创建容器配置：

Copy-Item -LiteralPath .\.env.docker.example -Destination .\.env.docker

打开 .env.docker，至少替换：

TOTP_ENCRYPTION_KEY
DOCUMENT_VERIFICATION_SECRET
INITIAL_ADMIN_PASSWORD

三者应使用不同的安全随机值。随后运行：

docker compose up --build --detach
docker compose ps
docker compose logs --follow app

打开 http://127.0.0.1:4173。

停止但保留 SQLite 数据：

docker compose down

8. 最小验证

启动成功后至少完成：

dotnet test .\Eis.slnx

并在浏览器检查：

首页可加载；
/health/live 返回 healthy；
初始管理员可登录；
/admin/dashboard 可进入；
页面刷新不会出现 404；
data/exam.sqlite 已生成。

更完整的检查方式见测试与故障排查。