From d42b0b2a1baf4364f1440ade2319ae6961c989c7 Mon Sep 17 00:00:00 2001 From: LoveChengke Date: Sat, 12 Sep 2026 08:49:41 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E5=AE=89=E8=A3=85?= =?UTF-8?q?=E5=8C=85=E6=95=85=E9=9A=9C=E6=8E=92=E6=9F=A5=EF=BC=88shared=20?= =?UTF-8?q?=E6=97=A7=E6=9E=84=E5=BB=BA=20/=20Electron=20=E5=AE=BF=E4=B8=BB?= =?UTF-8?q?=E4=B8=8B=E7=9A=84=20node.exe=EF=BC=89=E5=B9=B6=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=E6=A0=A1=E9=AA=8C=E9=A1=B9=E5=8F=A3=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/production.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/production.md b/docs/production.md index 6de5b45..ea0e2a3 100644 --- a/docs/production.md +++ b/docs/production.md @@ -214,22 +214,24 @@ start.cmd :: Windows ## 六、故障排查 -| 现象 | 排查方向 | -| ------------------ | ----------------------------------------------------------------------------- | -| 浏览器打不开管理端 | `status.cmd`；`logs\server.log` 是否有启动报错；端口是否被占用 | -| 启动即退出（生产） | 数据库不可用（`DATABASE_URL`/MySQL 未就绪）或 `JWT_SECRET` 未按生产要求配置 | -| 页面能开但接口 401 | 令牌过期或更换过 `JWT_SECRET`，重新登录 | -| 限流误伤（自己人） | 反向代理未设 `TRUST_PROXY=1`，导致所有请求都算作代理 IP | -| 实时推送不生效 | 反向代理未放行 `/socket.io/` 的 WebSocket 升级（见 nginx 样例） | -| 安装后服务没起来 | 查看 `logs\server.error.log`；`start.cmd` 会输出就绪等待结果 | -| 数据库文件损坏 | 从备份恢复 `data/classhelper.db`；SQLite 场景请确保同一时间只有一个服务实例 | -| 升级后需要重新登录 | 说明 `.env` 被覆盖（JWT 密钥变化）；覆盖安装应保留 `.env`，请检查安装目录权限 | +| 现象 | 排查方向 | +| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 浏览器打不开管理端 | `status.cmd`；`logs\server.log` 是否有启动报错；端口是否被占用 | +| 启动即退出（生产） | 数据库不可用（`DATABASE_URL`/MySQL 未就绪）或 `JWT_SECRET` 未按生产要求配置 | +| 页面能开但接口 401 | 令牌过期或更换过 `JWT_SECRET`，重新登录 | +| 限流误伤（自己人） | 反向代理未设 `TRUST_PROXY=1`，导致所有请求都算作代理 IP | +| 实时推送不生效 | 反向代理未放行 `/socket.io/` 的 WebSocket 升级（见 nginx 样例） | +| 安装后服务没起来 | 查看 `logs\server.error.log`；`start.cmd` 会输出就绪等待结果 | +| 数据库文件损坏 | 从备份恢复 `data/classhelper.db`；SQLite 场景请确保同一时间只有一个服务实例 | +| 升级后需要重新登录 | 说明 `.env` 被覆盖（JWT 密钥变化）；覆盖安装应保留 `.env`，请检查安装目录权限 | +| 报 `does not provide an export named ...` | 安装包内的 `node_modules/@classhelper/shared/dist` 是旧构建（打包机没有先构建 shared）。重新执行 `pnpm dist:server`，该脚本会先构建 shared/server/web 并校验产物新鲜度 | +| 报 `node.exe` 不是有效应用 / 服务启动即退出 | 安装包内置的 `node.exe` 被误打成 Electron 可执行文件（打包机在 Electron 宿主里跑 pnpm 时会取到 `process.execPath`）。已由 `scripts/lib/node-runtime.mjs` 修正；可用 `install\node.exe -v` 确认能打印 Node 版本 | --- ## 七、性能与容量参考 -- 单机 SQLite 形态适合**单校规模**（数千用户、每天数百次写操作），实测 54 项接口与实时推送全部达标。 +- 单机 SQLite 形态适合**单校规模**（数千用户、每天数百次写操作），实测 62 项接口与实时推送全部达标。 - 多校区 / 高并发建议切 MySQL，并横向扩容服务端（Socket.IO 需要配置 Redis adapter 才能多实例广播， 当前为单实例广播；如需多实例请参考 `packages/server/src/realtime/socket.ts` 引入 `@socket.io/redis-adapter`）。 - 静态资源已设置 immutable 长缓存 + gzip；Web 管理端为 SPA，首屏包体约 900 KB（gzip 约 290 KB），