openlearn-next 0.3.7 → 0.3.9

package/cli-data.mjs

@@ -0,0 +1,252 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+/**
+ * 解析本地目标数据库路径
+ * @param {string} [customPath]
+ * @returns {string}
+ */
+export function resolveDbPath(customPath) {
+  if (customPath) return path.resolve(customPath);
+  if (process.env.OPENLEARN_DB_PATH) return path.resolve(process.env.OPENLEARN_DB_PATH);
+  return path.join(os.homedir(), 'openlearn-next', 'data.db');
+}
+
+/**
+ * 一键数据冷备
+ * @param {string} [outputFile]
+ * @param {Object} [options]
+ * @returns {Promise<{ ok: boolean, targetFile?: string, error?: string }>}
+ */
+export async function runBackup(outputFile, options = {}) {
+  const log = options.silent ? () => {} : (msg) => console.log(`[openlearn-next] ${msg}`);
+  const dbPath = resolveDbPath(options.dbPath);
+
+  if (!fs.existsSync(dbPath)) {
+    const msg = `数据库文件未找到: ${dbPath}`;
+    log(`✗ 备份失败: ${msg}`);
+    return { ok: false, error: msg };
+  }
+
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  const timestamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}_${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  const target = outputFile
+    ? path.resolve(outputFile)
+    : path.resolve(process.cwd(), `openlearn_backup_${timestamp}.db`);
+
+  try {
+    const Database = (await import('better-sqlite3')).default;
+    const db = new Database(dbPath, { readonly: true });
+    await db.backup(target);
+    db.close();
+
+    const stat = fs.statSync(target);
+    const sizeKb = Math.round(stat.size / 1024);
+    log(`✓ 数据库冷备完成！`);
+    log(`  快照文件: ${target} (${sizeKb} KB)`);
+    return { ok: true, targetFile: target };
+  } catch (err) {
+    // 降级为物理文件复制
+    try {
+      fs.copyFileSync(dbPath, target);
+      const stat = fs.statSync(target);
+      const sizeKb = Math.round(stat.size / 1024);
+      log(`✓ 数据库文件冷备完成（直接镜像模式）：${target} (${sizeKb} KB)`);
+      return { ok: true, targetFile: target };
+    } catch (copyErr) {
+      log(`✗ 备份写入失败: ${copyErr.message}`);
+      return { ok: false, error: copyErr.message };
+    }
+  }
+}
+
+/**
+ * 数据安全回滚与还原
+ * @param {string} sourceFile
+ * @param {Object} [options]
+ * @returns {Promise<{ ok: boolean, error?: string }>}
+ */
+export async function runRestore(sourceFile, options = {}) {
+  const log = options.silent ? () => {} : (msg) => console.log(`[openlearn-next] ${msg}`);
+  if (!sourceFile) {
+    const msg = '未指定待还原的备份文件。用法: npx openlearn-next restore <backup.db>';
+    log(`✗ ${msg}`);
+    return { ok: false, error: msg };
+  }
+
+  const src = path.resolve(sourceFile);
+  if (!fs.existsSync(src)) {
+    const msg = `指定的备份文件不存在: ${src}`;
+    log(`✗ ${msg}`);
+    return { ok: false, error: msg };
+  }
+
+  // 校验 SQLite 文件头 (Magic Header: "SQLite format 3\0")
+  try {
+    const fd = fs.openSync(src, 'r');
+    const buffer = Buffer.alloc(16);
+    fs.readSync(fd, buffer, 0, 16, 0);
+    fs.closeSync(fd);
+    const headerStr = buffer.toString('utf-8');
+    if (!headerStr.startsWith('SQLite format 3')) {
+      const msg = `文件并非有效的 SQLite 数据库备份: ${src}`;
+      log(`✗ ${msg}`);
+      return { ok: false, error: msg };
+    }
+  } catch (err) {
+    log(`✗ 读取备份文件头失败: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+
+  const dbPath = resolveDbPath(options.dbPath);
+  const dbDir = path.dirname(dbPath);
+  fs.mkdirSync(dbDir, { recursive: true });
+
+  // 创建自动回滚副本
+  if (fs.existsSync(dbPath)) {
+    const bakFile = `${dbPath}.bak_${Date.now()}`;
+    fs.copyFileSync(dbPath, bakFile);
+    log(`ℹ 已为现有数据库创建安全回滚镜像: ${bakFile}`);
+  }
+
+  try {
+    fs.copyFileSync(src, dbPath);
+    // 清理旧的 WAL 与 SHM
+    const wal = `${dbPath}-wal`;
+    const shm = `${dbPath}-shm`;
+    if (fs.existsSync(wal)) fs.unlinkSync(wal);
+    if (fs.existsSync(shm)) fs.unlinkSync(shm);
+
+    log(`✓ 数据库还原成功！当前主库已切换为 ${src} 的数据。`);
+    return { ok: true };
+  } catch (err) {
+    log(`✗ 覆盖写入数据库失败: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * 命令行一键重置管理员 (admin) 密码
+ * @param {string} [newPassword='admin']
+ * @param {Object} [options]
+ * @returns {Promise<{ ok: boolean, error?: string }>}
+ */
+export async function runResetAdmin(newPassword = 'admin', options = {}) {
+  const log = options.silent ? () => {} : (msg) => console.log(`[openlearn-next] ${msg}`);
+  const dbPath = resolveDbPath(options.dbPath);
+
+  if (!fs.existsSync(dbPath)) {
+    const msg = `数据库尚未初始化 (${dbPath})。请直接启动一次平台即可生成默认 admin/admin 账号。`;
+    log(`ℹ ${msg}`);
+    return { ok: false, error: msg };
+  }
+
+  try {
+    let hash;
+    try {
+      const bcrypt = (await import('bcryptjs')).default;
+      hash = bcrypt.hashSync(newPassword, 10);
+    } catch {
+      const crypto = await import('node:crypto');
+      hash = crypto.createHash('sha256').update(newPassword).digest('hex');
+    }
+
+    const Database = (await import('better-sqlite3')).default;
+    const db = new Database(dbPath);
+
+    const updateRes = db.prepare('UPDATE users SET password_hash = ? WHERE username = ?').run(hash, 'admin');
+
+    if (updateRes.changes === 0) {
+      // 若数据库中无 admin 用户，则插入
+      db.prepare('INSERT INTO users (id, username, password_hash, role, name, created_at) VALUES (?, ?, ?, ?, ?, ?)')
+        .run(`usr_admin_${Date.now()}`, 'admin', hash, 'administrator', 'System Admin', Date.now());
+      log(`✓ 管理员账号不存在，已新建管理员账号: admin (密码: ${newPassword})`);
+    } else {
+      log(`✓ 管理员 (admin) 密码已成功重置为: ${newPassword}`);
+    }
+
+    db.close();
+    return { ok: true };
+  } catch (err) {
+    log(`✗ 重置密码失败: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * 命令行插件状态速查
+ * @param {Object} [options]
+ * @returns {Promise<{ ok: boolean, plugins?: Array<any>, error?: string }>}
+ */
+export async function runPluginsList(options = {}) {
+  const log = options.silent ? () => {} : (msg) => console.log(`[openlearn-next] ${msg}`);
+  const dbPath = resolveDbPath(options.dbPath);
+
+  if (!fs.existsSync(dbPath)) {
+    log(`数据库文件尚未创建 (${dbPath})，暂无插件安装记录。`);
+    return { ok: true, plugins: [] };
+  }
+
+  try {
+    const Database = (await import('better-sqlite3')).default;
+    const db = new Database(dbPath, { readonly: true });
+
+    // 检查 plugins 表是否存在
+    const tableCheck = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='plugins'").get();
+    if (!tableCheck) {
+      log(`未检测到 plugins 数据表，平台尚未加载插件体系。`);
+      db.close();
+      return { ok: true, plugins: [] };
+    }
+
+    const rows = db.prepare('SELECT * FROM plugins ORDER BY id ASC').all();
+    db.close();
+
+    const plugins = rows.map((p) => {
+      let version = '1.0.0';
+      if (p.manifest) {
+        try {
+          const parsed = JSON.parse(p.manifest);
+          if (parsed.version) version = parsed.version;
+        } catch {}
+      }
+      return {
+        id: p.id,
+        name: p.name,
+        version,
+        status: p.status,
+        loader_version: p.loader_version || p.execution_mode || 'inline',
+      };
+    });
+
+    if (!options.silent) {
+      const bold = '\x1b[1m';
+      const green = '\x1b[32m';
+      const yellow = '\x1b[33m';
+      const cyan = '\x1b[36m';
+      const reset = '\x1b[0m';
+
+      console.log(`\n${bold}${cyan}已安装插件清单 (${plugins.length} 个):${reset}`);
+      console.log(`┌──────────────────────────────────────────────┬─────────┬──────────┬──────────┐`);
+      console.log(`│ ${bold}Plugin ID${reset}${' '.repeat(37)}│ ${bold}Version${reset} │ ${bold}Status${reset}   │ ${bold}Mode${reset}     │`);
+      console.log(`├──────────────────────────────────────────────┼─────────┼──────────┼──────────┤`);
+
+      for (const p of plugins) {
+        const idCol = p.id.padEnd(44);
+        const verCol = (p.version || '1.0.0').padEnd(7);
+        const statusColor = p.status === 'active' ? green : yellow;
+        const statusCol = `${statusColor}${p.status.padEnd(8)}${reset}`;
+        const modeCol = (p.loader_version || 'inline').padEnd(8);
+        console.log(`│ ${idCol} │ ${verCol} │ ${statusCol} │ ${modeCol} │`);
+      }
+      console.log(`└──────────────────────────────────────────────┴─────────┴──────────┴──────────┘\n`);
+    }
+
+    return { ok: true, plugins };
+  } catch (err) {
+    log(`✗ 查询插件失败: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+}

package/cli-doctor.mjs

@@ -0,0 +1,189 @@
+import os from 'node:os';
+import net from 'node:net';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 诊断指定端口是否可用
+ * @param {number} port
+ * @param {string} host
+ * @returns {Promise<boolean>}
+ */
+export function checkPortAvailable(port, host = '0.0.0.0') {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        resolve(false);
+      } else {
+        resolve(false);
+      }
+    });
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, host);
+  });
+}
+
+/**
+ * 获取本机所有局域网可用 IPv4 地址
+ * @returns {string[]}
+ */
+export function getNetworkIps() {
+  const ips = [];
+  const interfaces = os.networkInterfaces();
+  for (const name of Object.keys(interfaces)) {
+    for (const iface of interfaces[name] || []) {
+      if (iface.family === 'IPv4' && !iface.internal && !iface.address.startsWith('127.')) {
+        ips.push(iface.address);
+      }
+    }
+  }
+  return ips;
+}
+
+/**
+ * 运行系统环境自检与健康诊断
+ * @param {Object} [options]
+ * @param {number} [options.port]
+ * @param {string} [options.dbPath]
+ * @param {boolean} [options.silent]
+ * @returns {Promise<{ ok: boolean, checks: Array<{ name: string, status: 'ok'|'warn'|'err', message: string }> }>}
+ */
+export async function runDoctor(options = {}) {
+  const checks = [];
+  const silent = Boolean(options.silent);
+
+  // 1. Node.js 版本检查 (>= 20.0.0)
+  const nodeVersion = process.versions.node;
+  const majorNodeVersion = parseInt(nodeVersion.split('.')[0], 10);
+  if (majorNodeVersion >= 20) {
+    checks.push({
+      name: 'Node.js Runtime',
+      status: 'ok',
+      message: `v${nodeVersion} (满足 >= 20.0.0 要求)`,
+    });
+  } else {
+    checks.push({
+      name: 'Node.js Runtime',
+      status: 'err',
+      message: `v${nodeVersion} 过低！OpenLearn 核心需要 Node.js >= 20.0.0，请升级。`,
+    });
+  }
+
+  // 2. 操作系统与硬件
+  const cpus = os.cpus() || [];
+  const totalMemGb = Math.round((os.totalmem() / 1024 / 1024 / 1024) * 10) / 10;
+  const freeMemMb = Math.round(os.freemem() / 1024 / 1024);
+  checks.push({
+    name: 'Hardware & OS',
+    status: 'ok',
+    message: `${process.platform} (${process.arch}, ${cpus.length} CPU 核心, ${totalMemGb} GB 内存)`,
+  });
+
+  if (freeMemMb < 256) {
+    checks.push({
+      name: 'Memory Headroom',
+      status: 'warn',
+      message: `剩余可用内存偏低 (${freeMemMb} MB)，可能影响大课件解析`,
+    });
+  } else {
+    checks.push({
+      name: 'Memory Headroom',
+      status: 'ok',
+      message: `充足 (当前剩余 ${freeMemMb} MB 可用)`,
+    });
+  }
+
+  // 3. 数据库目录与读写权限
+  const dbPath = options.dbPath
+    ? path.resolve(options.dbPath)
+    : (process.env.OPENLEARN_DB_PATH
+        ? path.resolve(process.env.OPENLEARN_DB_PATH)
+        : path.join(os.homedir(), 'openlearn-next', 'data.db'));
+  const dbDir = path.dirname(dbPath);
+
+  try {
+    fs.mkdirSync(dbDir, { recursive: true });
+    // 测试临时写入
+    const testFile = path.join(dbDir, `.doctor_write_test_${Date.now()}`);
+    fs.writeFileSync(testFile, 'test');
+    fs.unlinkSync(testFile);
+    checks.push({
+      name: 'Database Storage',
+      status: 'ok',
+      message: `${dbPath} (目录正常且具备读写权限)`,
+    });
+  } catch (err) {
+    checks.push({
+      name: 'Database Storage',
+      status: 'err',
+      message: `目录 ${dbDir} 写入失败: ${err.message}`,
+    });
+  }
+
+  // 4. 端口可用性检查
+  const targetPort = options.port || parseInt(process.env.PORT || '9000', 10);
+  const isPortAvailable = await checkPortAvailable(targetPort);
+  if (isPortAvailable) {
+    checks.push({
+      name: `Port ${targetPort}`,
+      status: 'ok',
+      message: `可用 (未被其他进程占用)`,
+    });
+  } else {
+    checks.push({
+      name: `Port ${targetPort}`,
+      status: 'warn',
+      message: `已被占用！启动时会自动重试或可通过 -p <other_port> 更换端口`,
+    });
+  }
+
+  // 5. 局域网接入点
+  const netIps = getNetworkIps();
+  if (netIps.length > 0) {
+    checks.push({
+      name: 'Network Access',
+      status: 'ok',
+      message: `检测到局域网 IP: ${netIps.join(', ')}`,
+    });
+  } else {
+    checks.push({
+      name: 'Network Access',
+      status: 'warn',
+      message: `未检测到外部局域网 IPv4 地址（仅可通过 localhost 本机访问）`,
+    });
+  }
+
+  const allOk = checks.every((c) => c.status !== 'err');
+
+  if (!silent) {
+    const bold = '\x1b[1m';
+    const green = '\x1b[32m';
+    const yellow = '\x1b[33m';
+    const red = '\x1b[31m';
+    const cyan = '\x1b[36m';
+    const reset = '\x1b[0m';
+
+    console.log(`\n${bold}${cyan}╔═════════════════════════════════════════════════════════════╗${reset}`);
+    console.log(`${bold}${cyan}║           OpenLearn V2 System Diagnostics (doctor)          ║${reset}`);
+    console.log(`${bold}${cyan}╚═════════════════════════════════════════════════════════════╝${reset}\n`);
+
+    for (const c of checks) {
+      let icon = `${green}✓${reset}`;
+      if (c.status === 'warn') icon = `${yellow}⚠${reset}`;
+      if (c.status === 'err') icon = `${red}✗${reset}`;
+      console.log(`  ${icon} ${bold}${c.name.padEnd(18)}${reset} : ${c.message}`);
+    }
+
+    console.log(`\n${cyan}───────────────────────────────────────────────────────────────${reset}`);
+    if (allOk) {
+      console.log(`  ${bold}${green}诊断通过！核心运行环境健康，已具备课堂部署就绪状态。${reset}\n`);
+    } else {
+      console.log(`  ${bold}${red}诊断发现阻断性问题，请根据上述提示处理后重试。${reset}\n`);
+    }
+  }
+
+  return { ok: allOk, checks };
+}

package/cli.mjs

@@ -2,16 +2,20 @@
 
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-import { mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { mkdirSync, readFileSync, existsSync, rmSync } from 'node:fs';
 import os from 'node:os';
+
 import { runClean } from './cli-cleaner.mjs';
+import { runDoctor } from './cli-doctor.mjs';
+import { runBackup, runRestore, runResetAdmin, runPluginsList } from './cli-data.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const args = process.argv.slice(2);
+const firstArg = args[0] || '';
 
-// ── Check Version & Help ───────────────────────────────────────────────────
+// ── Check Version ────────────────────────────────────────────────────────────
 if (args.includes('-v') || args.includes('--version')) {
   try {
     const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf-8'));
@@ -22,31 +26,70 @@ if (args.includes('-v') || args.includes('--version')) {
   process.exit(0);
 }
 
+// ── Help Documentation ───────────────────────────────────────────────────────
 if (args.includes('-h') || args.includes('--help')) {
   console.log(`Usage: npx openlearn-next [command] [options]
 
 Commands:
+  doctor                   运行环境自检与健康诊断 (Node.js/硬件内存/存储权限/端口/网络)
+  backup [file]            一键数据库快照在线备份 (默认输出至当前目录 openlearn_backup_*.db)
+  restore <file>           从备份快照文件安全还原数据 (自动生成现有数据库回滚副本)
+  reset-admin [options]    重置系统管理员 (admin) 密码 (默认重置为 admin)
+                           选项: --password, -P <pwd>
+  plugins [list]           查看当前已安装的平台插件清单与加载状态
   clean, clean-cache       清理 NPX 包缓存与本地临时运行数据
                            选项:
                              --npx     仅清理 ~/.npm/_npx 中的 openlearn-next 历史包缓存
                              --db      重置本地 SQLite 数据库 (下次启动全新自动初始化)
                              --all     清理全部（NPX 历史包 + 运行临时日志 + 重置数据库）
 
-Options:
-  -p, --port <port>        监听端口 (默认: 9000)
+Server Options:
+  -p, --port <port>        服务监听端口 (默认: 9000 或 process.env.PORT)
+  -H, --host <host>        绑定网络接口 IP (默认: 0.0.0.0 局域网全网监听)
+  -o, --open               服务就绪后自动唤起系统默认浏览器访问
+  --demo, --temp           临时演示沙盒模式：在系统临时目录创建一次性数据库，退出即自动销毁
+  --cors <origins>         允许跨域访问来源白名单 (多个以逗号分隔，如: "http://example.com,*")
+  --db-path <path>         自定义 SQLite 数据库文件绝对路径
   -v, --version            显示版本号
   -h, --help               显示此帮助信息
-  --clean, --clean-cache   快捷清理缓存并退出
 
-Environment:
-  OPENLEARN_DB_PATH        SQLite database path (默认: ~/openlearn-next/data.db)
-  GEMINI_API_KEY           Optional fallback AI key; configured via admin dashboard
+Environment Variables:
+  PORT                     HTTP 服务端口 (默认: 9000)
+  HOST                     监听主机地址 (默认: 0.0.0.0)
+  OPENLEARN_DB_PATH        SQLite 数据库绝对路径 (默认: ~/openlearn-next/data.db)
+  ALLOWED_ORIGINS          CORS 白名单来源 (默认放行同源与开发环境)
+  GEMINI_API_KEY           AI 助手兜底密钥 (推荐在管理员后台界面配置)
 `);
   process.exit(0);
 }
 
-// ── Handle Clean Command ───────────────────────────────────────────────────
-const firstArg = args[0];
+// ── Extract Options Helper ──────────────────────────────────────────────────
+let customPort = null;
+let customHost = null;
+let customDbPath = null;
+let customCors = null;
+const isDemo = args.includes('--demo') || args.includes('--temp');
+const isOpen = args.includes('-o') || args.includes('--open');
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '-p' || args[i] === '--port') {
+    customPort = args[++i];
+  } else if (args[i] === '-H' || args[i] === '--host') {
+    customHost = args[++i];
+  } else if (args[i] === '--db-path') {
+    customDbPath = args[++i];
+  } else if (args[i] === '--cors') {
+    customCors = args[++i];
+  }
+}
+
+if (customPort) process.env.PORT = customPort;
+if (customHost) process.env.HOST = customHost;
+if (customCors) process.env.ALLOWED_ORIGINS = customCors;
+if (customDbPath) process.env.OPENLEARN_DB_PATH = resolve(customDbPath);
+if (isOpen) process.env.OPEN_BROWSER = 'true';
+
+// ── Command: clean / clean-cache ─────────────────────────────────────────────
 const isCleanCommand =
   firstArg === 'clean' ||
   firstArg === 'clean-cache' ||
@@ -63,17 +106,64 @@ if (isCleanCommand) {
   process.exit(0);
 }
 
-let port = null;
+// ── Command: doctor ──────────────────────────────────────────────────────────
+if (firstArg === 'doctor' || args.includes('--doctor')) {
+  const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 9000;
+  const res = await runDoctor({ port, dbPath: process.env.OPENLEARN_DB_PATH });
+  process.exit(res.ok ? 0 : 1);
+}
 
-for (let i = 0; i < args.length; i++) {
-  if (args[i] === '-p' || args[i] === '--port') {
-    port = args[++i];
+// ── Command: backup ──────────────────────────────────────────────────────────
+if (firstArg === 'backup' || args.includes('--backup')) {
+  const backupIdx = args.findIndex((a) => a === 'backup' || a === '--backup');
+  let targetFile = undefined;
+  if (backupIdx !== -1 && args[backupIdx + 1] && !args[backupIdx + 1].startsWith('-')) {
+    targetFile = args[backupIdx + 1];
+  }
+  const res = await runBackup(targetFile, { dbPath: process.env.OPENLEARN_DB_PATH });
+  process.exit(res.ok ? 0 : 1);
+}
+
+// ── Command: restore ─────────────────────────────────────────────────────────
+if (firstArg === 'restore' || args.includes('--restore')) {
+  const restoreIdx = args.findIndex((a) => a === 'restore' || a === '--restore');
+  let sourceFile = undefined;
+  if (restoreIdx !== -1 && args[restoreIdx + 1] && !args[restoreIdx + 1].startsWith('-')) {
+    sourceFile = args[restoreIdx + 1];
+  }
+  const res = await runRestore(sourceFile, { dbPath: process.env.OPENLEARN_DB_PATH });
+  process.exit(res.ok ? 0 : 1);
+}
+
+// ── Command: reset-admin ─────────────────────────────────────────────────────
+if (firstArg === 'reset-admin' || args.includes('--reset-admin')) {
+  let newPassword = 'admin';
+  const pwdIdx = args.findIndex((a) => a === '--password' || a === '-P');
+  if (pwdIdx !== -1 && args[pwdIdx + 1] && !args[pwdIdx + 1].startsWith('-')) {
+    newPassword = args[pwdIdx + 1];
+  } else if (args[1] && !args[1].startsWith('-')) {
+    newPassword = args[1];
   }
+  const res = await runResetAdmin(newPassword, { dbPath: process.env.OPENLEARN_DB_PATH });
+  process.exit(res.ok ? 0 : 1);
+}
+
+// ── Command: plugins / plugins list ──────────────────────────────────────────
+if (firstArg === 'plugins' || args.includes('--plugins')) {
+  const res = await runPluginsList({ dbPath: process.env.OPENLEARN_DB_PATH });
+  process.exit(res.ok ? 0 : 1);
 }
 
-if (port) process.env.PORT = port;
+// ── Normal Server Startup ────────────────────────────────────────────────────
+let demoDir = null;
 
-if (!process.env.OPENLEARN_DB_PATH) {
+if (isDemo) {
+  demoDir = join(os.tmpdir(), `openlearn-demo-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`);
+  mkdirSync(demoDir, { recursive: true });
+  process.env.OPENLEARN_DB_PATH = join(demoDir, 'data.db');
+  console.log(`[openlearn-next] 临时沙盒模式已激活: ${demoDir}`);
+  console.log(`[openlearn-next] 提示: 退出程序时将自动销毁沙盒数据，不保留任何历史记录。`);
+} else if (!process.env.OPENLEARN_DB_PATH) {
   const dataDir = join(os.homedir(), 'openlearn-next');
   mkdirSync(dataDir, { recursive: true });
   process.env.OPENLEARN_DB_PATH = join(dataDir, 'data.db');
@@ -82,7 +172,11 @@ if (!process.env.OPENLEARN_DB_PATH) {
 process.env.NODE_ENV = process.env.NODE_ENV || 'production';
 
 console.log(`[openlearn-next] PORT=${process.env.PORT || '9000'}`);
+console.log(`[openlearn-next] HOST=${process.env.HOST || '0.0.0.0'}`);
 console.log(`[openlearn-next] DB=${process.env.OPENLEARN_DB_PATH}`);
+if (process.env.ALLOWED_ORIGINS) {
+  console.log(`[openlearn-next] CORS_ALLOWED=${process.env.ALLOWED_ORIGINS}`);
+}
 
 const serverPath = join(__dirname, 'dist', 'server.cjs');
 const child = spawn('node', [serverPath], {
@@ -90,6 +184,40 @@ const child = spawn('node', [serverPath], {
   env: { ...process.env },
 });
 
+let cleanedUp = false;
+const cleanup = () => {
+  if (cleanedUp) return;
+  cleanedUp = true;
+  if (isDemo && demoDir && existsSync(demoDir)) {
+    try {
+      rmSync(demoDir, { recursive: true, force: true });
+      console.log('\n[openlearn-next] 临时沙盒环境清理完毕。');
+    } catch {}
+  }
+};
+
+let isShuttingDown = false;
+const handleSignal = (sig) => {
+  if (isShuttingDown) return;
+  isShuttingDown = true;
+  if (child && !child.killed) {
+    child.kill(sig);
+    // 3秒后强制保底退出
+    setTimeout(() => {
+      cleanup();
+      process.exit(0);
+    }, 3000).unref();
+  } else {
+    cleanup();
+    process.exit(0);
+  }
+};
+
+process.on('SIGINT', () => handleSignal('SIGINT'));
+process.on('SIGTERM', () => handleSignal('SIGTERM'));
+process.on('exit', cleanup);
+
 child.on('exit', (code) => {
+  cleanup();
   process.exit(code || 0);
 });