nodebbs 0.0.0 → 0.0.1

package/README.md

@@ -1,397 +1,526 @@
-nodebbs
-=================
-
-A new CLI generated with oclif
+# NodeBBS CLI
 
+> 全栈友好的 NodeBBS 部署和管理命令行工具
 
 [![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
 [![Version](https://img.shields.io/npm/v/nodebbs.svg)](https://npmjs.org/package/nodebbs)
-[![Downloads/week](https://img.shields.io/npm/dw/nodebbs.svg)](https://npmjs.org/package/nodebbs)
 
+## 📖 简介
 
-<!-- toc -->
-* [Usage](#usage)
-* [Commands](#commands)
-<!-- tocstop -->
-# Usage
-<!-- usage -->
-```sh-session
-$ npm install -g nodebbs
-$ nodebbs COMMAND
-running command...
-$ nodebbs (--version)
-nodebbs/0.0.0 darwin-arm64 node-v22.19.0
-$ nodebbs --help [COMMAND]
-USAGE
-  $ nodebbs COMMAND
-...
-```
-<!-- usagestop -->
-# Commands
-<!-- commands -->
-* [`nodebbs hello PERSON`](#nodebbs-hello-person)
-* [`nodebbs hello world`](#nodebbs-hello-world)
-* [`nodebbs help [COMMAND]`](#nodebbs-help-command)
-* [`nodebbs plugins`](#nodebbs-plugins)
-* [`nodebbs plugins add PLUGIN`](#nodebbs-plugins-add-plugin)
-* [`nodebbs plugins:inspect PLUGIN...`](#nodebbs-pluginsinspect-plugin)
-* [`nodebbs plugins install PLUGIN`](#nodebbs-plugins-install-plugin)
-* [`nodebbs plugins link PATH`](#nodebbs-plugins-link-path)
-* [`nodebbs plugins remove [PLUGIN]`](#nodebbs-plugins-remove-plugin)
-* [`nodebbs plugins reset`](#nodebbs-plugins-reset)
-* [`nodebbs plugins uninstall [PLUGIN]`](#nodebbs-plugins-uninstall-plugin)
-* [`nodebbs plugins unlink [PLUGIN]`](#nodebbs-plugins-unlink-plugin)
-* [`nodebbs plugins update`](#nodebbs-plugins-update)
+NodeBBS CLI 是一个专为全栈开发者设计的命令行工具，用于简化 NodeBBS 项目的开发、部署和管理流程。它提供了直观的命令接口，让你可以轻松管理 Docker 容器、查看日志、操作数据库等。
+
+### 特性
+
+- 🚀 **快速启动** - 一键启动开发环境
+- 🎯 **全栈友好** - 命令设计贴近开发者思维
+- 🔧 **服务级控制** - 可以单独管理每个服务
+- 📊 **实时日志** - 方便查看各服务日志
+- 💾 **数据库管理** - 内置数据库迁移和管理工具
+- 🌐 **内置模板** - 无需本地配置文件即可使用
+- 🇨🇳 **中文界面** - 所有输出均为中文
 
-## `nodebbs hello PERSON`
+## 📦 安装
 
-Say hello
+```bash
+# 使用 npm
+npm install -g nodebbs
 
+# 使用 pnpm
+pnpm add -g nodebbs
+
+# 使用 yarn
+yarn global add nodebbs
 ```
-USAGE
-  $ nodebbs hello PERSON -f <value>
 
-ARGUMENTS
-  PERSON  Person to say hello to
+或者直接使用 npx（无需安装）：
+
+```bash
+npx nodebbs [command]
+```
 
-FLAGS
-  -f, --from=<value>  (required) Who is saying hello
+## 🚀 快速开始
 
-DESCRIPTION
-  Say hello
+### 1. 初始化项目
 
-EXAMPLES
-  $ nodebbs hello friend --from oclif
-  hello friend from oclif! (./src/commands/hello/index.ts)
+```bash
+# 首次使用，初始化项目环境
+npx nodebbs setup
 ```
 
-_See code: [src/commands/hello/index.ts](https://github.com/nodebbs/nodebbs/blob/v0.0.0/src/commands/hello/index.ts)_
+这会创建 `.env` 文件，请编辑该文件并修改：
+- `POSTGRES_PASSWORD` - 数据库密码
+- `REDIS_PASSWORD` - Redis 密码
+- `JWT_SECRET` - JWT 密钥
 
-## `nodebbs hello world`
+### 2. 启动开发环境
 
-Say hello world
+```bash
+# 启动所有服务
+npx nodebbs dev
 
+# 或者重新构建并启动
+npx nodebbs dev --rebuild
 ```
-USAGE
-  $ nodebbs hello world
 
-DESCRIPTION
-  Say hello world
+### 3. 查看服务状态
 
-EXAMPLES
-  $ nodebbs hello world
-  hello world! (./src/commands/hello/world.ts)
+```bash
+# 查看所有服务状态
+npx nodebbs status
 ```
 
-_See code: [src/commands/hello/world.ts](https://github.com/nodebbs/nodebbs/blob/v0.0.0/src/commands/hello/world.ts)_
+### 4. 访问应用
 
-## `nodebbs help [COMMAND]`
+- **Web 前端**: http://localhost:3100
+- **API 文档**: http://localhost:7100/docs
+- **健康检查**: http://localhost:7100/api
 
-Display help for nodebbs.
+## 📚 命令参考
 
+### 核心命令
+
+#### `nodebbs setup`
+初始化项目（首次使用）
+
+```bash
+npx nodebbs setup
 ```
-USAGE
-  $ nodebbs help [COMMAND...] [-n]
 
-ARGUMENTS
-  [COMMAND...]  Command to show help for.
+#### `nodebbs dev`
+启动开发环境
 
-FLAGS
-  -n, --nested-commands  Include all nested commands in the output.
+```bash
+# 启动所有服务
+npx nodebbs dev
 
-DESCRIPTION
-  Display help for nodebbs.
+# 重新构建并启动
+npx nodebbs dev --rebuild
+npx nodebbs dev -r
+
+# 指定环境启动
+npx nodebbs dev -e production
+npx nodebbs dev -e lowmem
+npx nodebbs dev -e basic
 ```
 
-_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.36/src/commands/help.ts)_
+**参数**：
+- `-e, --env` - 部署环境（production, lowmem, basic）
+- `-r, --rebuild` - 重新构建镜像
 
-## `nodebbs plugins`
+#### `nodebbs deploy`
+部署到生产环境
 
-List installed plugins.
+```bash
+# 完整部署流程
+npx nodebbs deploy
 
+# 指定环境部署
+npx nodebbs deploy -e production
 ```
-USAGE
-  $ nodebbs plugins [--json] [--core]
 
-FLAGS
-  --core  Show core plugins.
+包含：
+- Docker 环境检查
+- 环境变量验证
+- 镜像构建
+- 服务启动
+- 健康检查
+- 数据库初始化（可选）
 
-GLOBAL FLAGS
-  --json  Format output as json.
+#### `nodebbs stop`
+停止服务
 
-DESCRIPTION
-  List installed plugins.
+```bash
+# 停止所有服务
+npx nodebbs stop
 
-EXAMPLES
-  $ nodebbs plugins
+# 停止服务并删除数据卷（危险！）
+npx nodebbs stop --volumes
+npx nodebbs stop -v
 ```
 
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/index.ts)_
+**参数**：
+- `-v, --volumes` - 同时删除数据卷
 
-## `nodebbs plugins add PLUGIN`
+#### `nodebbs restart`
+重启所有服务
 
-Installs a plugin into nodebbs.
+```bash
+npx nodebbs restart
+```
 
+#### `nodebbs status`
+查看服务状态
+
+```bash
+npx nodebbs status
 ```
-USAGE
-  $ nodebbs plugins add PLUGIN... [--json] [-f] [-h] [-s | -v]
 
-ARGUMENTS
-  PLUGIN...  Plugin to install.
+### 日志管理
 
-FLAGS
-  -f, --force    Force npm to fetch remote resources even if a local copy exists on disk.
-  -h, --help     Show CLI help.
-  -s, --silent   Silences npm output.
-  -v, --verbose  Show verbose npm output.
+#### `nodebbs logs`
+查看所有服务日志
 
-GLOBAL FLAGS
-  --json  Format output as json.
+```bash
+npx nodebbs logs
+```
 
-DESCRIPTION
-  Installs a plugin into nodebbs.
+#### `nodebbs logs:api`
+查看 API 服务日志
 
-  Uses npm to install plugins.
+```bash
+npx nodebbs logs:api
+```
 
-  Installation of a user-installed plugin will override a core plugin.
+#### `nodebbs logs:web`
+查看 Web 服务日志
 
-  Use the NODEBBS_NPM_LOG_LEVEL environment variable to set the npm loglevel.
-  Use the NODEBBS_NPM_REGISTRY environment variable to set the npm registry.
+```bash
+npx nodebbs logs:web
+```
 
-ALIASES
-  $ nodebbs plugins add
+#### `nodebbs logs:db`
+查看数据库日志
 
-EXAMPLES
-  Install a plugin from npm registry.
+```bash
+npx nodebbs logs:db
+```
 
-    $ nodebbs plugins add myplugin
+#### `nodebbs logs:redis`
+查看 Redis 日志
 
-  Install a plugin from a github url.
+```bash
+npx nodebbs logs:redis
+```
 
-    $ nodebbs plugins add https://github.com/someuser/someplugin
+### Shell 访问
 
-  Install a plugin from a github slug.
+#### `nodebbs shell:api`
+进入 API 容器
 
-    $ nodebbs plugins add someuser/someplugin
+```bash
+npx nodebbs shell:api
 ```
 
-## `nodebbs plugins:inspect PLUGIN...`
+#### `nodebbs shell:web`
+进入 Web 容器
 
-Displays installation properties of a plugin.
+```bash
+npx nodebbs shell:web
+```
 
+#### `nodebbs shell:db`
+进入数据库（自动启动 psql）
+
+```bash
+npx nodebbs shell:db
 ```
-USAGE
-  $ nodebbs plugins inspect PLUGIN...
 
-ARGUMENTS
-  PLUGIN...  [default: .] Plugin to inspect.
+#### `nodebbs shell:redis`
+进入 Redis（自动启动 redis-cli）
 
-FLAGS
-  -h, --help     Show CLI help.
-  -v, --verbose
+```bash
+npx nodebbs shell:redis
+```
 
-GLOBAL FLAGS
-  --json  Format output as json.
+### 数据库管理
 
-DESCRIPTION
-  Displays installation properties of a plugin.
+#### `nodebbs db`
+打开数据库管理界面（Drizzle Studio）
 
-EXAMPLES
-  $ nodebbs plugins inspect myplugin
+```bash
+npx nodebbs db
 ```
 
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/inspect.ts)_
+#### `nodebbs db:generate`
+生成数据库迁移文件
 
-## `nodebbs plugins install PLUGIN`
+```bash
+npx nodebbs db:generate
+```
 
-Installs a plugin into nodebbs.
+#### `nodebbs db:migrate`
+执行数据库迁移
 
+```bash
+npx nodebbs db:migrate
 ```
-USAGE
-  $ nodebbs plugins install PLUGIN... [--json] [-f] [-h] [-s | -v]
 
-ARGUMENTS
-  PLUGIN...  Plugin to install.
+#### `nodebbs db:push`
+推送数据库 schema
 
-FLAGS
-  -f, --force    Force npm to fetch remote resources even if a local copy exists on disk.
-  -h, --help     Show CLI help.
-  -s, --silent   Silences npm output.
-  -v, --verbose  Show verbose npm output.
+```bash
+npx nodebbs db:push
+```
 
-GLOBAL FLAGS
-  --json  Format output as json.
+#### `nodebbs db:seed`
+初始化数据库数据
 
-DESCRIPTION
-  Installs a plugin into nodebbs.
+```bash
+npx nodebbs db:seed
+```
 
-  Uses npm to install plugins.
+#### `nodebbs db:reset`
+重置并重新初始化数据（危险！）
 
-  Installation of a user-installed plugin will override a core plugin.
+```bash
+npx nodebbs db:reset
+```
 
-  Use the NODEBBS_NPM_LOG_LEVEL environment variable to set the npm loglevel.
-  Use the NODEBBS_NPM_REGISTRY environment variable to set the npm registry.
+## 🎯 使用场景
 
-ALIASES
-  $ nodebbs plugins add
+### 场景 1：新开发者加入项目
 
-EXAMPLES
-  Install a plugin from npm registry.
+```bash
+# 1. 初始化项目
+npx nodebbs setup
 
-    $ nodebbs plugins install myplugin
+# 2. 启动开发环境
+npx nodebbs dev
 
-  Install a plugin from a github url.
+# 3. 初始化数据库
+npx nodebbs db:push
+npx nodebbs db:seed
 
-    $ nodebbs plugins install https://github.com/someuser/someplugin
+# 4. 查看服务状态
+npx nodebbs status
+```
 
-  Install a plugin from a github slug.
+### 场景 2：日常开发
 
-    $ nodebbs plugins install someuser/someplugin
-```
+```bash
+# 启动开发环境
+npx nodebbs dev
 
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/install.ts)_
+# 查看 API 日志
+npx nodebbs logs:api
 
-## `nodebbs plugins link PATH`
+# 进入 API 容器调试
+npx nodebbs shell:api
 
-Links a plugin into the CLI for development.
+# 打开数据库管理
+npx nodebbs db
 
+# 重置测试数据
+npx nodebbs db:reset
 ```
-USAGE
-  $ nodebbs plugins link PATH [-h] [--install] [-v]
 
-ARGUMENTS
-  PATH  [default: .] path to plugin
+### 场景 3：代码更新后重新构建
+
+```bash
+# 停止服务
+npx nodebbs stop
 
-FLAGS
-  -h, --help          Show CLI help.
-  -v, --verbose
-      --[no-]install  Install dependencies after linking the plugin.
+# 重新构建并启动
+npx nodebbs dev --rebuild
 
-DESCRIPTION
-  Links a plugin into the CLI for development.
+# 查看日志确认启动成功
+npx nodebbs logs
+```
 
-  Installation of a linked plugin will override a user-installed or core plugin.
+### 场景 4：生产部署
 
-  e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
-  command will override the user-installed or core plugin implementation. This is useful for development work.
+```bash
+# 部署到生产环境
+npx nodebbs deploy -e production
 
+# 查看服务状态
+npx nodebbs status
 
-EXAMPLES
-  $ nodebbs plugins link myplugin
+# 查看日志
+npx nodebbs logs
+
+# 执行数据库迁移
+npx nodebbs db:migrate
 ```
 
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/link.ts)_
+### 场景 5：数据库操作
+
+```bash
+# 打开数据库管理界面
+npx nodebbs db
 
-## `nodebbs plugins remove [PLUGIN]`
+# 运行迁移
+npx nodebbs db:migrate
 
-Removes a plugin from the CLI.
+# 填充数据
+npx nodebbs db:seed
 
+# 进入数据库命令行
+npx nodebbs shell:db
 ```
-USAGE
-  $ nodebbs plugins remove [PLUGIN...] [-h] [-v]
 
-ARGUMENTS
-  [PLUGIN...]  plugin to uninstall
+## 🔄 从 Makefile 迁移
 
-FLAGS
-  -h, --help     Show CLI help.
-  -v, --verbose
+如果你之前使用 Makefile，这里是命令对照表：
 
-DESCRIPTION
-  Removes a plugin from the CLI.
+| Makefile 命令 | NodeBBS CLI 命令 |
+|--------------|-----------------|
+| `make init` | `npx nodebbs setup` |
+| `make up` | `npx nodebbs dev` |
+| `make build` | `npx nodebbs dev --rebuild` |
+| `make rebuild` | `npx nodebbs dev --rebuild` |
+| `ENV=prod make rebuild` | `npx nodebbs deploy -e production` |
+| `make down` | `npx nodebbs stop` |
+| `make restart` | `npx nodebbs restart` |
+| `make ps` | `npx nodebbs status` |
+| `make logs` | `npx nodebbs logs` |
+| `make logs-api` | `npx nodebbs logs:api` |
+| `make exec-api` | `npx nodebbs shell:api` |
+| `make db-studio` | `npx nodebbs db` |
+| `make clean-all` | `npx nodebbs stop --volumes` |
 
-ALIASES
-  $ nodebbs plugins unlink
-  $ nodebbs plugins remove
+## ⚙️ 环境配置
 
-EXAMPLES
-  $ nodebbs plugins remove myplugin
-```
+### 支持的环境
 
-## `nodebbs plugins reset`
+- **basic** - 基础环境（仅用于测试）
+- **lowmem** - 低配环境（1C1G/1C2G）
+- **production** - 生产环境（2C4G+，推荐）
 
-Remove all user-installed and linked plugins.
+### 环境变量
 
-```
-USAGE
-  $ nodebbs plugins reset [--hard] [--reinstall]
+在 `.env` 文件中配置：
+
+```env
+# 数据库配置
+POSTGRES_PASSWORD=your_secure_password
+POSTGRES_DB=nodebbs
+
+# Redis 配置
+REDIS_PASSWORD=your_redis_password
+
+# JWT 配置
+JWT_SECRET=your_jwt_secret
 
-FLAGS
-  --hard       Delete node_modules and package manager related files in addition to uninstalling plugins.
-  --reinstall  Reinstall all plugins after uninstalling.
+# 应用配置
+APP_URL=http://localhost:3100
+API_URL=http://localhost:7100
+
+# CORS 配置
+CORS_ORIGIN=*
 ```
 
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/reset.ts)_
+## 🛠️ 高级用法
 
-## `nodebbs plugins uninstall [PLUGIN]`
+### 内置模板
 
-Removes a plugin from the CLI.
+NodeBBS CLI 内置了 Docker Compose 配置文件，即使项目中没有这些文件，也可以直接使用：
 
+```bash
+# 在任何目录运行
+npx nodebbs dev
 ```
-USAGE
-  $ nodebbs plugins uninstall [PLUGIN...] [-h] [-v]
 
-ARGUMENTS
-  [PLUGIN...]  plugin to uninstall
+CLI 会自动：
+1. 检查当前目录是否有 `docker-compose.yml`
+2. 如果没有，使用内置模板
+3. 使用当前目录作为项目目录
 
-FLAGS
-  -h, --help     Show CLI help.
-  -v, --verbose
+### 自定义配置
 
-DESCRIPTION
-  Removes a plugin from the CLI.
+如果需要自定义配置，在项目根目录创建：
+- `docker-compose.yml` - 基础配置
+- `docker-compose.prod.yml` - 生产环境配置
+- `docker-compose.lowmem.yml` - 低配环境配置
 
-ALIASES
-  $ nodebbs plugins unlink
-  $ nodebbs plugins remove
+CLI 会优先使用本地配置文件。
 
-EXAMPLES
-  $ nodebbs plugins uninstall myplugin
-```
+## 🐛 故障排除
 
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/uninstall.ts)_
+### 服务启动失败
 
-## `nodebbs plugins unlink [PLUGIN]`
+```bash
+# 查看日志
+npx nodebbs logs
 
-Removes a plugin from the CLI.
+# 查看特定服务日志
+npx nodebbs logs:api
 
+# 检查服务状态
+npx nodebbs status
 ```
-USAGE
-  $ nodebbs plugins unlink [PLUGIN...] [-h] [-v]
 
-ARGUMENTS
-  [PLUGIN...]  plugin to uninstall
+### 数据库连接问题
 
-FLAGS
-  -h, --help     Show CLI help.
-  -v, --verbose
+```bash
+# 进入数据库检查
+npx nodebbs shell:db
+
+# 重置数据库
+npx nodebbs db:reset
+```
 
-DESCRIPTION
-  Removes a plugin from the CLI.
+### 端口冲突
 
-ALIASES
-  $ nodebbs plugins unlink
-  $ nodebbs plugins remove
+检查以下端口是否被占用：
+- 3100 - Web 前端
+- 7100 - API 服务
+- 5432 - PostgreSQL
+- 6379 - Redis
 
-EXAMPLES
-  $ nodebbs plugins unlink myplugin
+### 清理环境
+
+```bash
+# 停止所有服务
+npx nodebbs stop
+
+# 停止并删除所有数据（危险！）
+npx nodebbs stop --volumes
 ```
 
-## `nodebbs plugins update`
+## 📝 开发
+
+### 本地开发
 
-Update installed plugins.
+```bash
+# 克隆仓库
+git clone https://github.com/nodebbs/nodebbs.git
+cd nodebbs
 
+# 安装依赖
+pnpm install
+
+# 构建
+pnpm build
+
+# 运行
+./bin/run.js [command]
 ```
-USAGE
-  $ nodebbs plugins update [-h] [-v]
 
-FLAGS
-  -h, --help     Show CLI help.
-  -v, --verbose
+### 测试命令
+
+```bash
+# 查看帮助
+./bin/run.js --help
+
+# 测试 dev 命令
+./bin/run.js dev --help
 
-DESCRIPTION
-  Update installed plugins.
+# 测试 logs 命令
+./bin/run.js logs --help
 ```
 
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/update.ts)_
-<!-- commandsstop -->
+## 🤝 贡献
+
+欢迎贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详情。
+
+## 📄 许可证
+
+MIT License - 详见 [LICENSE](LICENSE) 文件
+
+## 🔗 相关链接
+
+- [NodeBBS 项目](https://github.com/nodebbs/nodebbs)
+- [问题反馈](https://github.com/nodebbs/nodebbs/issues)
+- [更新日志](CHANGELOG.md)
+
+## 💡 提示
+
+- 使用 `npx nodebbs --help` 查看所有可用命令
+- 使用 `npx nodebbs [command] --help` 查看特定命令的帮助
+- 所有命令都支持 `--help` 参数
+- 建议在生产环境使用前先在测试环境验证
+
+---
+
+Made with ❤️ by NodeBBS Team