Table of Contents
部署指南
本地开发
开发环境固定使用 SQLite，首次运行会创建 src/Jiaowu.Api/data/jiaowu-dev.sqlite，只初始化系统角色和课程分类，不自动写入演示组织、人员、课程、业务记录或测试账号。
$env:SeedAdmin__UserName = 'admin'
$env:SeedAdmin__Password = '请替换为本机开发密码'
$env:SeedAdmin__DisplayName = '系统管理员'
dotnet run --project src/Jiaowu.Api
另开终端运行前端：
Set-Location web
npm install
npm run dev
访问 http://localhost:5173。首次管理员创建成功后，立即清除三个 SeedAdmin__* 环境变量。若不需要前端热更新，可先执行 npm --prefix web run build，再启动 API，访问 http://localhost:5255。
构建与发布
生产构建使用：
dotnet publish src/Jiaowu.Api -c Release -o .artifacts/publish
发布时会自动执行前端依赖安装和构建，并把静态文件写入发布目录 wwwroot。特殊 CI 流水线需要跳过此步骤时可传递 -p:BuildFrontendOnPublish=false。构建发布包不需要生产连接串、JWT 密钥或真实密码，且不应把这些秘密写入包中。
生产配置
将发布目录中的 .env.example 复制为 .env 并填入真实配置。程序读取可执行文件所在目录的 .env；也可用 JIAOWU_ENV_FILE 指定位置。真实进程环境变量优先级高于 .env。
核心配置包括：
| 配置组 | 用途 |
|---|---|
Database__*、ConnectionStrings__MySql |
MySQL 8.4 连接、超时和迁移行为。 |
Jwt__* |
签发者、受众、至少 32 随机字节的密钥及会话时长。 |
AllowedHosts、Cors__Origins__* |
公开域名和跨域来源白名单。 |
ConnectionStrings__Redis |
多实例缓存和共享短期状态，可选。 |
RabbitMq__*、BackgroundJobs__* |
多实例后台任务消息传输与并发。 |
OfficialDocuments__* |
凭证机构信息和最终 HTTPS 公网根地址。 |
Sso__* |
可选 Keycloak 单点登录。 |
Operations__* |
备份目录、MySQL 客户端路径和运维工具超时。 |
Plugins__* |
签名插件存储目录、包大小上限和受信任发布者公钥。 |
生产非 Development 环境只允许 MySQL。数据库使用 utf8mb4，连接建议启用 TLS 并校验证书。.env 不得提交到仓库、打进发布包或允许非服务账号读取；Linux/macOS 建议 chmod 600 .env，Windows 使用 ACL 限制服务账号和管理员。
签名插件的存储目录必须放在持久化卷，并仅允许服务账号读写；发布者公钥可读但不可由应用进程或普通运维账号随意替换，签名私钥不得部署到服务器。示例配置：
Plugins__StoragePath=/var/lib/jiaowu/plugins
Plugins__MaximumPackageMegabytes=20
Plugins__TrustedPublishers__0__Id=school-it
Plugins__TrustedPublishers__0__PublicKeyPath=/etc/jiaowu/plugin-publishers/school-it-public.pem
数据库迁移与升级
首次部署及每次升级服务端前，先停止旧实例，在目标环境执行：
Jiaowu.Api --migrate-only
确认迁移成功、备份有效和健康检查通过后再启动服务。不要用应用业务账号覆盖未知数据库，也不要把生产库文件复制到开发环境继续使用。仅对专用空演示库使用演示数据命令，并遵循命令的生产确认参数。
systemd（Linux）
仓库提供 deploy/systemd/jiaowu.service 示例。假定发布包位于 /opt/jiaowu，服务账号为无登录权限的 jiaowu。部署前创建服务账号、设置发布目录和备份目录权限，配置 /opt/jiaowu/.env，然后安装服务单元：
sudo install --owner=root --group=root --mode=0644 deploy/systemd/jiaowu.service /etc/systemd/system/jiaowu.service
sudo systemctl daemon-reload
sudo systemctl enable --now jiaowu.service
sudo systemctl status jiaowu.service --no-pager
curl --fail http://127.0.0.1:8080/health/ready
升级流程：停止服务 → 替换发布文件 → 执行 --migrate-only → 启动服务 → 检查日志、健康检查、插件装载、关键页面与后台任务。实时日志：journalctl --unit=jiaowu.service --follow。如插件中心存在待激活或待回滚版本，应在维护窗口重启后确认其状态和插件日志；不要仅凭上传成功判断插件已经运行。
Docker 与反向代理
仓库提供 Dockerfile 和 Compose 示例，可用于连接外部 MySQL 或启动一体化演示环境。容器运行时把 .env / 密钥通过安全的环境变量或密钥管理系统注入，数据卷挂载到持久化存储。反向代理必须正确传递 HTTPS 与主机信息，并使用最终公网 HTTPS 地址配置 CORS、SSO 回调和电子凭证二维码根地址。
上线验收清单
- MySQL 连接、迁移和备份恢复演练通过。
/health/ready可用，HTTPS 证书和反向代理正确。- 管理员可登录，验证码获取/刷新/一次性校验、学生自助激活和普通登录可用。
- CORS、JWT、SSO 回调与公开域名一致。
- 排课、选课、成绩、考试、凭证验真等关键链路按角色验证。
- 体测批次导入/计分/发布、学生本人查询和更正后重新发布按角色验证。
- 插件存储和公钥权限正确；内置插件停用不丢数据，签名插件暂存/激活/重启装载/回滚链路通过。
- Redis/RabbitMQ（如启用）连接、后台消费者和失败告警可用。
- Swagger 默认为关闭，仅在受控窗口按需开放。