Novora 文档

外观

9. 日常维护（Vercel 云端） ​

维护包括源码更新、部署监控、数据库备份、账号审计和故障处理。按固定周期检查，比出现问题后再处理更稳妥。

这里只讲 Vercel 云端维护。本地/内网部署的更新脚本、数据卷备份和反向代理维护见本地更新与维护。

更新前原则 ​

每次更新前先完成：

  1. 阅读目标版本的 Release Notes 和升级说明；
  2. 确认当前生产版本；
  3. 备份 Neon 数据；
  4. 记录当前 Vercel 成功部署；
  5. 避开考试和上课高峰；
  6. 准备回滚方案。

V2 对旧字段有一定兼容和按需补列能力，但不保证所有 V1 自定义业务数据自动迁移。跨大版本升级前必须单独验证。

第一步：确认 Fork 与生产分支 ​

先在 Vercel Settings → Git 查看 Connected Git Repository。

检查项正确状态
Connected Git Repository自己账号或学校组织下、来源为 PikaNova/Novora 的 Fork
Production Branchmain
作者发布新版后先将作者仓库同步到自己的 Fork，再部署
有学校自定义代码时建立升级分支，合并上游、解决冲突和测试后再合入 main

唯一的代码更新来源是同步 Fork

Deploy Hook、Redeploy 和 Vercel 的重新构建都不会下载作者仓库的新代码。自己的 Fork 未同步时，无论重新部署多少次，线上版本都不会变化。

第二步：备份并记录当前状态 ​

  1. 在 Novora “系统设置 → 版本与更新”记录当前版本。
  2. 在 Vercel Deployments 记录当前 Ready 的生产 Deployment、提交号和时间。
  3. 使用 Neon 分支、pg_dump 或学校既定方案备份数据库。
  4. 导出需要额外留存的大型考试和周测 JSON。
  5. 选择没有考试、周测和课堂使用的维护窗口。

第三步：同步作者仓库到 Fork ​

使用 Fork 时，可以通过 GitHub 的 Sync fork 获取上游更新。若存在自己的代码修改，不要在生产前直接强制覆盖，应先在分支中合并并检查冲突。

零基础 Fork 更新步骤：

  1. 登录 GitHub，打开自己名下的 Novora 仓库。
  2. 检查页面是否显示 This branch is behind PikaNova/Novora。
  3. 点击 Sync fork。
  4. 点击 Update branch。
  5. 等待同步完成，确认生产分支仍为 main。
  6. 打开最新提交，确认版本文件和 Release Notes 对应目标版本。

如果 GitHub 提示冲突，不要点击丢弃自定义提交。应先建立测试分支处理冲突，或联系维护人员。同步完成后，Fork 的 main 才包含新版代码。

必须整目录同步

V2.8.0 起，api/ 目录的内部结构有调整（为了适配 Vercel 的函数数量上限， 入口合并、私有模块移到 _ 前缀目录），vercel.json 也增加了函数配置。 升级时请用 Sync fork 或 git pull 整目录更新，不要只复制个别文件， 否则会出现「构建通过但接口 404」或函数数量超限。

第四步：确认版本和同步结果 ​

  1. 使用有部署权限的超级管理员登录。
  2. 打开 系统设置 → 版本与更新。
  3. 点击 检查更新。
  4. 核对当前版本、最新版本和更新说明。
  5. 展开 查看后续更新完整流程，确认前置工作已完成。

如果客户端发现新版本，但 Fork 尚未同步，先返回 GitHub 同步源码。进入 Fork 的 main 提交页，确认最新提交已经包含目标版本，再进行部署。

“检查更新”读取官方 GitHub Release；它只负责比较版本，不会下载代码、修改数据库或自动开始部署。

第五步：等待或触发 Vercel 部署 ​

同步到 Fork 的 main 后，Vercel 的 Git 集成通常会自动创建新的 Production Deployment。优先使用这条自动部署：

  1. 打开 Vercel 项目 Deployments。
  2. 确认出现以 Fork main 最新提交为来源的新部署。
  3. 打开构建详情，确认依赖安装、npm run build 和输出发布成功。
  4. 等待 Production 状态变为 Ready。

如果同步完成后几分钟内没有自动部署，先在 Settings → Git 检查 Connected Git Repository 和 Production Branch 是否仍指向自己的 Fork main。确认无误后，可以在 Vercel 对该提交执行 Redeploy。

也可以由具备 deployment.trigger 权限的管理员在 Novora 的“系统设置 → 版本与更新”点击 一键部署更新。该按钮只是调用 VERCEL_DEPLOY_HOOK_URL 重新构建当前 Fork；它不是获取更新的步骤，只应在 Fork 已完成同步而 Vercel 未自动开始部署时使用。若按钮不可用，回到配置环境变量：创建 Deploy Hook检查 Hook、Production 环境和 Redeploy。

重新部署不会自动修改 Neon 中已存在的管理员密码，也不会清空业务数据。

第六步：更新后验收 ​

每次更新至少验证：

  • 首页和自定义域名；
  • /api/time；
  • 管理员登录；
  • 后台读取和保存；
  • 当前班级考试大屏；
  • PDF 下载；
  • ClassIsland 同步（如启用）；
  • 浏览器更新提示和缓存刷新。

同时在“系统设置 → 关于”确认当前版本已经变化。若仍显示旧版本：

  1. 确认 Fork 的 main 确实包含新版本；
  2. 确认 Vercel 新部署使用的是该提交；
  3. 等待 Service Worker 更新提示并刷新；
  4. 必要时关闭全部旧标签页后重新打开。

第七步：记录更新结果 ​

记录更新时间、旧版本、新版本、Git 提交、Vercel Deployment、数据库备份位置、执行人和验收结果。学校多人维护时，这一步能避免重复部署和版本责任不清。

更新失败时回滚 ​

若新部署出现严重问题：

  1. 打开 Vercel 项目的 Deployments；
  2. 找到更新前已验证成功的部署；
  3. 使用平台当前提供的 Promote、Rollback 或重新部署功能恢复；
  4. 验证主域名是否已指向旧版本；
  5. 记录故障版本和影响。

代码回滚不等于数据库回滚

如果新版本已经改变数据库数据，恢复旧前端代码不一定能恢复数据状态。数据库恢复必须基于更新前备份评估，不能盲目覆盖生产库。

数据库备份和恢复 ​

使用 PostgreSQL 官方工具导出：

bash
pg_dump --dbname="生产连接串" --format=custom --no-owner --no-privileges --file=novora-YYYY-MM-DD.dump

恢复到一套新的空数据库进行演练：

bash
pg_restore --dbname="测试数据库连接串" --no-owner --no-privileges novora-YYYY-MM-DD.dump

不要直接拿未验证的备份覆盖生产数据库。恢复演练应使用独立 Neon 项目或分支，并确认管理员登录、学校结构和考试数据完整。

数据维护和重置 ​

系统设置支持整体或按模块清理大型考试、周测、学校结构、设备/插件和调度设置。登录用户不会随普通业务数据重置自动删除。

数据重置是高风险操作。执行前：

  • 确认选择的模块；
  • 导出或备份数据；
  • 通知正在使用系统的人员；
  • 避免多名管理员同时操作；
  • 完成后重新验收设备绑定和调度。

记录表维护脚本（V2.8.0） ​

两个一次性脚本，平时不需要跑。执行前先备份数据库，并在没有考试和上课的时段进行； 脚本读取环境里的 DATABASE_URL，在项目目录里执行。

bash
# 1. 旧考试的记录缺少时间窗与时间戳时回填
npm run backfill:record-timestamps

# 2. 清理「快照已删除、记录表还留着」的孤儿记录
npm run purge:orphan-records                              # 只统计，不删除
npm run purge:orphan-records -- --yes                     # 确认后真的删除
npm run purge:orphan-records -- --yes --with-operations   # 连带删除这些考试的操作日志
  • 孤儿记录在界面上看不到（列表按快照过滤），但会一直累积，建议每学期清理一次；
  • 默认不动 exam_record_operations：那是审计与操作历史，留着比删掉安全；
  • 判断口径与 GET /api/exams?resource=record-consistency 返回的 orphaned 一致。

查看日志 ​

V2.8.0 起，排查日志有两个来源：Vercel 平台日志（所有请求）和 Novora 内置的诊断日志（管理员主动上传的错误包）。

Vercel Functions 日志 ​

遇到 API 错误时：

  1. 记录页面显示的请求 ID、时间和操作；
  2. 打开 Vercel 项目的 Logs 或 Functions 日志；
  3. 按请求 ID 搜索；
  4. 检查是认证、权限、数据库、GitHub API 还是外部网络错误；
  5. 不要在公开反馈中粘贴完整环境变量。

超时或临时断线可以有限次数重试；认证失败、环境变量缺失和数据库结构问题应先修正根因。

诊断日志（V2.8.0 起） ​

管理员可以在 系统设置 → 诊断日志 里配置本机错误包的保留策略：

设置项说明
错误发生时保留前后日志出错时采集前后各若干秒的客户端日志
日志保留天数1–30 天，超期自动清除，不占用空间
手动上传只有管理员主动点击后，日志包才会发送给作者端

默认情况下日志只留在这台设备上，不会自动外发。需要作者协助排查时，先在诊断日志面板点一次手动上传，再把页面显示的请求 ID 一起提供给维护人员。

同意遥测后，客户端还会静默上报影响稳定性的错误（接口 5xx、数据库读写失败、页面渲染异常、分包加载失败等）。权限不足、登录过期、密码错误这类正常业务提示不会作为系统错误上报；作者端不可用时自动跳过，不影响正常使用。上报内容经过脱敏，不包含考试正文、管理员密码、恢复密钥和登录会话。

账号维护 ​

建议每月检查：

  • 超级管理员数量；
  • 停用账号；
  • 年级和班级授权范围；
  • 审计日志中的异常删除、重置或部署操作；
  • 是否仍有人共享账号；
  • 密码重置后旧会话是否失效。

域名维护 ​

  • 开启域名自动续费并检查付款方式；
  • 不要删除 Vercel 要求的 DNS 记录；
  • 更换 DNS 服务商前完整复制记录；
  • 域名或证书异常时先查看 Vercel Domains 状态；
  • 每学期至少用学校网络和移动网络复测。

推荐维护周期 ​

周期工作
每周检查部署、数据库和关键页面是否正常
每月数据备份、账号权限和审计日志检查
每学期校历、周次、节假日、年级班级和设备复核
每次更新前读发布说明、备份、安排维护窗口
每次更新后执行核心验收和记录版本

遇到问题时进入故障排查。需要修改代码时进入本地开发。

Novora 部署与维护文档

内容基于 Novora V2.8.1 整理