CLI 命令
您可以使用 Paideia LMS 提供的命令行界面（CLI）来运行服务器、管理数据库迁移以及从终端窗口执行管理任务。
Paideia LMS 是一个双模式二进制文件，既可以作为 Web 服务器，也可以作为命令行界面。默认情况下，不带任何参数运行 paideia 会启动服务器。通过运行 paideia <command> 可以使用 CLI 命令。
运行 Paideia
Section titled “运行 Paideia”启动服务器（默认行为）:
# 启动服务器（默认行为）paideia
# 或显式指定paideia server获取帮助:
# 显示帮助信息和可用命令paideia help终端将显示以下消息：
╔═══════════════════════════════════════════════════════╗║ ║║ ██████╗ █████╗ ██╗██████╗ ██████╗██╗ █████╗ ║║ ██╔══██╗██╔══██╗██║██╔══██╗██╔═══╝██║██╔══██╗ ║║ ██████╔╝███████║██║██║ ██║██████╗██║███████║ ║║ ██╔═══╝ ██╔══██║██║██║ ██║██╔═══╝██║██╔══██║ ║║ ██║ ██║ ██║██║██████╔╝██████╗██║██║ ██║ ║║ ╚═╝ ╚═╝ ╚═╝╚═╝╚═════╝ ╚═════╝╚═╝╚═╝ ╚═╝ ║║ ║║ Learning Management System ║║ ║╚═══════════════════════════════════════════════════════╝
Paideia LMS - 0.5.5 Paideia CLI Commands┌────────────────────────┬───────────────────────────────────────────────────────────────┐│ Command │ Description │├────────────────────────┼───────────────────────────────────────────────────────────────┤│ paideia help │ Show help ││ paideia server │ Start the Paideia server ││ paideia migrate status │ Show migration status ││ paideia migrate up │ Run pending migrations ││ paideia migrate fresh │ Drop all database entities and re-run migrations from scratch ││ paideia migrate dump │ Dump database to SQL file ││ paideia sandbox reset │ Reset sandbox database (only when SANDBOX_MODE is enabled) │└────────────────────────┴───────────────────────────────────────────────────────────────┘paideia server
Section titled “paideia server”启动 Paideia LMS Web 服务器。这是不带任何参数运行 paideia 时的默认行为。
# 启动服务器paideia server
# 或简单运行（默认行为）paideia服务器将启动并监听配置的端口（默认：后端 3001，前端 3000）。服务器将一直运行，直到使用 Ctrl+C 停止。
paideia help
Section titled “paideia help”显示 ASCII 徽标、介绍和可用命令。这提供了 Paideia LMS 功能和所有 CLI 命令的概述。
paideia helppaideia version
Section titled “paideia version”显示 Paideia LMS 版本号。
paideia versionPaideia LMS 提供了一套全面的数据库迁移命令，用于管理数据库架构和执行管理任务。
paideia migrate status
Section titled “paideia migrate status”显示所有数据库迁移的当前状态。这将显示哪些迁移已运行，哪些待处理。
paideia migrate status输出示例:
Migration Name Status────────────────────────────────────────1234567890_initial_schema ✅ Applied1234567891_add_users_table ✅ Applied1234567892_add_courses_table ⏳ Pendingpaideia migrate up
Section titled “paideia migrate up”运行所有待处理的迁移。这将应用尚未执行的任何迁移。
paideia migrate up使用场景:
- 更新 Paideia LMS 后应用数据库架构更改
- 在生产环境中运行新迁移
- 拉取代码更改后更新数据库结构
paideia migrate fresh
Section titled “paideia migrate fresh”删除所有数据库实体并从头重新运行所有迁移。这是一个破坏性操作，将删除所有数据和架构，然后重建所有内容。
# 全新迁移（将提示确认）paideia migrate fresh
# 或使用强制标志跳过确认paideia migrate fresh --force-accept-warning使用场景:
- 开发期间完全重置数据库
- 从干净的数据库开始
- 从头重建数据库
paideia migrate dump
Section titled “paideia migrate dump”将整个数据库转储到 SQL 文件。这将创建数据库的备份，可以在以后恢复。
# 使用自动生成的文件名转储paideia migrate dump
# 使用自定义文件名转储paideia migrate dump -o my-backup.sql
# 或使用长格式paideia migrate dump --output my-backup.sql输出位置: 所有转储文件都保存到项目根目录的 paideia_data/ 目录中。如果目录不存在，将自动创建。
文件名格式: 如果未指定文件名，转储文件将命名为 paideia-dump-{timestamp}.sql。
使用场景:
- 在重大更改之前创建数据库备份
- 导出数据库以迁移到另一台服务器
- 创建灾难恢复备份
- 通过 cron 作业或脚本自动备份
输出示例:
paideia migrate dump
# ✅ 数据库转储完成: paideia_data/paideia-dump-2025-11-02T10-30-45-123Z.sqlPaideia LMS 为开发和测试环境提供沙盒管理命令。
paideia sandbox reset
Section titled “paideia sandbox reset”当 SANDBOX_MODE 启用时，手动重置沙盒数据库。此命令删除所有用户数据（学生、课程等），同时保留系统表（作业日志、迁移等），在重置过程中实现零停机时间。
# 重置沙盒数据库（仅在 SANDBOX_MODE 启用时有效）paideia sandbox reset要求:
SANDBOX_MODE环境变量必须设置为"1"或"true"- 如果沙盒模式被禁用，命令将静默退出
功能:
- 删除所有用户数据集合（用户、课程、注册、提交等）
- 保留系统表（
payload-jobs、payload-jobs-log、payload-migrations等） - 使用
seed.json（如果可用）中的新数据重新填充数据库 - 实现零停机时间 - 应用程序在重置期间继续运行
使用场景:
- 开发期间手动重置数据库
- 测试数据库重置功能
- 在不重启服务器的情况下重置测试数据
- 在保留系统状态的同时清除用户数据
输出示例:
paideia sandbox reset
╔═══════════════════════════════════════════════════════╗║ ║║ ██████╗ █████╗ ██╗██████╗ ██████╗██╗ █████╗ ║║ ██╔══██╗██╔══██╗██║██╔══██╗██╔═══╝██║██╔══██╗ ║║ ██████╔╝███████║██║██║ ██║██████╗██║███████║ ║║ ██╔═══╝ ██╔══██║██║██║ ██║██╔═══╝██║██╔══██║ ║║ ██║ ██║ ██║██║██████╔╝██████╗██║██║ ██║ ║║ ╚═╝ ╚═╝ ╚═╝╚═╝╚═════╝ ╚═════╝╚═╝╚═╝ ╚═╝ ║║ ║║ Learning Management System ║║ ║╚═══════════════════════════════════════════════════════╝
🔄 正在重置沙盒数据库...✅ 沙盒数据库重置成功完成！零停机时间
沙盒重置过程通过在重置期间保留系统表来实现零停机时间。应用程序在清除和重新填充用户数据时继续正常运行。这与删除整个数据库并导致停机的 migrate fresh 不同。
所有命令都支持以下全局标志：
--help 或 -h
Section titled “--help 或 -h”显示指定命令的帮助信息。
paideia migrate --help迁移命令标志
Section titled “迁移命令标志”--force-accept-warning
Section titled “--force-accept-warning”跳过破坏性操作的确认提示。请谨慎使用。
适用于:
paideia migrate fresh
示例:
paideia migrate fresh --force-accept-warning-o 或 --output（用于 migrate dump）
Section titled “-o 或 --output（用于 migrate dump）”指定数据库转储的自定义输出文件名。文件名相对于 paideia_data/ 目录。
示例:
paideia migrate dump -o backup-before-update.sql-
始终先备份: 在生产环境中运行迁移之前创建数据库转储
终端窗口 paideia migrate dump -o backup-before-migration.sqlpaideia migrate up -
检查状态: 在应用迁移之前和之后验证迁移状态
终端窗口 paideia migrate status -
在开发环境中测试: 始终先在开发环境中测试迁移
-
谨慎使用 Fresh: 仅在开发环境中使用
migrate fresh
-
定期备份: 安排定期数据库转储
终端窗口 # 每日备份的 cron 作业示例0 2 * * * cd /path/to/paideia && paideia migrate dump -o daily-$(date +\%Y-\%m-\%d).sql -
在重大更改之前: 始终在以下操作之前转储：
- 运行迁移
- 更新 Paideia LMS
- 进行重大架构更改
-
存储: 将转储文件移动到外部存储（S3 等）以长期保留
-
测试: 定期测试恢复过程以确保备份有效
- 转储位置: 所有数据库转储自动保存到
paideia_data/目录 - 目录创建: 如果
paideia_data/目录不存在，将自动创建 - Git 忽略:
paideia_data/目录自动被 git 忽略 - Docker 忽略:
paideia_data/目录从 Docker 构建中排除
Paideia CLI 命令返回适当的退出代码：
- 0: 命令成功完成
- 1: 命令失败并出现错误
这允许轻松集成到脚本和自动化工具中：
#!/bin/bashif paideia migrate up; then echo "迁移应用成功"else echo "迁移失败" exit 1fi编译二进制文件支持
Section titled “编译二进制文件支持”所有 CLI 命令都可以与编译的单二进制文件部署无缝配合：
-
开发: 直接运行命令
终端窗口 bun server/index.ts migrate status -
生产: 编译为单二进制文件并运行
终端窗口 bun build server/index.ts --compile --outfile paideia./paideia migrate status
CLI 模式可以与编译的二进制文件配合使用，因为：
- 迁移在编译时捆绑到二进制文件中
- 迁移实用程序没有文件系统依赖
- 所有命令在编译和非编译模式下工作方式相同
迁移命令不工作:
- 确保您在正确的项目目录中
- 检查数据库连接是否正确配置
- 验证
DATABASE_URL环境变量是否已设置
转储命令失败:
- 检查您在项目目录中是否有写入权限
- 确保有足够的磁盘空间
- 验证数据库连接是否处于活动状态
服务器无法启动:
- 检查所需端口是否已被使用
- 验证环境变量是否正确设置
- 检查日志以获取特定错误消息
- 配置参考 - 环境变量和配置选项
- 安装和设置 - 初始设置和配置
- 数据库管理 (EN) - 数据库管理和管理
