先聊一个实际场景很多团队在内部培训考核、校园课程测验、企业满意度调研、社区活动报名收集时都需要一套“能发问卷、能组织考试、能刷题练习”的系统。如果直接用商业化 SaaS要么按人数收费要么数据不在自己手里要么无法二次开发和定制。如果从零开发问卷和考试模块后端表单设计、题目管理、成绩统计、防作弊、权限控制一套下来工作量非常大。SurveyKing项目也叫“卷王”正是为了解决这些问题而开源的一套问卷考试系统。它把问卷调查、在线考试、题库刷题、智能组卷等常见功能整合在一起部署之后可以直接在浏览器中使用。本文会从零开始完整讲解 SurveyKing 的安装部署、环境配置、初始化数据、系统使用、常见报错排查和项目落地建议。本文适合以下读者想要快速搭建内部考试平台的运维或后端开发学校、培训机构需要自建在线考试系统的技术负责人对 Spring Boot Vue 前后端分离项目感兴趣想找一个完整开源项目来实操的开发者想基于开源系统做二次开发但不知道怎么部署和改配置的初学者。读完本文你将掌握 SurveyKing 的本地部署流程、Docker 部署方式、管理员初始化、问卷创建、考试发布、刷题模式配置以及 AI 智能试卷的使用思路。1. SurveyKing卷王功能和架构速览1.1 什么是 SurveyKingSurveyKing 是一套基于开源技术栈的问卷考试系统核心功能覆盖三个典型场景问卷收集、在线考试、题库刷题。它不是一个简单的“问卷表单生成器”而是把题目管理、答卷收集、自动阅卷、成绩统计、错题记录、智能组卷等完整闭环都做了进去。从使用者的角度来说系统分为两类角色管理员/出题人创建题目、组织试卷、发布考试、查看统计结果。参与者/考生填写问卷、参加考试、刷题练习、查看自己的成绩和错题。从系统模块的角度来看它包含问卷模块支持单选、多选、填空、评分、矩阵等题型适合做调研和满意度收集。考试模块支持定时发布、限时作答、自动计分、切屏检测、成绩导出等功能。刷题模块把题库拆成专项练习和随机练习用户答题后可以查看解析和错题记录。AI 智能试卷基于大模型能力根据题目数量和知识点要求自动生成试卷减少出题人的工作量。1.2 技术架构SurveyKing 本身是典型的前后端分离项目这一点对开发者也很有参考价值。通常包含后端Spring Boot、MyBatis/JPA 等 Java 生态技术栈前端Vue Element UI / Ant Design Vue 这类后台管理框架数据库MySQL存储题目、试卷、答卷、用户等数据缓存Redis用于会话管理、验证码、热点数据缓存权限认证基于 JWT 的 Token 机制。这种架构的好处是前后端职责清晰后端只提供 API前端负责页面交互后续如果要扩展小程序端、移动端 H5可以复用同一套后端接口。1.3 为什么推荐自建这类系统在企业内部或教育场景中自建问卷考试系统有几个实际优势数据私有化问卷结果、考试成绩都存自己的服务器不依赖外部 SaaS可以二次开发开源项目自带源码可以改 Logo、加登录方式、对接统一身份认证按需扩展如果只做问卷调查可以关闭考试模块如果要万人同时在线考试可以扩展部署学习价值如果你是 Java 后端开发者SurveyKing 是一个很好的全栈实战项目可以学到权限管理、导入导出、统计报表、数据库设计等知识。2. 环境准备与部署方式选择2.1 部署方式对比SurveyKing 的部署方式主要有三种部署方式适合场景难度说明Docker Compose 部署快速体验、生产方式低一条命令拉起前后端和依赖服务手动编译部署已有服务器环境、二次开发中需要自己安装 Java、Node.js、MySQL、Redis本地 IDE 启动学习源码、调试功能中前后端分开启动适合开发调试如果你是第一次接触这个项目想快速看效果建议优先使用 Docker Compose。如果你想改代码、学原理建议使用本地编译部署。2.2 编译部署所需环境如果选择手动编译或本地调试需要准备以下环境JDK 1.8 或 JDK 11 及以上版本Maven 3.6 以上Node.js 14 及以上版本前端构建用MySQL 5.7 或 8.0Redis 5.x 及以上版本。不同的开源版本对 JDK、MySQL 版本要求可能不同建议先看项目 README 和 pom 文件中的版本声明。这里不写死具体版本号因为 SurveyKing 版本迭代较快以你拉取代码时的实际要求为准。2.3 服务器要求如果是生产环境使用建议服务器配置不低于CPU2 核内存4 GB硬盘40 GB系统CentOS 7.x / Ubuntu 20.04 及以上。如果只是本地体验Windows / macOS 上都可运行内存 8 GB 的电脑足够。2.4 域名和端口规划默认情况下后端 API 服务、前端页面都通过 Nginx 或 Spring Boot 的端口暴露。建议提前规划前端页面端口比如 8080后端 API 端口比如 8081如果使用 https提前准备好域名和 SSL 证书。3. 手动部署从源码开始安装 SurveyKing3.1 获取源码与项目结构首先需要把源码拉到本地。方式很简单git clone https://gitee.com/vvkeeper/surveyking.git cd surveyking进入项目后目录结构大致如下surveyking/ ├── backend/ # 后端 Spring Boot 项目 │ ├── src/main/java # Java 源码 │ ├── src/main/resources # 配置文件 │ └── pom.xml # Maven 依赖 ├── frontend/ # 前端 Vue 项目 │ ├── src/ │ └── package.json ├── docker-compose.yml # Docker 编排文件 └── README.md建议先查看README.md因为每次版本更新后部署步骤可能会有调整。3.2 初始化数据库SurveyKing 启动时需要 MySQL 数据库。我们可以先创建一个数据库再执行源码中提供的初始化 SQL。CREATE DATABASE surveyking DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;创建完成后在backend/src/main/resources下查看 SQL 初始化脚本一般会有类似db.sql或init.sql的文件。执行方式如下mysql -uroot -p surveyking backend/src/main/resources/db.sql注意数据库字符集建议使用utf8mb4否则遇到 emoji 表情或生僻字可能出现乱码。3.3 修改后端配置后端启动前需要修改数据库和 Redis 连接配置。在backend/src/main/resources/application.yml或application.properties中配置类似下面内容spring: datasource: url: jdbc:mysql://localhost:3306/surveyking?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root password: your_password redis: host: localhost port: 6379 password:这里需要根据自己的实际环境修改数据库地址、用户名、密码和 Redis 密码。3.4 启动后端后端是标准 Spring Boot 项目可以直接使用 Maven 打包启动cd backend mvn clean package -DskipTests java -jar target/surveyking-backend-*.jar如果 Maven 命令执行较慢可以配置阿里云 Maven 镜像。启动成功后看到类似Started SurveykingApplication的日志就说明后端启动成功。3.5 构建并启动前端前端是 Vue 项目先安装依赖再构建静态文件cd frontend npm install npm run build构建完成后dist目录中就是打包好的前端静态文件。我们可以用 Nginx 来托管这些静态文件并将/api请求代理到后端服务。Nginx 配置示例server { listen 8080; server_name localhost; root /path/to/surveyking/frontend/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8081; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }这里假设后端运行在8081端口。配置完成后重启 Nginx通过http://服务器IP:8080就能访问系统首页。4. Docker Compose 一键部署推荐对于不想折腾 Java 和 Node 环境的同学Docker Compose 是最省事的方式。源码中通常已经提供docker-compose.yml文件我们只需要准备 MySQL、Redis 和应用三个服务。4.1 编写 Docker Compose 文件如果源码目录中已有现成的docker-compose.yml可以直接按 README 启动。如果没有可以参考下面的思路version: 3 services: mysql: image: mysql:8.0 container_name: surveyking-mysql environment: MYSQL_ROOT_PASSWORD: root123456 MYSQL_DATABASE: surveyking ports: - 3306:3306 volumes: - mysql-data:/var/lib/mysql command: --character-set-serverutf8mb4 --collation-serverutf8mb4_general_ci redis: image: redis:7 container_name: surveyking-redis ports: - 6379:6379 surveyking: image: your-registry/surveyking:latest container_name: surveyking-app depends_on: - mysql - redis ports: - 8080:8080 environment: SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/surveyking?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai SPRING_DATASOURCE_USERNAME: root SPRING_DATASOURCE_PASSWORD: root123456 SPRING_REDIS_HOST: redis SPRING_REDIS_PORT: 6379 volumes: mysql-data:如果官方没有提供可直接使用的镜像可以先在本地把后端代码打成 Docker 镜像再用 Compose 启动。GitHub/Gitee 仓库中一般会有 Dockerfile构建命令通常是docker build -t surveyking:latest .4.2 启动服务在包含docker-compose.yml的目录下执行docker-compose up -d等待镜像拉取和容器启动完成后用下面命令查看容器状态docker-compose ps如果三个服务都处于Up状态说明部署成功。此时访问http://服务器IP:8080即可看到系统页面。4.3 查看日志如果启动过程中出现问题可以使用日志排查docker-compose logs -f surveyking这种方式的优势在于不污染宿主机环境后续升级版本时只需要替换镜像并重新创建容器即可。5. 数据库初始化与管理员账号设置5.1 首次启动的自动建表SurveyKing 通常在启动时会自动创建数据库表所以第 3 节中的手动db.sql执行可以省略。但如果你使用的是旧版本或者需要手动维护数据库建议执行源码中的初始化脚本。5.2 管理员账号初始化系统首次启动后需要初始化管理员账号。不同版本管理后台的入口可能不同常见的方式有两种通过命令行参数传入初始管理员账号通过页面注册第一个账号并自动赋予管理员权限通过 SQL 脚本插入管理员数据。部署完成后建议第一时间进入系统找到“系统设置”或“用户管理”修改默认管理员密码。如果默认账号是admin/admin123这类常见密码一定要在生产环境中改掉避免被扫描器攻击。5.3 数据库备份策略数据库中的试卷、问卷、用户数据都是核心资产建议开启 MySQL 定时备份。一个简单的每日备份脚本思路如下#!/bin/bash backup_dir/data/backup/surveyking mkdir -p $backup_dir mysqldump -uroot -p你的密码 surveyking $backup_dir/surveyking_$(date %Y%m%d).sql find $backup_dir -type f -mtime 7 -exec rm -f {} \;将脚本加入 crontab 后可以每天凌晨执行一次。生产环境的备份策略建议遵循“本地备份 异地备份”双副本原则。6. 系统使用实战问卷、考试、刷题与 AI 智能试卷6.1 创建问卷收集登录系统管理后台后在“问卷管理”或“问卷列表”中点击“创建问卷”。创建问卷时需要配置以下信息问卷标题建议写成“XX部门员工满意度调查”这类清晰标题问卷说明填写给参与者的引导语匿名设置如果需要匿名收集开启匿名提交截止时间设置收集截止日期题型选择单选、多选、单选下拉、评分、矩阵、填空等。问卷编辑器中每个题目可以设置是否必填选项随机顺序逻辑跳转分值如果用于打分。保存并发布后系统会生成一个问卷链接或二维码。参与者打开链接即可填写不需要注册系统账号。6.2 创建并发布在线考试在线考试模块比问卷更严格适合用来做正式考核。发布一场在线考试的基本流程为创建题库先把题目录入题库或者从 Excel 模板批量导入创建试卷从题库中随机抽题或手动挑选题目设置考试参数考试时长、及格分数、是否允许查看答案、是否开启切屏检测发布考试选择考试时间范围生成考试链接考生答卷考生在浏览器中作答自动阅卷客观题系统自动判分主观题由管理员人工评阅。在实际使用中建议先创建一份“测试试卷”用自己账号模拟一次完整考试流程确认切屏检测、倒计时交卷等逻辑符合预期后再正式发布。6.3 题库维护与批量导入对于有大量题目的培训机构手工录题效率太低。SurveyKing 通常支持 Excel 模板导入一般步骤如下下载系统提供的导入模板按模板填写题干、选项、正确答案、解析、所属知识点在题目列表中点击“批量导入”上传模板文件系统校验并导入。导入时要注意模板不能随意修改列名多选题答案格式一般使用 A,B,C 这种分隔符。如果导入失败通常会返回具体行号的错误提示按提示修正后重新上传即可。6.4 刷题模式配置刷题模块面向“平时练习”场景与正式考试的区别在于刷题可以即时查看解析和答案适合学生自主巩固知识。常用配置包括专项刷题按知识点、章节出题随机练习每次随机抽取一定数量的题目错题本自动收集做错的题目方便反复强化练习模式答题一题一题作答提交后立刻显示解析。刷题功能在“题库练习”或“学习中心”中配置。管理员只需保证题库数据完整并设置好题目的知识点分类即可。6.5 AI 智能试卷思路与配置AI 智能试卷是 SurveyKing 比较吸引人的功能。它的核心价值在于出题人只需要输入考试主题、题目数量和题型分布AI 就能结合大模型生成一套包含题干、选项和答案的试卷供后续人工校对和发布。使用 AI 智能试卷前通常需要做以下准备检查当前版本是否包含 AI 试卷入口配置大模型 API Key不同的版本可能对接不同的模型服务提供商准备足够的题库数据或知识库上下文方便 AI 生成符合要求的题目在系统设置中填写模型接口地址、Token 等信息。如果版本没有内置 AI 生成能力也可以自己二次开发调用大模型 API把题目要求作为提示词让模型生成 JSON 结构的数据再通过后端接口自动导入题库。这个思路不依赖具体的实现类实施起来更灵活。无论使用哪种方式AI 生成的题目都建议人工审校。因为模型生成的题目可能存在知识点错误、选项重复、答案不准确的问题不能直接用于正式考试。7. 常见问题与排查思路7.1 高频问题表下面整理部署和使用过程中比较常见的几类问题问题现象常见原因解决思路后端启动失败提示数据库连接失败数据库地址或密码错误检查 application.yml 中的配置确认 MySQL 可远程访问页面能访问但登录接口报 401Redis 未启动或 Token 校验失败确认 Redis 进程存在检查前后端 API 地址是否一致中文乱码数据库字符集不对创建数据库时使用 utf8mb4检查 serverTimezone 配置上传 Excel 后题目导入失败模板列名不符合要求重新下载最新模板保持列名和格式不变部署后刷新页面 404前端 history 路由未配置 try_filesNginx 配置try_files $uri $uri/ /index.html;容器启动后立刻退出环境变量或依赖服务未就绪查看日志确认 MySQL、Redis 连接是否正常考试过程中切屏被强制交卷开启了切屏检测在新 tab 打开文档不会有问题但正式考试应关闭无关页面7.2 端口被占用启动后端或前端时如果提示端口被占用先找出占用进程lsof -i:8080在 Linux 上也可以使用netstat -tunlp | grep 8080确认占用进程后要么关闭进程要么修改应用配置文件中的端口。7.3 前后端联调时接口 404前端页面能打开但点击登录提示接口不存在。这种问题通常是前端请求的 API 前缀和后端服务的 context-path 不一致Nginx 没有正确代理/api路径后端启动失败接口服务根本没起来。建议先用 curl 直接测试后端接口curl http://127.0.0.1:8081/api/health如果后端接口正常再去排查 Nginx 代理配置。7.4 部署到 Nginx 后刷新 404这个问题在前端路由中非常经典。Vue 的 history 模式在刷新时会向服务器请求当前路径而服务器上并没有对应的物理文件导致 404。解决办法就是添加try_files配置让所有未匹配路径都落到index.html。8. 最佳实践与工程建议8.1 运维层面的建议生产环境一定要开启 HTTPS。考试/问卷场景会收集用户数据明文传输存在窃听风险数据库、Redis 密码不要使用简单密码避免使用默认密码定时备份数据库并在另一台服务器或对象存储保存备份文件部署到 Docker 时不要用 root 用户运行容器尽量使用专用用户Nginx 开启 Gzip 压缩可以提高前端资源加载速度如果参与人数较多考试当天提前压测确认服务器带宽和数据库连接池足够。8.2 业务使用层面的建议正式考试前先创建一份模拟试卷完整走一遍检查计分逻辑和交卷流程问卷收集如果涉及多个渠道可以在标题或 URL 上带渠道参数方便统计来源题库导入后安排专人抽查题目答案的正确性考生答案的查看权限要严格控制避免成绩泄露对于主观题人工评阅后要支持成绩复核流程。8.3 二次开发层面的建议如果需要对接公司内部用户体系可以新增一个登录接口复用 JWT 生成逻辑如果要做数据大屏可以写定时任务把答卷数据统计结果汇总到独立表减少对主库的压力前后端分离的项目建议统一使用 API 文档工具如 Knife4j、Swagger维护接口文档修改代码时不要直接改application.yml里的生产配置推荐使用环境变量或配置中心。8.4 安全加固清单最后列出安全方面的自查项修改默认管理员账号密码关闭不必要的服务器对外端口使用数据库最小权限账号为 Redis 设置密码并禁止外网访问定期更新 SurveyKing 版本关注官方安全公告。9. 总结与下一步学习方向至此我们从零走通了 SurveyKing 的完整安装与使用流程先了解了系统定位和技术架构接着完成了手动编译部署和 Docker 部署两种方式然后学习了数据库初始化、管理员设置、问卷创建、在线考试、题库刷题和 AI 智能试卷的使用思路最后整理了高频报错和工程落地建议。如果你部署成功那么下一步可以这样继续深入仔细读一遍后端controller、service层的代码理解 JWT 登录和创建试卷的完整流程尝试新增一种题型从前端表单到后端存储完整实现一次尝试对接企业微信或钉钉的扫码登录尝试用 Nginx 部署 HTTPS配置域名和自动续期证书尝试写一个简单的数据导出脚本把考试结果定时同步到公司内部系统。SurveyKing 这类开源系统最大的价值不只是“能用”而是“可以学到一套完整的企业级全栈思路”。如果你正在学习 Spring Boot 和 Vue 项目把它当作实战项目来拆解收获会很大。如果在部署过程中还有其他问题欢迎在评论区描述你的部署方式和日志截图可以一起交流排查经验。实测通过的部署流程别忘了收藏备用。
