Love_Chengke/ClassHelper
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(server,web,desktop,shared,deploy,docs): Linux 一键安装与 classhelper 运维命令、更新检查、图表去 echarts，版本统一 1.1.0

Browse Source 
Linux 交付链（新增）
- deploy/install.sh：一键安装器（CLASSHELPER 大字 TUI、native/docker 双形态、向导选安装目录/
  端口/数据库/初始管理员密码）；识别 apt/yum/dnf 只补缺的依赖、建独立系统用户、下载内置 Node
  运行时（glibc < 2.28 的 CentOS 7 自动改用 unofficial-builds 的 glibc-217 构建）、幂等覆盖安装
  （保留 config.env 与 data/，不重置密钥）、全程写 /var/log/classhelper/install.log；
  `--check` 只体检（不需要 root）、`--yes` 无人值守、`--package` 支持内网离线分发。
- deploy/classhelper：运维命令 —— status / doctor / password / backup(list,restore,schedule) /
  upgrade / rollback / start|stop|restart|reload / logs / config / port / key rotate / uninstall /
  completion / help。特权操作一律校验 EUID，关键动作写 /var/log/classhelper/audit.log。
- deploy/tools/admin-cli.mjs：离线账号工具（改密、列账号、VACUUM INTO 一致性快照、哈希回滚），
  直连数据库 —— 服务停机也能救急，不需要先有一个能登录的账号。
- deploy/{classhelper.service,profile.d,logrotate.d,systemd}/ 模板 + Dockerfile.linux-package。
- scripts/dist-server.mjs 增加 --platform linux（根脚本 `pnpm dist:server:linux`），产物
  classhelper-server-linux-x64-<版本>.tar.gz + 同名 .sha256；新增 GitHub Actions workflow 在
  ubuntu runner 上构建并挂 Release（@libsql/linux-* 这类平台相关依赖只能在 Linux 上装）。
- docs/linux-deploy.md：安装 / 运维命令 / 升级回滚 / 备份恢复 / 排障 / 安全清单 /
  Ubuntu 22.04 与 Rocky 9 的验收清单。deploy/install-linux.sh 改为转发壳，不留两份实现。

三处必须知道的取舍（已写进 AGENTS.md §5 第 59 条）
- 配置真身在 /etc/classhelper/config.env，安装目录里的 .env 是指向它的软链：Web 端
  「数据库管理 → 一键切换」改写的是 <安装目录>/.env，而 systemd 注入的是同一份配置 ——
  两处不是同一个文件时，切换会「看起来成功、重启后又连回旧库」。classhelper doctor 有专门断言。
- 升级/回滚替换程序文件用「改名 + 就位」而不是 rm+cp：升级时正在运行的就是 bin/classhelper
  自己，直接删掉同名文件会让 bash 读到半个脚本。
- 交叉构建（在非 Linux 机器上打 Linux 包）会在包内写 .cross-built 标记、doctor 据此提示：
  已核对 @libsql/linux-x64-gnu 与 -musl 就位且无 win32 残留，但 prisma CLI 的原生 schema engine
  是宿主平台的，Web 端「数据库一键切换」那一步存疑；正式产物一律走 CI。

更新检查（此前只在工作区，本次一并提交）
- 服务端 modules/update：由服务端转发 GitHub Releases（Web 端 CSP 不允许直连），离线/限流/超时
  一律收敛成 ok:false + 一句人话，失败结果同样进缓存；?force=1 只对管理员生效（避免刷爆匿名限流）。
- 版本比较放 @classhelper/shared（compareVersions / isNewerVersion），三端共用；服务端版本号
  改由 lib/version.ts 读 package.json，不再在 app.ts 里写字面量。
- Web 端顶栏「检查更新」弹窗、客户端「关于」页的检查更新与诊断信息。

Web 端 / 客户端
- 成绩图表改用自包含的轻量组件（ScoreBarChart / ScoreLineChart），不再全量引入 echarts
  （原先 echarts 占桌面端渲染产物 1.12MB、Web 端 1.13MB）；柱状图是纯 HTML/CSS，折线图是
  viewBox SVG，均无 resize 监听。
- Element Plus 图标改为按需注册（两端各一份 icons.ts），新增 scripts/check-icons.mjs 静态门禁
  并挂进两端 build —— 漏注册的后果是界面静默渲染空白，只在控制台一条 warning。

版本号统一 1.1.0
- 5 份 package.json、deploy/package.runtime.json、.env.example 的 APP_VERSION、
  docker-compose 与两个 Dockerfile 的镜像标签、Linux 安装包名示例、README 首页版本；
- ClassIsland 插件 manifest.yml 与 BridgeService.PluginVersion 同步（verify:classisland-plugin
  有 manifest ↔ code 的一致性断言）；
- 刻意保持不变的是**历史性表述与举例**：docs/mysql.md 的「自 v1.0.0 起内置 MySQL 适配器」、
  shared/utils.ts 讲版本比较用的 1.0.0 / 1.0.0-fix、README 验收表里的实测记录。
This commit is contained in:
LoveChengke committed 2026-10-05 16:39:38 +08:00
1 parent aad22df4fd
commit 9a38f86cd3
77 files changed
+8021 -899
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/production.md
+85 -109
View File
@@ -6,7 +6,7 @@
| --------------------- | -------------------------------------------- | -------------------------------------------------------- | -------------------------------------- |
| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统） | `release-server/班级小助手服务端-<版本>-x64-setup.exe` | ✅ 已完整实测（静默安装/启停/卸载/UI） |
| **B. Docker + MySQL** | 云服务器、多终端共享一套数据（推荐长期方案） | `deploy/Dockerfile` + `deploy/docker-compose.yml` | ⚠️ 文件已提供，本机无 Docker 未实测 |
| **C. Linux 原生部署** | 已有 Linux 服务器（systemd + SQLite） | `deploy/install-linux.sh` + `deploy/classhelper.service` | ⚠️ 脚本已提供，本机无 Linux 未实测 |
| **C. Linux 原生部署** | 已有 Linux 服务器（systemd，SQLite 或 MySQL） | [`deploy/install.sh`](../deploy/install.sh) + `classhelper` 运维命令 | ⚠️ 本机无 Linux，实机验收见 [linux-deploy.md](linux-deploy.md) §10 |
| **D. 手动部署** | 已有 Node 环境的服务器、需要自定义 | `pnpm dist:server` 的免安装目录 | ✅ 免安装目录已实测（163 项端到端） |
---
@@ -25,7 +25,7 @@ pnpm dist:server -- --reuse-deps # 迭代打包：复用已安装依赖，跳
| 路径 | 说明 |
| ----------------------------------------------------- | ----------------------------------------------- |
| `release-server/classhelper-server/` | 免安装目录，可直接拷到任意 Windows x64 机器运行 |
| `release-server/班级小助手服务端-1.0.0-x64-setup.exe` | 安装程序（约 34 MB，NSIS） |
| `release-server/班级小助手服务端-1.1.0-x64-setup.exe` | 安装程序（约 34 MB，NSIS） |
打包内容：内置 **Node 运行时**（目标机无需安装 Node.js）、后端产物、Web 管理端产物、
生产依赖（真实目录，非软链）、迁移 SQL、`.env`（随机 JWT 密钥）、启停脚本。
@@ -35,7 +35,7 @@ pnpm dist:server -- --reuse-deps # 迭代打包：复用已安装依赖，跳
双击安装程序即可，**无需管理员权限**（当前用户级安装）：
- 安装目录：`%LOCALAPPDATA%\Programs\ClassHelperServer`
- 静默安装：`"班级小助手服务端-1.0.0-x64-setup.exe" /S`
- 静默安装：`"班级小助手服务端-1.1.0-x64-setup.exe" /S`
- 开始菜单：启动服务 / 停止服务 / 重启服务 / 打开管理端 / 使用说明 / 卸载
- 桌面：`班级小助手服务端.lnk`（打开管理端）
- 自动加入当前用户开机自启（`HKCU\...\CurrentVersion\Run`）
@@ -149,108 +149,97 @@ docker compose -f deploy/docker-compose.sqlite.yml --env-file deploy/.env.sqlite
---
## 三、Linux 原生部署（形态 C，systemd + SQLite）
## 三、Linux 部署（形态 C，推荐一键安装器）
适用：Ubuntu / Debian / CentOS / Rocky 等有 systemd 的服务器，单机跑一套（SQLite），
用 Nginx 挂 HTTPS 给校内网/公网访问。
适用：Ubuntu 20.04+ / Debian 11+ / CentOS 7+ / Rocky / AlmaLinux，任何有 systemd 的服务器
（容器环境用下面的 Docker 形态）。**完整指南见 [linux-deploy.md](linux-deploy.md)**，这里是速查。
### 3.1 一键脚本（推荐）
### 3.1 一键安装（推荐）
在**仓库根目录**先构建，然后执行脚本（需要 root）：
Linux 包由 GitHub Actions 在 ubuntu runner 上构建（平台相关的依赖只能在 Linux 上装），
产物挂在 Release 上；也可以本地 `pnpm dist:server:linux` 后把 tar.gz 拷到服务器。
安装器脚本两个文件都在仓库的 `deploy/` 下：
```bash
# 1) 构建（Node ≥ 20.19，推荐 22 LTS；目标机没有 pnpm 时可在别的机器上构建后拷仓库过来）
corepack enable && corepack prepare pnpm@11.8.0 --activate
pnpm install
pnpm build:shared
pnpm --filter @classhelper/server build
pnpm --filter @classhelper/web-admin build
# 开发机：做出 Linux 包并连同脚本一起拷到服务器
pnpm dist:server:linux
scp release-server/classhelper-server-linux-x64-*.tar.gz deploy/install.sh deploy/verify-linux.sh \
root@<服务器>:/tmp/
# 2) 安装成 systemd 服务
sudo bash deploy/install-linux.sh # 默认端口 4000、目录 /opt/classhelper
# 常用变体：
# bash deploy/install-linux.sh --check # 只体检（不需要 root）：校验构建产物/Node/端口探针
# sudo bash deploy/install-linux.sh --port 8080
# sudo bash deploy/install-linux.sh --dir /srv/classhelper
# sudo bash deploy/install-linux.sh --no-service # 只铺文件，自己托管进程
# sudo bash deploy/install-linux.sh --uninstall # 停服务并移除 unit（保留 data 与 .env）
# 服务器上
bash /tmp/install.sh --check # 只体检（不需要 root，不改动系统）
sudo bash /tmp/install.sh # 交互式：选形态 → 选目录 → 选库 → 设初始管理员密码
```
> 建议先跑一次 `--check`：它只读地校验"构建产物齐不齐、Node 版本够不够、目标端口上有没有旧实例"，
> 不需要 root，也不会改任何东西。输出示例见 `deploy/install-linux.sh` 头部注释。
脚本做的事：建系统用户 `classhelper` → 把后端产物、`prisma/migrations`、Web 管理端拷到
`/opt/classhelper` → `npm install --omit=dev`（清单就是 `deploy/package.runtime.json`，与
容器运行时同一份）→ 生成 `.env`（随机 `JWT_SECRET`、`AUTO_MIGRATE=true`）→ 装 systemd unit →
`enable --now` → 轮询 `/healthz` 就绪后打印地址与初始管理员。
安装后的目录（与已验证的 Windows 免安装目录同构，因此 `.env` 里的相对路径语义一致）：
```
/opt/classhelper/
├── .env 全部配置（权限 600）
├── server/dist 后端程序（入口 index.js）
├── server/prisma 迁移 SQL（首启动自动执行）
├── web/ Web 管理端（后端托管，单端口）
├── node_modules/ 仅生产依赖
├── data/ classhelper.db + server.pid（备份只复制这里）
└── logs/
```
首次启动会自动建表并创建管理员 `admin / admin123`（**登录后立刻改密码**）。
### 3.2 手动部署（不想用脚本 / 没有 systemd）
等价的手工步骤，便于排查：
非交互（批量部署 / 验收用）：
```bash
sudo useradd --system --shell /usr/sbin/nologin classhelper
sudo mkdir -p /opt/classhelper/{server,web,data,logs}
printf '%s\n' 'StrongPass!2026' | sudo bash /tmp/install.sh --yes \
--dir /srv/classhelper --port 8080 --admin-password-stdin \
--package /tmp/classhelper-server-linux-x64-1.1.0.tar.gz
```
# 程序产物
sudo cp -R packages/server/dist /opt/classhelper/server/dist
sudo cp -R packages/server/prisma /opt/classhelper/server/prisma
sudo cp -R packages/web-admin/dist /opt/classhelper/web
sudo cp deploy/package.runtime.json /opt/classhelper/package.json
安装器做的事：识别发行版与包管理器补依赖 → 建系统用户 `classhelper` → 下载包并校验 sha256 →
铺文件（`server/` `web/` `node_modules/` `tools/` `bin/`）→ 下载内置 Node 运行时 →
写 `/etc/classhelper/config.env`（随机 `JWT_SECRET`，权限 600）→ 装 systemd 单元与
`/usr/local/bin/classhelper` → 启动并轮询 `/healthz` 通过为止。全过程写
`/var/log/classhelper/install.log`。
# 生产依赖 + 工作区共享包
cd /opt/classhelper && sudo npm install --omit=dev --no-audit --no-fund
sudo mkdir -p /opt/classhelper/node_modules/@classhelper/shared
sudo cp -R packages/shared/dist /opt/classhelper/node_modules/@classhelper/shared/dist
sudo cp packages/shared/package.json /opt/classhelper/node_modules/@classhelper/shared/package.json
重跑就是**覆盖安装**：`config.env`（含密钥）与 `data/` 保留，已登录用户不会被踢下线。
# 配置（参考脚本生成的 .env，务必自己生成 JWT_SECRET）
sudo tee /opt/classhelper/.env >/dev/null <<'EOF'
NODE_ENV=production
HOST=0.0.0.0
PORT=4000
DATABASE_PROVIDER=sqlite
DATABASE_URL="file:../data/classhelper.db"
AUTO_MIGRATE=true
JWT_SECRET=换成 openssl rand -hex 48 的输出
JWT_EXPIRES_IN=7d
CORS_ORIGIN=https://class.example.com
TRUST_PROXY=1
RATE_LIMIT_ENABLED=true
STARTUP_DB_CHECK=true
PID_FILE=../data/server.pid
LOG_LEVEL=info
EOF
### 3.2 安装后的布局与运维
sudo chown -R classhelper:classhelper /opt/classhelper/{data,logs,node_modules} /opt/classhelper/.env
sudo chmod 600 /opt/classhelper/.env
```
/opt/classhelper/ 程序、node_modules、内置 Node、data/、tools/、bin/
/etc/classhelper/config.env 唯一配置真身（600）；安装目录里的 .env 是指向它的软链
/var/log/classhelper/ install.log + audit.log
/var/backups/classhelper/ 备份与程序快照（回滚用）
```
# systemd
sudo sed -e 's#__NODE__#/usr/bin/node#' -e 's#__DIR__#/opt/classhelper#' -e 's#__USER__#classhelper#' \
deploy/classhelper.service | sudo tee /etc/systemd/system/classhelper.service
> 为什么安装目录的 `.env` 是软链：Web 端「数据库管理 → 一键切换」改写的是 `<安装目录>/.env`，
> 而 systemd 用 `EnvironmentFile=` 注入同一份配置；两处不是同一个文件时，切换会"看起来成功、
> 重启后又连回旧库"。软链把两者收成一份真身（`classhelper doctor` 会检查它）。
日常运维全部走 `classhelper`（`classhelper help` 看全部）：
| 事项 | 命令 |
| ------ | --------------------------------------------------------------------------------------- |
| 状态 | `classhelper status [--json]` |
| 体检 | `classhelper doctor`（权限 / Node / 服务单元 / 探针 / 数据库 / 磁盘 / 备份） |
| 改密码 | `classhelper password [用户名]`（交互输入、不回显、不进 shell history） |
| 备份 | `classhelper backup`；每日自动：`classhelper backup schedule daily` |
| 升级 | `classhelper upgrade [--check]`（下载 + 校验 sha256 + 备份 + 替换 + 探针，失败自动回滚） |
| 回滚 | `classhelper rollback [--list]` |
| 日志 | `classhelper logs -f` |
| 改配置 | `classhelper config set KEY VALUE` / `config show` / `port 8080` |
| 换密钥 | `classhelper key rotate`（所有用户需重新登录） |
| 卸载 | `classhelper uninstall`（默认保留配置、数据与备份） |
| 服务 | `classhelper start｜stop｜restart｜reload` |
### 3.3 手动部署（不想用安装器 / 没有 systemd）
没有 systemd 的容器里可以用安装器的"只铺文件"模式，再自己托管进程：
```bash
sudo bash /tmp/install.sh --yes --force --package /tmp/classhelper-server-linux-x64-1.1.0.tar.gz
sudo -u classhelper /opt/classhelper/runtime/node/bin/node /opt/classhelper/server/dist/index.js
```
完全手工也可以（等价步骤，便于排查）：解包后把 `server/` `web/` `node_modules/` `tools/` 铺到安装目录，
配置写到 `/etc/classhelper/config.env`（`JWT_SECRET` 用 `openssl rand -hex 48`），再用
`deploy/classhelper.service` 模板生成单元 —— 注意模板有 5 个占位符
（`__NODE__` `__DIR__` `__USER__` `__CONFIG__` `__CONFIGDIR__`）：
```bash
sudo sed -e "s#__NODE__#/opt/classhelper/runtime/node/bin/node#" \
-e "s#__DIR__#/opt/classhelper#" -e "s#__USER__#classhelper#" \
-e "s#__CONFIG__#/etc/classhelper/config.env#" -e "s#__CONFIGDIR__#/etc/classhelper#" \
deploy/classhelper.service > /tmp/classhelper.service
sudo install -m 644 /tmp/classhelper.service /etc/systemd/system/classhelper.service
sudo systemctl daemon-reload && sudo systemctl enable --now classhelper
systemctl status classhelper --no-pager
```
也可以用 PM2 之类托管（`pm2 start /opt/classhelper/server/dist/index.js --name classhelper`），
但 systemd 更省心：`Restart=always`、日志进 journald、开机自启一次配好。
### 3.3 Nginx + HTTPS
### 3.4 Nginx + HTTPS
```bash
sudo cp deploy/nginx.conf /etc/nginx/conf.d/classhelper.conf
@@ -259,7 +248,7 @@ sudo nginx -t && sudo systemctl reload nginx
```
`deploy/nginx.conf` 已经处理了最容易踩的两点：`/socket.io/` 的 WebSocket 升级头，
以及 `X-Forwarded-For/X-Forwarded-Proto` 透传（配合 `.env` 里 `TRUST_PROXY=1`，限流才会按真实 IP 统计）。
以及 `X-Forwarded-For/X-Forwarded-Proto` 透传（配合配置里的 `TRUST_PROXY=1`，限流才会按真实 IP 统计）。
用 certbot 签证书：
```bash
@@ -267,31 +256,19 @@ sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d class.example.com
```
### 3.4 升级 / 备份 / 排障
升级（不会动 `.env`，JWT 密钥不变，学生端不用重新登录）：
### 3.5 验收
```bash
git pull && pnpm install
pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build
sudo bash deploy/install-linux.sh # 覆盖程序文件 + 自动补迁移（AUTO_MIGRATE）
journalctl -u classhelper -n 30 --no-pager
sudo bash /tmp/verify-linux.sh --admin-password-stdin <<< 'StrongPass!2026'
# 追加升级 / 回滚链路（会真的替换一次程序文件）：
sudo bash /tmp/verify-linux.sh --full --package /tmp/classhelper-server-linux-x64-1.0.1.tar.gz \
--admin-password-stdin <<< 'StrongPass!2026'
```
| 事项 | 命令 |
| -------- | ---------------------------------------------------------------------------------------------------------- |
| 备份 | `systemctl stop classhelper && cp -a /opt/classhelper/data /root/classhelper-data-$(date +%F)`（然后启动） |
| 恢复 | 停服务 → 用备份覆盖 `data/` → 启动 |
| 看日志 | `journalctl -u classhelper -f` |
| 重启 | `systemctl restart classhelper`（改 `.env` 后必须重启） |
| 探针 | `curl -s localhost:4000/healthz` / `/readyz`（就绪 200，数据库不可用 503） |
| 换端口 | 改 `.env` 的 `PORT` → 重启；同时改 Nginx 的 `upstream` |
| 换数据库 | 见 `docs/mysql.md`：切 provider + 装 `@prisma/adapter-mariadb` + `npx prisma migrate deploy` |
覆盖安装结果、服务探针、API 登录、改密（含审计与回滚）、备份、配置读写、key rotate、
升级与回滚整条链路，末尾打印 `=== 结果：N/N 项通过 ===`。逐条清单见
[linux-deploy.md](linux-deploy.md) 第 10 节。
> 注意：本机（开发环境）是 Windows 且无 Docker/WSL 发行版，因此 **3.1 的脚本没有在 Linux 实机跑过**。
> 它复用的两套东西都已验证：Windows 免安装目录（同样的目录结构、`.env` 相对路径与
> `AUTO_MIGRATE` 首启动行为）和 `deploy/Dockerfile` 的 runtime 阶段（同样的依赖清单与产物布局）。
> 首次在服务器上执行后请按 3.4 的探针 + Web 登录 + `pnpm verify:e2e`（把 `VERIFY_BASE_URL` 指向服务器）确认。
---
@@ -337,7 +314,6 @@ start.cmd :: Windows
| `PID_FILE` | — | PID 文件路径（安装包启停脚本依赖），相对 `server` 根 |
| `WEB_DIST_DIR` | 自动探测 | Web 管理端产物目录（`../web-admin/dist` 或 `./web`） |
| `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |
| `DEFAULT_STUDENT_PASSWORD` | `123456` | 新增/重置学生账号的默认密码 |
| `DEFAULT_CLASS_PASSWORD` | `123456` | 新建班级时班级账号（学生端登录）的默认密码 |
| `DEFAULT_TEACHER_PASSWORD` | `123456` | 新增/重置教师账号的默认密码（管理员录入教师用） |
| `TERM_START_DATE` | — | 第 1 教学周的周一，用于"当前周次"与课表默认视图 |