feat(server,web,desktop,shared,deploy,docs): Linux 一键安装与 classhelper 运维命令、更新检查、图表去 echarts，版本统一 1.1.0

Linux 交付链（新增）
- deploy/install.sh：一键安装器（CLASSHELPER 大字 TUI、native/docker 双形态、向导选安装目录/
  端口/数据库/初始管理员密码）；识别 apt/yum/dnf 只补缺的依赖、建独立系统用户、下载内置 Node
  运行时（glibc < 2.28 的 CentOS 7 自动改用 unofficial-builds 的 glibc-217 构建）、幂等覆盖安装
  （保留 config.env 与 data/，不重置密钥）、全程写 /var/log/classhelper/install.log；
  `--check` 只体检（不需要 root）、`--yes` 无人值守、`--package` 支持内网离线分发。
- deploy/classhelper：运维命令 —— status / doctor / password / backup(list,restore,schedule) /
  upgrade / rollback / start|stop|restart|reload / logs / config / port / key rotate / uninstall /
  completion / help。特权操作一律校验 EUID，关键动作写 /var/log/classhelper/audit.log。
- deploy/tools/admin-cli.mjs：离线账号工具（改密、列账号、VACUUM INTO 一致性快照、哈希回滚），
  直连数据库 —— 服务停机也能救急，不需要先有一个能登录的账号。
- deploy/{classhelper.service,profile.d,logrotate.d,systemd}/ 模板 + Dockerfile.linux-package。
- scripts/dist-server.mjs 增加 --platform linux（根脚本 `pnpm dist:server:linux`），产物
  classhelper-server-linux-x64-<版本>.tar.gz + 同名 .sha256；新增 GitHub Actions workflow 在
  ubuntu runner 上构建并挂 Release（@libsql/linux-* 这类平台相关依赖只能在 Linux 上装）。
- docs/linux-deploy.md：安装 / 运维命令 / 升级回滚 / 备份恢复 / 排障 / 安全清单 /
  Ubuntu 22.04 与 Rocky 9 的验收清单。deploy/install-linux.sh 改为转发壳，不留两份实现。

三处必须知道的取舍（已写进 AGENTS.md §5 第 59 条）
- 配置真身在 /etc/classhelper/config.env，安装目录里的 .env 是指向它的软链：Web 端
  「数据库管理 → 一键切换」改写的是 <安装目录>/.env，而 systemd 注入的是同一份配置 ——
  两处不是同一个文件时，切换会「看起来成功、重启后又连回旧库」。classhelper doctor 有专门断言。
- 升级/回滚替换程序文件用「改名 + 就位」而不是 rm+cp：升级时正在运行的就是 bin/classhelper
  自己，直接删掉同名文件会让 bash 读到半个脚本。
- 交叉构建（在非 Linux 机器上打 Linux 包）会在包内写 .cross-built 标记、doctor 据此提示：
  已核对 @libsql/linux-x64-gnu 与 -musl 就位且无 win32 残留，但 prisma CLI 的原生 schema engine
  是宿主平台的，Web 端「数据库一键切换」那一步存疑；正式产物一律走 CI。

更新检查（此前只在工作区，本次一并提交）
- 服务端 modules/update：由服务端转发 GitHub Releases（Web 端 CSP 不允许直连），离线/限流/超时
  一律收敛成 ok:false + 一句人话，失败结果同样进缓存；?force=1 只对管理员生效（避免刷爆匿名限流）。
- 版本比较放 @classhelper/shared（compareVersions / isNewerVersion），三端共用；服务端版本号
  改由 lib/version.ts 读 package.json，不再在 app.ts 里写字面量。
- Web 端顶栏「检查更新」弹窗、客户端「关于」页的检查更新与诊断信息。

Web 端 / 客户端
- 成绩图表改用自包含的轻量组件（ScoreBarChart / ScoreLineChart），不再全量引入 echarts
  （原先 echarts 占桌面端渲染产物 1.12MB、Web 端 1.13MB）；柱状图是纯 HTML/CSS，折线图是
  viewBox SVG，均无 resize 监听。
- Element Plus 图标改为按需注册（两端各一份 icons.ts），新增 scripts/check-icons.mjs 静态门禁
  并挂进两端 build —— 漏注册的后果是界面静默渲染空白，只在控制台一条 warning。

版本号统一 1.1.0
- 5 份 package.json、deploy/package.runtime.json、.env.example 的 APP_VERSION、
  docker-compose 与两个 Dockerfile 的镜像标签、Linux 安装包名示例、README 首页版本；
- ClassIsland 插件 manifest.yml 与 BridgeService.PluginVersion 同步（verify:classisland-plugin
  有 manifest ↔ code 的一致性断言）；
- 刻意保持不变的是**历史性表述与举例**：docs/mysql.md 的「自 v1.0.0 起内置 MySQL 适配器」、
  shared/utils.ts 讲版本比较用的 1.0.0 / 1.0.0-fix、README 验收表里的实测记录。

packages/server/src/app.ts

@@ -6,6 +6,7 @@ import { env } from './config/env.js';
 import { pingDatabase } from './lib/db.js';
 import { sendOk } from './lib/http.js';
 import { logger } from './lib/logger.js';
+import { APP_VERSION } from './lib/version.js';
 import { mountWebAdmin, resolveWebDistDir } from './lib/web-static.js';
 import { errorHandler, notFoundHandler } from './middleware/error.js';
 import { apiRateLimiter, loginRateLimiter, requestLogger, securityHeaders } from './middleware/security.js';
@@ -37,7 +38,8 @@ async function healthHandler(_req: Request, res: Response): Promise<void> {
     res,
     {
       status: 'ok',
-      version: '1.0.0',
+      // 版本号取自 package.json（见 lib/version.ts）：更新检查要拿它跟 GitHub 上的 Release 比
+      version: APP_VERSION,
       env: env.nodeEnv,
       uptimeSeconds: Math.round(process.uptime()),
       database: {
@@ -68,7 +70,7 @@ function createRootHandler(webDistDir: string | null) {
         res,
         {
           service: 'class-helper-server',
-          version: '1.0.0',
+          version: APP_VERSION,
           environment: env.nodeEnv,
           apiPrefix: API_PREFIX,
           socket: '/socket.io',
@@ -115,7 +117,7 @@ function renderLandingPage(webAdminServed: boolean): string {
   <body>
     <div class="card">
       <h1>班级小助手 · 后端服务 <span class="ok">running</span></h1>
-      <p class="sub">版本 1.0.0 · 运行环境 ${env.nodeEnv} · 数据库 ${env.databaseProvider}</p>
+      <p class="sub">版本 ${APP_VERSION} · 运行环境 ${env.nodeEnv} · 数据库 ${env.databaseProvider}</p>
       <p class="sub">
         健康检查 <a href="${API_PREFIX}/health">${API_PREFIX}/health</a> ·
         存活 /healthz · 就绪 /readyz

packages/server/src/config/env.ts

@@ -156,7 +156,6 @@ export const env = {
           .map((item) => item.trim())
           .filter(Boolean),
   bcryptRounds: raw.BCRYPT_ROUNDS,
-  /** 新增学生时未指定密码时的初始密码 */
   /** 新建班级时的默认班级密码（班级账号登录） */
   defaultClassPassword: raw.DEFAULT_CLASS_PASSWORD,
   /** 新建/重置教师账号时的初始密码 */

packages/server/src/lib/version.ts

@@ -0,0 +1,41 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { env } from '../config/env.js';
+import { logger } from './logger.js';
+
+/**
+ * 服务端版本号。
+ *
+ * 为什么不再硬编码：`app.ts` 里原本写了两个字面量 `'1.0.0'`（健康检查 + 首页），
+ * 而版本号在仓库里已经有 5 份 package.json —— 更新检查要靠它判断"本机是不是旧版"，
+ * 再留一份手写副本就一定会漂移。
+ *
+ * 取哪一份（按顺序）：
+ * 1. `serverRoot/..` —— 打包形态下是运行时清单（`scripts/dist-server.mjs` 把**根**
+ *    package.json 的 version 写进 `staging/package.json`），也就是产物命名用的那个版本；
+ * 2. `serverRoot` —— 开发形态下是 `packages/server/package.json`。
+ *
+ * 与 `config/env.ts` 加载 `.env` 的双候选写法同一思路：不依赖启动时的 cwd。
+ */
+function readVersion(): string {
+  const candidates = [
+    path.resolve(env.serverRoot, '..', 'package.json'),
+    path.resolve(env.serverRoot, 'package.json'),
+  ];
+
+  for (const file of candidates) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8')) as { version?: unknown };
+      if (typeof parsed.version === 'string' && parsed.version.trim()) {
+        return parsed.version.trim();
+      }
+    } catch {
+      // 换下一个候选
+    }
+  }
+
+  logger.warn(`未能从 package.json 读到版本号（候选：${candidates.join('、')}），暂时按 0.0.0 处理`);
+  return '0.0.0';
+}
+
+export const APP_VERSION = readVersion();

packages/server/src/lib/web-static.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import express, { type Express, type RequestHandler } from 'express';
+import express, { type Express } from 'express';
 import { env } from '../config/env.js';
 import { logger } from './logger.js';
 
@@ -100,9 +100,3 @@ export function mountWebAdmin(app: Express): string | null {
   logger.info(`Web 管理端已挂载：${distDir}`);
   return distDir;
 }
-
-/** 静态资源请求判断（用于日志降噪等场景） */
-export const staticAssetMatcher: RequestHandler = (req, _res, next) => {
-  req.headers['x-classhelper-static'] = req.path.startsWith('/assets/') ? '1' : '0';
-  next();
-};

packages/server/src/middleware/security.ts

@@ -85,11 +85,20 @@ export function loginRateLimiter(): RequestHandler {
   });
 }
 
-/** 请求耗时日志（生产 info，开发 debug） */
+/**
+ * 请求耗时日志（生产 info，开发 debug）。
+ *
+ * 静态构建产物（`/assets/*`，带内容哈希、长缓存）**成功的请求不打点**：
+ * Web 管理端首屏一次就有十几个资源请求，逐条刷 info 会把真正有用的接口日志淹掉，
+ * 而且每条都要走一次 stdout 写入。失败的静态请求（404 / 500）照常记录 ——
+ * 那种情况恰恰是最需要看见的（产物缺失、路径不对）。
+ */
 export function requestLogger(): RequestHandler {
   return (req, res, next) => {
+    const isStaticAsset = req.path.startsWith('/assets/');
     const startedAt = process.hrtime.bigint();
     res.on('finish', () => {
+      if (isStaticAsset && res.statusCode < 400) return;
       const durationMs = Number(process.hrtime.bigint() - startedAt) / 1_000_000;
       const message = `${req.method} ${req.originalUrl} ${res.statusCode} ${durationMs.toFixed(1)}ms`;
       if (res.statusCode >= 500) logger.error(message);

packages/server/src/modules/registry.ts

@@ -12,6 +12,7 @@ import { notificationsModule } from './notifications/notifications.module.js';
 import { schedulesModule } from './schedules/schedules.module.js';
 import { studentsModule } from './students/students.module.js';
 import { teachersModule } from './teachers/teachers.module.js';
+import { updateModule } from './update/update.module.js';
 import type { ApiModule } from './module.types.js';
 
 /**
@@ -36,4 +37,5 @@ export const apiModules: ApiModule[] = [
   teachersModule,
   dashboardModule,
   databaseModule,
+  updateModule,
 ].filter((module) => module.enabled !== false);

packages/server/src/modules/update/update.module.ts

@@ -0,0 +1,32 @@
+import { Router } from 'express';
+import { sendOk } from '../../lib/http.js';
+import { authenticate, getAuthUser } from '../../middleware/auth.js';
+import { defineModule } from '../module.types.js';
+import * as updateService from './update.service.js';
+
+const router = Router();
+router.use(authenticate());
+
+/**
+ * GET /api/update/check?force=1 - 检查 GitHub 上有没有比本机新的版本
+ *
+ * 为什么 Web 管理端不直连 GitHub：浏览器的请求受服务端下发的 CSP 约束，
+ * `connect-src` 只放行 `'self'` 与 WebSocket（见 `middleware/security.ts`），
+ * 直连 `api.github.com` 会被浏览器拦掉。走服务端转发还顺带让所有管理员共享同一份缓存。
+ *
+ * 桌面客户端不受这条约束（它由主进程直连），但两边拿到的 `UpdateInfo` 结构是一致的。
+ *
+ * 权限：任何已登录用户都能查（信息本身来自公开仓库）。`force=1` 绕过服务端缓存，
+ * 但**只有管理员生效** —— 否则任意登录用户都能靠刷这个参数把匿名限流打满。
+ */
+router.get('/check', async (req, res) => {
+  const user = getAuthUser(req);
+  const force = req.query.force === '1' && user.role === 'ADMIN';
+  sendOk(res, await updateService.checkForUpdates({ force }), '更新检查完成');
+});
+
+export const updateModule = defineModule({
+  name: 'update',
+  basePath: '/update',
+  router,
+});

packages/server/src/modules/update/update.service.ts

@@ -0,0 +1,152 @@
+import {
+  GITHUB_RELEASES_LATEST_API,
+  GITHUB_RELEASES_PAGE,
+  UPDATE_CHECK_CACHE_TTL_MS,
+  UPDATE_CHECK_TIMEOUT_MS,
+  UPDATE_CHECK_USER_AGENT,
+  isNewerVersion,
+  normalizeVersion,
+  type UpdateAssetDto,
+  type UpdateInfo,
+} from '@classhelper/shared';
+import { logger } from '../../lib/logger.js';
+import { APP_VERSION } from '../../lib/version.js';
+
+/**
+ * 更新检查：问 GitHub 上最新的 Release 是不是比本机新。
+ *
+ * 三个设计约束：
+ * 1. **失败是常态，不是异常**：学校的服务器常常在只有内网的机房网络里，
+ *    因此离线 / 限流 / 超时一律收敛成 `ok:false` + 一句人话，绝不抛给路由层（否则管理员看到的会是 500）。
+ * 2. **必须带 User-Agent**：GitHub API 对没有 UA 的请求直接 403。
+ * 3. **必须有缓存**：匿名调用限流是 60 次/小时/IP，而 Web 管理端每次打开弹窗都会问一次。
+ *
+ * 这里用 Node 内置的 `fetch`（Node 20+ / Electron 同源），不引入任何 HTTP 依赖 ——
+ * 这也是本服务端**唯一**的出网请求。
+ */
+
+/** GitHub Releases API 里我们真正用到的字段（其余忽略，避免把整个响应建模一遍） */
+interface GithubReleasePayload {
+  tag_name?: unknown;
+  name?: unknown;
+  published_at?: unknown;
+  body?: unknown;
+  html_url?: unknown;
+  assets?: unknown;
+}
+
+let cache: { at: number; info: UpdateInfo } | null = null;
+
+/** 失败的统一出口：结构完整，界面不必做 null 判断 */
+function failure(error: string): UpdateInfo {
+  return {
+    ok: false,
+    error,
+    currentVersion: APP_VERSION,
+    latestVersion: null,
+    hasUpdate: false,
+    releaseUrl: GITHUB_RELEASES_PAGE,
+    releaseName: null,
+    publishedAt: null,
+    notes: null,
+    assets: [],
+    checkedAt: new Date().toISOString(),
+  };
+}
+
+function toAssets(raw: unknown): UpdateAssetDto[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((item) => item as { name?: unknown; browser_download_url?: unknown; size?: unknown })
+    .filter(
+      (item): item is { name: string; browser_download_url: string; size?: unknown } =>
+        typeof item.name === 'string' && typeof item.browser_download_url === 'string',
+    )
+    .map((item) => ({
+      name: item.name,
+      downloadUrl: item.browser_download_url,
+      size: typeof item.size === 'number' && Number.isFinite(item.size) ? item.size : 0,
+    }));
+}
+
+function toInfo(payload: GithubReleasePayload): UpdateInfo {
+  const latestVersion = normalizeVersion(typeof payload.tag_name === 'string' ? payload.tag_name : '');
+  // 拿不到版本号就当"查不到"，不要伪造一个 latestVersion 出来
+  if (!latestVersion) {
+    logger.warn('更新检查：GitHub 返回的 Release 里没有可识别的 tag_name');
+    return failure('GitHub 返回的版本号无法识别');
+  }
+
+  return {
+    ok: true,
+    error: null,
+    currentVersion: APP_VERSION,
+    latestVersion,
+    hasUpdate: isNewerVersion(APP_VERSION, latestVersion),
+    // 优先用 Release 自己的 html_url，拿不到才回落到列表页
+    releaseUrl:
+      typeof payload.html_url === 'string' && payload.html_url ? payload.html_url : GITHUB_RELEASES_PAGE,
+    releaseName: typeof payload.name === 'string' ? payload.name : null,
+    publishedAt: typeof payload.published_at === 'string' ? payload.published_at : null,
+    notes: typeof payload.body === 'string' ? payload.body : null,
+    assets: toAssets(payload.assets),
+    checkedAt: new Date().toISOString(),
+  };
+}
+
+/** 把各种失败翻译成一句管理员能看懂的话 */
+function describeFailure(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  if (error instanceof Error && error.name === 'TimeoutError') {
+    return `连接 GitHub 超时（${UPDATE_CHECK_TIMEOUT_MS / 1000} 秒），本机可能没有外网`;
+  }
+  if (/fetch failed|ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT|certificate/i.test(message)) {
+    return '无法连接 GitHub，本机可能没有外网';
+  }
+  return `检查更新失败：${message}`;
+}
+
+/**
+ * 检查更新（结果带缓存）。
+ *
+ * @param options.force 绕过缓存（由路由层限定为管理员才能生效）
+ */
+export async function checkForUpdates(options: { force?: boolean } = {}): Promise<UpdateInfo> {
+  const now = Date.now();
+  if (!options.force && cache && now - cache.at < UPDATE_CHECK_CACHE_TTL_MS) {
+    return cache.info;
+  }
+
+  let info: UpdateInfo;
+  try {
+    const response = await fetch(GITHUB_RELEASES_LATEST_API, {
+      headers: {
+        'User-Agent': UPDATE_CHECK_USER_AGENT,
+        Accept: 'application/vnd.github+json',
+      },
+      signal: AbortSignal.timeout(UPDATE_CHECK_TIMEOUT_MS),
+    });
+
+    if (!response.ok) {
+      // 403 / 429 基本都是匿名限流（60 次/小时/IP）—— 给出可操作的提示而不是原始状态码
+      info =
+        response.status === 403 || response.status === 429
+          ? failure('GitHub 暂时拒绝了请求（匿名查询次数过多），请过一会儿再试')
+          : failure(`GitHub 返回 HTTP ${response.status}`);
+      logger.warn(`更新检查失败：HTTP ${response.status}（本机版本 ${APP_VERSION}）`);
+    } else {
+      info = toInfo((await response.json()) as GithubReleasePayload);
+      logger.info(
+        `更新检查：本机 ${APP_VERSION} / 最新 ${info.latestVersion ?? '-'}` +
+          `${info.hasUpdate ? '（有新版本）' : '（已是最新）'}`,
+      );
+    }
+  } catch (error) {
+    info = failure(describeFailure(error));
+    logger.warn(`更新检查失败：${info.error}（本机版本 ${APP_VERSION}）`);
+  }
+
+  // 失败结果**也缓存**：否则机房断网时，管理员每点一次按钮都要白等一个超时。
+  cache = { at: now, info };
+  return info;
+}