快速开始

本页帮助你在本机把 CSMS 跑起来，并完成首次数据库初始化。

环境要求

依赖	版本要求	说明
Node.js	≥ 18（推荐 22+）	运行与构建 CSMS
包管理器	npm / pnpm	安装依赖
数据库	SQLite（内置）	无需额外安装，由 Drizzle 驱动

当前文档以 Node.js 22 为例。Windows 用户建议使用 PowerShell 5.1+。

安装

# 1. 获取源码
git clone https://github.com/QianKunBoss/ClassScoreManageSystem.git
cd ClassScoreManageSystem

# 2. 安装依赖
npm install
# 或使用 pnpm（本仓库锁定 pnpm@9.9.0）
# pnpm install

环境变量

复制环境变量示例并按需修改：

cp .env.example .env

关键变量：

变量	必填	说明
`NUXT_SESSION_PASSWORD`	✅	Session 加密密钥，运行期实时生效，任何部署方式都必须设置。可用 `openssl rand -hex 32` 生成
`SESSION_SECRET`	⚪	构建期备选密钥，运行期修改无效
`HOST`	⚪	监听地址，默认 `::`
`PORT`	⚪	监听端口，默认 `3000`
`NODE_ENV`	⚪	运行环境

注意

NUXT_SESSION_PASSWORD 在 Windows 下即使使用预构建产物（.output）也必须设置，否则无法启动。

初始化数据库

# 生成迁移文件（首次或 schema 变更后）
npm run db:generate

# 执行迁移，创建主库与分库表结构
npm run db:migrate

# （可选）直接推送 schema，无需手写迁移
# npm run db:push

# （可选）打开 Drizzle Studio 查看数据
# npm run db:studio

开发模式

npm run dev

默认监听 http://localhost:3000。首次启动后访问首页，按完成学校入驻与首个管理员创建。

生产构建

npm run build
# 构建产物位于 .output/
npm run preview
# 或直接运行
node .output/server/index.mjs

生产部署的多种方式（Docker / PM2 / Windows / 宝塔）请见。

数据库操作速查

命令	作用
`npm run db:generate`	根据 schema 生成迁移 SQL
`npm run db:migrate`	执行迁移
`npm run db:push`	直接同步 schema 到数据库（跳过迁移文件）
`npm run db:studio`	启动 Drizzle Studio 可视化浏览数据

数据持久化与备份

CSMS 的数据全部位于 data/ 目录：

主库：data/csms.db（学校、管理员、公告、API 凭证等系统级数据）
各校分库：data/schools/{schoolId}.db（年级、班级、学生、积分等）