v2.4.2 patch3

校级管理员可查看全部实验项目与成绩单。
学院管理员仅可查看本学院开课，或由本学院教师承担/管理的实验课。
场次取消、参与学生查看也同步执行上述范围校验，避免通过场次 ID 越权。
增加覆盖：校级全量、学院自有课程、跨学院管理课程可见、无关学院课程不可见。

.env.docker.example

@@ -8,9 +8,19 @@ MYSQL_USER=jiaowu
 MYSQL_PASSWORD=
 MYSQL_ROOT_PASSWORD=
 
+CLICKHOUSE_USER=jiaowu_analytics
+CLICKHOUSE_PASSWORD=
+
+RABBITMQ_USER=jiaowu
+RABBITMQ_PASSWORD=
+BACKGROUND_JOB_AUTOMATIC_SCHEDULE_CONCURRENCY=1
+BACKGROUND_JOB_SCHEDULE_PUBLISH_CONCURRENCY=1
+BACKGROUND_JOB_MAKEUP_EXAM_AUTO_CONCURRENCY=1
+
 JWT_KEY=
 ALLOWED_HOSTS=localhost
 CORS_ORIGIN=http://localhost:8080
+OFFICIAL_DOCUMENTS_PUBLIC_BASE_URL=http://localhost:8080
 
 # 仅首次创建演示管理员时使用；演示数据成功写入后删除下面三行。
 SEED_ADMIN_USERNAME=demo-admin

.env.example

@@ -2,18 +2,125 @@
 ASPNETCORE_ENVIRONMENT=Production
 ASPNETCORE_URLS=http://0.0.0.0:8080
 
+# 反向代理必须在转发请求时设置 X-Forwarded-For 和 X-Forwarded-Proto。
+# 仅填写实际直接连接 API 的代理 IP；多个代理依次使用 __0、__1……。
+# 使用 Docker 时通常是宿主机/代理容器在 Docker 网络中的 IP，而非访客 IP。
+# 默认仅信任 127.0.0.1 和 ::1。
+# ReverseProxy__TrustedProxies__0=127.0.0.1
+# ReverseProxy__TrustedProxies__1=::1
+
 Database__Provider=MySql
 Database__ApplyMigrationsOnStartup=false
 Database__CommandTimeoutSeconds=30
 ConnectionStrings__MySql="Server=db.example.edu.cn;Port=3306;Database=jiaowu;User=APP_USER;Password=REPLACE_WITH_A_STRONG_PASSWORD;SslMode=VerifyFull;SslCa=/etc/jiaowu/mysql-ca.pem;"
+# 仅供备份与隔离恢复演练使用。该账号需要读取业务库，并仅能创建/删除
+# jiaowu_restore_drill_* 临时库；不要在此复用日常业务账号。
+# ConnectionStrings__OperationsMySql="Server=db.example.edu.cn;Port=3306;Database=jiaowu;User=OPS_USER;Password=REPLACE_WITH_A_STRONG_PASSWORD;SslMode=VerifyFull;SslCa=/etc/jiaowu/mysql-ca.pem;"
+# Redis 是可选加速器；留空时应用仅使用进程内缓存。
+# ConnectionStrings__Redis="redis.example.edu.cn:6380,user=jiaowu,password=REPLACE_WITH_A_STRONG_PASSWORD,ssl=true,abortConnect=false"
+
+# 单机可继续使用 InMemory；多实例生产部署建议启用 RabbitMQ。
+BackgroundJobs__Transport=InMemory
+BackgroundJobs__AutomaticScheduleConcurrency=1
+BackgroundJobs__SchedulePublishConcurrency=1
+BackgroundJobs__MakeupExamAutoConcurrency=1
+BackgroundJobs__ExamArrangementConcurrency=1
+BackgroundJobs__CourseGradeStatisticsRefreshConcurrency=1
+# RabbitMq__HostName=rabbitmq.example.edu.cn
+# RabbitMq__Port=5671
+# RabbitMq__UserName=jiaowu
+# RabbitMq__Password=REPLACE_WITH_A_STRONG_PASSWORD
+# RabbitMq__VirtualHost=/jiaowu
+# RabbitMq__UseTls=true
+# RabbitMq__TlsServerName=rabbitmq.example.edu.cn
+
+Cache__Enabled=true
+Cache__KeyPrefix=jiaowu:v1
+Cache__ReferenceExpirationMinutes=30
+Cache__ReferenceLocalExpirationSeconds=120
+Cache__TimetableExpirationMinutes=10
+Cache__TimetableLocalExpirationSeconds=30
+Cache__AnalyticsExpirationMinutes=3
+Cache__AnalyticsLocalExpirationSeconds=30
+Cache__MaximumPayloadKilobytes=2048
+
+# 应用日志建立接口与慢 SQL 基线；日志系统可按 DurationMs、RequestId、QueryName 聚合。
+Observability__Enabled=true
+Observability__ServiceName=jiaowu-api
+Observability__LogAllApiRequests=true
+Observability__SlowRequestThresholdMilliseconds=1000
+Observability__SlowQueryThresholdMilliseconds=500
+# 默认不记录完整 SQL，避免日志或追踪系统接触业务数据。
+Observability__IncludeSqlText=false
+Observability__MaximumSqlTextLength=2000
+
+# 系统内“运维与审计 → 系统性能”从 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
+
+# ClickHouse 仅作为异步分析读模型，不参与教务事务写入。启用前请为应用创建
+# 仅能操作该分析库的独立账号，并通过 TLS 或受信任的内网访问。
+ClickHouseAnalytics__Enabled=false
+# ClickHouseAnalytics__Endpoint=https://clickhouse.example.edu.cn:8443
+# ClickHouseAnalytics__Database=jiaowu_analytics
+# ClickHouseAnalytics__UserName=jiaowu_analytics
+# ClickHouseAnalytics__Password=REPLACE_WITH_A_STRONG_PASSWORD
+ClickHouseAnalytics__CreateSchemaOnStartup=true
+ClickHouseAnalytics__SyncIntervalSeconds=60
+ClickHouseAnalytics__SourceLookbackDays=90
+ClickHouseAnalytics__BatchSize=1000
+
+# 运维控制台备份目录必须位于持久化、仅服务账号可写的位置。
+Operations__BackupDirectory=/var/lib/jiaowu/backups
+Operations__BackupWarningHours=24
+Operations__ToolTimeoutMinutes=30
+Operations__MySqlDumpPath=mysqldump
+Operations__MySqlClientPath=mysql
+# 按实际客户端补充 TLS 参数；Oracle MySQL 客户端示例：
+# Operations__MySqlAdditionalArguments__0=--ssl-mode=VERIFY_IDENTITY
+# Operations__MySqlAdditionalArguments__1=--ssl-ca=/etc/jiaowu/mysql-ca.pem
 
 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
+Cors__Origins__1=capacitor://localhost
+Cors__Origins__2=https://localhost
+Cors__Origins__3=http://localhost
+
+# 二维码使用的公网根地址；反向代理部署时必须填写最终 HTTPS 地址。
+OfficialDocuments__InstitutionName=明序大学
+OfficialDocuments__IssuingOffice=教务处
+OfficialDocuments__DocumentNumberPrefix=MXU
+OfficialDocuments__PublicBaseUrl=https://jiaowu.example.edu.cn
+# 默认使用系统中文字体；仅在自定义字体部署时填写绝对路径。
+# OfficialDocuments__FontPath=/usr/share/fonts/noto/NotoSansCJK-Regular.ttc
 
 # 仅首次创建管理员时临时取消注释，创建成功后立即删除。
 # SeedAdmin__UserName=admin

.gitea/workflows/publish.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Set up .NET
         uses: https://github.com/actions/setup-dotnet@v4
         with:
-          dotnet-version: "10.0.302"
+          dotnet-version: "10.0.400"
 
       - name: Set up Node.js
         uses: https://github.com/actions/setup-node@v4
@@ -46,6 +46,11 @@ jobs:
           npm ci
           npm run build
 
+      - name: Install Chinese PDF font for backend tests
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes fonts-noto-cjk
+
       - name: Run backend tests
         run: dotnet test Jiaowu.slnx --configuration Release
 
@@ -73,7 +78,7 @@ jobs:
           echo "version=$version" >> "$GITHUB_OUTPUT"
           echo "profile=$profile" >> "$GITHUB_OUTPUT"
 
-      - name: Build self-contained platform packages
+      - name: Build framework-dependent platform packages
         shell: bash
         run: |
           bash ./scripts/publish-platform-packages.sh \
@@ -155,7 +160,7 @@ jobs:
             - Windows x64：`.zip`
             - Linux x64 / ARM64：`.tar.gz`
             - `SHA256SUMS`：发布包校验值
-            - 自包含程序包无需预装 .NET 或 ASP.NET Core Runtime
+            - 二进制程序包不包含 .NET 或 ASP.NET Core Runtime；请先安装匹配版本的 ASP.NET Core Runtime
 
             Windows ARM64 与 macOS Intel / Apple Silicon 包可通过手动运行工作流并启用扩展平台生成。