feat: 生产化改造（服务端安装程序/PWA/Docker+HTTPS）并修复侧边栏点击无反应、SPA 静态托管 dotfiles 两个缺陷

- 修复 web-admin 与 desktop-client 侧边栏点击无反应：el-menu 的 index 是路径，不能当路由名使用
- 修复 Web 产物目录含点号目录（如 .cache）时 res.sendFile 因 dotfiles:ignore 返回 500
- 后端生产模式：静态托管 Web 端 + SPA 回退、helmet、限流（通用/登录）、trust proxy、
  /healthz 与 /readyz、请求耗时日志、生产环境变量强校验、首启动自动迁移与创建管理员、PID 文件
- Web 管理端 PWA：manifest + service worker + 图标，可在浏览器安装为应用
- 新增服务端 + Web 管理端 Windows 安装程序（内置 Node 运行时、启停与服务脚本、开机自启、卸载保留数据）
- 新增 Docker/Compose/Nginx 部署样例与 docs/production.md
- 新增 UI 回归测试：Web 端 Electron 驱动真实点击 7 项、客户端冒烟 11 项（含侧边栏点击与离线回退）

packages/server/src/app.ts

@@ -1,36 +1,93 @@
 import express, { type Express, type Request, type Response } from 'express';
+import compression from 'compression';
 import cors from 'cors';
 import { API_PREFIX } from '@classhelper/shared';
 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 { mountWebAdmin, resolveWebDistDir } from './lib/web-static.js';
 import { errorHandler, notFoundHandler } from './middleware/error.js';
+import { apiRateLimiter, loginRateLimiter, requestLogger, securityHeaders } from './middleware/security.js';
 import { apiModules } from './modules/registry.js';
 
+/** 存活探针：进程活着即 200（供容器 livenessProbe / 守护进程使用） */
+function livenessHandler(_req: Request, res: Response): void {
+  res.status(200).json({
+    success: true,
+    data: { status: 'alive', uptimeSeconds: Math.round(process.uptime()) },
+    message: 'ok',
+  });
+}
+
+/** 就绪探针：数据库可连才 200，否则 503（供负载均衡摘流 / 安装程序自检） */
+async function readinessHandler(_req: Request, res: Response): Promise<void> {
+  const connected = await pingDatabase();
+  if (!connected) {
+    res
+      .status(503)
+      .json({ success: false, data: { database: false }, message: '数据库不可用', code: 'NOT_READY' });
+    return;
+  }
+  res.status(200).json({ success: true, data: { database: true }, message: 'ready' });
+}
+
 async function healthHandler(_req: Request, res: Response): Promise<void> {
   sendOk(
     res,
     {
       status: 'ok',
       version: '0.1.0',
+      env: env.nodeEnv,
       uptimeSeconds: Math.round(process.uptime()),
       database: {
         provider: env.databaseProvider,
         connected: await pingDatabase(),
       },
       modules: apiModules.map((module) => module.name),
+      webAdmin: env.webDistDir ? 'configured' : 'auto',
     },
     '服务运行正常',
   );
 }
 
 /**
- * 根路径落地页。
- * API 全部挂在 /api 下，根路径本身不是接口；这里给出一个可读的服务首页，
- * 避免浏览器直接访问 4000 端口时看到 404 JSON 而误以为服务没起来。
+ * 根路径。
+ * - 已托管 Web 管理端且客户端接受 HTML：交给静态资源与 SPA 回退处理（即打开管理端首页）
+ * - 否则返回服务信息页（浏览器）或 JSON（API 客户端）
  */
-function renderLandingPage(): string {
+function createRootHandler(webDistDir: string | null) {
+  return (req: Request, res: Response, next: express.NextFunction): void => {
+    if (webDistDir && req.accepts(['html', 'json']) === 'html') {
+      next();
+      return;
+    }
+
+    if (req.accepts(['html', 'json']) === 'json') {
+      sendOk(
+        res,
+        {
+          service: 'class-helper-server',
+          version: '0.1.0',
+          environment: env.nodeEnv,
+          apiPrefix: API_PREFIX,
+          socket: '/socket.io',
+          webAdmin: webDistDir ? '/' : 'http://127.0.0.1:5173',
+          health: `${API_PREFIX}/health`,
+          liveness: '/healthz',
+          readiness: '/readyz',
+          modules: apiModules.map((module) => `${API_PREFIX}${module.basePath}`),
+        },
+        '服务运行正常，API 前缀为 /api',
+      );
+      return;
+    }
+
+    res.type('html').send(renderLandingPage(Boolean(webDistDir)));
+  };
+}
+
+function renderLandingPage(webAdminServed: boolean): string {
   const moduleRows = apiModules
     .map((module) => `<li><code>${API_PREFIX}${module.basePath}</code> <span>${module.name}</span></li>`)
     .join('');
@@ -42,9 +99,9 @@ function renderLandingPage(): string {
     <title>班级小助手 · 后端服务</title>
     <style>
       body { margin: 0; padding: 40px; font-family: 'PingFang SC', 'Microsoft YaHei', sans-serif; background: #f5f7fa; color: #303133; }
-      .card { max-width: 720px; margin: 0 auto; background: #fff; border: 1px solid #e4e7ed; border-radius: 12px; padding: 28px 32px; }
+      .card { max-width: 760px; margin: 0 auto; background: #fff; border: 1px solid #e4e7ed; border-radius: 12px; padding: 28px 32px; }
       h1 { margin: 0 0 6px; font-size: 20px; }
-      p.sub { margin: 0 0 20px; color: #909399; font-size: 13px; }
+      p.sub { margin: 0 0 8px; color: #909399; font-size: 13px; }
       .ok { display: inline-block; padding: 2px 10px; border-radius: 999px; background: #f0f9eb; color: #67c23a; font-size: 12px; }
       ul { columns: 2; padding-left: 18px; margin: 12px 0 0; }
       li { margin: 6px 0; font-size: 13px; }
@@ -52,6 +109,7 @@ function renderLandingPage(): string {
       code { background: #f5f7fa; padding: 1px 6px; border-radius: 4px; font-size: 12px; }
       a { color: #409eff; text-decoration: none; }
       .hint { margin-top: 22px; padding-top: 16px; border-top: 1px dashed #e4e7ed; font-size: 13px; color: #606266; line-height: 1.9; }
+      .btn { display: inline-block; margin-top: 4px; padding: 8px 16px; background: #409eff; color: #fff !important; border-radius: 6px; font-size: 13px; }
     </style>
   </head>
   <body>
@@ -59,63 +117,63 @@ function renderLandingPage(): string {
       <h1>班级小助手 · 后端服务 <span class="ok">running</span></h1>
       <p class="sub">版本 0.1.0 · 运行环境 ${env.nodeEnv} · 数据库 ${env.databaseProvider}</p>
       <p class="sub">
-        健康检查：<a href="${API_PREFIX}/health">${API_PREFIX}/health</a> ·
-        管理端开发地址：<a href="http://127.0.0.1:5173">http://127.0.0.1:5173</a>
+        健康检查 <a href="${API_PREFIX}/health">${API_PREFIX}/health</a> ·
+        存活 /healthz · 就绪 /readyz
       </p>
+      ${webAdminServed ? '<a class="btn" href="/">打开 Web 管理端</a>' : '<p class="sub">Web 管理端未随本服务托管，请单独启动（pnpm dev:web → http://127.0.0.1:5173）。</p>'}
       <strong>已挂载模块（${apiModules.length} 个）</strong>
       <ul>${moduleRows}</ul>
       <div class="hint">
-        提示：本服务只提供 REST API 与 WebSocket，没有网页界面。<br />
-        网页界面请访问 Web 管理端 <code>http://127.0.0.1:5173</code>（pnpm dev:web），
-        WebSocket 端点为 <code>ws://127.0.0.1:${env.port}/socket.io</code>。
+        WebSocket 端点：<code>ws://${env.host === '0.0.0.0' ? '本机地址' : env.host}:${env.port}/socket.io</code><br />
+        本服务只提供 REST API 与 WebSocket；学生端请使用「班级小助手」桌面客户端。
       </div>
     </div>
   </body>
 </html>`;
 }
 
-/** 组装 Express 应用：中间件 -> 健康检查 -> 模块路由 -> 404 -> 统一错误处理 */
+/** 组装 Express 应用：安全中间件 -> 健康检查 -> 模块路由 -> Web 静态托管 -> 404 -> 统一错误处理 */
 export function createApp(): Express {
   const app = express();
   app.disable('x-powered-by');
 
+  // 反向代理场景下正确识别客户端 IP（限流、日志依赖）
+  app.set('trust proxy', env.trustProxy);
+
+  const webDistDir = resolveWebDistDir();
+
+  app.use(securityHeaders());
+  app.use(compression());
   app.use(cors({ origin: env.corsOrigins, credentials: true }));
   app.use(express.json({ limit: '2mb' }));
   app.use(express.urlencoded({ extended: true }));
+  app.use(requestLogger());
 
-  app.use((req, _res, next) => {
-    logger.debug(`${req.method} ${req.originalUrl}`);
-    next();
+  // 探针（不参与限流）
+  app.get('/healthz', livenessHandler);
+  app.get('/readyz', (req, res) => {
+    void readinessHandler(req, res);
+  });
+  app.get(`${API_PREFIX}/health`, (req, res) => {
+    void healthHandler(req, res);
+  });
+  app.get('/health', (req, res) => {
+    void healthHandler(req, res);
   });
 
-  // 服务首页（浏览器可读）；如果客户端显式要 JSON，则返回结构化信息
-  app.get('/', (req, res) => {
-    if (req.accepts(['html', 'json']) === 'json') {
-      sendOk(
-        res,
-        {
-          service: 'class-helper-server',
-          version: '0.1.0',
-          apiPrefix: API_PREFIX,
-          webAdmin: 'http://127.0.0.1:5173',
-          socket: `/socket.io`,
-          modules: apiModules.map((module) => `${API_PREFIX}${module.basePath}`),
-        },
-        '服务运行正常，API 前缀为 /api',
-      );
-      return;
-    }
-    res.type('html').send(renderLandingPage());
-  });
+  // 根路径信息页（Web 管理端托管时让位给前端首页）
+  app.get('/', createRootHandler(webDistDir));
 
-  // 浏览器会自动请求 favicon，直接返回 204，避免污染日志
-  app.get('/favicon.ico', (_req, res) => {
-    res.status(204).end();
-  });
+  // 浏览器会自动请求 favicon；有前端产物时交给静态托管处理
+  if (!webDistDir) {
+    app.get('/favicon.ico', (_req, res) => {
+      res.status(204).end();
+    });
+  }
 
-  // 健康检查（同时暴露已挂载模块列表，便于确认模块化装配结果）
-  app.get(`${API_PREFIX}/health`, healthHandler);
-  app.get('/health', healthHandler);
+  // 限流：先挂通用限流，再挂更严格的登录限流（后挂者决定响应头里的策略，便于观察暴力破解防护）
+  app.use(API_PREFIX, apiRateLimiter());
+  app.use(`${API_PREFIX}/auth/login`, loginRateLimiter());
 
   // 模块化装配：注册表里的每个模块挂载到 /api<basePath>
   for (const module of apiModules) {
@@ -124,6 +182,9 @@ export function createApp(): Express {
     logger.info(`已挂载模块 ${module.name.padEnd(14)} -> ${mountPath}`);
   }
 
+  // Web 管理端静态资源 + SPA 回退（必须放在 API 之后）
+  mountWebAdmin(app);
+
   app.use(notFoundHandler);
   app.use(errorHandler);
 

packages/server/src/config/env.ts

@@ -10,12 +10,17 @@ const currentDir = path.dirname(fileURLToPath(import.meta.url));
  */
 export const serverRoot = path.resolve(currentDir, '..', '..');
 
-// 显式按包根目录加载 .env，避免受启动时 cwd 影响
+// 显式按包根目录加载 .env，避免受启动时 cwd 影响。
+// 打包安装后配置文件放在安装根目录（server 的上一级），因此按顺序尝试两处；
+// dotenv 默认不覆盖已存在的变量，所以先匹配到的文件优先生效。
 loadEnv({ path: path.join(serverRoot, '.env') });
+loadEnv({ path: path.join(serverRoot, '..', '.env') });
 
 const envSchema = z.object({
   NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
   PORT: z.coerce.number().int().min(1).max(65535).default(4000),
+  /** 监听地址：生产环境建议 0.0.0.0（容器/内网访问），本地开发可用 127.0.0.1 */
+  HOST: z.string().default('0.0.0.0'),
   DATABASE_PROVIDER: z.enum(['sqlite', 'mysql']).default('sqlite'),
   DATABASE_URL: z.string().min(1).default('file:./prisma/dev.db'),
   JWT_SECRET: z.string().min(16),
@@ -25,6 +30,30 @@ const envSchema = z.object({
   DEFAULT_STUDENT_PASSWORD: z.string().min(6).default('123456'),
   TERM_START_DATE: z.string().default(''),
   LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  /** 反向代理层数（nginx / 容器场景一般填 1），用于正确识别客户端 IP 与协议 */
+  TRUST_PROXY: z.string().default('false'),
+  /** Web 管理端构建产物目录；留空则自动探测 ../web-admin/dist 或 ./web */
+  WEB_DIST_DIR: z.string().default(''),
+  /** 是否启用接口限流（压测时可置 false） */
+  RATE_LIMIT_ENABLED: z
+    .string()
+    .default('true')
+    .transform((value) => value !== 'false' && value !== '0'),
+  /** 启动时是否校验数据库连通性 */
+  STARTUP_DB_CHECK: z
+    .string()
+    .default('true')
+    .transform((value) => value !== 'false' && value !== '0'),
+  /** 自动初始化：数据库为空时是否自动执行迁移（安装程序首启动用） */
+  AUTO_MIGRATE: z
+    .string()
+    .default('false')
+    .transform((value) => value === 'true' || value === '1'),
+  /** 进程 PID 文件（相对路径以 server 根目录为基准），供安装包的启停脚本使用 */
+  PID_FILE: z.string().default(''),
+  /** 首次初始化（空库）时创建的管理员账号 */
+  INITIAL_ADMIN_USERNAME: z.string().min(3).default('admin'),
+  INITIAL_ADMIN_PASSWORD: z.string().min(6).default('admin123'),
 });
 
 const parsed = envSchema.safeParse(process.env);
@@ -46,16 +75,57 @@ function resolveSqliteUrl(url: string): string {
   return `file:${absolute.replace(/\\/g, '/')}`;
 }
 
+/** 从 file: URL 中取出真实的文件系统路径（供启动前建目录等使用） */
+function sqliteFilePathOf(url: string): string {
+  const withoutPrefix = url.startsWith('file:') ? url.slice('file:'.length) : url;
+  return withoutPrefix.replace(/\\/g, path.sep).replace(/\//g, path.sep);
+}
+
 const isSqlite = raw.DATABASE_PROVIDER === 'sqlite';
+const isProduction = raw.NODE_ENV === 'production';
+
+const resolvedDatabaseUrl = isSqlite ? resolveSqliteUrl(raw.DATABASE_URL) : raw.DATABASE_URL;
+/** SQLite 数据文件的绝对路径（MySQL 时为空字符串），供启动前创建目录使用 */
+const sqliteFilePath = isSqlite ? sqliteFilePathOf(resolvedDatabaseUrl) : '';
+
+/** 生产环境配置自检：不安全的默认值直接拒绝启动，避免把开发配置带上生产 */
+const INSECURE_SECRET_MARKERS = ['change-me', 'changeme', 'secret', 'classhelper-dev'];
+if (isProduction) {
+  const problems: string[] = [];
+  if (raw.JWT_SECRET.length < 32) problems.push('JWT_SECRET 长度必须 ≥ 32 位');
+  if (INSECURE_SECRET_MARKERS.some((marker) => raw.JWT_SECRET.toLowerCase().includes(marker))) {
+    problems.push('JWT_SECRET 仍是示例/开发用值，请重新生成');
+  }
+  if (isSqlite && raw.DATABASE_URL.includes('dev.db')) {
+    problems.push('生产环境仍在使用 dev.db，请指定正式的数据文件或改用 MySQL');
+  }
+  if (problems.length > 0) {
+    throw new Error(
+      `生产环境（NODE_ENV=production）配置检查未通过：\n${problems.map((item) => `  - ${item}`).join('\n')}\n` +
+        '请修改 packages/server/.env 后重试。',
+    );
+  }
+}
+
+/** trust proxy 支持 false / 数字跳数 / loopback 等字符串形式 */
+function resolveTrustProxy(value: string): boolean | number | string {
+  if (value === 'false' || value === '') return false;
+  if (value === 'true') return true;
+  if (/^\d+$/.test(value)) return Number(value);
+  return value;
+}
 
 export const env = {
   nodeEnv: raw.NODE_ENV,
-  isProduction: raw.NODE_ENV === 'production',
+  isProduction,
   isDevelopment: raw.NODE_ENV === 'development',
   port: raw.PORT,
+  host: raw.HOST,
   databaseProvider: raw.DATABASE_PROVIDER,
   /** 已规范化为绝对路径（SQLite）/ 原始连接串（MySQL） */
-  databaseUrl: isSqlite ? resolveSqliteUrl(raw.DATABASE_URL) : raw.DATABASE_URL,
+  databaseUrl: resolvedDatabaseUrl,
+  /** SQLite 数据文件绝对路径（MySQL 时为空） */
+  sqliteFilePath,
   rawDatabaseUrl: raw.DATABASE_URL,
   jwtSecret: raw.JWT_SECRET,
   jwtExpiresIn: raw.JWT_EXPIRES_IN,
@@ -71,6 +141,15 @@ export const env = {
   defaultStudentPassword: raw.DEFAULT_STUDENT_PASSWORD,
   termStartDate: raw.TERM_START_DATE,
   logLevel: raw.LOG_LEVEL,
+  trustProxy: resolveTrustProxy(raw.TRUST_PROXY),
+  webDistDir: raw.WEB_DIST_DIR,
+  rateLimitEnabled: raw.RATE_LIMIT_ENABLED,
+  startupDbCheck: raw.STARTUP_DB_CHECK,
+  autoMigrate: raw.AUTO_MIGRATE,
+  /** PID 文件的绝对路径（未配置时为空字符串） */
+  pidFile: raw.PID_FILE ? path.resolve(serverRoot, raw.PID_FILE) : '',
+  initialAdminUsername: raw.INITIAL_ADMIN_USERNAME,
+  initialAdminPassword: raw.INITIAL_ADMIN_PASSWORD,
   serverRoot,
 } as const;
 

packages/server/src/index.ts

@@ -1,24 +1,90 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import { createServer } from 'node:http';
 import { API_PREFIX } from '@classhelper/shared';
 import { createApp } from './app.js';
 import { env } from './config/env.js';
 import { disconnectPrisma, pingDatabase } from './lib/db.js';
+import { ensureInitialAdmin, ensureSchema } from './lib/db-bootstrap.js';
 import { logger } from './lib/logger.js';
+import { resolveWebDistDir } from './lib/web-static.js';
 import { initRealtime } from './realtime/socket.js';
 
+/** 数据库自检与可选的首次初始化 */
+async function prepareDatabase(): Promise<void> {
+  // SQLite：确保数据文件所在目录存在，否则 libsql 会以 SQLITE_CANTOPEN(14) 失败
+  if (env.sqliteFilePath) {
+    try {
+      fs.mkdirSync(path.dirname(env.sqliteFilePath), { recursive: true });
+    } catch (error) {
+      logger.warn(`创建数据目录失败：${path.dirname(env.sqliteFilePath)}`, error);
+    }
+  }
+
+  if (env.autoMigrate) {
+    try {
+      const result = await ensureSchema();
+      logger.info(`数据库初始化：${result.detail}`);
+      const admin = await ensureInitialAdmin();
+      if (admin.created) logger.info('可使用该账号登录 Web 管理端，并立即修改密码');
+    } catch (error) {
+      logger.error('数据库初始化失败', error);
+    }
+  }
+
+  if (!env.startupDbCheck) return;
+
+  if (await pingDatabase()) {
+    logger.info('数据库连接正常');
+    return;
+  }
+
+  logger.error(
+    '数据库连接失败：请检查 DATABASE_URL，并确认已执行迁移（pnpm db:migrate / prisma migrate deploy）',
+  );
+  if (env.isProduction) {
+    logger.error('生产环境启动中止：数据库不可用时不应对外提供服务');
+    process.exit(1);
+  }
+}
+
+await prepareDatabase();
+
 const app = createApp();
 const httpServer = createServer(app);
 const io = initRealtime(httpServer);
 
-if (!(await pingDatabase())) {
-  logger.warn('数据库连接失败：请先执行 pnpm db:migrate 与 pnpm db:seed');
+/** 写入 PID 文件（安装包的 start.cmd / stop.cmd 依赖它精确控制进程） */
+function writePidFile(): void {
+  if (!env.pidFile) return;
+  try {
+    fs.mkdirSync(path.dirname(env.pidFile), { recursive: true });
+    fs.writeFileSync(env.pidFile, String(process.pid), 'utf8');
+  } catch (error) {
+    logger.warn('写入 PID 文件失败', error);
+  }
 }
 
-httpServer.listen(env.port, () => {
-  logger.info(`班级小助手后端已启动：http://127.0.0.1:${env.port}${API_PREFIX}`);
-  logger.info(`健康检查：http://127.0.0.1:${env.port}${API_PREFIX}/health`);
-  logger.info(`WebSocket：ws://127.0.0.1:${env.port}/socket.io`);
-  logger.info(`运行环境：${env.nodeEnv}，数据库：${env.databaseProvider}`);
+function removePidFile(): void {
+  if (!env.pidFile) return;
+  try {
+    if (fs.existsSync(env.pidFile)) fs.unlinkSync(env.pidFile);
+  } catch {
+    // 忽略清理失败
+  }
+}
+
+httpServer.listen(env.port, env.host, () => {
+  writePidFile();
+  const displayHost = env.host === '0.0.0.0' ? '127.0.0.1' : env.host;
+  const webDir = resolveWebDistDir();
+  logger.info(`班级小助手后端已启动：http://${displayHost}:${env.port}${API_PREFIX}`);
+  logger.info(`运行环境：${env.nodeEnv} · 监听：${env.host}:${env.port} · 数据库：${env.databaseProvider}`);
+  if (webDir) {
+    logger.info(`Web 管理端：http://${displayHost}:${env.port}/（静态目录 ${webDir}）`);
+  }
+  logger.info(`探针：/healthz（存活） · /readyz（就绪） · ${API_PREFIX}/health（详情）`);
+  logger.info(`WebSocket：ws://${displayHost}:${env.port}/socket.io`);
 });
 
 let shuttingDown = false;
@@ -28,9 +94,18 @@ async function shutdown(signal: string): Promise<void> {
   shuttingDown = true;
   logger.info(`收到 ${signal}，正在优雅关闭...`);
 
+  // 停止接收新连接，并给在途请求 5 秒收尾时间
+  const forceExit = setTimeout(() => {
+    logger.warn('关闭超时，强制退出');
+    process.exit(1);
+  }, 5000);
+  forceExit.unref();
+
   await new Promise<void>((resolve) => io.close(() => resolve()));
   await new Promise<void>((resolve) => httpServer.close(() => resolve()));
   await disconnectPrisma();
+  removePidFile();
+  clearTimeout(forceExit);
   logger.info('已关闭所有连接');
   process.exit(0);
 }
@@ -44,3 +119,7 @@ process.on('SIGTERM', () => {
 process.on('unhandledRejection', (reason) => {
   logger.error('未处理的 Promise 拒绝', reason);
 });
+process.on('uncaughtException', (error) => {
+  logger.error('未捕获异常，进程即将退出', error);
+  void shutdown('uncaughtException');
+});

packages/server/src/lib/db-bootstrap.ts

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createClient } from '@libsql/client';
+import { env } from '../config/env.js';
+import { prisma } from './db.js';
+import { logger } from './logger.js';
+import { hashPassword } from './password.js';
+
+/**
+ * 首次启动时的数据库初始化（SQLite/libSQL）。
+ *
+ * 场景：安装程序首次运行、Docker 挂载了空数据卷、用户手动删除了数据库文件。
+ * 做法：若目标库中还没有业务表，就把随包发布的 Prisma 迁移 SQL 依次执行一遍。
+ *
+ * 说明：
+ * - 只处理 SQLite（本项目打包安装的默认形态）；
+ *   MySQL 请在部署流程中执行 `prisma migrate deploy`（Docker 镜像已内置该步骤）。
+ * - 迁移文件按目录名（时间戳）升序执行，与 Prisma 的行为一致。
+ */
+
+/** 迁移文件所在目录（打包后随 server 一起发布） */
+function migrationsRoot(): string {
+  const candidates = [
+    env.isProduction ? path.resolve(env.serverRoot, 'prisma', 'migrations') : '',
+    path.resolve(env.serverRoot, 'prisma', 'migrations'),
+    path.resolve(env.serverRoot, '..', 'prisma', 'migrations'),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return path.resolve(env.serverRoot, 'prisma', 'migrations');
+}
+
+/** 收集迁移 SQL 文件（按目录名升序） */
+export function listMigrationFiles(): string[] {
+  const root = migrationsRoot();
+  if (!fs.existsSync(root)) return [];
+
+  return fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+    .map((name) => path.join(root, name, 'migration.sql'))
+    .filter((file) => fs.existsSync(file));
+}
+
+/** 业务表是否已存在（用 User 表作为探针） */
+async function schemaExists(): Promise<boolean> {
+  try {
+    const rows = await prisma.$queryRaw<Array<{ name: string }>>`
+      SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'User'
+    `;
+    return rows.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+export interface BootstrapResult {
+  applied: number;
+  skipped: boolean;
+  detail: string;
+}
+
+/**
+ * 初始化管理员账号。
+ *
+ * 全新安装的数据库是空的，没有任何账号可登录，因此首次启动（AUTO_MIGRATE=true）
+ * 会创建一个管理员账号；如果使用的是默认密码，会在日志中给出醒目提示。
+ */
+export async function ensureInitialAdmin(): Promise<{ created: boolean; username: string }> {
+  const existing = await prisma.user.count({ where: { role: 'ADMIN' } });
+  if (existing > 0) return { created: false, username: env.initialAdminUsername };
+
+  await prisma.user.create({
+    data: {
+      username: env.initialAdminUsername,
+      name: '系统管理员',
+      role: 'ADMIN',
+      passwordHash: await hashPassword(env.initialAdminPassword),
+    },
+  });
+
+  if (env.initialAdminPassword === 'admin123') {
+    logger.warn(
+      `已创建初始管理员 ${env.initialAdminUsername} / ${env.initialAdminPassword}（默认密码），请登录后立即在「修改密码」中更换`,
+    );
+  } else {
+    logger.info(`已创建初始管理员账号：${env.initialAdminUsername}`);
+  }
+
+  return { created: true, username: env.initialAdminUsername };
+}
+
+/**
+ * 确保数据库结构存在。
+ * 仅在 AUTO_MIGRATE=true 时由启动流程调用。
+ */
+export async function ensureSchema(): Promise<BootstrapResult> {
+  if (env.databaseProvider !== 'sqlite') {
+    return {
+      applied: 0,
+      skipped: true,
+      detail: '非 SQLite 数据库：请在部署流程中执行 prisma migrate deploy',
+    };
+  }
+
+  if (await schemaExists()) {
+    return { applied: 0, skipped: true, detail: '数据库结构已存在，跳过初始化' };
+  }
+
+  const files = listMigrationFiles();
+  if (files.length === 0) {
+    return { applied: 0, skipped: true, detail: '未找到迁移文件，请手动执行 pnpm db:migrate' };
+  }
+
+  const client = createClient({ url: env.databaseUrl });
+  let applied = 0;
+  try {
+    for (const file of files) {
+      const sql = fs.readFileSync(file, 'utf8');
+      await client.executeMultiple(sql);
+      applied += 1;
+      logger.info(`已应用迁移：${path.basename(path.dirname(file))}`);
+    }
+  } finally {
+    client.close();
+  }
+
+  return { applied, skipped: false, detail: `已应用 ${applied} 个迁移文件` };
+}

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

@@ -0,0 +1,108 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import express, { type Express, type RequestHandler } from 'express';
+import { env } from '../config/env.js';
+import { logger } from './logger.js';
+
+/**
+ * Web 管理端静态托管（生产模式）。
+ *
+ * 部署形态：后端同时充当 Web 管理端的静态服务器 —— 单端口即可访问
+ * `http://<host>:4000/` 打开管理端，`/api` 与 `/socket.io` 走同一端口，
+ * 因此不再需要额外的 Nginx/Vite 进程（需要 HTTPS/域名时在前面加反向代理）。
+ *
+ * 目录探测顺序：
+ *   1) 环境变量 WEB_DIST_DIR
+ *   2) Monorepo 开发布局：<serverRoot>/../web-admin/dist
+ *   3) 安装包布局：<serverRoot>/web
+ */
+export function resolveWebDistDir(): string | null {
+  const candidates = [
+    env.webDistDir,
+    path.resolve(env.serverRoot, '..', 'web-admin', 'dist'),
+    path.resolve(env.serverRoot, 'web'),
+    path.resolve(env.serverRoot, '..', 'web'),
+  ].filter((item): item is string => Boolean(item));
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(candidate, 'index.html'))) return candidate;
+  }
+  return null;
+}
+
+/**
+ * 挂载静态资源与 SPA 回退。
+ * 仅在探测到构建产物时生效；否则保持纯 API 服务（开发模式下 Web 端由 Vite 提供）。
+ */
+export function mountWebAdmin(app: Express): string | null {
+  const distDir = resolveWebDistDir();
+  if (!distDir) {
+    logger.info('未检测到 Web 管理端构建产物，跳过静态托管（仅提供 API 与 WebSocket）');
+    return null;
+  }
+
+  // 带内容哈希的构建产物：长缓存
+  // dotfiles: 'allow' —— 安装/部署目录路径里可能含点号目录（如 .cache、/opt/.apps），
+  // 默认的 'ignore' 会让 express.static / res.sendFile 直接 404（进而 500）
+  app.use(
+    '/assets',
+    express.static(path.join(distDir, 'assets'), {
+      immutable: true,
+      maxAge: '1y',
+      fallthrough: true,
+      index: false,
+      dotfiles: 'allow',
+    }),
+  );
+
+  // 其余静态文件（favicon、manifest、service worker 等）：短缓存
+  app.use(
+    express.static(distDir, {
+      maxAge: '1h',
+      etag: true,
+      index: false,
+      dotfiles: 'allow',
+      setHeaders: (res, filePath) => {
+        // Service Worker 与 index.html 不能被长缓存，否则更新不生效
+        if (filePath.endsWith('sw.js') || filePath.endsWith('index.html')) {
+          res.setHeader('Cache-Control', 'no-cache');
+        }
+      },
+    }),
+  );
+
+  const indexHtml = path.join(distDir, 'index.html');
+
+  /**
+   * SPA 回退：非 /api、非 /socket.io、且接受 HTML 的 GET 请求统一返回 index.html，
+   * 保证前端路由（/grades、/classes/xxx 等）刷新后仍可用。
+   */
+  app.get(/^\/(?!api\/|socket\.io\/|healthz$|readyz$).*/, (req, res, next) => {
+    if (!req.accepts('html')) {
+      next();
+      return;
+    }
+    res.setHeader('Cache-Control', 'no-cache');
+    res.sendFile(indexHtml, { dotfiles: 'allow' }, (error) => {
+      if (!error) return;
+      logger.error(`返回 Web 管理端首页失败：${indexHtml}`, error);
+      if (!res.headersSent) {
+        res.status(500).json({
+          success: false,
+          data: null,
+          message: 'Web 管理端资源不可用，请检查构建产物是否完整',
+          code: 'WEB_DIST_UNAVAILABLE',
+        });
+      }
+    });
+  });
+
+  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

@@ -0,0 +1,102 @@
+import type { RequestHandler } from 'express';
+import helmet from 'helmet';
+import { rateLimit } from 'express-rate-limit';
+import { env } from '../config/env.js';
+import { logger } from '../lib/logger.js';
+
+/**
+ * 安全响应头（helmet）。
+ *
+ * CSP 说明：
+ * - style-src 需要 'unsafe-inline'：Element Plus 运行时注入行内样式
+ * - connect-src 需要放行 WebSocket（同源 ws/wss）与已配置的跨域后端
+ * - 桌面客户端通过 file:// 加载页面，因此不启用 COOP/COEP，资源策略设为 cross-origin
+ */
+export function securityHeaders(): RequestHandler {
+  const connectSrc = new Set<string>(["'self'", 'ws:', 'wss:']);
+  if (Array.isArray(env.corsOrigins)) {
+    for (const origin of env.corsOrigins) connectSrc.add(origin);
+  }
+
+  return helmet({
+    contentSecurityPolicy: {
+      useDefaults: true,
+      directives: {
+        'default-src': ["'self'"],
+        'script-src': ["'self'"],
+        'style-src': ["'self'", "'unsafe-inline'"],
+        'img-src': ["'self'", 'data:', 'blob:'],
+        'font-src': ["'self'", 'data:'],
+        'connect-src': [...connectSrc],
+        'object-src': ["'none'"],
+        'base-uri': ["'self'"],
+        'frame-ancestors': ["'none'"],
+        'form-action': ["'self'"],
+      },
+    },
+    crossOriginEmbedderPolicy: false,
+    crossOriginOpenerPolicy: false,
+    // 允许桌面客户端等跨源场景读取静态资源与接口响应
+    crossOriginResourcePolicy: { policy: 'cross-origin' },
+    referrerPolicy: { policy: 'no-referrer' },
+    hsts: env.isProduction ? { maxAge: 15552000, includeSubDomains: true } : false,
+  });
+}
+
+/** 通用接口限流：防止单 IP 高频刷接口 */
+export function apiRateLimiter(): RequestHandler {
+  const limiter = rateLimit({
+    windowMs: 5 * 60 * 1000,
+    limit: env.isProduction ? 600 : 3000,
+    standardHeaders: 'draft-7',
+    legacyHeaders: false,
+    skip: () => !env.rateLimitEnabled,
+    handler: (req, res) => {
+      logger.warn(`触发接口限流：${req.ip ?? '-'} ${req.method} ${req.originalUrl}`);
+      res.status(429).json({
+        success: false,
+        data: null,
+        message: '请求过于频繁，请稍后再试',
+        code: 'TOO_MANY_REQUESTS',
+      });
+    },
+  });
+  return limiter;
+}
+
+/** 登录接口专用限流：防暴力破解 */
+export function loginRateLimiter(): RequestHandler {
+  return rateLimit({
+    windowMs: 10 * 60 * 1000,
+    limit: env.isProduction ? 20 : 200,
+    standardHeaders: 'draft-7',
+    legacyHeaders: false,
+    skipSuccessfulRequests: true,
+    skip: () => !env.rateLimitEnabled,
+    handler: (req, res) => {
+      logger.warn(`登录尝试过于频繁：${req.ip ?? '-'}`);
+      res.status(429).json({
+        success: false,
+        data: null,
+        message: '登录尝试过于频繁，请 10 分钟后再试',
+        code: 'TOO_MANY_REQUESTS',
+      });
+    },
+  });
+}
+
+/** 请求耗时日志（生产 info，开发 debug） */
+export function requestLogger(): RequestHandler {
+  return (req, res, next) => {
+    const startedAt = process.hrtime.bigint();
+    res.on('finish', () => {
+      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);
+      else if (res.statusCode >= 400) logger.warn(message);
+      else if (env.isProduction) logger.info(message);
+      else logger.debug(message);
+    });
+    next();
+  };
+}