Merge branch 'master' into codex/shiyan

# Conflicts:
#	web/package-lock.json

.env.example

@@ -36,6 +36,24 @@ Cache__AnalyticsExpirationMinutes=3
 Cache__AnalyticsLocalExpirationSeconds=30
 Cache__MaximumPayloadKilobytes=2048
 
+# OpenTelemetry 默认收集 HTTP、运行时和数据库指标；配置 OTLP 地址后才会外发。
+Observability__Enabled=true
+Observability__ServiceName=jiaowu-api
+Observability__SlowQueryThresholdMilliseconds=500
+# 默认不记录完整 SQL，避免日志或追踪系统接触业务数据。
+Observability__IncludeSqlText=false
+Observability__MaximumSqlTextLength=2000
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.edu.cn:4317
+# OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20REPLACE_WITH_TOKEN
+
+# 系统内“运维与审计 → 系统性能”从 Prometheus 只读查询汇总指标。
+PerformanceReporting__Enabled=false
+# PerformanceReporting__PrometheusBaseUrl=https://prometheus.example.edu.cn/
+# PerformanceReporting__BearerToken=REPLACE_WITH_READ_ONLY_TOKEN
+# PerformanceReporting__GrafanaBaseUrl=https://grafana.example.edu.cn/
+PerformanceReporting__CacheSeconds=30
+PerformanceReporting__TimeoutSeconds=10
+
 # 运维控制台备份目录必须位于持久化、仅服务账号可写的位置。
 Operations__BackupDirectory=/var/lib/jiaowu/backups
 Operations__BackupWarningHours=24
@@ -49,7 +67,26 @@ Operations__MySqlClientPath=mysql
 Jwt__Issuer=Jiaowu.Api
 Jwt__Audience=Jiaowu.Web
 Jwt__Key=REPLACE_WITH_AT_LEAST_32_RANDOM_BYTES
-Jwt__ExpireMinutes=60
+Jwt__AccessTokenMinutes=10
+Jwt__WebIdleMinutes=30
+Jwt__AppIdleMinutes=4320
+
+# Keycloak SSO（可选）。Authority 必须指向 realm，例如：
+# https://sso.example.edu.cn/realms/mingxu
+Sso__Enabled=false
+# Sso__DisplayName=学校统一身份认证
+# Sso__Authority=https://sso.example.edu.cn/realms/mingxu
+# Sso__ClientId=jiaowu-web
+# Sso__ClientSecret=REPLACE_WITH_KEYCLOAK_CLIENT_SECRET
+# Sso__UserNameClaim=preferred_username
+# Sso__RequireHttpsMetadata=true
+# 首次 SSO 登录优先绑定同名本地账号；用户名不同时由用户输入现有账号密码完成绑定。
+# 不会自动创建账号或授予角色。
+# Sso__LinkExistingUsersByUserName=true
+# 前后端同域部署时留空；开发或分离部署时填写前端公开根地址。
+# Sso__FrontendBaseUrl=https://jiaowu.example.edu.cn
+# 必须与 Keycloak 客户端的 Valid redirect URI 完全一致。
+# Sso__CallbackUrl=https://jiaowu.example.edu.cn/signin-keycloak
 
 AllowedHosts=jiaowu.example.edu.cn
 Cors__Origins__0=https://jiaowu.example.edu.cn

README.md

@@ -144,6 +144,50 @@ Kubernetes 或密钥管理系统仍可覆盖文件中的值。
 `chmod 600 .env`，Windows 应通过 ACL 只允许服务账号和管理员读取。连接串中的证书
 路径必须是运行服务器上的实际路径。
 
+### Keycloak 单点登录（可选）
+
+系统支持 Keycloak 的 OpenID Connect 授权码流程。Keycloak 只负责验证身份；账号是否
+启用、角色和学院数据范围仍以本系统 Identity 数据为准。首次 SSO 登录会用
+`preferred_username`（可通过 `Sso__UserNameClaim` 修改）优先匹配已有登录账号并记录
+外部账号绑定。如果 Keycloak 用户名与教务系统账号不同，认证后会进入账户绑定页，用户
+需要再输入一次现有教务系统账号和密码；验证成功后建立永久绑定并直接登录。绑定不会
+自动创建本地账号、修改人员档案或从 Keycloak 导入高权限角色。同一 Keycloak 身份不能
+绑定多个本地账号，同一本地账号也不能绑定多个 Keycloak 身份。原账号密码登录和学生
+自助激活入口不受影响。
+
+在 Keycloak 中创建 OpenID Connect 客户端，并至少配置：
+
+- Valid redirect URI：`https://jiaowu.example.edu.cn/signin-keycloak`
+- Valid post logout redirect URI：`https://jiaowu.example.edu.cn/*`（若后续启用 Keycloak 全局退出）
+- Standard flow：开启；Implicit flow：关闭；PKCE：`S256`
+
+然后在 `.env` 中配置：
+
+```dotenv
+Sso__Enabled=true
+Sso__DisplayName=学校统一身份认证
+Sso__Authority=https://sso.example.edu.cn/realms/mingxu
+Sso__ClientId=jiaowu-web
+Sso__ClientSecret=REPLACE_WITH_KEYCLOAK_CLIENT_SECRET
+Sso__UserNameClaim=preferred_username
+Sso__RequireHttpsMetadata=true
+Sso__LinkExistingUsersByUserName=true
+Sso__FrontendBaseUrl=https://jiaowu.example.edu.cn
+Sso__CallbackUrl=https://jiaowu.example.edu.cn/signin-keycloak
+```
+
+前后端同域时 `Sso__FrontendBaseUrl` 可以留空。本地 Vite 开发默认回到
+`http://localhost:5173`，Keycloak 测试客户端需同时允许
+`http://localhost:5255/signin-keycloak`。`Sso__CallbackUrl` 是应用实际发送给 Keycloak
+的 `redirect_uri`，必须与客户端的 Valid redirect URI 完全一致；建议生产环境始终显式
+配置它，避免反向代理导致 scheme 或 host 推导错误。个人账户页的“管理员配置参考”也会
+显示当前生效的完整回调地址。多实例部署应配置 Redis，以便任意实例都能兑换两分钟内
+有效、使用后即删除的 SSO 登录码及五分钟内有效的绑定意图。
+
+用户登录后可从页面右上角进入“个人账户”，主动绑定或解除 Keycloak 账号。主动绑定先
+使用当前 JWT 创建五分钟有效的一次性绑定意图，再跳转 Keycloak；回调只能绑定到发起该
+意图的本地账号。解绑需要再次验证本地密码，避免仅凭未锁屏的登录会话解除身份关联。
+
 ### Linux systemd 服务
 
 仓库提供 [`deploy/systemd/jiaowu.service`](deploy/systemd/jiaowu.service)，适用于
@@ -322,6 +366,55 @@ Redis 只作为可丢弃的查询缓存。连接失败时应用回源数据库
 `allkeys-lfu` 淘汰策略，不启用持久化。`compose.app.example.yml` 不创建 Redis；
 如需连接外部 Redis，在 `.env` 中配置上述连接串即可。
 
+### OpenTelemetry 与慢查询定位
+
+应用已接入 OpenTelemetry 的 ASP.NET Core、HttpClient、.NET Runtime 指标，并通过
+`Jiaowu.Api.Database` ActivitySource 和 Meter 记录 EF Core 数据库命令。配置
+`OTEL_EXPORTER_OTLP_ENDPOINT` 后才启动 OpenTelemetry SDK 并向 OTLP Collector 外发；
+未配置时不会创建无处消费的请求 Span，也不会尝试连接本地 Collector，结构化慢查询日志
+仍然有效。
+
+```text
+Observability__Enabled=true
+Observability__ServiceName=jiaowu-api
+Observability__SlowQueryThresholdMilliseconds=500
+OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.edu.cn:4317
+```
+
+数据库指标包括 `jiaowu.db.command.duration`、`jiaowu.db.command.slow` 和
+`jiaowu.db.command.failed`。为关键 EF 查询添加 `TagWith("模块.查询名")` 后，日志和
+追踪会直接显示该稳定名称；无标签查询只显示操作类型和 SQL 模板哈希。默认
+`Observability__IncludeSqlText=false`，不会把 SQL、参数值或连接串发送到日志和追踪
+系统。仅在受控诊断窗口内临时启用完整 SQL 模板，并限制 Collector 权限与保留时间。
+
+应用侧阈值用于关联接口、TraceId 和查询名称；生产 MySQL 还应由数据库管理员启用慢查询
+日志，并将 `long_query_time` 设为与应用阈值一致。先按查询哈希/标签汇总高频慢查询，再
+对脱敏后的 `SELECT` 在测试库或只读副本执行 `EXPLAIN ANALYZE`，根据实际扫描行数和循环
+次数决定是否补组合索引或改写投影。`EXPLAIN ANALYZE` 会真实执行语句，不能直接用于生产
+写操作。参考 [MySQL 慢查询日志](https://dev.mysql.com/doc/refman/8.0/en/slow-query-log.html)
+和 [MySQL 8.4 EXPLAIN](https://dev.mysql.com/doc/refman/8.4/en/explain.html)。
+
+OpenTelemetry Collector 将指标写入 Prometheus 后，超级管理员可直接在“组织与权限 →
+运维与审计 → 系统性能”查看请求量、5xx 比例、HTTP/数据库 P95、慢查询趋势，以及最慢
+接口和数据库查询排行。报表由 API 使用固定 PromQL 只读查询 Prometheus，浏览器不会
+接触 Prometheus 地址或令牌；结果默认缓存 30 秒。原始 Trace 和更长时间范围仍建议在
+Grafana 中下钻，配置其地址后页面会显示跳转入口。
+
+```text
+PerformanceReporting__Enabled=true
+PerformanceReporting__PrometheusBaseUrl=https://prometheus.example.edu.cn/
+PerformanceReporting__BearerToken=REPLACE_WITH_READ_ONLY_TOKEN
+PerformanceReporting__GrafanaBaseUrl=https://grafana.example.edu.cn/
+PerformanceReporting__CacheSeconds=30
+PerformanceReporting__TimeoutSeconds=10
+```
+
+`PrometheusBaseUrl` 必须指向可访问 `/api/v1/query` 和 `/api/v1/query_range` 的
+Prometheus 兼容接口，令牌应仅具有查询权限。未启用、未配置或指标源暂时不可用时，页面
+会显示明确的空状态，不会改查业务数据库或拖慢正常请求。若 Collector/Prometheus 对
+指标名或 `service_name` 标签做了转换，可通过 `PerformanceReporting` 下对应的
+`*MetricName` 和 `ServiceNameLabel` 配置项适配，无需改前端。
+
 ### 后台任务与 RabbitMQ
 
 自动排课、课表发布和补考自动生成使用数据库 Outbox 保存任务消息。创建业务任务与
@@ -368,9 +461,10 @@ Outbox 租约恢复改为按维护周期执行，避免积压发布时每条消
 
 ### 运维与审计控制台
 
-超级管理员可从“组织与权限 → 运维与审计”查询写操作日志、三类失败后台任务、数据库、
+超级管理员可从“组织与权限 → 运维与审计”查看系统性能，查询写操作日志、三类失败后台
-缓存与任务通道健康状态，并查看由 5xx、失败/重试任务、健康探针和备份时效汇总出的异常
+任务、数据库、缓存与任务通道健康状态，并查看由 5xx、失败/重试任务、健康探针和备份
-告警。查询接口和备份操作均在后端强制要求 `SuperAdmin`，不能只依赖前端菜单隐藏。
+时效汇总出的异常告警。查询接口和备份操作均在后端强制要求 `SuperAdmin`，不能只依赖
+前端菜单隐藏。
 
 SQLite 开发环境直接使用在线备份 API。MySQL 环境需要在服务器安装 `mysqldump` 与
 `mysql`（容器镜像已包含对应的 `mariadb-dump` 与 `mariadb` 客户端），并配置独立的

compose.example.yml

@@ -30,7 +30,9 @@ x-jiaowu-environment: &jiaowu-environment
   Jwt__Issuer: Jiaowu.Api
   Jwt__Audience: Jiaowu.Web
   Jwt__Key: "${JWT_KEY:?请在 .env.docker 中设置 JWT_KEY}"
-  Jwt__ExpireMinutes: "60"
+  Jwt__AccessTokenMinutes: "10"
+  Jwt__WebIdleMinutes: "30"
+  Jwt__AppIdleMinutes: "4320"
   AllowedHosts: "${ALLOWED_HOSTS:-localhost}"
   Cors__Origins__0: "${CORS_ORIGIN:-http://localhost:8080}"
   OfficialDocuments__PublicBaseUrl: "${OFFICIAL_DOCUMENTS_PUBLIC_BASE_URL:-http://localhost:8080}"