@mjh-odoo/cli 0.1.0 → 0.1.6

package/src/commands.mjs

@@ -1,7 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parseEnv } from 'node:util';
 import { archiveDirectory, checkModuleNames, publicSettings } from './lib/environment.mjs';
-import { databaseName, serviceNames, withLock } from './project.mjs';
+import { databaseName, openProject, serviceNames, withLock } from './project.mjs';
+import { archiveLocation, archiveSource, resolveArchive, saveArchive, startupSeed, rememberRuntime, tagName, withArchiveCatalog } from './archive.mjs';
 
 const start = (ctx, services = ['odoo'], timeout = 300) => ctx.run(['up', '-d', '--no-build', '--wait', '--wait-timeout', String(timeout), ...services]);
 
@@ -31,6 +34,15 @@ export function configuration(ctx) {
 
 export async function up(ctx, options) {
   await withLock(ctx, async () => {
+    const seed = await startupSeed(ctx.root, ctx.values);
+    await rememberRuntime(ctx.root, ctx.values.PROJECT_NAME);
+    if (seed.reference) {
+      await seedDatabase(ctx, options, seed.reference);
+      await start(ctx, ['odoo'], options.waitTimeout);
+      console.log('Odoo: http://localhost:' + ctx.values.ODOO_HTTP_PORT);
+      return;
+    }
+    if (readRecovery(ctx)?.database === ctx.values.PGDATABASE) throw new Error('当前数据库恢复尚未完成，请先处理恢复任务。');
     const args = ['up', '-d', options.build ? '--build' : '--no-build', '--wait', '--wait-timeout', String(options.waitTimeout)];
     if (options.pull) args.push('--pull', options.pull);
     await ctx.run(args);
@@ -48,6 +60,7 @@ export async function down(ctx, options) {
   await withLock(ctx, async () => {
     if (options.volumes) console.error('删除本项目数据库和附件卷: ' + ctx.values.PROJECT_NAME);
     await ctx.run(args);
+    if (options.volumes) for (const file of [originsFile(ctx), recoveryFile(ctx)]) fs.rmSync(file, {force: true});
   });
 }
 
@@ -98,11 +111,22 @@ async function sql(ctx, database, query) {
   return JSON.parse(result || '[]');
 }
 
+function databases(ctx) {
+  return sql(ctx, 'postgres', "SELECT coalesce(json_agg(t), '[]'::json) FROM (SELECT datname AS name FROM pg_database WHERE NOT datistemplate AND datname <> 'postgres' ORDER BY datname) t");
+}
+
 export async function listDatabases(ctx, options) {
-  const data = await sql(ctx, 'postgres', "SELECT coalesce(json_agg(t), '[]'::json) FROM (SELECT datname AS name FROM pg_database WHERE NOT datistemplate AND datname <> 'postgres' ORDER BY datname) t");
-  const rows = data.map(row => ({...row, current: row.name === ctx.values.PGDATABASE}));
+  const origins = readOrigins(ctx);
+  const pending = readRecovery(ctx);
+  const rows = (await databases(ctx)).map(row => ({...row, current: row.name === ctx.values.PGDATABASE, origin: origins[row.name]}));
+  if (pending) {
+    const row = rows.find(row => row.name === pending.database);
+    const recovery = {recoverable: pending.disposable};
+    if (row) row.recovery = recovery;
+    else rows.push({name: pending.database, current: pending.database === ctx.values.PGDATABASE, recovery});
+  }
   if (options.json) console.log(JSON.stringify(rows, null, 2));
-  else for (const row of rows) console.log((row.current ? '* ' : '  ') + row.name);
+  else for (const row of rows) console.log((row.current ? '* ' : '  ') + row.name + (row.recovery ? '  待恢复处理' : ''));
 }
 
 export async function listModules(ctx, options) {
@@ -112,52 +136,330 @@ export async function listModules(ctx, options) {
   else for (const row of data) console.log(`${row.name.padEnd(40)} ${row.state.padEnd(14)} ${row.version || '-'}`);
 }
 
-async function validateZip(ctx, filename) {
+async function validateZip(ctx, filename, {quiet = false, build = false} = {}) {
   const fd = fs.openSync(filename, 'r');
-  try { await ctx.run(['run', '--rm', '--no-deps', '-T', '--entrypoint', 'python3', 'odoo', '/opt/odoo/scripts/backup_utils.py', 'validate'], {stdio: [fd, 'inherit', 'inherit']}); }
+  try { await ctx.run(['run', '--rm', '--no-deps', '-T', ...(build ? ['--build'] : []), '--entrypoint', 'python3', 'odoo', '/opt/odoo/scripts/backup_utils.py', 'validate'], {stdio: [fd, quiet ? 'ignore' : 2, 'inherit']}); }
   finally { fs.closeSync(fd); }
 }
 
+async function writeBackup(ctx, database, target) {
+  if (fs.existsSync(target)) throw new Error('存档已存在: ' + target);
+  fs.mkdirSync(path.dirname(target), {recursive: true});
+  const temporary = target + '.' + randomUUID() + '.part';
+  let fd = fs.openSync(temporary, 'wx', 0o600);
+  try {
+    await ctx.run(['exec', '-T', 'odoo', 'odoo', 'db', '-c', '/etc/odoo/odoo.conf', 'dump', database, '-'], {stdio: ['ignore', fd, 'inherit']});
+    fs.closeSync(fd);
+    fd = undefined;
+    await validateZip(ctx, temporary);
+    fs.linkSync(temporary, target);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    fs.rmSync(temporary, {force: true});
+  }
+}
+
 export async function backup(ctx, options) {
   const database = databaseName(options.database || ctx.values.PGDATABASE);
+  if (options.name !== undefined) {
+    const title = options.name.trim();
+    const note = (options.note || '').trim();
+    const tag = options.tag === undefined ? undefined : tagName(options.tag);
+    if (!title || title.length > 120 || note.length > 2000) throw new Error('请填写有效存档名称，名称最多 120 字，备注最多 2000 字。');
+    return withArchiveCatalog(ctx.root, true, (db, project) => withLock(ctx, async () => {
+      if (readRecovery(ctx)?.database === database) throw new Error('该数据库恢复尚未完成，无法保存存档。');
+      const id = randomUUID();
+      const file = archiveLocation(db, ctx.root, id);
+      const {environment, revision} = archiveSource(db, project, ctx.root);
+      await writeBackup(ctx, database, file);
+      let archive;
+      try {
+        archive = {id, projectId: project.id, title, note, environment, database, file,
+          bytes: fs.statSync(file).size, created: new Date().toISOString(), revision, source: 'backup', tags: tag ? [tag] : []};
+        saveArchive(db, archive, tag);
+      } catch (error) {
+        fs.rmSync(file, {force: true});
+        throw error;
+      }
+      console.log(options.json ? JSON.stringify(archive) : '存档已保存：' + title + ' (' + id + ')' + (tag ? ' · ' + tag : ''));
+    }));
+  }
+
   const stamp = new Date().toISOString().replace(/[:.]/g, '-');
   const target = path.resolve(options.file || path.join(archiveDirectory(ctx.values), database + '-' + stamp + '.zip'));
-  if (fs.existsSync(target)) throw new Error('存档已存在: ' + target);
-  await withLock(ctx, async () => {
-    fs.mkdirSync(path.dirname(target), {recursive: true});
-    const temporary = target + '.part';
-    let fd;
+  await withLock(ctx, () => {
+    if (readRecovery(ctx)?.database === database) throw new Error('该数据库恢复尚未完成，无法导出。');
+    return writeBackup(ctx, database, target);
+  });
+  console.log('存档已保存: ' + target);
+}
+
+export async function importArchive(ctx, filename, {name, json}) {
+  const original = path.resolve(filename);
+  const title = (name ?? path.basename(original).replace(/\.zip$/i, '').slice(0, 120)).trim();
+  if (!title || title.length > 120) throw new Error('请填写存档名称，最多 120 字。');
+  if (!fs.statSync(original, {throwIfNoEntry: false})?.isFile()) throw new Error('请提供已有的 Odoo ZIP 存档。');
+  await withArchiveCatalog(ctx.root, true, async (db, project) => {
+    const id = randomUUID();
+    const file = archiveLocation(db, ctx.root, id);
+    const temporary = file + '.part';
     try {
-      fd = fs.openSync(temporary, 'wx', 0o600);
-      await ctx.run(['exec', '-T', 'odoo', 'odoo', 'db', '-c', '/etc/odoo/odoo.conf', 'dump', database, '-'], {stdio: ['ignore', fd, 'inherit']});
-      fs.closeSync(fd);
-      fd = undefined;
-      await validateZip(ctx, temporary);
-      fs.linkSync(temporary, target);
-      console.log('存档已保存: ' + target);
-    } finally {
-      if (fd !== undefined) fs.closeSync(fd);
-      fs.rmSync(temporary, {force: true});
-    }
+      fs.copyFileSync(original, temporary, fs.constants.COPYFILE_EXCL);
+      if (process.platform !== 'win32') fs.chmodSync(temporary, 0o600);
+      await validateZip(ctx, temporary, {quiet: json, build: true});
+      fs.linkSync(temporary, file);
+      const row = {id, projectId: project.id, title, note: '', environment: '本机导入', database: '',
+        file, bytes: fs.statSync(file).size, created: new Date().toISOString(), revision: '', source: 'import'};
+      try { saveArchive(db, row); }
+      catch (error) { fs.rmSync(file, {force: true}); throw error; }
+      console.log(json ? JSON.stringify(row) : '已导入存档：' + title + ' (' + id + ')');
+    } finally { fs.rmSync(temporary, {force: true}); }
+  });
+}
+
+const originsFile = ctx => path.join(ctx.root, '.local', 'db-origins.json');
+
+function readOrigins(ctx) {
+  try { return Object.assign(Object.create(null), JSON.parse(fs.readFileSync(originsFile(ctx), 'utf8'))); }
+  catch (error) { if (error.code === 'ENOENT') return Object.create(null); throw error; }
+}
+
+function recordOrigin(ctx, database, archive, reference) {
+  const origins = readOrigins(ctx);
+  if (archive) origins[database] = {id: archive.id, title: archive.title, reference, created: archive.created};
+  else if (Object.hasOwn(origins, database)) delete origins[database];
+  else return;
+  writeEnv(originsFile(ctx), JSON.stringify(origins, null, 2) + '\n', 0o600);
+}
+
+const dbMaintenance = ['run', '--rm', '--no-deps', '-T'];
+const dbReady = ['up', '-d', '--wait', 'db'];
+
+async function runningServices(ctx) {
+  return (await ctx.run(['ps', '--status', 'running', '--services'], {capture: true})).split(/\r?\n/);
+}
+
+async function loadZip(ctx, source, database, force, container) {
+  const args = [...dbMaintenance, '--name', container, '--entrypoint', 'python3', 'odoo', '/opt/odoo/scripts/backup_utils.py', 'restore', database];
+  if (force) args.push('--force');
+  const fd = fs.openSync(source, 'r');
+  try { await ctx.run(args, {stdio: [fd, 'inherit', 'inherit']}); }
+  finally { fs.closeSync(fd); }
+}
+
+function dropDatabase(ctx, database) {
+  return ctx.run([...dbMaintenance, '--entrypoint', 'odoo', 'odoo', 'db', '-c', '/etc/odoo/odoo.conf', 'drop', database]);
+}
+
+const recoveryFile = ctx => path.join(ctx.root, '.local', 'db-recovery.json');
+
+function readRecovery(ctx) {
+  let record;
+  try { record = JSON.parse(fs.readFileSync(recoveryFile(ctx), 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  if (!record || typeof record.disposable !== 'boolean' || typeof record.resume !== 'boolean' ||
+    !/^mjh-restore-[0-9a-f-]{36}$/.test(record.container)) throw new Error('恢复记录无效，请检查 .local/db-recovery.json。');
+  databaseName(record.database);
+  return record;
+}
+
+async function removeInterrupted(ctx, record) {
+  const running = await ctx.docker(['ps', '-a', '--filter', 'name=^/' + record.container + '$', '--format', '{{.Names}}'], {capture: true});
+  if (running) throw new Error('恢复容器仍在运行，请等它退出后再重试。');
+  if (!record.disposable) throw new Error('上一次覆盖恢复尚未完成。请使用可信 ZIP 重新执行恢复并显式指定 --force。');
+  const rows = await databases(ctx);
+  if (rows.some(row => row.name === record.database)) await dropDatabase(ctx, record.database);
+  recordOrigin(ctx, record.database);
+  fs.rmSync(recoveryFile(ctx), {force: true});
+}
+
+async function verifyDatabase(ctx, database) {
+  const installedTable = await sql(ctx, database, "SELECT to_json(to_regclass('public.ir_module_module') IS NOT NULL)");
+  if (installedTable !== true ||
+    await sql(ctx, database, "SELECT to_json(EXISTS (SELECT 1 FROM ir_module_module WHERE name = 'base' AND state = 'installed'))") !== true) {
+    throw new Error('目标库未完成 Odoo 初始化：' + database);
+  }
+}
+
+async function restoreChecked(ctx, source, database, {force, disposable, resume, archive, reference}) {
+  const record = {database, disposable, resume, container: 'mjh-restore-' + randomUUID()};
+  writeEnv(recoveryFile(ctx), JSON.stringify(record), 0o600);
+  try {
+    console.log('正在恢复数据库和附件：' + database);
+    await loadZip(ctx, source, database, force, record.container);
+    console.log('正在验证 Odoo 数据库：' + database);
+    await verifyDatabase(ctx, database);
+    recordOrigin(ctx, database, archive, reference);
+    fs.rmSync(recoveryFile(ctx), {force: true});
+  } catch (error) {
+    if (!disposable) throw error;
+    try { await removeInterrupted(ctx, record); }
+    catch (cleanup) { throw new Error('恢复失败，目标库已隔离。清理失败：' + cleanup.message, {cause: error}); }
+    throw new Error('恢复失败，本次创建的数据库已清理。' + error.message, {cause: error});
+  }
+}
+
+export async function recoverDatabase(project) {
+  await withLock(project, async () => {
+    const ctx = await openProject(project.root, {runner: project.runner});
+    const record = readRecovery(ctx);
+    if (!record) throw new Error('没有待清理的恢复任务。');
+    await ctx.run(dbReady);
+    await removeInterrupted(ctx, record);
+    if (record.resume && record.database !== ctx.values.PGDATABASE) await start(ctx);
+    console.log('恢复残留已清理，可以重试。');
   });
 }
 
-export async function restore(ctx, options) {
-  const source = path.resolve(options.file);
+async function seedDatabase(ctx, {build, pull, waitTimeout}, reference) {
+  const database = databaseName(ctx.values.PGDATABASE);
+  if (database === 'postgres' || database === 'template0' || database === 'template1') throw new Error('请选择普通开发数据库作为首次加载的目标。');
+  const pullArgs = pull ? ['--pull', pull] : [];
+  await ctx.run([...dbReady, '--wait-timeout', String(waitTimeout), ...pullArgs]);
+  const previous = readRecovery(ctx);
+  if (previous?.database === database) await removeInterrupted(ctx, previous);
+  const running = await runningServices(ctx);
+  const rows = await databases(ctx);
+  if (running.includes('odoo') || rows.some(row => row.name !== database)) {
+    if (build) await ctx.run(['build', 'odoo']);
+    return;
+  }
+  const exists = rows.some(row => row.name === database);
+  if (exists) {
+    const relations = await sql(ctx, database, `SELECT to_json(EXISTS (
+      SELECT FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg_%'
+      AND c.relkind IN ('r','p','m','v','S','f')))`);
+    if (relations === true) {
+      if (build) await ctx.run(['build', 'odoo']);
+      return;
+    }
+    if (relations !== false) throw new Error('无法确认目标数据库为空。');
+  }
+  if (Object.keys(readOrigins(ctx)).length) throw new Error('环境已有恢复记录。请手动恢复数据库，或用 down -v 显式重置环境。');
+  const archive = await resolveArchive(ctx.root, reference);
+  if (build) await ctx.run(['build', 'odoo']);
+  console.log('首次加载存档：' + archive.title + ' (' + archive.id + ')');
+  if (readRecovery(ctx)) throw new Error('请先清理上一次恢复。');
+  await validateZip(ctx, archive.file);
+  await restoreChecked(ctx, archive.file, database, {force: exists, disposable: true, resume: false, archive, reference});
+}
+
+export async function restore(project, options) {
+  const selected = options.archive ? await resolveArchive(project.root, options.archive) : null;
+  const source = selected?.file || path.resolve(options.file);
   if (!fs.statSync(source, {throwIfNoEntry: false})?.isFile()) throw new Error('请提供已有的 ZIP 存档。');
-  const database = databaseName(options.database || ctx.values.PGDATABASE);
-  await withLock(ctx, async () => {
-    await validateZip(ctx, source);
-    await ctx.run(['up', '-d', '--wait', 'db']);
-    await ctx.run(['stop', 'odoo']);
-    const args = ['run', '--rm', '--no-deps', '-T', '--entrypoint', 'python3', 'odoo', '/opt/odoo/scripts/backup_utils.py', 'restore', database];
-    if (options.force) args.push('--force');
-    const fd = fs.openSync(source, 'r');
-    try { await ctx.run(args, {stdio: [fd, 'inherit', 'inherit']}); }
-    finally { fs.closeSync(fd); }
-    if (options.restart !== false) await start(ctx);
+  await withLock(project, async () => {
+    if (selected) console.log('恢复存档：' + selected.title + ' (' + selected.id + ')');
+    await validateZip(project, source);
+    const ctx = await openProject(project.root, {runner: project.runner});
+    const database = databaseName(options.database || ctx.values.PGDATABASE);
+    if (['postgres', 'template0', 'template1'].includes(database)) throw new Error('请选择普通开发数据库作为恢复目标。');
+    await ctx.run(dbReady);
+    const previous = readRecovery(ctx);
+    if (previous) {
+      if (previous.database !== database) throw new Error('请先清理上一次恢复，再恢复另一份数据库。');
+      if (previous.disposable) await removeInterrupted(ctx, previous);
+      else {
+        if (!options.force) throw new Error('上一次覆盖恢复尚未完成，请明确指定 --force 后重试。');
+        if (await ctx.docker(['ps', '-a', '--filter', 'name=^/' + previous.container + '$', '--format', '{{.Names}}'], {capture: true})) {
+          throw new Error('上一次恢复容器仍在运行。');
+        }
+      }
+    }
+    const exists = (await databases(ctx)).some(row => row.name === database);
+    if (exists && !options.force) throw new Error('目标数据库已存在，请使用新名称：' + database);
+    if (options.use && database === ctx.values.PGDATABASE) throw new Error('恢复并切换需要使用与当前库不同的新名称。');
+    const running = (await runningServices(ctx)).includes('odoo');
+    const resume = options.restart !== false && (running || previous?.resume || options.legacy === true);
+    if (running) await ctx.run(['stop', 'odoo']);
+    try {
+      await restoreChecked(ctx, source, database, {force: options.force, disposable: !exists && previous?.disposable !== false,
+        resume, archive: selected, reference: options.archive});
+    } catch (error) {
+      if (resume && (database !== ctx.values.PGDATABASE || !exists)) {
+        try { await start(ctx); }
+        catch (restartError) { throw new Error(error.message + ' 原库重新启动失败：' + restartError.message, {cause: error}); }
+      }
+      throw error;
+    }
     console.log('已恢复并中和外发任务: ' + database);
-    if (database !== ctx.values.PGDATABASE) console.log('使用新库时，将项目 .env 中的 PGDATABASE 改为 ' + database + '。');
+    if (options.use) {
+      try { await selectDatabase(ctx, database, resume); }
+      catch (error) {
+        if (resume && !(await runningServices(ctx)).includes('odoo')) {
+          const latest = await openProject(ctx.root, {runner: ctx.runner});
+          if (latest.values.PGDATABASE === ctx.values.PGDATABASE) await start(latest);
+        }
+        throw error;
+      }
+    }
+    else if (resume) await start(ctx);
+  });
+}
+
+function writeEnv(filename, content, mode) {
+  const temporary = filename + '.' + randomUUID() + '.part';
+  fs.writeFileSync(temporary, content, {mode, flag: 'wx'});
+  try { fs.renameSync(temporary, filename); }
+  finally { fs.rmSync(temporary, {force: true}); }
+}
+
+async function selectDatabase(ctx, database, running) {
+  const filename = path.join(ctx.root, '.env');
+  const original = fs.readFileSync(filename, 'utf8');
+  const setting = /^[ \t]*(?:export[ \t]+)?PGDATABASE[ \t]*=[^\r\n]*/gm;
+  if ([...original.matchAll(setting)].length !== 1) throw new Error('.env 中需要有且仅有一行 PGDATABASE。');
+  const next = original.replace(setting, 'PGDATABASE=' + database);
+  const values = parseEnv(next);
+  if (values.PGDATABASE !== database || Object.entries(ctx.values).some(([key, value]) => key !== 'PGDATABASE' && values[key] !== value)) {
+    throw new Error('无法安全更新 .env 中的 PGDATABASE。');
+  }
+  if (ctx.values.PGDATABASE === database) {
+    console.log('当前数据库：' + database);
+    return;
+  }
+  const mode = fs.statSync(filename).mode & 0o777;
+  if (fs.readFileSync(filename, 'utf8') !== original) throw new Error('.env 已被其他操作修改，请重试。');
+  writeEnv(filename, next, mode);
+  try {
+    if (running) await start(await openProject(ctx.root, {runner: ctx.runner}));
+  } catch (error) {
+    if (fs.readFileSync(filename, 'utf8') !== next) throw new Error('切库失败，且 .env 已有其他改动，请检查当前环境。', {cause: error});
+    writeEnv(filename, original, mode);
+    try { await start(ctx); }
+    catch (rollbackError) { throw new Error('已恢复原数据库配置，但 Odoo 未能重新启动：' + rollbackError.message, {cause: error}); }
+    throw new Error('切库失败，已恢复原数据库：' + error.message, {cause: error});
+  }
+  console.log('数据库已切换到：' + database);
+}
+
+export async function useDatabase(project, name) {
+  const database = databaseName(name);
+  await withLock(project, async () => {
+    const ctx = await openProject(project.root, {runner: project.runner});
+    const running = await runningServices(ctx);
+    if (!running.includes('db')) await ctx.run(dbReady);
+    if (readRecovery(ctx)?.database === database) throw new Error('该数据库恢复尚未完成，请先处理恢复任务。');
+    if (!(await databases(ctx)).some(row => row.name === database)) throw new Error('目标数据库不存在：' + database);
+    await verifyDatabase(ctx, database);
+    await selectDatabase(ctx, database, running.includes('odoo'));
+  });
+}
+
+export async function deleteDatabase(project, name) {
+  const database = databaseName(name);
+  await withLock(project, async () => {
+    const ctx = await openProject(project.root, {runner: project.runner});
+    const running = await runningServices(ctx);
+    if (readRecovery(ctx)?.database === database) throw new Error('请通过 db recover 清理恢复残留。');
+    const live = running.includes('odoo') ? await ctx.run(['exec', '-T', 'odoo', 'printenv', 'PGDATABASE'], {capture: true}) : '';
+    if (database === ctx.values.PGDATABASE || database === live) throw new Error('请先切换到另一个数据库。');
+    if (!running.includes('db')) await ctx.run(dbReady);
+    if (!(await databases(ctx)).some(row => row.name === database)) throw new Error('目标数据库不存在：' + database);
+    await dropDatabase(ctx, database);
+    recordOrigin(ctx, database);
+    console.log('已删除数据库及附件：' + database);
   });
 }
 

package/src/lib/environment.mjs

@@ -11,7 +11,10 @@ export function readEnv(root) {
 }
 
 export function projectName(root) {
-  const location = fs.realpathSync(root);
+  return projectNameForPath(fs.realpathSync(root));
+}
+
+export function projectNameForPath(location) {
   const prefix = path.basename(location).toLowerCase().replace(/[^a-z0-9_-]/g, '_').replace(/^[_-]+/, '') || 'odoo';
   return prefix.slice(0, 32) + '_' + crypto.createHash('sha256').update(location).digest('hex').slice(0, 10);
 }
@@ -32,6 +35,10 @@ export function validateEnv(values) {
   if (!/^[a-z0-9][a-z0-9_-]*$/.test(values.PROJECT_NAME)) throw new Error('Invalid PROJECT_NAME.');
   if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(values.PGDATABASE)) throw new Error('Invalid PGDATABASE.');
   if (!['DEV', 'TEST', 'PROD'].includes(values.ENV)) throw new Error('ENV must be DEV, TEST or PROD.');
+  if (values.ODOO_SEED_MODE && !['manual', 'first-start', 'empty'].includes(values.ODOO_SEED_MODE)) throw new Error('ODOO_SEED_MODE 仅支持 manual、first-start 或 empty。');
+  if (values.ODOO_SEED && !/^(?:tag:[a-z][a-z0-9._-]{0,63}|id:[a-zA-Z0-9_-]{1,100})$/.test(values.ODOO_SEED)) throw new Error('ODOO_SEED 请填写 tag:latest 或 id:<存档ID>。');
+  if (values.ENV === 'PROD' && values.ODOO_SEED && values.ODOO_SEED_MODE === 'first-start') throw new Error('首次加载存档仅用于开发和测试环境。');
+
   const ports = ['DB_PORT', 'ODOO_HTTP_PORT', 'ODOO_GEVENT_PORT'].map(key => {
     const value = values[key];
     if (!/^\d+$/.test(value || '') || +value < 1 || +value > 65535) throw new Error('Invalid ' + key + '.');
@@ -55,16 +62,18 @@ export async function prepareEnv(root) {
     if ((await Promise.all(candidate.map(portFree))).every(Boolean)) { ports = candidate; break; }
   }
   if (!ports) throw new Error('No free host port set found.');
-  Object.assign(values, {
+  const generated = {
     PROJECT_NAME: name, DB_PORT: String(ports[0]), ODOO_HTTP_PORT: String(ports[1]), ODOO_GEVENT_PORT: String(ports[2]),
-    PGPASSWORD: crypto.randomBytes(24).toString('hex'),
-    ODOO_MASTER_PASSWORD: crypto.randomBytes(24).toString('hex'),
-    ODOO_ADMIN_PASSWORD: crypto.randomBytes(24).toString('hex'),
-  });
-  validateEnv(values);
-  for (const key of ['PROJECT_NAME', 'DB_PORT', 'ODOO_HTTP_PORT', 'ODOO_GEVENT_PORT', 'PGPASSWORD', 'ODOO_MASTER_PASSWORD', 'ODOO_ADMIN_PASSWORD']) {
-    const pattern = new RegExp('^' + key + '=.*$', 'm');
-    text = text.replace(pattern, key + '=' + values[key]);
+  };
+  for (const key of ['PGPASSWORD', 'ODOO_MASTER_PASSWORD', 'ODOO_ADMIN_PASSWORD']) {
+    if (!values[key]) generated[key] = crypto.randomBytes(24).toString('hex');
+  }
+  validateEnv({...values, ...generated});
+  const newline = text.includes('\r\n') ? '\r\n' : '\n';
+  for (const [key, value] of Object.entries(generated)) {
+    const pattern = new RegExp('^[ \t]*(?:export[ \t]+)?' + key + '[ \t]*=[^\r\n]*', 'gm');
+    if (pattern.test(text)) text = text.replace(pattern, () => key + '=' + value);
+    else text += (text && !text.endsWith('\n') ? newline : '') + key + '=' + value + newline;
   }
   try { fs.writeFileSync(filename, text, {flag: 'wx', mode: 0o600}); }
   catch (error) { if (error.code !== 'EEXIST') throw error; }

package/src/lib/logs.mjs

@@ -20,7 +20,7 @@ export function parseLogOptions(args) {
     follow: {type: 'boolean', short: 'f', default: false},
     tail: {type: 'string', short: 'n', default: '200'},
     since: {type: 'string'}, until: {type: 'string'}, level: {type: 'string'},
-    match: {type: 'string'}, context: {type: 'string'},
+    match: {type: 'string'}, context: {type: 'string'}, 'hide-health': {type: 'boolean', default: false},
     json: {type: 'boolean', default: false}, file: {type: 'string'},
   }});
   const services = [...new Set((positionals.length ? positionals : ['odoo']).flatMap(service => service === 'all' ? ['odoo', 'db'] : [service]))];
@@ -32,7 +32,7 @@ export function parseLogOptions(args) {
   if (values.match !== undefined && (!values.match.trim() || /[\r\n]/.test(values.match))) throw new Error('--match 需要非空的单行文本。');
   if (values.context !== undefined && (!/^\d+$/.test(values.context) || +values.context > 100)) throw new Error('--context 必须为 0..100。');
   if (values.file !== undefined && !values.file.trim()) throw new Error('--file 需要输出文件路径。');
-  if (values.follow && (level || values.match || values.context !== undefined || values.json || values.file)) throw new Error('级别、关键词、上下文、JSON 和文件导出用于快照；持续跟随请单独使用 -f。');
+  if (values.follow && (level || values.match || values.context !== undefined || values['hide-health'] || values.json || values.file)) throw new Error('级别、关键词、上下文、JSON 和文件导出用于快照；持续跟随请单独使用 -f。');
   return {...values, level, services, context: +(values.context ?? 2), file: values.file ? path.resolve(values.file) : undefined};
 }
 
@@ -85,6 +85,23 @@ export function parseLogEvents(lines) {
   return {events: events.map(({messages, ...event}) => ({...event, message: messages.join('\n')})), diagnostics};
 }
 
+function isSuccessfulHealthCheck(event) {
+  return event.service === 'odoo' && event.level === 'info' && event.lines.length === 1 &&
+    (event.logger === 'odoo.http.server' || event.logger === 'werkzeug') &&
+    /"(?:GET|HEAD) \/web\/health(?:\?[^"\s]*)? HTTP\/\d+(?:\.\d+)?"\s+2\d{2}(?:\s|$)/.test(event.message);
+}
+
+function reachedTail(events, tail) {
+  if (tail === 'all' || Number(tail) === 0) return false;
+  const counts = new Map();
+  for (const event of events) {
+    const count = (counts.get(event.container) || 0) + event.lines.length;
+    if (count >= Number(tail)) return true;
+    counts.set(event.container, count);
+  }
+  return false;
+}
+
 export function selectLogEvents(events, options) {
   const matching = events.map(event => (!options.level || (levels[event.level] ?? 0) >= levels[options.level]) && (!options.match || event.message.toLowerCase().includes(options.match.toLowerCase())));
   const selected = new Set();
@@ -158,14 +175,15 @@ export async function executeLogs(options, {root, env, values, compose, read = d
   // must not change service attribution or severity detection.
   const {events, diagnostics: rawDiagnostics} = parseLogEvents(result.lines.map(line => stripVTControlCharacters(line)));
   const diagnostics = rawDiagnostics.map(mask);
-  const selection = selectLogEvents(events, options);
+  const candidates = options['hide-health'] ? events.filter(event => !isSuccessfulHealthCheck(event)) : events;
+  const selection = selectLogEvents(candidates, options);
   const selected = {matched: selection.matched, events: selection.events.map(event => ({
     ...event, message: mask(event.message), lines: event.lines.map(maskLine),
     ...(event.logger ? {logger: mask(event.logger)} : {}),
     ...(event.database ? {database: mask(event.database)} : {}),
   }))};
   const exported = selected.events.map(({lines, index, ...event}) => event);
-  const payload = {project: values.PROJECT_NAME, services: options.services, query: {tail: options.tail, since: options.since, until: options.until, level: options.level, match: options.match ? mask(options.match) : undefined, context: options.context}, scanned: events.length, matched: selected.matched, shown: exported.length, diagnostics, events: exported};
+  const payload = {project: values.PROJECT_NAME, services: options.services, query: {tail: options.tail, since: options.since, until: options.until, level: options.level, match: options.match ? mask(options.match) : undefined, context: options.context, hideHealth: options['hide-health']}, scanned: events.length, hiddenHealth: events.length - candidates.length, tailReached: reachedTail(events, options.tail), matched: selected.matched, shown: exported.length, diagnostics, events: exported};
   const output = options.json ? JSON.stringify(payload, null, 2) + '\n' : selected.events.flatMap(event => event.lines).join('\n') + (selected.events.length ? '\n' : '');
   if (!options.json) for (const line of diagnostics) stderr.write(line + '\n');
   if (options.file) {

package/src/project.mjs

@@ -54,20 +54,43 @@ export async function openProject(root, {initialize = false, runner = runDocker}
   const compose = ['compose', '--file', path.join(root, 'compose.yaml'), '--project-directory', root, '--env-file', path.join(root, '.env'), '--project-name', values.PROJECT_NAME];
   const docker = (args, io = {}) => runner(args, {root, env, ...io});
   const run = (args, io) => docker([...compose, ...args], io);
-  return {root, values, env, compose, docker, run};
+  return {root, values, env, compose, docker, run, runner};
+}
+
+function deadOwner(lock) {
+  try {
+    const {pid} = JSON.parse(fs.readFileSync(path.join(lock, 'owner.json'), 'utf8'));
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    process.kill(pid, 0);
+  } catch (error) { return error.code === 'ESRCH'; }
+  return false;
 }
 
 export async function withLock(ctx, action) {
-  const lock = path.join(ctx.root, '.local', 'operation.lock');
-  fs.mkdirSync(path.dirname(lock), {recursive: true});
+  const local = path.join(ctx.root, '.local');
+  const lock = path.join(local, 'operation.lock');
+  const reclaim = path.join(local, 'operation.reclaim');
+  fs.mkdirSync(local, {recursive: true});
   try { fs.mkdirSync(lock); }
   catch (error) {
-    if (error.code === 'EEXIST') throw new Error('本项目存在进行中的维护操作。若操作曾中断，请先核对 .local/operation.lock/owner.json 中的进程，再清理过期锁。');
-    throw error;
+    if (error.code !== 'EEXIST') throw error;
+    const busy = '本项目有进行中的操作。若操作已中断，请检查 .local/operation.lock/owner.json。';
+    if (!deadOwner(lock)) throw new Error(busy);
+    try { fs.mkdirSync(reclaim); }
+    catch (error) { if (error.code === 'EEXIST') throw new Error(busy); throw error; }
+    try {
+      if (fs.existsSync(lock)) {
+        if (!deadOwner(lock)) throw new Error(busy);
+        fs.rmSync(lock, {recursive: true});
+      }
+      try { fs.mkdirSync(lock); }
+      catch (error) { if (error.code === 'EEXIST') throw new Error(busy); throw error; }
+    } finally { fs.rmdirSync(reclaim); }
   }
-  fs.writeFileSync(path.join(lock, 'owner.json'), JSON.stringify({pid: process.pid, started: new Date().toISOString()}), {mode: 0o600});
-  try { return await action(); }
-  finally { fs.rmSync(lock, {recursive: true, force: true}); }
+  try {
+    fs.writeFileSync(path.join(lock, 'owner.json'), JSON.stringify({pid: process.pid, started: new Date().toISOString()}), {mode: 0o600});
+    return await action();
+  } finally { fs.rmSync(lock, {recursive: true, force: true}); }
 }
 
 export function projectVersion(root) {