nodebbs 0.3.3 → 0.4.1

package/README.md

@@ -77,28 +77,31 @@ $ nodebbs
   upgrade       升级服务
   status        查看服务状态
   logs          查看服务日志  [+]
+  db            数据库操作 (种子数据, 重置等)  [+]
+  backup        备份数据 (数据库, 上传文件等)  [+]
+  import        导入/恢复数据  [+]
+  clean         清理 Docker 缓存和残留资源
   shell         进入容器终端  [+]
-  db            数据库操作 (备份, 迁移, 种子数据等)  [+]
   pack          生成离线部署包
-  clean         清理 Docker 缓存和残留资源
-  help          显示帮助信息
   ❌ 退出
 ```
 
 #### 命令说明
 
 | 命令 | 说明 |
-|------|---------|
+|------|---------| 
 | **start** | 启动服务（根据当前配置环境）|
 | **stop** | 停止所有服务 |
 | **restart** | 重启服务（相当于 `docker compose up --force-recreate`）|
 | **upgrade** | 升级服务（拉取最新 Docker 镜像或重新构建本地镜像）|
 | **status** | 查看所有容器的运行状态和健康检查结果 |
 | **logs** | 查看服务日志（支持选择特定服务 API/Web/DB/Redis）|
-| **shell** | 进入容器终端进行调试（支持选择特定服务）|
-| **db** | 数据库高级操作：<br>• 备份 (backup)<br>• 恢复 (import)<br>• 迁移 (migrate)<br>• 种子数据 (seed) |
+| **db** | 数据库操作：种子数据 (seed)、重置 (reset) 等 |
+| **backup** | 备份数据：<br>• 数据库 (db)<br>• 上传文件 (uploads)<br>• 一键全部备份 (all) |
+| **import** | 恢复数据：<br>• 数据库 (db)<br>• 上传文件 (uploads)<br>• 一键全部恢复 (all) |
 | **pack** | 生成离线部署包（**仅限源码模式**），方便在无网环境部署 |
 | **clean** | 清理工具（删除未使用镜像、容器、卷，释放磁盘空间）|
+| **shell** | 进入容器终端进行调试（支持选择特定服务）|
 
 ### 离线服务器部署
 

package/dist/commands/backup/all.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class BackupAll extends Command {
+    static description: string;
+    static flags: {
+        output: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        env: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/backup/all.js

@@ -0,0 +1,71 @@
+import { Command, Flags } from '@oclif/core';
+import { logger } from '../../utils/logger.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import BackupDb from './db.js';
+import BackupUploads from './uploads.js';
+export default class BackupAll extends Command {
+    static description = '一键备份全部数据 (数据库 + 上传文件)';
+    static flags = {
+        output: Flags.string({
+            char: 'o',
+            description: '输出目录路径',
+        }),
+        env: Flags.string({
+            char: 'e',
+            description: '运行环境 (production, lowmem, default)',
+            options: ['production', 'lowmem', 'default'],
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(BackupAll);
+        // 生成备份目录
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+        const backupDirName = flags.output || `backup_${timestamp}`;
+        const backupDir = path.resolve(process.cwd(), backupDirName);
+        // 创建备份目录
+        if (!fs.existsSync(backupDir)) {
+            fs.mkdirSync(backupDir, { recursive: true });
+        }
+        logger.info(`开始完整备份，输出目录: ${backupDir}`);
+        logger.info('='.repeat(50));
+        const dbBackupFile = path.join(backupDir, 'database.sql');
+        const uploadsBackupFile = path.join(backupDir, 'uploads.tar.gz');
+        // 1. 备份数据库
+        logger.info('\n[1/2] 备份数据库...');
+        try {
+            const dbArgs = ['-o', dbBackupFile];
+            if (flags.env) {
+                dbArgs.push('-e', flags.env);
+            }
+            await BackupDb.run(dbArgs);
+        }
+        catch (error) {
+            logger.error('数据库备份失败，终止操作');
+            this.exit(1);
+        }
+        // 2. 备份上传文件
+        logger.info('\n[2/2] 备份上传文件...');
+        try {
+            await BackupUploads.run(['-o', uploadsBackupFile]);
+        }
+        catch (error) {
+            logger.warning('上传文件备份失败 (可能卷不存在)');
+            // 不终止，因为数据库已备份
+        }
+        // 生成备份清单
+        logger.info('\n' + '='.repeat(50));
+        logger.success('完整备份完成！');
+        logger.info(`\n备份目录: ${backupDir}`);
+        logger.info('包含文件:');
+        const files = fs.readdirSync(backupDir);
+        for (const file of files) {
+            const filePath = path.join(backupDir, file);
+            const stats = fs.statSync(filePath);
+            const sizeMB = (stats.size / 1024 / 1024).toFixed(2);
+            logger.info(`  - ${file} (${sizeMB} MB)`);
+        }
+        logger.info('\n使用以下命令恢复数据:');
+        logger.info(`  nodebbs import all -d ${backupDir}`);
+    }
+}

package/dist/commands/{db/backup.d.ts → backup/db.d.ts}

@@ -1,5 +1,5 @@
 import { Command } from '@oclif/core';
-export default class DbBackup extends Command {
+export default class BackupDb extends Command {
     static description: string;
     static flags: {
         env: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/{db/backup.js → backup/db.js}

@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import dotenv from 'dotenv';
 import { EnvFlag, selectEnvironment } from '../../utils/selection.js';
-export default class DbBackup extends Command {
+export default class BackupDb extends Command {
     static description = '备份数据库 (PostgreSQL)';
     static flags = {
         env: EnvFlag,
@@ -16,14 +16,14 @@ export default class DbBackup extends Command {
         }),
     };
     async run() {
-        const { flags } = await this.parse(DbBackup);
+        const { flags } = await this.parse(BackupDb);
         // 1. 选择环境
         const env = await selectEnvironment(flags.env);
         // 2. 确定输出文件
         let outputFile = flags.output;
         if (!outputFile) {
             const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-            outputFile = `backup_${timestamp}.sql`;
+            outputFile = `backup_db_${timestamp}.sql`;
         }
         // 确保绝对路径
         const outputPath = path.resolve(process.cwd(), outputFile);

package/dist/commands/backup/uploads.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class BackupUploads extends Command {
+    static description: string;
+    static flags: {
+        output: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    /**
+     * 获取上传文件数据卷名称
+     * 优先级: 1. .env 中的 COMPOSE_PROJECT_NAME  2. 当前目录名  3. 自动搜索
+     */
+    private getUploadsVolumeName;
+}

package/dist/commands/backup/uploads.js

@@ -0,0 +1,117 @@
+import { Command, Flags } from '@oclif/core';
+import { logger } from '../../utils/logger.js';
+import { execa } from 'execa';
+import fs from 'node:fs';
+import path from 'node:path';
+import dotenv from 'dotenv';
+export default class BackupUploads extends Command {
+    static description = '备份上传文件 (用户头像、附件等)';
+    static flags = {
+        output: Flags.string({
+            char: 'o',
+            description: '输出文件路径 (.tar.gz)',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(BackupUploads);
+        // 获取上传文件卷名
+        const volumeName = await this.getUploadsVolumeName();
+        if (!volumeName) {
+            logger.error('未找到上传文件数据卷。请确保服务已启动过至少一次。');
+            this.exit(1);
+        }
+        // 确定输出文件
+        let outputFile = flags.output;
+        if (!outputFile) {
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+            outputFile = `backup_uploads_${timestamp}.tar.gz`;
+        }
+        // 确保绝对路径
+        const outputPath = path.resolve(process.cwd(), outputFile);
+        const outputDir = path.dirname(outputPath);
+        const outputFileName = path.basename(outputPath);
+        logger.info(`正在备份上传文件...`);
+        logger.info(`数据卷: ${volumeName}`);
+        logger.info(`输出文件: ${outputPath}`);
+        try {
+            // 使用 alpine 容器备份卷内容
+            await execa('docker', [
+                'run', '--rm',
+                '-v', `${volumeName}:/data:ro`,
+                '-v', `${outputDir}:/backup`,
+                'alpine',
+                'tar', 'czf', `/backup/${outputFileName}`, '-C', '/data', '.'
+            ], {
+                stdio: 'inherit'
+            });
+            // 检查输出文件
+            if (fs.existsSync(outputPath)) {
+                const stats = fs.statSync(outputPath);
+                logger.success(`上传文件备份成功！文件大小: ${(stats.size / 1024 / 1024).toFixed(2)} MB`);
+            }
+            else {
+                logger.error('备份文件未生成');
+                this.exit(1);
+            }
+        }
+        catch (error) {
+            logger.error('上传文件备份失败');
+            if (error instanceof Error) {
+                if (error.message.includes('No such volume')) {
+                    logger.error(`数据卷 "${volumeName}" 不存在。请确保服务已启动过至少一次。`);
+                }
+                else {
+                    logger.error(error.message);
+                }
+            }
+            this.exit(1);
+        }
+    }
+    /**
+     * 获取上传文件数据卷名称
+     * 优先级: 1. .env 中的 COMPOSE_PROJECT_NAME  2. 当前目录名  3. 自动搜索
+     */
+    async getUploadsVolumeName() {
+        // 1. 优先从 .env 获取项目名称
+        const envConfig = dotenv.config().parsed || {};
+        if (envConfig.COMPOSE_PROJECT_NAME) {
+            const volumeName = `${envConfig.COMPOSE_PROJECT_NAME}_api_uploads`;
+            try {
+                await execa('docker', ['volume', 'inspect', volumeName]);
+                return volumeName;
+            }
+            catch {
+                // 卷不存在，继续尝试其他方式
+            }
+        }
+        // 2. 尝试使用当前目录名（与 Docker Compose 默认行为一致）
+        const dirName = path.basename(process.cwd());
+        const volumeByDir = `${dirName}_api_uploads`;
+        try {
+            await execa('docker', ['volume', 'inspect', volumeByDir]);
+            return volumeByDir;
+        }
+        catch {
+            // 卷不存在，继续
+        }
+        // 3. 自动搜索包含 api_uploads 的卷
+        try {
+            const result = await execa('docker', ['volume', 'ls', '--format', '{{.Name}}']);
+            const volumes = result.stdout.split('\n').filter(v => v.includes('api_uploads'));
+            if (volumes.length === 1) {
+                return volumes[0];
+            }
+            else if (volumes.length > 1) {
+                // 多个匹配，提示用户
+                logger.warning('找到多个可能的上传卷:');
+                volumes.forEach(v => logger.info(`  - ${v}`));
+                logger.info('请在 .env 中设置 COMPOSE_PROJECT_NAME 以指定正确的卷');
+                return volumes[0]; // 默认使用第一个
+            }
+        }
+        catch {
+            // 忽略错误
+        }
+        return null;
+    }
+}

package/dist/commands/import/all.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class ImportAll extends Command {
+    static description: string;
+    static flags: {
+        dir: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        env: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/import/all.js

@@ -0,0 +1,128 @@
+import { Command, Flags } from '@oclif/core';
+import { logger } from '../../utils/logger.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { select, input, confirm } from '@inquirer/prompts';
+import ImportDb from './db.js';
+import ImportUploads from './uploads.js';
+export default class ImportAll extends Command {
+    static description = '一键恢复全部数据 (数据库 + 上传文件)';
+    static flags = {
+        dir: Flags.string({
+            char: 'd',
+            description: '备份目录路径 (包含 .sql 和 .tar.gz 文件)',
+        }),
+        env: Flags.string({
+            char: 'e',
+            description: '运行环境 (production, lowmem, default)',
+            options: ['production', 'lowmem', 'default'],
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(ImportAll);
+        // 确定备份目录
+        let backupDir = flags.dir;
+        if (!backupDir) {
+            // 尝试查找当前目录下的备份目录
+            const dirs = fs.readdirSync(process.cwd())
+                .filter(f => {
+                const fullPath = path.join(process.cwd(), f);
+                return fs.statSync(fullPath).isDirectory() && f.startsWith('backup_');
+            })
+                .sort((a, b) => b.localeCompare(a)); // 按名称倒序（最新的在前）
+            if (dirs.length > 0) {
+                const choices = dirs.map(d => ({ name: d, value: d }));
+                choices.push({ name: '手动输入路径', value: '__MANUAL__' });
+                const selection = await select({
+                    message: '请选择备份目录:',
+                    choices: choices,
+                });
+                if (selection === '__MANUAL__') {
+                    backupDir = await input({ message: '请输入备份目录路径:' });
+                }
+                else {
+                    backupDir = selection;
+                }
+            }
+            else {
+                backupDir = await input({ message: '未找到备份目录，请输入路径:' });
+            }
+        }
+        // 验证备份目录
+        const backupPath = path.resolve(process.cwd(), backupDir);
+        if (!fs.existsSync(backupPath) || !fs.statSync(backupPath).isDirectory()) {
+            logger.error(`目录不存在或不是有效目录: ${backupPath}`);
+            this.exit(1);
+        }
+        // 查找备份文件
+        const files = fs.readdirSync(backupPath);
+        const sqlFile = files.find(f => f.endsWith('.sql'));
+        const uploadsFile = files.find(f => f.endsWith('.tar.gz'));
+        if (!sqlFile && !uploadsFile) {
+            logger.error('备份目录中未找到有效的备份文件 (.sql 或 .tar.gz)');
+            this.exit(1);
+        }
+        logger.info(`备份目录: ${backupPath}`);
+        logger.info('找到以下备份文件:');
+        if (sqlFile)
+            logger.info(`  - 数据库: ${sqlFile}`);
+        if (uploadsFile)
+            logger.info(`  - 上传文件: ${uploadsFile}`);
+        // 最终确认
+        logger.warning('\n警告: 此操作将清空当前所有数据并从备份恢复！');
+        const isConfirmed = await confirm({
+            message: '确认继续完整恢复？(数据丢失不可撤销)',
+            default: false
+        });
+        if (!isConfirmed) {
+            logger.info('操作已取消');
+            this.exit(0);
+        }
+        logger.info('\n开始完整恢复...');
+        logger.info('='.repeat(50));
+        // 1. 恢复数据库
+        if (sqlFile) {
+            logger.info('\n[1/2] 恢复数据库...');
+            try {
+                const dbArgs = ['-i', path.join(backupPath, sqlFile)];
+                if (flags.env) {
+                    dbArgs.push('-e', flags.env);
+                }
+                // 设置环境变量跳过确认（因为上面已确认）
+                process.env.NODEBBS_SKIP_CONFIRM = 'true';
+                await ImportDb.run(dbArgs);
+            }
+            catch (error) {
+                logger.error('数据库恢复失败');
+                this.exit(1);
+            }
+            finally {
+                delete process.env.NODEBBS_SKIP_CONFIRM;
+            }
+        }
+        else {
+            logger.info('\n[1/2] 跳过数据库恢复 (未找到 .sql 文件)');
+        }
+        // 2. 恢复上传文件
+        if (uploadsFile) {
+            logger.info('\n[2/2] 恢复上传文件...');
+            try {
+                process.env.NODEBBS_SKIP_CONFIRM = 'true';
+                await ImportUploads.run(['-i', path.join(backupPath, uploadsFile)]);
+            }
+            catch (error) {
+                logger.warning('上传文件恢复失败');
+            }
+            finally {
+                delete process.env.NODEBBS_SKIP_CONFIRM;
+            }
+        }
+        else {
+            logger.info('\n[2/2] 跳过上传文件恢复 (未找到 .tar.gz 文件)');
+        }
+        logger.info('\n' + '='.repeat(50));
+        logger.success('完整恢复完成！');
+        logger.info('\n请重启服务以确保更改生效:');
+        logger.info('  nodebbs restart');
+    }
+}

package/dist/commands/{db/import.d.ts → import/db.d.ts}

@@ -1,5 +1,5 @@
 import { Command } from '@oclif/core';
-export default class DbImport extends Command {
+export default class ImportDb extends Command {
     static description: string;
     static flags: {
         env: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/{db/import.js → import/db.js}

@@ -7,7 +7,7 @@ import path from 'node:path';
 import dotenv from 'dotenv';
 import { EnvFlag, selectEnvironment } from '../../utils/selection.js';
 import { confirm, select, input } from '@inquirer/prompts';
-export default class DbImport extends Command {
+export default class ImportDb extends Command {
     static description = '导入数据库 (从 SQL 文件恢复)';
     static flags = {
         env: EnvFlag,
@@ -17,7 +17,7 @@ export default class DbImport extends Command {
         }),
     };
     async run() {
-        const { flags } = await this.parse(DbImport);
+        const { flags } = await this.parse(ImportDb);
         // 1. 选择环境
         const env = await selectEnvironment(flags.env);
         // 2. 确定输入文件
@@ -27,7 +27,7 @@ export default class DbImport extends Command {
             const files = fs.readdirSync(process.cwd())
                 .filter(f => f.endsWith('.sql'))
                 .sort((a, b) => {
-                // 尝试按时间倒序 (虽然文件名可能有时间戳，但用文件修改时间更准)
+                // 按文件修改时间倒序
                 const statA = fs.statSync(a);
                 const statB = fs.statSync(b);
                 return statB.mtime.getTime() - statA.mtime.getTime();
@@ -76,7 +76,7 @@ export default class DbImport extends Command {
         if (isBuiltIn) {
             composeArgs.push('--project-directory', process.cwd());
         }
-        // 加载环境配置获取数据库信息 (用于可能的连接参数，虽然 docker exec 默认用 postgres 用户通常足够)
+        // 加载环境配置
         const envConfig = dotenv.config().parsed || {};
         const dbUser = envConfig.POSTGRES_USER || 'postgres';
         const dbName = envConfig.POSTGRES_DB || 'nodebbs';
@@ -84,8 +84,7 @@ export default class DbImport extends Command {
         // 5. 执行恢复
         logger.info('正在准备恢复数据库...');
         try {
-            // 步骤 A: 重置 Schema (Drop & Create public)
-            // 这样做比单纯导入更干净，因为 pg_dump 默认可能不包含 DROP TABLE
+            // 步骤 A: 重置 Schema
             logger.info('正在重置数据库 Schema...');
             const resetCmd = [...composeArgs, 'exec', '-T', 'postgres', 'psql', '-U', dbUser, '-d', dbName, '-c', 'DROP SCHEMA public CASCADE; CREATE SCHEMA public;'];
             // 如果有密码

package/dist/commands/import/uploads.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class ImportUploads extends Command {
+    static description: string;
+    static flags: {
+        input: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    /**
+     * 获取或创建上传文件数据卷
+     * 优先级: 1. .env 中的 COMPOSE_PROJECT_NAME  2. 当前目录名  3. 自动搜索  4. 创建新卷
+     */
+    private getOrCreateUploadsVolume;
+}

package/dist/commands/import/uploads.js

@@ -0,0 +1,146 @@
+import { Command, Flags } from '@oclif/core';
+import { logger } from '../../utils/logger.js';
+import { execa } from 'execa';
+import fs from 'node:fs';
+import path from 'node:path';
+import dotenv from 'dotenv';
+import { confirm, select, input } from '@inquirer/prompts';
+export default class ImportUploads extends Command {
+    static description = '恢复上传文件 (从 tar.gz 备份恢复)';
+    static flags = {
+        input: Flags.string({
+            char: 'i',
+            description: '输入文件路径 (.tar.gz)',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(ImportUploads);
+        // 确定输入文件
+        let inputFile = flags.input;
+        if (!inputFile) {
+            // 尝试自动查找当前目录下的 .tar.gz 文件
+            const files = fs.readdirSync(process.cwd())
+                .filter(f => f.endsWith('.tar.gz') && f.includes('uploads'))
+                .sort((a, b) => {
+                const statA = fs.statSync(a);
+                const statB = fs.statSync(b);
+                return statB.mtime.getTime() - statA.mtime.getTime();
+            });
+            if (files.length > 0) {
+                const choices = files.map(f => ({
+                    name: `${f} (${(fs.statSync(f).size / 1024 / 1024).toFixed(2)} MB)`,
+                    value: f
+                }));
+                choices.push({ name: '手动输入路径', value: '__MANUAL__' });
+                const selection = await select({
+                    message: '请选择上传文件备份:',
+                    choices: choices,
+                });
+                if (selection === '__MANUAL__') {
+                    inputFile = await input({ message: '请输入文件路径:' });
+                }
+                else {
+                    inputFile = selection;
+                }
+            }
+            else {
+                inputFile = await input({ message: '未找到上传备份文件 (.tar.gz)，请输入路径:' });
+            }
+        }
+        // 确保绝对路径并检查是否存在
+        const inputPath = path.resolve(process.cwd(), inputFile);
+        if (!fs.existsSync(inputPath)) {
+            logger.error(`文件未找到: ${inputPath}`);
+            this.exit(1);
+        }
+        // 获取或创建上传文件卷
+        const volumeName = await this.getOrCreateUploadsVolume();
+        // 危险操作确认
+        if (process.env.NODEBBS_SKIP_CONFIRM !== 'true') {
+            logger.warning('警告: 此操作将清空当前上传目录的所有文件并从备份恢复！');
+            logger.warning(`目标文件: ${inputPath}`);
+            logger.warning(`数据卷: ${volumeName}`);
+            const isConfirmed = await confirm({
+                message: '确认继续？(文件丢失不可撤销)',
+                default: false
+            });
+            if (!isConfirmed) {
+                logger.info('操作已取消');
+                this.exit(0);
+            }
+        }
+        logger.info('正在恢复上传文件...');
+        logger.info(`数据卷: ${volumeName}`);
+        const inputDir = path.dirname(inputPath);
+        const inputFileName = path.basename(inputPath);
+        try {
+            // 使用 alpine 容器恢复卷内容
+            await execa('docker', [
+                'run', '--rm',
+                '-v', `${volumeName}:/data`,
+                '-v', `${inputDir}:/backup:ro`,
+                'alpine',
+                'sh', '-c', `rm -rf /data/* && tar xzf /backup/${inputFileName} -C /data`
+            ], {
+                stdio: 'inherit'
+            });
+            logger.success('上传文件恢复成功！');
+        }
+        catch (error) {
+            logger.error('上传文件恢复失败');
+            if (error instanceof Error) {
+                logger.error(error.message);
+            }
+            this.exit(1);
+        }
+    }
+    /**
+     * 获取或创建上传文件数据卷
+     * 优先级: 1. .env 中的 COMPOSE_PROJECT_NAME  2. 当前目录名  3. 自动搜索  4. 创建新卷
+     */
+    async getOrCreateUploadsVolume() {
+        // 1. 优先从 .env 获取项目名称
+        const envConfig = dotenv.config().parsed || {};
+        if (envConfig.COMPOSE_PROJECT_NAME) {
+            const volumeName = `${envConfig.COMPOSE_PROJECT_NAME}_api_uploads`;
+            try {
+                await execa('docker', ['volume', 'inspect', volumeName]);
+                return volumeName;
+            }
+            catch {
+                // 卷不存在，继续
+            }
+        }
+        // 2. 尝试使用当前目录名（与 Docker Compose 默认行为一致）
+        const dirName = path.basename(process.cwd());
+        const volumeByDir = `${dirName}_api_uploads`;
+        try {
+            await execa('docker', ['volume', 'inspect', volumeByDir]);
+            return volumeByDir;
+        }
+        catch {
+            // 卷不存在，继续
+        }
+        // 3. 自动搜索包含 api_uploads 的卷
+        try {
+            const result = await execa('docker', ['volume', 'ls', '--format', '{{.Name}}']);
+            const volumes = result.stdout.split('\n').filter(v => v.includes('api_uploads'));
+            if (volumes.length === 1) {
+                return volumes[0];
+            }
+            else if (volumes.length > 1) {
+                logger.warning('找到多个可能的上传卷:');
+                volumes.forEach(v => logger.info(`  - ${v}`));
+                logger.info('请在 .env 中设置 COMPOSE_PROJECT_NAME 以指定正确的卷');
+                return volumes[0];
+            }
+        }
+        catch {
+            // 忽略错误
+        }
+        // 4. 基于目录名创建新卷
+        logger.info(`数据卷 "${volumeByDir}" 不存在，正在创建...`);
+        await execa('docker', ['volume', 'create', volumeByDir]);
+        return volumeByDir;
+    }
+}

package/dist/interactive.js

@@ -29,9 +29,11 @@ export async function runInteractive(root) {
     }
     await navigate(tree, [], config);
 }
-const GLOBAL_PRIORITY = ['start', 'stop', 'restart', 'upgrade', 'status', 'logs', 'shell', 'db', 'pack'];
+const GLOBAL_PRIORITY = ['start', 'stop', 'restart', 'upgrade', 'status', 'logs', 'db', 'backup', 'import', 'clean', 'shell', 'pack'];
 const SCOPED_PRIORITIES = {
     'logs': ['all', 'web', 'api', 'db', 'redis'],
+    'backup': ['all', 'db', 'uploads'],
+    'import': ['all', 'db', 'uploads'],
 };
 async function navigate(node, breadcrumbs, config) {
     const currentPath = breadcrumbs.join(':');

package/dist/templates/config.yml

@@ -0,0 +1,22 @@
+# NodeBBS 自定义配置
+# 此文件用于挂载自定义静态资源（如 logo、favicon 等）
+# 将此文件复制到项目根目录并取消需要的注释即可生效
+#
+# 使用方法：
+#   1. 复制此文件到项目根目录：cp config.yml ./
+#   2. 在项目根目录创建 web 文件夹：mkdir -p web
+#   3. 将自定义资源放入 web 文件夹
+#   4. 取消下方对应行的注释
+#   5. 重启服务：npx nodebbs restart
+
+services:
+  web:
+    volumes:
+      # 网站图标
+      - ./web/favicon.ico:/app/apps/web/public/favicon.ico
+
+      # 网站 Logo
+      - ./web/logo.svg:/app/apps/web/public/logo.svg
+
+      # Apple Touch Icon (iOS 主屏幕图标)
+      - ./web/apple-touch-icon.png:/app/apps/web/public/apple-touch-icon.png

package/dist/templates/docker-compose.yml

@@ -91,11 +91,7 @@ services:
       PORT: 3100
       SERVER_API_URL: ${SERVER_API_URL:-http://api:7100}
       TZ: ${TZ:-Asia/Shanghai}
-    # volumes:
-      # 自定义资源挂载（如有需要，请取消注释并在同级目录下创建 web 文件夹及对应文件）
-      # - ./web/favicon.ico:/app/apps/web/public/favicon.ico
-      # - ./web/logo.svg:/app/apps/web/public/logo.svg
-      # - ./web/apple-touch-icon.png:/app/apps/web/public/apple-touch-icon.png
+    # 自定义资源挂载请使用 config.yml，参见 src/templates/config.yml
     ports:
       - "${WEB_PORT:-3100}:3100"
     depends_on:

package/dist/templates/env

@@ -2,9 +2,6 @@
 # NodeBBS Docker Compose 环境变量配置
 # ========================================
 
-# 应用名称
-APP_NAME=nodebbs
-
 # ========================================
 # 数据库配置
 # ========================================

package/dist/utils/docker.js

@@ -75,6 +75,12 @@ export async function getComposeFiles(env) {
             files.push(templateBuild);
         }
     }
+    // 4. 检测自定义配置文件 (config.yml)
+    // 用于挂载自定义静态资源（如 logo、favicon 等），仅当文件存在时加载
+    const configFile = path.join(workDir, 'config.yml');
+    if (await fileExists(configFile)) {
+        files.push(configFile);
+    }
     return { files, isBuiltIn };
 }
 /**

package/oclif.manifest.json

@@ -1,5 +1,121 @@
 {
   "commands": {
+    "backup:all": {
+      "aliases": [],
+      "args": {},
+      "description": "一键备份全部数据 (数据库 + 上传文件)",
+      "flags": {
+        "output": {
+          "char": "o",
+          "description": "输出目录路径",
+          "name": "output",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "env": {
+          "char": "e",
+          "description": "运行环境 (production, lowmem, default)",
+          "name": "env",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "production",
+            "lowmem",
+            "default"
+          ],
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "backup:all",
+      "pluginAlias": "nodebbs",
+      "pluginName": "nodebbs",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "backup",
+        "all.js"
+      ]
+    },
+    "backup:db": {
+      "aliases": [],
+      "args": {},
+      "description": "备份数据库 (PostgreSQL)",
+      "flags": {
+        "env": {
+          "char": "e",
+          "description": "部署环境 (production, lowmem, default)",
+          "name": "env",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "production",
+            "lowmem",
+            "default"
+          ],
+          "type": "option"
+        },
+        "output": {
+          "char": "o",
+          "description": "输出文件路径",
+          "name": "output",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "backup:db",
+      "pluginAlias": "nodebbs",
+      "pluginName": "nodebbs",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "backup",
+        "db.js"
+      ]
+    },
+    "backup:uploads": {
+      "aliases": [],
+      "args": {},
+      "description": "备份上传文件 (用户头像、附件等)",
+      "flags": {
+        "output": {
+          "char": "o",
+          "description": "输出文件路径 (.tar.gz)",
+          "name": "output",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "backup:uploads",
+      "pluginAlias": "nodebbs",
+      "pluginName": "nodebbs",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "backup",
+        "uploads.js"
+      ]
+    },
     "clean": {
       "aliases": [],
       "args": {},
@@ -54,10 +170,10 @@
         "index.js"
       ]
     },
-    "db:backup": {
+    "db:push": {
       "aliases": [],
       "args": {},
-      "description": "备份数据库 (PostgreSQL)",
+      "description": "推送数据库 schema (db:push)",
       "flags": {
         "env": {
           "char": "e",
@@ -71,19 +187,11 @@
             "default"
           ],
           "type": "option"
-        },
-        "output": {
-          "char": "o",
-          "description": "输出文件路径",
-          "name": "output",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "db:backup",
+      "id": "db:push",
       "pluginAlias": "nodebbs",
       "pluginName": "nodebbs",
       "pluginType": "core",
@@ -94,13 +202,13 @@
         "dist",
         "commands",
         "db",
-        "backup.js"
+        "push.js"
       ]
     },
-    "db:import": {
+    "db:reset": {
       "aliases": [],
       "args": {},
-      "description": "导入数据库 (从 SQL 文件恢复)",
+      "description": "重置数据库 (db:reset) - 危险操作！",
       "flags": {
         "env": {
           "char": "e",
@@ -114,19 +222,11 @@
             "default"
           ],
           "type": "option"
-        },
-        "input": {
-          "char": "i",
-          "description": "输入文件路径",
-          "name": "input",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "db:import",
+      "id": "db:reset",
       "pluginAlias": "nodebbs",
       "pluginName": "nodebbs",
       "pluginType": "core",
@@ -137,13 +237,13 @@
         "dist",
         "commands",
         "db",
-        "import.js"
+        "reset.js"
       ]
     },
-    "db:push": {
+    "db:seed": {
       "aliases": [],
       "args": {},
-      "description": "推送数据库 schema (db:push)",
+      "description": "填充种子数据 (db:seed)",
       "flags": {
         "env": {
           "char": "e",
@@ -161,7 +261,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "db:push",
+      "id": "db:seed",
       "pluginAlias": "nodebbs",
       "pluginName": "nodebbs",
       "pluginType": "core",
@@ -172,17 +272,25 @@
         "dist",
         "commands",
         "db",
-        "push.js"
+        "seed.js"
       ]
     },
-    "db:reset": {
+    "import:all": {
       "aliases": [],
       "args": {},
-      "description": "重置数据库 (db:reset) - 危险操作！",
+      "description": "一键恢复全部数据 (数据库 + 上传文件)",
       "flags": {
+        "dir": {
+          "char": "d",
+          "description": "备份目录路径 (包含 .sql 和 .tar.gz 文件)",
+          "name": "dir",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "env": {
           "char": "e",
-          "description": "部署环境 (production, lowmem, default)",
+          "description": "运行环境 (production, lowmem, default)",
           "name": "env",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -196,7 +304,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "db:reset",
+      "id": "import:all",
       "pluginAlias": "nodebbs",
       "pluginName": "nodebbs",
       "pluginType": "core",
@@ -206,14 +314,14 @@
       "relativePath": [
         "dist",
         "commands",
-        "db",
-        "reset.js"
+        "import",
+        "all.js"
       ]
     },
-    "db:seed": {
+    "import:db": {
       "aliases": [],
       "args": {},
-      "description": "填充种子数据 (db:seed)",
+      "description": "导入数据库 (从 SQL 文件恢复)",
       "flags": {
         "env": {
           "char": "e",
@@ -227,11 +335,19 @@
             "default"
           ],
           "type": "option"
+        },
+        "input": {
+          "char": "i",
+          "description": "输入文件路径",
+          "name": "input",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "db:seed",
+      "id": "import:db",
       "pluginAlias": "nodebbs",
       "pluginName": "nodebbs",
       "pluginType": "core",
@@ -241,8 +357,38 @@
       "relativePath": [
         "dist",
         "commands",
-        "db",
-        "seed.js"
+        "import",
+        "db.js"
+      ]
+    },
+    "import:uploads": {
+      "aliases": [],
+      "args": {},
+      "description": "恢复上传文件 (从 tar.gz 备份恢复)",
+      "flags": {
+        "input": {
+          "char": "i",
+          "description": "输入文件路径 (.tar.gz)",
+          "name": "input",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "import:uploads",
+      "pluginAlias": "nodebbs",
+      "pluginName": "nodebbs",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "import",
+        "uploads.js"
       ]
     },
     "logs:all": {
@@ -781,5 +927,5 @@
       ]
     }
   },
-  "version": "0.3.3"
+  "version": "0.4.1"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nodebbs",
   "description": "NodeBBS 论坛系统专业运维工具",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "author": "wengqianshan",
   "bin": {
     "nodebbs": "./bin/run.js"
@@ -62,7 +62,13 @@
         "description": "查看服务日志"
       },
       "db": {
-        "description": "数据库操作 (备份, 迁移, 种子数据等)"
+        "description": "数据库操作 (种子数据, 重置等)"
+      },
+      "backup": {
+        "description": "备份数据 (数据库, 上传文件等)"
+      },
+      "import": {
+        "description": "导入/恢复数据"
       },
       "shell": {
         "description": "进入容器终端"