MathBank使用指南
v3.1.0GitHub下载软件
MATHBANK HANDBOOK / 06

更新与备份

先留一份完整备份,再安心更新。

本页目录
i
更新顺序:备份 → 关闭服务 → 合并新版内容 → 启动核对

保留原来的项目目录、浏览器和访问地址。按下方系统步骤合并程序文件。

先留一份完整备份

MathBank 的完整备份包含数据库、被引用的上传图片与自定义元数据,并附带文件校验清单。questions_backup.json 只是同步导出,不能代替可恢复的完整备份。

完整备份需要输入一条命令。先找到包含启动器的 MathBank 文件夹,选择电脑系统,再按下面的说明操作。

Windows 便携包:在文件资源管理器打开软件文件夹,在地址栏输入 powershell 并回车,再执行:

.\python\python.exe -m scripts.backup

源码版请使用你的项目虚拟环境解释器。

macOS:打开「终端」,输入 cd 和一个空格,将软件文件夹拖入窗口,回车后执行:

./venv/bin/python -m scripts.backup

确认工具报告成功,并在 data_backup/snapshots/ 找到 mathbank-backup-时间戳.zip。将这份备份另存到独立位置。

i
完整备份不包含 API 密钥

.env、本地 Token 和 API 密钥不会进入完整备份。换电脑后需重新配置密钥;如自行保留密钥文件,请私下妥善存放。

覆盖更新,按这个顺序

  1. 先保存编辑,再备份。保存当前未完成的题目修改,然后创建完整备份并确认成功。
  2. 安全关闭服务。使用 MathBank 的电源按钮或「关闭题库」,等待停止提示。仅关闭浏览器标签页不够。
  3. 下载并解压新版到临时目录。可在「系统设置 → 版本更新」检查,或前往发布页面。
  4. 复制新版文件夹里的内容到原目录。替换同名程序文件、合并目录,保留原有数据。
  5. 重新运行启动器。确认题库就绪、版本正确,并打开一道旧题核对题干与配图。

Windows:正常停服后先把便携包原目录里的 python 文件夹改为未占用的备份名,例如 python-before-upgrade,再复制新版目录内的内容。确认新版可启动后保留或清理旧运行时。

macOS 用 Finder 分两次复制

在新版解压目录按 Command + Shift + . 显示隐藏文件。

  1. 第一次:把新版目录里除 static 以外的内容复制到原题库目录,覆盖同名程序文件。
  2. 第二次:分别打开新版和旧版的 static 文件夹。把新版 static 里除 uploads 以外的内容复制进旧版 static,覆盖同名程序文件。旧的 static/uploads 留在原处,不要替换整个旧 static 文件夹。
macOS 备用方式:用终端合并

在终端输入 /usr/bin/ditto 和一个空格,拖入新版解压文件夹,再输入空格并拖入原题库文件夹。核对顺序为“新版目录、原题库目录”,然后回车。

受支持的旧版可直接跨版本升级,无需逐版安装。首次启动若需更新数据库结构,会自动先创建并校验数据库快照(自动快照只含数据库文件,升级前仍须另存上方含图片与自定义元数据的完整备份)。请等待启动完成,不要在迁移过程中强行关闭。

若要退回旧版,不能只换回旧程序文件;还需要恢复升级前的完整备份,否则较新的数据库结构可能无法由旧版打开。恢复后数据回到备份时的状态,升级后新增或修改的内容需另行保留。

正式下载、主分支与本地开发有什么区别?

已于 2026-11-18 核对 GitHub。最新正式下载仍为 V3.1.0,发布于北京时间 2026 年 11 月 17 日;Windows 与 macOS 附件均可用。同一版本号不表示源码和下载包包含完全相同的改动。

你使用的是对应功能
V3.1.0 正式下载包PDF 拆题恢复、可选 MinerU、基础 TikZ 几何构造与验算、包含/排除关键词、列表跳页、重复 ZIP 确认、Word 公式与列表改进,以及 macOS 可选外置资料存储。
GitHub 主分支 4040cf7在正式包之后增加 TikZ 参考图视向、关键线段方向、顶点位置投影拟合和点名避让改进;这些后续改进未包含在上述正式附件中。
本地开发预览GeoGebra 动态演示、前端体验调整及新版 PDF 报错解释。尚未进入上面核对的主分支或正式附件;教程会单独标注。

普通使用请下载正式 ZIP。不要因为教程里有本地预览,就把下载包缺少相应入口当成安装失败。返回正式软件下载。

V3.0.3 的更新

V3.0.3 正式下载包包含以下改进。

  • 启动地址:启动器核对当前程序目录,优先打开本目录已运行的题库;端口被其他程序占用时,提示确认后才切换并记住新端口。浏览器草稿、选题篮与未保存卷面仍留在原地址,不会自动迁移。
  • PDF 局部容错:部分配图或完整性说明缺失时保留可用正文并提示核对;完整模型回复中个别题目数据无效时,保留有效题卡,明确提示未接收的数量,需对照原页检查漏题。
  • Word / PDF 图片:改进正文与答案图片引用的识别和导出;Word 学生卷不再把仅属于答案的图片补到题干,答案版保留答案中的图片。PDF 同步改进原位图片及答案 TikZ 的处理。
  • 已保存试卷:重新载入时保留题目明确设置的 0 分,不再变回默认 5 分。

本次也包含下方 Pillow 与 Windows 兼容策略。更新后仍请对照原题核对内容、图片和分值;这些修复不代表模型返回的题目已全部正确。

来源记录边界:程序源码与安装包不携带个人收录批次记录;你在本机主动备份、分享或导出时,会保留相应来源声明。

V3.1.0 覆盖升级:从 3.0.3 升级时,首次启动先保留旧数据库快照,再更新数据库结构。启动后用原浏览器和原地址核对版本、旧题及配图。当前正式下载仍以页面所列 Release 为准。

源码用户:Pillow 与 Python 环境

V3.1.0 延续 V3.0.3 的 Python 兼容策略:Windows 便携包随包提供 Python,macOS 启动器使用本机项目的 Python 环境。

更新后的源码按实际 Python 环境选择图片处理依赖:Python 3.11 及以上使用 Pillow 13.0.0,Python 3.10 继续使用 Pillow 12.3.0。Windows 便携包继续保留 Python 3.10;12.3.0 的相关图片解码安全问题仍未消除,不能视为全平台安全修复完成。

macOS 旧环境可以继续用,怎样选择是否迁移?

现有 Python 3.10 环境可以继续运行。macOS 启动器优先复用项目原有的 venv;仅在电脑上安装新 Python,不会自动替换这个环境,也不能保证启动器随后选中新版本。

如希望使用 Pillow 13,可在确认新 Python 支持本机 macOS 后自行迁移:先保存、完整备份并正常关闭服务,将旧 venv 改名保留,再用新解释器的明确路径在原项目创建新的同名 venv,安装更新后源码的依赖。核对 Python 与 Pillow 版本,确认题目、图片及原浏览器草稿正常后,再决定是否删除旧环境。不要只把创建命令写成可能仍指向旧版本的 python3。

若迁移失败,先关闭服务,保留新环境供排查,再把旧环境恢复原名。详细命令与回退步骤见软件 README 的 macOS 可选迁移说明。本次不要求同时更换 Python;继续使用旧环境时仍需了解上方的安全边界。

给同事一份题目,用 ZIP 分享包

在「系统设置 → 题库分享」中,可以将选定题目导出为 ZIP 分享给同事,或直接批量导入他人分享的题目。分享包完整保留所选题目的题干、配图、解析、教师评析、分类、知识点、TikZ 与包内题间关联,接收方无需重新识别(请使用支持该分享格式的版本)。

  1. 筛选题目。按来源或关键词查找;展开「更多筛选」还可按教材位置与考查知识点选择。
  2. 勾选并核对。支持逐题勾选、「全选本页」与「全选筛选结果」;更换筛选不会清空已选项,可在「已选」查看跨页选择。需要分享全库时,先清除筛选,再全选筛选结果。
  3. 导出分享包。确认按钮上的题数后导出 ZIP。列表中的配图提示只为便于选择,分享包仍包含题目所需原图。
  4. 接收并导入。在同一页面切换「导入分享包」,选择 MathBank 导出的 ZIP,点击「批量导入」,等待完成提示。
!
同一个分享包重复导入,会再次新增全部题目

分享导入按新增处理,不查重、不覆盖已有题目,每道题分配新 ID,同名图片安全改名。通过校验后,系统会先创建完整备份,再一次性写入;若连接中断,先查看题库结果,再决定是否重试。

分享 ZIP 上限为 512 MiB,展开后总量上限为 1 GiB;较大的题库请按来源分批。分享包不包含 API 密钥、系统设置或已保存试卷。只分享有权传播的内容,并保留包内资料来源声明。

分享包用于向现有题库新增题目;完整备份用于换机或恢复整份题库。两者虽然都是 ZIP,不能互相替代。恢复完整备份会替换目标数据,操作前请继续阅读下方说明。

V3.1.0 的重复 ZIP 提醒:改名后的同一份 ZIP 也会提示。勾选确认后直接使用刚上传的 ZIP,再次新增包内题目。待确认文件暂存 10 分钟,可在确认前取消。从 V3.0.3 升级后可在新版界面看到该提示。

后台分批处理与断线查询

分享导入会显示校验、指纹处理、备份和写入等阶段,大题库会自动分批处理以减少等待与内存占用(进度显示写入完成后,请等待任务最终完成提示再关闭程序)。关闭设置窗口或刷新页面后会继续查询同一次任务;若网络断连,点击「重新连接」只会查询进度,不会重新上传或重复新增。导出同样在后台打包,完成后点击「下载分享包」即可。

启动或接受分享任务前,系统会预先检查所需目录能否写入;若提示空间不足、无写入权限或文件被占用,请按错误中标明的用途和目录排查。需要移动程序时,请先正常关闭服务,再移动整个 MathBank 文件夹。查看目录写入问题的处理步骤 →

若服务在提交期间意外中断、结果无法确认,请先核实题库与备份,再结束旧任务记录,不要把结果未知直接当作导入失败而盲目重传。

旧题缺图时的备份容错

分享导入前会自动备份现有题库。如果现有题库中某些旧题引用的图片文件已经丢失,系统会保留数据库原文、图片引用与其余可用图片,在备份清单中记录缺失项并提示缺图警告后继续导入(不会凭空补造图片,也不会删除旧题的图片引用;权限、空间、数据库或文件校验失败仍会阻止导入)。

手动执行的完整备份默认仍要求所有引用图片齐全。若确需在旧题缺图时创建备份,可在上方备份命令后追加 --allow-missing-images;含缺图记录的备份需使用 V3.0.2 或更高版本校验与恢复,且恢复后原先缺失的图片仍需另行补回。查看缺图导致备份失败的排查步骤 →

macOS 外接资料盘:V3.1.0 可选功能

V3.1.0 的 macOS 外置资料存储需要单独配置,默认关闭。启用后,题库主数据库、运行文件和资料索引继续保存在电脑内盘;已有资料不会因启用而整批迁走。新增正式配图及上传的 PDF、Word、TeX 原件先完整保存在本机,再由后台复制到指定外盘。

后台会核对文件大小与 SHA-256,确认外盘副本和本地索引已可靠保存,才允许清理本地缓存。默认在资料闲置约 1 小时后清理,并避开正在使用的请求和任务。以后通过原来的题目入口读取时,会先校验并回填需要的本地缓存;图片引用无需手动修改。

断盘时,仍可保存新题目和新资料。没有接外盘时,新增文件暂存在内盘,重新连接指定资料盘后继续校验、复制与迁出。已经只保存在外盘、且本机没有缓存的附件,需要接盘后才能查看、导出或交给模型读取;主库留内盘不等于全部附件也能离盘读取。请留意页面中的资料盘状态提示。

备份、覆盖更新或停用前,先回填

  1. 保存编辑并正常关闭题库服务。连接原来的资料盘,不要删除运行锁或强制清理资料索引。
  2. 在已启用外置存储的原程序目录中执行回填。macOS 使用该目录的 Python 环境,等待工具报告本地资料校验成功:
    ./venv/bin/python -m scripts.tiered_storage restore-local
    若提示外盘不可用、文件缺失或校验失败,先保留当前程序、外盘与索引,核对原因后重试。
  3. 再创建并核验完整备份,最后覆盖更新或停用。用旧代码覆盖、换电脑或关闭分层存储前,都须先确认回填成功;不能只关闭配置或换回旧程序。

同时保留外盘资料、本机原文档档案和 .system_generated/tiered_storage/ 中的配置、索引及记录。它们共同确定资料位置和校验值。原有完整备份 ZIP 仍用于恢复数据库、被引用的配图与自定义元数据,不能替代这些原文档和分层存储记录的独立保留。不要把“外盘副本已校验”当作另有一份独立备份。

这些文件和目录,需要保留

内容用途
*.db 与 WAL/SHM题库数据库及相关文件
static/uploads/已上传的题目配图
data_backup/备份、自定义元数据等
.env你自己的 API 配置
.system_generated/、venv/程序运行数据与本地环境

换电脑或恢复数据

先在新电脑准备对应系统的软件与环境,保留已验证的完整备份。恢复前必须完全关闭题库服务;实际恢复会替换当前数据,先确认目标电脑上没有需要保留的新题目。

查看完整备份的校验与恢复操作

沿用上方选择的系统与终端位置,把 备份文件.zip 替换为实际 ZIP 路径。

第一步:只检查备份,不替换数据。

Windows 便携包 · PowerShell

.\python\python.exe -m scripts.restore "备份文件.zip"

macOS · 终端

./venv/bin/python -m scripts.restore "备份文件.zip"

第二步:确认替换后,再恢复。仅在检查通过、服务已完全停止,且确定要用备份替换当前数据时执行:

.\python\python.exe -m scripts.restore "备份文件.zip" --apply --yes
./venv/bin/python -m scripts.restore "备份文件.zip" --apply --yes

若提示运行锁被占用,先返回软件正常关闭服务,不要删除锁文件。恢复后重新启动,检查题目和图片,并按需重新配置 API。

更新后仍显示旧版本?

很可能仍打开了旧的运行服务。先在网页内正常关闭题库,再运行原目录中的新版启动器。服务就绪后重新查看版本;若仍不一致,核对启动器所在目录与覆盖更新的目录是否相同。

搜索使用指南

输入问题或关键词,查找对应的操作步骤。

图片预览