nodebbs 0.3.2 → 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** | 进入容器终端进行调试（支持选择特定服务）|
 
 ### 离线服务器部署
 
@@ -131,7 +134,7 @@ vi .env
 
 - **production** - 生产环境（推荐，启用资源限制与安全配置）
 - **lowmem** - 低配环境（适用于 1C2G 服务器）
-- **basic** - 基础环境（测试用，无资源限制）
+- **default** - 默认环境（无资源限制，适用于开发或高配服务器）
 
 ### 环境变量
 

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/commands/shell/db.js

@@ -2,6 +2,7 @@ import { Command } from '@oclif/core';
 import { runCompose, getComposeFiles } from '../../utils/docker.js';
 import { logger } from '../../utils/logger.js';
 import { EnvFlag, selectEnvironment } from '../../utils/selection.js';
+import { getEnvValue } from '../../utils/env.js';
 export default class ShellDb extends Command {
     static description = '进入数据库 shell (psql)';
     static flags = {
@@ -11,7 +12,9 @@ export default class ShellDb extends Command {
         const { flags } = await this.parse(ShellDb);
         const env = await selectEnvironment(flags.env);
         const { files, isBuiltIn } = await getComposeFiles(env);
+        // 从环境变量获取数据库名，默认为 nodebbs
+        const dbName = await getEnvValue('POSTGRES_DB') || 'nodebbs';
         logger.info('正在进入数据库 shell...');
-        await runCompose(files, ['exec', 'postgres', 'psql', '-U', 'postgres', '-d', 'nodebbs'], isBuiltIn);
+        await runCompose(files, ['exec', 'postgres', 'psql', '-U', 'postgres', '-d', dbName], isBuiltIn);
     }
 }