初始化、备份和升级
这篇文档集中说明开源版 v1.12.0 第一次初始化、导出备份、导入恢复和升级系统的操作。
使用场景
- 第一次部署完成后，浏览器进入了
/setup页面。 - 准备升级、迁移服务器或更换部署方式。
- 需要定期备份系统数据，避免误删或服务器故障导致数据丢失。
升级、迁移、导入备份前，先导出一份备份包并保存到自己的电脑。不要只把备份放在原服务器上。
初始化系统
1. 打开 /setup
部署完成后，在浏览器打开部署文档里给出的访问地址。
如果系统还没有初始化，会自动进入 /setup 页面。没有自动跳转时，可以手动访问：
http://你的访问地址/setup
截图：首次打开系统进入 /setup 页面，标注「H2 内置数据库」「MySQL 数据库」「下一步」位置 文件名：setup-select-database.png
2. 选择数据库
| 选择 | 适合场景 |
|---|---|
| H2 内置数据库 | 试用、小范围演示、不想安装 MySQL |
| MySQL 数据库 | 正式使用、多人填写、数据比较重要 |
正式使用建议选 MySQL。H2 更适合先体验功能。
3. 填写 MySQL 信息
如果你选择 MySQL 数据库，先选择部署方式，再填写数据库连接信息。
常见填写方式：
| 部署方式 | 数据库地址 | 端口号 | 数据库名称 | 用户名 | 密码 |
|---|---|---|---|---|---|
| Docker Compose 一键脚本 | mysql | 3306 | surveyking | surveyking | surveyking/.env 里的密码 |
| 群晖 / 飞牛 NAS 本文 Compose | mysql | 3306 | surveyking | root | surveyking |
| 宝塔手动 / Linux 手动 | localhost | 3306 | surveyking | 你创建的用户 | 你设置的 MySQL 密码 |
| 外部 MySQL | MySQL 地址 | 3306 | 你的数据库名 | MySQL 用户名 | MySQL 密码 |
填写后点击 测试连接。测试通过后再继续。
Docker Compose 和 NAS 部署时，/setup 里的 MySQL 端口通常填 3306，不是 33060。33060 是给 NAS 或服务器外部连接 MySQL 用的端口。
4. 填写系统信息
按页面提示填写：
| 配置项 | 说明 |
|---|---|
| 系统名称 | 登录页和浏览器标题里显示的名称 |
| 系统描述 | 可不填 |
| 默认语言 | 默认选择简体中文 |
| 开放注册 | 不确定时先关闭 |
| AI 配置 | 可以先关闭，后面到系统设置里再打开 |
确认信息后点击 开始初始化。
- 选择 H2：初始 化完成后，点击 进入系统。
- 选择 MySQL：系统会自动重启，重启完成后跳转到登录页。
默认账号：
| 项目 | 默认值 |
|---|---|
| 账号 | admin |
| 密码 | 123456 |
第一次登录后，马上进入 系统管理 → 个人设置 → 安全设置 修改默认密码。
导出备份
1. 进入数据备份
用管理员账号登录系统，进入 系统管理 → 系统设置。
在页面下方找到 数据备份。
截图：系统管理 → 系统设置页面，标注「数据备份」「导出备份」「导入备份」按钮 文件名：system-setting-backup.png
2. 点击导出备份
点击 导出备份，浏览器会下载一个 .zip 文件，文件名类似：
surveyking-backup-20260502_153000.zip
备份包包含：
| 内容 | 说明 |
|---|---|
manifest.json | 备份清单、版本和来源信息 |
data/*.ndjson | 每张数据表的数据 |
files/ | 上传的附件目录 |
不要手动修改备份包里的文件。导入时会校验备份内容，改坏后可能无法恢复。
3. 保存备份包
建议至少保存两份：
- 一份放在自己电脑或移动硬盘。
- 一份放在网盘、对象存储或其他服务器。
如果要升级系统，先确认备份包已经下载完成，再继续操作。
导入恢复
1. 准备目标系统
先部署并初始化一个可登录的卷王系统。
如果是迁移到新服务器，建议目标系统版本和原系统一致，或高于原系统版本。不要把新版本备份导入到旧版本系统。
2. 上传备份包
进入 系统管理 → 系统设置 → 数据备份，点击 导入备份，选择之前导出的 .zip 文件 。
系统会提示“导入备份将覆盖当前系统数据”，确认无误后点击 继续导入。
导入备份会覆盖当前系统中的同名数据表和上传文件目录。导入前，先把当前系统也导出一份备份。
3. 检查导入结果
导入成功后，系统会提示恢复了多少张表、多少条数据、多少个文件。
如果提示有跳过的数据表，通常是版本不一致导致目标系统没有对应的数据表。先确认目标系统版本，再决定是否重新部署到更合适的版本。
升级系统
1. 推荐方式：重新部署新版本
对没 有技术基础的用户，最稳妥的升级方式是重新部署一套新版本，再导入备份。
操作顺序：
- 在旧系统里进入 系统管理 → 系统设置 → 数据备份，点击 导出备份。
- 按部署文档重新部署一套新版本卷王。
- 打开新系统，先完成
/setup初始化。 - 登录新系统，进入 系统管理 → 系统设置 → 数据备份，点击 导入备份。
- 检查项目、用户、答卷和上传附件是否正常。
- 确认没问题后，再停掉旧系统或切换域名。
这种方式的好处是：旧系统还在，升级失败也可以先退回旧系统。
2. 原地升级
如果你熟悉当前部署方式，也可以原地替换程序。
| 部署方式 | 升级动作 |
|---|---|
| Docker Compose | docker compose pull 后执行 docker compose up -d |
| Docker 单容器 | docker pull 后删除旧容器，再用原来的挂载目录重新启动 |
| Windows 一键包 | 停止旧程序，解压新版本，启动新版本后导入备份 |
| 宝塔 / Linux | 停止项目，替换新版本 jar，再启动项目 |
| NAS Compose | 在 Compose 项目里重新拉取镜像，或重新构建并启动项目 |
原地升级前也要先导出备份。不要在没有备份的情况下直接删除容器、删除目录或替换数据库。
3. 是否需要执行数据库脚本
如果更新说明里要求执行数据库升级脚本，按版本顺序执行。比如从 v1.6 升到 v1.8，先执行 v1.6 -> v1.7，再执行 v1.7 -> v1.8。
如果更新说明没有要求执行脚本，通常只需要更新程序并重启。
常见问题
初始化完成后还能重新进入 /setup 吗？
不能正常重复初始化。
初始化完成后，系统会进入登录页。系统名称、注册设置、AI 配置可以在 系统管理 → 系统设置 里修改。
如果你要重新初始化，建议重新部署一套空系统，然后导入需要的备份。
备份包能从 H2 恢复到 MySQL 吗？
可以尝试，前提是目标系统版本和原系统一致，或高于原系统版本。
更稳妥的做法：
- 部署一套使用 MySQL 的新系统。
- 完成
/setup初始化。 - 在新系统里导入 H2 系统导出的备份包。
- 检查项目、用户、答卷和附件是否完整。
导入备份会不会覆盖现在的数据？
会。
导入备份会覆盖当前系统中的同名数据表和上传文件目录。导入前，先导出当前系统备份。
备份包包含上传的图片和附件吗？
包含。
备份包里的 files/ 目录就是系统上传文件目录。导入备份时，这个目录也会一起恢复。
系统已经打不开了，还能备份吗？
如果系统页面打不开，优先联系技术人员做服务器层面的备份。
至少要备份：
| 部署方式 | 重点备份内容 |
|---|---|
| Docker Compose | MySQL 数据卷或 mysql/data、files |
| Docker 单容器 | 挂载的 db、files、logs 目录 |
| Windows 一键包 | 解压目录里的数据库和上传文件目录 |
| Linux 手动 | /opt/surveyking/db、/opt/surveyking/files、MySQL 数据库 |
| NAS Compose | 项目目录里的 mysql/data、files |