openlearn-next 0.6.0 → 0.7.4

package/README.md

@@ -98,7 +98,11 @@ openlearn-next                  # 启动
 npm update -g openlearn-next    # 更新
 ```
 
-默认账号：`admin` / `admin`（管理员）、`teacher` / `teacher`（教师）。
+种子账号用户名仍是 `admin`（管理员）和 `teacher`（教师），但**不再使用与用户名相同的默认密码**。首次空库启动时：
+
+- 若设置了 `OPENLEARN_ADMIN_PASSWORD` / `OPENLEARN_TEACHER_PASSWORD`，使用该口令。口令若仍等于用户名，登录后必须立刻修改，期间除改密、登出和会话查询外，其余 `/api` 请求（含 GET）返回 403。
+- 未设置时随机生成 20 位口令，明文只打印一次，并写入 `storage/bootstrap-credentials.txt`（权限 600）。请在首次登录后修改并删除该文件。
+- 已有数据库若口令仍是 `admin` / `teacher`，可以登录，但同样被强制改密拦住，直到 `POST /api/auth/change-password` 成功。不要在生产环境设置 `PLAYWRIGHT_TEST`（该变量会保留测试用默认口令并跳过改密门禁）。
 
 ### 本地开发
 

package/cli-data.mjs

@@ -1,6 +1,96 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const requireFromHere = createRequire(import.meta.url);
+
+/**
+ * 敏感文件权限收紧（与 `packages/core/db/secure-files.ts` 同一口径）。
+ *
+ * ## 为什么在这里内联而不是 import
+ *
+ * CLI 脚本必须能在**发布包**里独立运行 —— 发布清单（package.json `files`）只有
+ * `cli-*.mjs` 与 `dist/*.cjs`，源码里的 `secure-files.ts` 并不存在。走 `import()`
+ * 会在任何非源码检出环境直接 MODULE_NOT_FOUND（与 `loadCliMigrator` 踩的是同一个坑）。
+ *
+ * ## 口径
+ *
+ * - 备份目录 0700、备份文件 0600：备份是**全量学生数据的未加密副本**。
+ * - **只收紧不放宽**：已合规（或比基线更严，如 0400）时不动，只在真的含有
+ *   group/other 位时才 chmod。
+ * - Windows 等不支持 chmod 的环境：try/catch 吞掉，不阻断备份/还原。
+ */
+const SECURE_FILE_MODE = 0o600;
+const SECURE_DIR_MODE = 0o700;
+/** group/other 位掩码：任何一位为 1 即视为「宽于基线」 */
+const GROUP_OTHER_BITS = 0o077;
+
+/**
+ * 把已存在的文件收紧到 600。
+ * @returns 是否发生了实际变更
+ */
+function hardenFile(filePath) {
+  try {
+    const mode = fs.statSync(filePath).mode & 0o777;
+    if ((mode & GROUP_OTHER_BITS) === 0) return false;
+    fs.chmodSync(filePath, SECURE_FILE_MODE);
+    return true;
+  } catch {
+    // 不存在 / Windows 不支持 chmod：交给调用方后续处理
+    return false;
+  }
+}
+
+/**
+ * 确保目录存在且合规：不存在则按 0700 创建，已存在但过宽则收紧。
+ */
+function ensureSecureDir(dirPath) {
+  try {
+    // mode 只对**新建**目录生效；0700 不含 group/other 位，因此 umask 不会削掉任何一位。
+    fs.mkdirSync(dirPath, { recursive: true, mode: SECURE_DIR_MODE });
+  } catch {
+    // 目录可能已存在或不可创建
+  }
+  try {
+    const mode = fs.statSync(dirPath).mode & 0o777;
+    if ((mode & GROUP_OTHER_BITS) !== 0) fs.chmodSync(dirPath, SECURE_DIR_MODE);
+  } catch {
+    // 同上
+  }
+}
+
+/**
+ * 加载迁移器（`pnpm build` 产出的 `dist/cli-migrator.cjs`）。
+ *
+ * ## 为什么不再直接 `import('./packages/core/db/migrator.js')`
+ *
+ * 那条路径**在任何环境都不存在**：源码检出里只有 `migrator.ts`，发布包的 `files`
+ * 清单里也只有 `dist/*` 与几个 `cli-*.mjs`。于是 `openlearn-next migrate status` /
+ * `migrate rollback` 一旦走到加载点就抛 MODULE_NOT_FOUND —— 两条帮助里宣传的命令
+ * 实际从未可用（`_migrations` 表不存在时会在更早的分支提前返回，把这个缺陷藏住了）。
+ *
+ * 现在与 `env-validation` 同法：构建期打成独立 CJS，运行时用 createRequire 载入
+ * （而不是 `await import('...')`，后者会被 Vite/Vitest 在转换期静态解析）。
+ *
+ * 产物缺失时给出**可操作**的报错，而不是让用户对着 MODULE_NOT_FOUND 猜。
+ */
+export function loadCliMigrator() {
+  const artifact = path.join(__dirname, 'dist', 'cli-migrator.cjs');
+  if (!fs.existsSync(artifact)) {
+    const error = new Error(
+      `迁移器构建产物缺失：${artifact}\n` +
+        '  源码检出请先执行 `pnpm build`（或 `bash scripts/build-cli-artifacts.sh`）；\n' +
+        '  若你安装的是发布包，这属于打包缺陷，请反馈。',
+    );
+    error.code = 'CLI_MIGRATOR_ARTIFACT_MISSING';
+    throw error;
+  }
+  return requireFromHere(artifact);
+}
 
 /**
  * 解析本地目标数据库路径
@@ -32,17 +122,90 @@ export async function runBackup(outputFile, options = {}) {
   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 isFull = Boolean(options.full);
+  const defaultExt = isFull ? '.zip' : '.db';
   const target = outputFile
     ? path.resolve(outputFile)
-    : path.resolve(process.cwd(), `openlearn_backup_${timestamp}.db`);
+    : path.resolve(process.cwd(), `openlearn_${isFull ? 'full_backup' : 'backup'}_${timestamp}${defaultExt}`);
+
+  ensureSecureDir(path.dirname(target));
 
-  fs.mkdirSync(path.dirname(target), { recursive: true });
+  if (isFull) {
+    try {
+      const JSZip = (await import('jszip')).default;
+      const zip = new JSZip();
+
+      // 1. 内存/临时备份 SQLite 数据库
+      const Database = (await import('better-sqlite3')).default;
+      const tempDbPath = path.join(os.tmpdir(), `openlearn_temp_backup_${Date.now()}.db`);
+      const db = new Database(dbPath, { readonly: true });
+      await db.backup(tempDbPath);
+      db.close();
+      const dbBuffer = fs.readFileSync(tempDbPath);
+      try {
+        fs.unlinkSync(tempDbPath);
+      } catch {}
+      zip.file('data.db', dbBuffer);
+
+      // 2. 递归打包 uploads 与 storage 目录
+      const dataDir = process.env.OPENLEARN_DATA_DIR || path.dirname(dbPath);
+      const uploadsDir = path.join(dataDir, 'uploads');
+      const storageDir = path.join(dataDir, 'storage');
+
+      const addDirToZip = (dir, prefix) => {
+        if (!fs.existsSync(dir)) return;
+        const items = fs.readdirSync(dir, { withFileTypes: true });
+        for (const item of items) {
+          const itemPath = path.join(dir, item.name);
+          const zipRel = prefix ? `${prefix}/${item.name}` : item.name;
+          if (item.isDirectory()) {
+            addDirToZip(itemPath, zipRel);
+          } else if (item.isFile()) {
+            zip.file(zipRel, fs.readFileSync(itemPath));
+          }
+        }
+      };
+
+      addDirToZip(uploadsDir, 'uploads');
+      addDirToZip(storageDir, 'storage');
+
+      // 3. 元数据信息
+      zip.file(
+        'metadata.json',
+        JSON.stringify(
+          {
+            version: '0.6.0',
+            type: 'openlearn-full-backup',
+            timestamp: Date.now(),
+            createdAt: new Date().toISOString(),
+          },
+          null,
+          2,
+        ),
+      );
+
+      const zipBuffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+      fs.writeFileSync(target, zipBuffer);
+      // 整包备份含全量学生数据（数据库 + 课件 + 作业）—— 落盘即 0600
+      hardenFile(target);
+      const stat = fs.statSync(target);
+      const sizeKb = Math.round(stat.size / 1024);
+      log(`✓ 系统全量整包备份完成（数据库 + 课件 uploads + 作业 storage）！`);
+      log(`  全量归档文件: ${target} (${sizeKb} KB)`);
+      return { ok: true, targetFile: target };
+    } catch (fullErr) {
+      log(`✗ 全量备份生成失败: ${fullErr.message}`);
+      return { ok: false, error: fullErr.message };
+    }
+  }
 
   try {
     const Database = (await import('better-sqlite3')).default;
     const db = new Database(dbPath, { readonly: true });
     await db.backup(target);
     db.close();
+    // 冷备是全量学生数据的未加密副本 —— 落盘即 0600
+    hardenFile(target);
 
     const stat = fs.statSync(target);
     const sizeKb = Math.round(stat.size / 1024);
@@ -53,6 +216,8 @@ export async function runBackup(outputFile, options = {}) {
     // 降级为物理文件复制
     try {
       fs.copyFileSync(dbPath, target);
+      // copyFileSync 按默认 umask 落盘 → 收紧到 600
+      hardenFile(target);
       const stat = fs.statSync(target);
       const sizeKb = Math.round(stat.size / 1024);
       log(`✓ 数据库文件冷备完成（直接镜像模式）：${target} (${sizeKb} KB)`);
@@ -65,15 +230,125 @@ export async function runBackup(outputFile, options = {}) {
 }
 
 /**
- * 数据安全回滚与还原
+ * 数据安全回滚与还原（支持 .db 镜像与 .zip 全量整包）
  * @param {string} sourceFile
  * @param {Object} [options]
  * @returns {Promise<{ ok: boolean, error?: string }>}
  */
+/**
+ * 读取 SQLite 快照的完整性信息。
+ *
+ * 迁移失败后的 `pre_migration_*.db` 与 `backup` 产物都是普通 SQLite 镜像：
+ * 直接覆盖主库前必须确认它真的能打开、`integrity_check` 通过，否则「恢复」
+ * 会用一个坏文件替掉还能用的库。
+ *
+ * @param {string} filePath
+ * @returns {Promise<{ ok: boolean, error?: string, migrations: string[] }>}
+ */
+async function inspectSqliteSnapshot(filePath) {
+  const Database = (await import('better-sqlite3')).default;
+  let db;
+  try {
+    db = new Database(filePath, { readonly: true, fileMustExist: true });
+    const integrity = db.pragma('integrity_check', { simple: true });
+    if (String(integrity).toLowerCase() !== 'ok') {
+      return { ok: false, error: `快照完整性校验失败: ${integrity}`, migrations: [] };
+    }
+    let migrations = [];
+    try {
+      migrations = db
+        .prepare('SELECT name FROM _migrations ORDER BY name')
+        .all()
+        .map((row) => String(row.name));
+    } catch {
+      // 极早期/非平台数据库没有 _migrations —— 交给迁移兼容性检查给出明确提示。
+      migrations = [];
+    }
+    return { ok: true, migrations };
+  } catch (err) {
+    return { ok: false, error: `无法打开快照（不是有效的 SQLite 数据库？）: ${err.message}`, migrations: [] };
+  } finally {
+    try {
+      db?.close();
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/** 当前代码自带的迁移文件（用于判断快照是否来自「未来版本」）。 */
+function listCurrentMigrationNames(migrationsDir) {
+  try {
+    // DB 里 `_migrations.name` 存的是**去扩展名**的迁移名（migrator 的约定）。
+    return fs
+      .readdirSync(migrationsDir)
+      .filter((name) => name.endsWith('.sql'))
+      .map((name) => name.replace(/\.sql$/, ''))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 迁移兼容性预检。
+ *
+ * - 快照里有当前代码不认识的迁移 → 快照来自更新版本，恢复后再启动会触发
+ *   checksum/结构不匹配。默认拒绝，`--force` 显式放行（管理员可能就是要回滚）。
+ * - 当前代码有快照没有的迁移 → 正常升级路径，下次启动会补上。
+ */
+function checkMigrationCompatibility(snapshotMigrations, migrationsDir) {
+  const current = new Set(listCurrentMigrationNames(migrationsDir));
+  const unknown = snapshotMigrations.filter((name) => current.size > 0 && !current.has(name));
+  const pending = [...current].filter((name) => !snapshotMigrations.includes(name));
+  return { unknown, pending };
+}
+
+/** 用 VACUUM INTO 生成一致性安全副本（直接 copy 会漏掉 WAL 里未 checkpoint 的页）。 */
+async function createSafetySnapshot(dbPath, backupsDir) {
+  const Database = (await import('better-sqlite3')).default;
+  // 备份目录装着全量学生数据副本：创建即 0700，不依赖 umask
+  ensureSecureDir(backupsDir);
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}_${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  const target = path.join(backupsDir, `pre_restore_${stamp}.db`);
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    db.exec(`VACUUM INTO '${target.replace(/'/g, "''")}'`);
+  } finally {
+    db.close();
+  }
+  // VACUUM INTO 生成的文件按默认 umask 落盘（实测 644）→ 收紧到 600
+  hardenFile(target);
+  return target;
+}
+
+/**
+ * 安全还原（Issue #150 加固）。
+ *
+ * 与旧实现的区别：
+ * 1. 先校验快照（SQLite 头 + `PRAGMA integrity_check`）再动主库；
+ * 2. 迁移兼容性预检：快照来自更新版本时默认拒绝（`force: true` 放行）；
+ * 3. 安全副本用 `VACUUM INTO` 生成，落在 `BACKUP_DIR`（默认 `<dbDir>/backups`），
+ *    失败时可原路恢复；
+ * 4. 原子替换：先写临时文件再 `rename`，避免半截库；替换后清理 `-wal`/`-shm`。
+ *
+ * 停服仍是操作者的责任：SQLite 文件被运行中的进程持有替换会得到旧句柄。
+ *
+ * @param {string} [sourceFile] `.db` 快照 / 全量 `.zip` 备份
+ * @param {Object} [options]
+ * @param {string} [options.dbPath]
+ * @param {boolean} [options.force] 允许恢复「快照迁移比当前代码更新」的库
+ * @param {string} [options.migrationsDir]
+ * @param {string} [options.backupsDir]
+ * @param {boolean} [options.silent]
+ */
 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>';
+    const msg =
+      '未指定待还原的备份文件。用法: npx openlearn-next restore <backup.db|backup.zip|--snapshot pre_migration_xxx.db>';
     log(`✗ ${msg}`);
     return { ok: false, error: msg };
   }
@@ -85,15 +360,23 @@ export async function runRestore(sourceFile, options = {}) {
     return { ok: false, error: msg };
   }
 
-  // 校验 SQLite 文件头 (Magic Header: "SQLite format 3\0")
+  const dbPath = resolveDbPath(options.dbPath);
+  const dbDir = path.dirname(dbPath);
+  const migrationsDir = options.migrationsDir || path.resolve(process.cwd(), 'migrations');
+  const backupsDir = options.backupsDir || process.env.BACKUP_DIR || path.join(dbDir, 'backups');
+  fs.mkdirSync(dbDir, { recursive: true });
+
+  // 识别文件类型：校验头字节（PK 为 Zip 压缩包，SQLite 为数据库镜像）
+  let isZip = false;
   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}`;
+    if (buffer[0] === 0x50 && buffer[1] === 0x4b) {
+      isZip = true;
+    } else if (!buffer.toString('utf-8').startsWith('SQLite format 3')) {
+      const msg = `文件既非 SQLite 数据库镜像亦非合法的 OpenLearn 备份 ZIP: ${src}`;
       log(`✗ ${msg}`);
       return { ok: false, error: msg };
     }
@@ -102,30 +385,99 @@ export async function runRestore(sourceFile, options = {}) {
     return { ok: false, error: err.message };
   }
 
-  const dbPath = resolveDbPath(options.dbPath);
-  const dbDir = path.dirname(dbPath);
-  fs.mkdirSync(dbDir, { recursive: true });
+  // ── 1. 把待恢复的数据库落到临时文件并校验 ───────────────────────────────
+  const stagePath = path.join(dbDir, `.restore_stage_${process.pid}_${Date.now()}.db`);
+  let extraction = null;
+  try {
+    if (isZip) {
+      const JSZip = (await import('jszip')).default;
+      const zip = await JSZip.loadAsync(fs.readFileSync(src));
+      const dbEntry = zip.file('data.db');
+      if (!dbEntry) throw new Error('ZIP 归档中未找到 data.db 数据库主体');
+      fs.writeFileSync(stagePath, await dbEntry.async('nodebuffer'));
+      extraction = zip;
+    } else {
+      fs.copyFileSync(src, stagePath);
+    }
+    // 暂存文件随后会被 rename 成主库 —— 权限按默认 umask 落盘（实测 644），
+    // 这里先收紧到 600，避免主库以宽权限重生。
+    hardenFile(stagePath);
 
-  // 创建自动回滚副本
-  if (fs.existsSync(dbPath)) {
-    const bakFile = `${dbPath}.bak_${Date.now()}`;
-    fs.copyFileSync(dbPath, bakFile);
-    log(`ℹ 已为现有数据库创建安全回滚镜像: ${bakFile}`);
-  }
+    const inspection = await inspectSqliteSnapshot(stagePath);
+    if (!inspection.ok) {
+      const msg = inspection.error || '快照校验失败';
+      log(`✗ ${msg}`);
+      return { ok: false, error: msg };
+    }
 
-  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 };
+    // ── 2. 迁移兼容性预检 ────────────────────────────────────────────────
+    const { unknown, pending } = checkMigrationCompatibility(inspection.migrations, migrationsDir);
+    if (unknown.length > 0) {
+      const msg =
+        `快照包含当前代码不认识的迁移（来自更新版本？）：${unknown.join(', ')}。` +
+        '恢复后再启动会触发结构与 checksum 不匹配；确认要回滚请加 --force。';
+      if (!options.force) {
+        log(`✗ ${msg}`);
+        return { ok: false, error: msg, unknownMigrations: unknown };
+      }
+      log(`⚠ ${msg}（--force 已放行）`);
+    }
+    if (pending.length > 0) {
+      log(`ℹ 快照缺少 ${pending.length} 条当前迁移，恢复后首次启动会自动补齐`);
+    }
+
+    // ── 3. 安全副本 ─────────────────────────────────────────────────────
+    let safetyBackup;
+    if (fs.existsSync(dbPath)) {
+      safetyBackup = await createSafetySnapshot(dbPath, backupsDir);
+      log(`ℹ 已创建恢复前安全副本: ${safetyBackup}`);
+    }
+
+    // ── 4. 原子替换 + 清理 WAL/SHM ──────────────────────────────────────
+    fs.renameSync(stagePath, dbPath);
+    // rename 会继承源文件的权限位；再收紧一次，确保主库始终 ≤600
+    hardenFile(dbPath);
+    for (const suffix of ['-wal', '-shm']) {
+      const sidecar = `${dbPath}${suffix}`;
+      if (fs.existsSync(sidecar)) fs.unlinkSync(sidecar);
+    }
+
+    // zip 备份里的 uploads/ 与 storage/ 一并还原（沿用旧行为）
+    if (extraction) {
+      const dataDir = process.env.OPENLEARN_DATA_DIR || dbDir;
+      let extractedCount = 0;
+      for (const [relPath, file] of Object.entries(extraction.files)) {
+        if (file.dir) continue;
+        if (relPath.startsWith('uploads/') || relPath.startsWith('storage/')) {
+          const dest = path.join(dataDir, relPath);
+          fs.mkdirSync(path.dirname(dest), { recursive: true });
+          fs.writeFileSync(dest, await file.async('nodebuffer'));
+          extractedCount++;
+        }
+      }
+      log(`✓ 全量整包还原成功！数据库与 ${extractedCount} 个资源文件已写入 ${dataDir}`);
+    } else {
+      log(`✓ 数据库还原成功！已切换为 ${src} 的数据。`);
+    }
+
+    return {
+      ok: true,
+      restoredFrom: src,
+      safetyBackup,
+      migrations: inspection.migrations.length,
+      pendingMigrations: pending.length,
+    };
   } catch (err) {
-    log(`✗ 覆盖写入数据库失败: ${err.message}`);
+    log(`✗ 还原失败: ${err.message}`);
     return { ok: false, error: err.message };
+  } finally {
+    if (fs.existsSync(stagePath)) {
+      try {
+        fs.unlinkSync(stagePath);
+      } catch {
+        /* ignore */
+      }
+    }
   }
 }
 
@@ -135,12 +487,23 @@ export async function runRestore(sourceFile, options = {}) {
  * @param {Object} [options]
  * @returns {Promise<{ ok: boolean, error?: string }>}
  */
-export async function runResetAdmin(newPassword = 'admin', options = {}) {
+function generateResetPassword() {
+  const alphabet = 'abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+  const bytes = crypto.randomBytes(20);
+  let out = '';
+  for (let i = 0; i < bytes.length; i++) out += alphabet[bytes[i] % alphabet.length];
+  if (!/[A-Za-z]/.test(out) || !/[0-9]/.test(out)) out = `${out.slice(0, 18)}a7`;
+  return out;
+}
+
+export async function runResetAdmin(newPassword, options = {}) {
   const log = options.silent ? () => {} : (msg) => console.log(`[openlearn-next] ${msg}`);
   const dbPath = resolveDbPath(options.dbPath);
+  const generated = newPassword === undefined || newPassword === null || String(newPassword).length === 0;
+  const password = generated ? generateResetPassword() : String(newPassword);
 
   if (!fs.existsSync(dbPath)) {
-    const msg = `数据库尚未初始化 (${dbPath})。请直接启动一次平台即可生成默认 admin/admin 账号。`;
+    const msg = `数据库尚未初始化 (${dbPath})。请先启动一次平台，口令来自环境变量或 storage/bootstrap-credentials.txt。`;
     log(`ℹ ${msg}`);
     return { ok: false, error: msg };
   }
@@ -149,10 +512,10 @@ export async function runResetAdmin(newPassword = 'admin', options = {}) {
     let hash;
     try {
       const bcrypt = (await import('bcryptjs')).default;
-      hash = bcrypt.hashSync(newPassword, 10);
+      hash = bcrypt.hashSync(password, 10);
     } catch {
-      const crypto = await import('node:crypto');
-      hash = crypto.createHash('sha256').update(newPassword).digest('hex');
+      const nodeCrypto = await import('node:crypto');
+      hash = nodeCrypto.createHash('sha256').update(password).digest('hex');
     }
 
     const Database = (await import('better-sqlite3')).default;
@@ -166,16 +529,33 @@ export async function runResetAdmin(newPassword = 'admin', options = {}) {
       return { ok: false, error: msg };
     }
 
-    const updateRes = db.prepare('UPDATE users SET password_hash = ? WHERE username = ?').run(hash, 'admin');
+    const hasMustChange = db
+      .prepare('PRAGMA table_info(users)')
+      .all()
+      .some((col) => col.name === 'must_change_password');
+    const mustChange = password === 'admin' || generated ? 1 : 0;
+    const updateSql = hasMustChange
+      ? 'UPDATE users SET password_hash = ?, must_change_password = ? WHERE username = ?'
+      : 'UPDATE users SET password_hash = ? WHERE username = ?';
+    const updateArgs = hasMustChange ? [hash, mustChange, 'admin'] : [hash, 'admin'];
+    const updateRes = db.prepare(updateSql).run(...updateArgs);
 
     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})`);
+      if (hasMustChange) {
+        db.prepare(
+          'INSERT INTO users (id, username, password_hash, role, name, created_at, must_change_password) VALUES (?, ?, ?, ?, ?, ?, ?)',
+        ).run(`usr_admin_${Date.now()}`, 'admin', hash, 'administrator', 'System Admin', Date.now(), mustChange);
+      } else {
+        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。口令：${password}`);
     } else {
-      log(`✓ 管理员 (admin) 密码已成功重置为: ${newPassword}`);
+      log(`✓ 管理员 (admin) 口令已重置。口令：${password}`);
+    }
+    if (mustChange) {
+      log('  该口令登录后必须立即修改。不要把口令设成用户名 admin。');
     }
 
     db.close();
@@ -263,3 +643,118 @@ export async function runPluginsList(options = {}) {
     return { ok: false, error: err.message };
   }
 }
+
+/**
+ * 查看数据库迁移状态清单 (已应用 / 待应用)
+ * @param {Object} [options]
+ * @returns {Promise<{ ok: boolean, applied?: Array<any>, pending?: Array<any>, error?: string }>}
+ */
+export async function runMigrateStatus(options = {}) {
+  const log = options.silent ? () => {} : (msg) => console.log(`[openlearn-next] ${msg}`);
+  const dbPath = resolveDbPath(options.dbPath);
+
+  if (!fs.existsSync(dbPath)) {
+    log(`✗ 数据库文件未找到: ${dbPath}`);
+    return { ok: false, error: 'Database file not found' };
+  }
+
+  try {
+    const Database = (await import('better-sqlite3')).default;
+    const db = new Database(dbPath, { readonly: true });
+
+    const tableCheck = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='_migrations'").get();
+    if (!tableCheck) {
+      log(`ℹ 数据库尚未执行过版本化迁移 (_migrations 表未建立)。`);
+      db.close();
+      return { ok: true, applied: [], pending: [] };
+    }
+
+    const appliedRows = db.prepare('SELECT name, applied_at, checksum FROM _migrations ORDER BY applied_at ASC').all();
+    db.close();
+
+    const { loadMigrationsFromDirectory, getDefaultMigrationsDir } = loadCliMigrator();
+    const allMigrations = loadMigrationsFromDirectory(getDefaultMigrationsDir());
+    const appliedSet = new Set(appliedRows.map((r) => r.name));
+    const pending = allMigrations.filter((m) => !appliedSet.has(m.name));
+
+    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}数据库迁移版本化状态 (总计 ${allMigrations.length} 个迁移脚本):${reset}`);
+      console.log(`  ${green}✓ 已应用 (${appliedRows.length} 个):${reset}`);
+      for (const row of appliedRows) {
+        const time = new Date(row.applied_at).toLocaleString();
+        console.log(`    ${green}●${reset} ${row.name.padEnd(35)} (应用时间: ${time})`);
+      }
+      if (pending.length > 0) {
+        console.log(`\n  ${yellow}○ 待应用 (${pending.length} 个):${reset}`);
+        for (const m of pending) {
+          console.log(`    ${yellow}○${reset} ${m.name}`);
+        }
+      } else {
+        console.log(`\n  ${green}✓ 架构版本全部对齐，无待执行的增量迁移。${reset}\n`);
+      }
+    }
+
+    return { ok: true, applied: appliedRows, pending };
+  } catch (err) {
+    log(`✗ 查询迁移状态失败: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * 安全回滚最近一次应用的单项迁移 (按 -- DOWN 逆操作)
+ * @param {Object} [options]
+ * @returns {Promise<{ ok: boolean, rolledBack?: string, error?: string }>}
+ */
+export async function runMigrateRollback(options = {}) {
+  const log = options.silent ? () => {} : (msg) => console.log(`[openlearn-next] ${msg}`);
+  const dbPath = resolveDbPath(options.dbPath);
+
+  if (!fs.existsSync(dbPath)) {
+    log(`✗ 数据库文件未找到: ${dbPath}`);
+    return { ok: false, error: 'Database file not found' };
+  }
+
+  try {
+    const Database = (await import('better-sqlite3')).default;
+    const db = new Database(dbPath);
+
+    const tableCheck = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='_migrations'").get();
+    if (!tableCheck) {
+      log(`✗ 数据库中未找到 _migrations 元表，无法执行回滚。`);
+      db.close();
+      return { ok: false, error: 'No _migrations table' };
+    }
+
+    const lastRow = db.prepare('SELECT name FROM _migrations ORDER BY applied_at DESC LIMIT 1').get();
+    if (!lastRow) {
+      log(`ℹ 数据库中当前暂无已应用的迁移记录可供回滚。`);
+      db.close();
+      return { ok: true };
+    }
+
+    const { loadMigrationsFromDirectory, getDefaultMigrationsDir, rollbackMigration } = loadCliMigrator();
+    const allMigrations = loadMigrationsFromDirectory(getDefaultMigrationsDir());
+    const targetMigration = allMigrations.find((m) => m.name === lastRow.name);
+
+    if (!targetMigration) {
+      log(`✗ 未在本地 migrations 目录中找到 "${lastRow.name}.sql"，无法获取 DOWN 段执行回滚。`);
+      db.close();
+      return { ok: false, error: `Migration file ${lastRow.name} not found` };
+    }
+
+    rollbackMigration(db, targetMigration);
+    db.close();
+    log(`✓ 成功回滚迁移: ${targetMigration.name} (已执行 DOWN 逆操作并清理 _migrations 记录)`);
+    return { ok: true, rolledBack: targetMigration.name };
+  } catch (err) {
+    log(`✗ 回滚迁移失败: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+}