生产环境

2026-07-25 20:21:42 +08:00
parent 1da6543a38
commit a576cc815d
30 changed files with 3325 additions and 4129 deletions
@@ -12,17 +12,14 @@

 ## 本地开发：热更新模式

-本地开发固定使用 SQLite。首次启动会自动创建 `src/Jiaowu.Api/data/jiaowu-dev.sqlite` 并写入演示组织数据。
-
-Development 环境还会按业务编码幂等补齐一套大规模测试数据：16 个常见学院或教学单位、52 个常见本科专业、每个专业 2 个 2026 级行政班、每班 35 名学生、每学院 8 名教师，以及覆盖公共必修、公共选修、专业必修、专业选修和实践教学的 150 余门课程。测试教师同时生成当前学期已审核通过的授课资格；重复启动不会重复累加数据，也不会覆盖已有记录。
-
-只执行数据库迁移和测试数据补齐、不启动 Web 服务时，可以运行：
-
-```powershell
-dotnet run --project src/Jiaowu.Api -- --seed-only
-```
+本地开发固定使用 SQLite。首次启动会自动创建空的
+`src/Jiaowu.Api/data/jiaowu-dev.sqlite`，只初始化系统角色和课程分类，不再写入
+演示组织、人员、课程、业务记录或内置测试账号。

 ```powershell
+$env:SeedAdmin__UserName = 'admin'
+$env:SeedAdmin__Password = '请替换为本机开发密码'
+$env:SeedAdmin__DisplayName = '系统管理员'
 dotnet run --project src/Jiaowu.Api
 ```

@@ -34,17 +31,8 @@ npm install
 npm run dev
 ```

-访问 `http://localhost:5173`。本地开发会自动创建以下分级权限账号：
-
-| 数据范围 | 账号 | 密码 |
-| --- | --- | --- |
-| 超级管理员 | `admin` | `Admin@123456` |
-| 校级教务 | `academic` | `Academic@123456` |
-| 学院教务 | `college` | `College@123456` |
-| 所带班级 | `counselor` | `Counselor@123456` |
-| 教师本人 | `teacher` | `Teacher@123456` |
-| 学生本人 | `student` | `Student@123456` |
-| 领导查看 | `leader` | `Leader@123456` |
+访问 `http://localhost:5173`。首次创建管理员后可以清除三个
+`SeedAdmin__*` 环境变量；后续账号和基础数据均通过管理界面维护。

 ## 本地开发：单服务模式

@@ -57,36 +45,73 @@ dotnet run --project src/Jiaowu.Api

 访问 `http://localhost:5255`。`/api` 和静态页面由同一个 ASP.NET Core 服务提供，`/base-data` 等前端路由刷新时也会回退到 `index.html`。

-## MySQL 部署
+## MySQL 8.4 生产部署

 非 Development 环境只允许使用 MySQL。`dotnet publish` 会自动执行 `npm ci` 和 `npm run build`，并将 Vue 静态文件放入发布目录的 `wwwroot`：

 ```powershell
 $env:ASPNETCORE_ENVIRONMENT = 'Production'
 $env:Database__Provider = 'MySql'
-$env:ConnectionStrings__MySql = 'Server=127.0.0.1;Port=3306;Database=jiaowu;User=YOUR_USER;Password=YOUR_PASSWORD;'
+$env:ConnectionStrings__MySql = 'Server=db.example.edu.cn;Port=3306;Database=jiaowu;User=YOUR_USER;Password=YOUR_PASSWORD;SslMode=VerifyFull;SslCa=C:\certs\mysql-ca.pem;'
 $env:Jwt__Key = '至少32字节的随机生产密钥'
+$env:AllowedHosts = 'jiaowu.example.edu.cn'
 dotnet publish src/Jiaowu.Api -c Release -o .artifacts/publish
-.artifacts/publish/Jiaowu.Api.exe
 ```

 如需在特殊流水线中跳过自动前端构建，可传入 `-p:BuildFrontendOnPublish=false`。

-生产环境不会创建默认管理员。首次部署前可以临时配置 `SeedAdmin__UserName`、`SeedAdmin__Password` 和 `SeedAdmin__DisplayName`，账号创建后移除这些配置。
+数据库应明确使用 `utf8mb4`；MySQL 8.4 的默认排序规则为
+`utf8mb4_0900_ai_ci`。新建数据库时可执行：
+
+```sql
+CREATE DATABASE `jiaowu`
+  CHARACTER SET utf8mb4
+  COLLATE utf8mb4_0900_ai_ci;
+```
+
+发布前使用具备 DDL 权限的迁移账号单独执行迁移：
+
+```powershell
+& '.artifacts\publish\Jiaowu.Api.exe' --migrate-only
+```
+
+迁移成功后，改用仅具备应用所需 DML 权限的运行账号并启动服务：
+
+```powershell
+& '.artifacts\publish\Jiaowu.Api.exe'
+```
+
+`Database:ApplyMigrationsOnStartup` 默认关闭。普通启动会检查待执行迁移并在架构落后时
+直接失败，避免多实例同时执行 DDL。只有明确接受启动期 DDL 风险的单实例部署才应将
+`Database__ApplyMigrationsOnStartup` 设为 `true`。
+
+生产环境不会创建默认管理员。首次部署可以临时配置
+`SeedAdmin__UserName`、`SeedAdmin__Password` 和 `SeedAdmin__DisplayName`，
+账号创建后立即移除这些配置。

 生产数据库使用 MySQL 专用 EF Core 迁移。部署前先恢复仓库工具并检查迁移：

 ```powershell
 dotnet tool restore
-dotnet ef migrations list --project src/Jiaowu.Api --startup-project src/Jiaowu.Api
+dotnet ef migrations list --no-connect --project src/Jiaowu.Api --startup-project src/Jiaowu.Api
 ```

-应用启动时会自动执行尚未应用的 MySQL 迁移。SQLite 只用于本地开发：新库通过 `EnsureCreated` 建立，已有开发库通过轻量、版本化的本地升级脚本补齐结构，不需要手动删除数据文件。SQLite 文件不能用于生产。
+不要使用当前提供程序生成的 `dotnet ef migrations script --idempotent` 作为 MySQL
+部署脚本；其条件块不是 MySQL 8.4 可直接执行的语法。应使用上述
+`--migrate-only` 入口，或在明确知道目标迁移状态时生成非幂等脚本并先做备份。
+MySQL 的 DDL 会隐式提交，迁移不能依赖外层事务整体回滚。
+
+SQLite 只用于本地开发：新库通过 `EnsureCreated` 建立，已有开发库通过轻量、版本化的
+本地升级脚本补齐结构，不需要手动删除数据文件。SQLite 文件不能用于生产。
+
+服务探针：
+
+- `/health/live`：只检查进程存活。
+- `/health`、`/health/ready`：实际检查数据库连接，失败时返回 HTTP 503。

 ## 验证

 ```powershell
 dotnet test Jiaowu.slnx
 npm --prefix web run build
-pwsh.exe -NoLogo -NoProfile -NonInteractive -File scripts/smoke-test.ps1
 ```