clickhouse

.env.docker.example

@@ -8,6 +8,9 @@ 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

.env.example

@@ -55,6 +55,18 @@ PerformanceReporting__Enabled=false
 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

README.md

@@ -415,6 +415,22 @@ Prometheus 兼容接口，令牌应仅具有查询权限。未启用、未配置
 指标名或 `service_name` 标签做了转换，可通过 `PerformanceReporting` 下对应的
 `*MetricName` 和 `ServiceNameLabel` 配置项适配，无需改前端。
 
+### ClickHouse 分析读模型
+
+ClickHouse 仅用于考勤、操作审计和成绩趋势的多维聚合，MySQL 仍是所有教务业务的唯一写入源。默认关闭；启用后，后台工作器以可重试的滚动窗口投影 MySQL 当前事实到 `ReplacingMergeTree` 表，重复投递不会改变读结果。
+
+生产环境请为分析库创建独立账号，并限制其只能访问 `ClickHouseAnalytics__Database`。推荐通过 HTTPS 或内网连接：
+
+```ini
+ClickHouseAnalytics__Enabled=true
+ClickHouseAnalytics__Endpoint=https://clickhouse.example.edu.cn:8443
+ClickHouseAnalytics__Database=jiaowu_analytics
+ClickHouseAnalytics__UserName=jiaowu_analytics
+ClickHouseAnalytics__Password=REPLACE_WITH_A_STRONG_PASSWORD
+```
+
+分析概览通过 `GET /api/clickhouse-analytics/overview` 提供；学院管理员只能读取本学院的考勤和成绩趋势，跨学院的操作审计仅对全校数据范围角色开放。ClickHouse 暂时不可用时，业务写入不会失败，工作器会在下一个周期重试。
+
 ### 后台任务与 RabbitMQ
 
 自动排课、课表发布和补考自动生成使用数据库 Outbox 保存任务消息。创建业务任务与