DWSurvey开源问卷系统私有化部署与二次开发实战

最近在给一家合作单位落地内部员工满意度调研系统翻了一圈市面上现成的问卷产品云端的倒是省事可数据全在别人那里甲方一听就摇头。后来决定走私有化部署路线在几个开源问卷项目里挑来挑去最终选了 DWSurvey。整个配置开发的过程踩了不少坑也摸清了这套系统不少底细趁热打铁把记录整理成一篇完整笔记给后面接手这类需求的朋友做个参考。DWSurvey的定位非常朴素它就是一个基于 Java 的在线问卷系统拿来就能用支持单选、多选、填空、评分、矩阵题等十几种常见题型也能做问卷的创建、发布、数据统计和报表导出。最关键的它的代码是开放的数据库、缓存、部署环境全都在你手里想怎么改就怎么改。适合有技术团队的公司拿来搭建内部测评、顾客回访、课程反馈这类工具也适合个人开发者学习一套完整 Web 项目的全链路设计。1. 项目背景与核心价值1.1 DWSurvey到底能解决什么问题先聊清楚它的定位。市面上的问卷产品大致分三种纯在线SaaS、免费但闭源的轻量工具、开源可私有化部署的服务端系统。前面两种对个人做小规模收集很友好比如丢个链接让朋友填一下。一旦牵扯到企业内部数据合规、员工绩效评分、客户满意度分析这类场景数据不能出内网定制需求又多SaaS和闭源产品就会卡脖子。DWSurvey就是冲着这种私有化需求去的。它把问卷的整个生命周期都管理起来了管理员创建问卷、配置题型、设置逻辑跳转然后把链接发给受访者受访者作答完成后系统自动回收数据、生成统计图表、支持按条件筛选、按明细导出。你不需要写一行代码部署起来就能跑完整流程。我在实际使用中发现它的核心价值并不是某个花哨的报表而是那一整套“问卷—答卷—统计—导出”闭环。很多开源项目只做前端问卷渲染后端数据全要自己搞定DWSurvey在这块做得相对完整。开发团队如果想基于它做二次开发也只需要关注业务层基础框架和后台上限都是现成的。1.2 为什么值得在私有化场景里选它当时我们对比了几个候选开源项目。有一款纯前端的问卷工具交互确实漂亮但数据存储全靠浏览器LocalStorage换个设备数据就丢了不适合正式调研还有一款基于 PHP 的问卷系统功能也不少但团队的 Java 技术栈比较深后面想改逻辑跳转和权限模型遇到瓶颈很难搞。DWSurvey用的是 Spring Boot MyBatis FreeMarker 这套常见组合团队接手成本低出了问题也好排查。它对手游、PC端的体验也做了兼顾手机浏览器打开问卷链接会自动切换为响应式布局受访者用手机作答没什么障碍。对做企业内部测评来说这个细节很实用很多老系统就卡在移动端适配这一关。如果你所在的团队已经以 Java 为主同时又有数据私有化、二次定制需求DWSurvey是一个很合适的底子。它不算满分产品但胜在全面、稳定、可改像一块成色不错的毛坯房装修空间很大。2. 环境准备与基础配置2.1 本地开发环境清单先列一份我在实操时用的环境版本尽量贴近实际踩坑经验。组件版本选择说明JDK1.8强烈建议项目底层对它最友好Maven3.6依赖管理和打包用的MySQL5.7 或 8.08.0 需要关注驱动配置Node.js可选前端资源编译场景才需要Redis可选做分布式缓存时才需要如果环境里已经有更高版本的 JDK比如 11 或 17不建议直接跑源码。项目里的很多类库是围绕 JDK 8 写的高版本会触发 javax/jakarta 的命名空间问题改起来费时费力。我见过有人硬用 JDK 17 启动报了一堆 ClassNotFound最后老老实实回退到 1.8 一次通过。MySQL 的版本影响主要在驱动类名和连接串上。5.7 用com.mysql.jdbc.Driver没问题8.0 要换成com.mysql.cj.jdbc.Driver同时连接串里要加serverTimezoneAsia/Shanghai不然数据库时区跟系统对不上时间字段会差几个小时。这些细节在后面的配置文件里会展开写。2.2 初始化数据库脚本源码仓库里一般会在src/main/resources/db目录下放数据库初始化脚本文件名通常类似dwsurvey.sql。操作顺序不要错先建库、再导数据顺序反了会报“表不存在”。CREATE DATABASE IF NOT EXISTS dwsurvey DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; USE dwsurvey; SOURCE /你的绝对路径/dwsurvey.sql;这里有个比较容易踩的坑MySQL 默认字符集可能不是 utf8mb4。如果建库时漏了字符集参数后续问卷题目里存了 emoji 或者特殊符号保存时会变成问号。utf8mb4 是 utf8 的超集能覆盖四字节符号建议无脑选它。SQL 脚本执行完以后可以顺手检查三张核心表t_survey、t_survey_answer、t_survey_member。分别对应问卷主体、答卷明细和用户信息。能查到初始数据就算成功了。3. 核心配置文件详解3.1 Spring Boot 数据源与端口配置DWSurvey的配置文件入口是application.yml在源码的src/main/resources目录下。刚开始我容易忽视这里面的参数含义后来发现整个系统的运行行为全由这几个配置项决定。server: port: 8080 spring: datasource: url: jdbc:mysql://127.0.0.1:3306/dwsurvey?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root password: yourpassword driver-class-name: com.mysql.cj.jdbc.Driver把useUnicodetruecharacterEncodingutf8加在连接串里非常关键。之前我在本地跑的时候没加字符集参数部署到服务器后登录页显示中文全部是乱码登录按钮直接变成“缝”查了两小时才发现是连接串少写了字符集配置。如果数据库用的是 MySQL 8.0驱动类必须用com.mysql.cj.jdbc.Driver用老驱动的后果是启动直接报Loading class com.mysql.jdbc.Driver is no longer supported。这时候别急着改代码先检查驱动版本和连接串多数情况不是代码问题。3.2 文件上传路径与日志配置问卷系统的文件上传主要用在自定义图片选项、问卷封面等场景DWSurvey默认把上传文件写到应用的运行目录下。配置项大概是web: upload-path: /data/dwsurvey/upload生产环境建议把这个路径设置成独立的磁盘目录不要放在临时目录或应用目录下。原因是临时目录可能在重启时被清理应用目录在升级部署时容易被覆盖。我刚部署的时候偷懒没配这个路径后来升级版本所有问卷图片被新包覆盖得一干二净教训很深刻。日志配置是另一个容易忽略的点。Spring Boot 集成 logback常规配置里日志默认只输出到控制台生产环境看不到历史记录排查问题很麻烦。建议至少配置logging: file: name: /data/dwsurvey/logs/dwsurvey.log max-history: 30 max-size: 50MB日志按天滚动、按大小切割配完之后磁盘不会莫名爆掉出问题时也能找到那几天的运行记录。3.3 前端静态资源的路径适配项目虽然是服务端渲染为主但也混了不少静态资源和模板。如果是直接 jar 包运行静态资源路径一般不用动如果打成 war 包部署到外部 Tomcatserver.context-path或server.servlet.context-path就得配。一个常见需求是用 Nginx 做反向代理并挂在子路径下比如https://xxx.com/survey/。这时候需要把 yml 里加上server: servlet: context-path: /survey同时前端页面的所有链接、接口路径都会自动带上/survey前缀。这个配置在本地感受不明显一旦上了 Nginx 之后忘了配置就会出现“页面能打开、接口全404”的割裂状态。我当时的处理办法是把 context-path 直接改成线上实际路径本地开发用默认根路径两边各一套配置。4. 打包部署与迁移实操4.1 Maven 打包出的目录结构源码拿到手以后第一件事是先把依赖拉下来然后进行第一次打包。直接用 IDEA 打开工程等 Maven 自动导入完依赖点击右侧 Maven 工具栏中的clean和package即可。命令行的写法是mvn clean package -DskipTests跳过测试是为了避免本地环境缺依赖导致打包中断。打包完成后target目录下会出现一个可执行的 jar 包和walnut目录。这里解释一下walnut目录是干嘛的它就是项目的前端发布目录里面包含WEB-INF、static、views等资源后端的 FreeMarker 模板和静态资源都在这里。jar 包启动时会自动关联这些资源所以不要手动删掉walnut。如果改动了前端模板比如自定义问卷页面的 CSS、调整登录页 HTML需要重新打包因为 FreeMarker 模板会被编译进产物里光替换 js 不生效。4.2 三种部署方式的选择我在不同环境里试过三种部署方式各有适用场景。方式一直接运行 jar 包nohup java -jar dwsurvey-xxxx.jar --spring.config.locationfile:/data/dwsurvey/application.yml /data/dwsurvey/logs/console.log 21 适合单机小规模使用。好处是部署简单只需一个 Java 运行时坏处是 Java 进程直接暴露在外面进程崩溃不会自动重启需要配合 systemd 或 supervisor 做守护。方式二war 包部署到外部 TomcatDWSurvey 默认打的是 jar如果公司有现成的 Tomcat 维护体系可以把 pom.xml 里的packagingjar/packaging改成packagingwar/packaging再把pom.xml里关于内嵌 Tomcat 的依赖 scope 设置为provided然后重新打包。这种模式下端口、线程池等配置由 Tomcat 管理Spring Boot 的 server.port 配置会失效别对着 yml 改端口却查半天为什么没生效。方式三Nginx 反代 jar 包实际生产环境最推荐的就是这一种。Nginx 监听 80/443处理 HTTPS 证书和静态资源缓存然后把动态请求转发到内网的 jar 端口。配置示例server { listen 443 ssl; server_name survey.example.com; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; location /survey/ { proxy_pass http://127.0.0.1:8080/survey/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 120s; } }这里有两个注意点。一是proxy_pass末尾要跟 context-path否则请求路径会剥掉前缀造成资源加载失败二是问卷提交接口偶尔会执行比较久Nginx 默认的 60 秒超时不够用我把它调到了 120 秒避免大问卷提交到一半被切断。4.3 迁移数据的坑从一套环境迁移到另一套环境不是简单拷一份数据库就完事。DWSurvey 的文件上传资源是存在本地磁盘的如果只迁移数据库问卷里的图片全部会变成裂图。当时我迁移后就吃了这个亏头像、选项图片全挂了。解决方案是把 upload 目录整体打包然后在目标环境配置好web.upload-path让路径指向新上传目录。重启之前检查两件事目标机器的 upload 目录是否存在且有写权限数据库连接串是否能从目标机器访问到。这两点没问题迁移基本就顺了。5. 常见问题与排查技巧实录5.1 数据库连接异常启动时报Communications link failure或Cannot create PoolableConnectionFactory八成是数据库连不上。先用命令行本地测mysql -h127.0.0.1 -uroot -p能连上但应用连不上检查 MySQL 用户授权。默认情况下root 用户可能只允许 localhost 登录如果应用跑在另一台机器上需要执行GRANT ALL PRIVILEGES ON dwsurvey.* TO dwsurvey% IDENTIFIED BY password; FLUSH PRIVILEGES;还有一个隐蔽问题防火墙。服务器安全组和系统内部防火墙都要放行 3306 端口如果只从本地连服务器调试可以用telnet 127.0.0.1 3306测通断。5.2 问卷页面中文乱码乱码问题要从三层排查。第一层是数据库连接串前面说的characterEncodingutf8必须加第二层是数据库表本身字符集用命令确认SELECT TABLE_NAME, TABLE_COLLATION FROM information_schema.TABLES WHERE TABLE_SCHEMAdwsurvey;如果排序列不是utf8mb4_*说明建库时字符集不对要重建库或者执行ALTER TABLE转换。第三层是 JVM 编码启动 jar 包时加上-Dfile.encodingUTF-8防止 Linux 下默认编码不对导致乱码。5.3 问卷发布后无法保存答案这个问题的定位思路是看控制台报错。如果出现字段长度超过限制比如Data too long for column answer_content是 t_survey_answer 表对应字段长度不够。长文本答案默认可能只有varchar(255)遇到开放题很容易超。解决办法是把字段改成TEXTALTER TABLE t_survey_answer MODIFY COLUMN answer_content TEXT;如果保存答案时报主键冲突通常是因为手工导入数据时没有把自增主键的起始值调好可以执行ALTER TABLE t_survey_answer AUTO_INCREMENT 1;清掉冲突后重新提交即可。5.4 问卷统计报表导出失败导出 Excel 是很多内部调研系统的硬需求。DWSurvey 的导出功能依赖 Apache POI如果项目里引入其他依赖时与 POI 版本冲突会出现NoClassDefFoundError或NoSuchMethodError。排查思路是先确认 pom.xml 里 POI 版本再看有没有传递依赖把 POI 老版本带进来。用mvn dependency:tree查一下mvn dependency:tree -Dincludesorg.apache.poi如果发现多个版本在 pom 里用排除依赖或者统一版本号解决。这个坑在我接入报表模块时出现过最终把 POI 固定在 4.1.2 版本后恢复正常。从项目运维角度建议每次改动前先用mvn dependency:tree看清楚依赖树。很多莫名其妙的运行时错误根本不是代码逻辑问题而是依赖冲突。5.5 静态资源 404如果页面能打开但 CSS 和 JS 全部找不到优先看 Nginx 的 location 配置再看 context-path 是否一致。另外一个容易被忽略的是 favicon.ico 和静态资源的缓存问题浏览器缓存了旧的失败请求后即使后端修好了前端仍然加载不出来。此时强制刷新或者清缓存往往立竿见影。6. 二次开发与定制扩展6.1 新增自定义题型DWSurvey 的题型设计采用数据库字典的方式来管理新增题型相对清晰。在t_question_type表里加一条记录然后在代码里新增对应的处理逻辑前端模板里加渲染片段。这里要小心的点是题型 ID 不能随便改试卷、问卷、数据统计模块都绕不开这个 ID最好按照已有类型往后面累加避免破坏历史数据。我第一次尝试新增“量表矩阵题”的时候把新题型的标识符写成了已有题型的别名结果旧问卷全部乱套所有多选题的选项都被渲染成了矩阵样式。后来老老实实重新建了 ID按从大到小的顺序追加才恢复正常。// 简单示意新增题型的枚举值 public enum QuestionType { RADIO(1, 单选题), CHECKBOX(2, 多选题), FILL_BLANK(3, 填空题), SCORE(4, 评分题), MATRIX_SCALE(5, 矩阵量表题); // 新增 }6.2 对接企业统一登录DWSurvey 默认自带登录注册体系表是t_survey_member。企业内部通常要求对接现有账号体系比如 OA 系统或统一身份认证。实现思路很直接在登录拦截器里加一个判断如果客户端带了可信的请求头如x-uid直接信任并建立会话不再弹出登录页。核心逻辑是在MemberController或对应拦截器里写一个适配层// 示意从请求头中读取登录用户 String userId request.getHeader(X-User-Id); if (StringUtils.isNotEmpty(userId)) { Member member memberService.findByUid(userId); if (member null) { member memberService.createSyncMember(userId); } session.setAttribute(loginMember, member); }对接的关键是保证userId唯一且可信同时处理“首次登录自动建号”的情况。这样做既省了密码同步流程也不影响原有的密码登录入口。6.3 实现定向投放问卷我们还有一个需求给不同部门发不同问卷链接。DWSurvey 支持给同一问卷配置多个投放渠道可以给每个渠道生成不同链接通过渠道参数区分答卷来源。在生成问卷链接时加上渠道标识https://survey.example.com/survey/answer/xxxx?channelhr然后在答卷入库时读取请求参数并写入channel字段。统计时可以按渠道过滤这样 HR 发的链接和研发部发的链接数据不混合出报告的时候也清晰。这个功能原生不直接支持但改造成本非常低只需要在后端接口里把 query 参数读过存起来。6.4 数据报表对接外部系统如果企业内部有独立的数据中心不希望每次都在后台看报表可以基于 DWSurvey 的数据库直连或者开发一个只读接口来获取答卷明细。数据库直连方式最简单但要注意避免频繁全表扫描问卷数据量大的时候查询会拖垮线上库。我当时给表加了(survey_id, create_date)联合索引查询速度提升非常明显。ALTER TABLE t_survey_answer ADD INDEX idx_survey_date (survey_id, create_date);同时建议在接口层做分页拉取一次最多拉 1000 条避免大响应体把网络打满。7. 项目结构里的几个关键模块7.1 后台管理模块DWSurvey 的后台管理路径是/WEB-INF/views下的管理端模板。整个模块围绕“问卷列表—设计问卷—投放—数据”这几个核心页面展开。对初次接触这套系统的人来说建议先打开“设计问卷”页面逐题查看对应的数据库字段再对照代码里的 service 层逻辑理解会快很多。7.2 用户答卷模块用户答卷有两个入口PC 端和 WAP 端。PC 端的答卷渲染走 FreeMarker 模板WAP 端走的是像 H5 页面一样的响应式适配。值得注意的是两个端共用同一套后端接口所以填空题、矩阵题的校验逻辑要同时兼顾两端。我实际测试过在手机端提交带特殊字符的答案后端入库没问题但如果在 PC 端改了校验规则手机端可能没同步改导致手机上能提交的数据在 PC 端被拦。改的时候注意同步双端。7.3 数据统计模块统计模块主要包含答卷回收量、题型响应分布、列表导出的逻辑。它的实现思路是遍历答卷明细按题型聚合计算再用图表库渲染。对于小规模问卷来说性能没问题但量到十万条答卷以上统计报表就会出现明显的加载延迟。此时建议先优化数据库索引再做缓存处理。7.4 权限控制模块DWSurvey 的权限设计是典型的角色模型超管、普通用户、访客。普通用户创建问卷后可以把自己设置的问卷权限分享给其他人。这个权限模型简单直接但对“某个部门只能看某个问卷的数据”这类需求就不够用了。如果要扩展可以在t_survey_group相关的表上增加部门 ID 字段再在数据访问层加一层可见性过滤。8. 上线运行后的运维经验8.1 备份策略问卷系统的核心资产就是数据答题数据一旦丢失很难找回。我们现在的备份策略是数据库每天凌晨全量备份一次保留最近 30 天上传目录每天增量同步到异地存储。数据库备份命令mysqldump -uroot -p dwsurvey --single-transaction --set-gtid-purgedOFF | gzip /data/backup/dwsurvey_$(date %F).sql.gz加--single-transaction是为了用 InnoDB 的快照机制导出时不锁表。注意备份文件不要只放在同一台服务器上一旦磁盘坏了备份和数据一起没了等于没备份。8.2 内存与 JVM 参数默认启动是java -jar堆内存完全交给 JVM 自适应数据量上来以后容易出现频繁 Full GC。建议显式指定java -Xms512m -Xmx1024m -XX:MetaspaceSize128m -jar dwsurvey-xxxx.jar如果服务器只有 2G 内存这个参数基本够用如果你是 4G也可以把 -Xmx 提到 2048m。不要盲目配置超大内存堆内存给得过多反而可能让操作系统内存不足导致 swap 频繁响应更慢。8.3 监控与告警开源系统不像商业产品自带完善的监控看板建议接入现有的监控体系。至少监听三个指标进程是否存在、端口是否响应、关键接口响应耗时。用脚本定时探测健康检查地址即可问卷这类业务并不需要太复杂的分布式追踪只要做到“挂了能发现、发现能拉起”就算合格。我目前用的最简单方案是 crontab 定时任务每两分钟 curl 一次健康检查接口如果连续三次失败就重启 jar 并发送告警消息。这套方案虽然土但确实管用稳定运行大半年没出过事。最后的一点个人体会从选型、部署到二次开发整个过程走下来最深的感受是DWSurvey 并不是一个拿来即用的商业产品而是一个非常扎实的“底子”。它的代码风格接近传统企业级项目结构直白好懂适合快速改造但它的文档相对零散很多配置细节要靠看源码和试错来补齐这也是我写这篇记录的原因。如果让我给后来者一个建议拿到项目后先别急着二次开发先把“创建问卷—投放—回收—导出”全流程在本地完整跑一遍弄清楚每一步涉及的表和接口再动业务改造的手。另外代码上手前先把数据库备份和部署回滚方案准备好这是所有开源系统落地时最容易忽略、也最致命的环节。有个很多时候看不见、但关键时刻能救命的备份机制兜底后面怎么折腾都不慌。