二级目录部署

需要通过 https://example.com/survey/ 访问开源版时，使用本页提供的 /survey 专用 JAR。该包已经包含适配二级目录的前端，Java 启动后即可同时提供页面和接口，无需单独部署前端。

例如，同一个域名的 / 提供原网站，/survey/ 提供问卷系统。应用本身可直接通过 http://服务器IP:1991/survey/ 访问；接入已有域名和 HTTPS 时，再配置 Nginx 反向代理。

适用范围

本文适用于 surveyking-v1.13.0-survey.jar，访问前缀固定为 /survey。该包使用 MySQL 8.0，需手动导入数据库并配置连接，不使用标准安装包的 /setup 初始化向导或 H2 配置。

普通根目录 JAR 不能只添加 --server.servlet.context-path=/survey 就完成适配，前端资源、页面跳转和接口地址也必须包含前缀。

1. 下载二级目录专用 JAR

下载 surveyking-v1.13.0-survey.jar（约 56 MB）。

服务器上也可以使用：

mkdir -p /opt/surveyking-survey
cd /opt/surveyking-survey
curl -fL -o surveyking-v1.13.0-survey.jar \
  https://download.surveyking.cn/files/surveyking-v1.13.0-survey.jar

该版本文件的 SHA-256：

788a9fabb7299763cd5641d62c220422ad9b0bd06bcfc21313091fe250d4e0ad

Linux 可运行 sha256sum surveyking-v1.13.0-survey.jar 核对；macOS 使用 shasum -a 256。

运行环境需要 Java 8 和 MySQL 8.0，服务器无需安装 Node.js。先执行 java -version 确认 Java 可用；本包已使用 Java 8 验证启动。

2. 准备数据库

创建专用数据库和账号，例如：

CREATE DATABASE surveyking CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'surveyking'@'localhost' IDENTIFIED BY 'ReplaceWithYourDatabasePassword';
GRANT ALL PRIVILEGES ON surveyking.* TO 'surveyking'@'localhost';

将示例密码替换为实际密码。数据库位于其他机器时，按应用所在地址设置账号允许连接的主机。

初始化 SQL 已包含在 JAR 中。在 JAR 所在目录使用 unzip 提取：

mkdir -p init-db
unzip -p surveyking-v1.13.0-survey.jar BOOT-INF/lib/rdbms-plain.jar > init-db/rdbms.jar
unzip -p init-db/rdbms.jar scripts/init-mysql.sql > init-db/init-mysql.sql
mysql -h 127.0.0.1 -u surveyking -p surveyking < init-db/init-mysql.sql

没有 unzip 时，可用解压软件先打开 JAR，再打开其中的 BOOT-INF/lib/rdbms-plain.jar，取出 scripts/init-mysql.sql 后导入。

只对新数据库执行初始化

初始化脚本包含删除并重建表的语句。已有业务数据时，应先备份并确认数据库结构兼容，不能重新导入初始化脚本。

3. 配置并启动

在 JAR 同目录创建 application.properties，填写实际数据库信息：

server.port=1991
spring.datasource.url=jdbc:mysql://127.0.0.1:3306/surveyking?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
spring.datasource.username=surveyking
spring.datasource.password=ReplaceWithYourDatabasePassword

保持当前工作目录为 JAR 和配置文件所在目录，执行：

java -jar surveyking-v1.13.0-survey.jar

默认已启用生产配置和 /survey 上下文，无需额外添加路径参数。Windows 也可以在 JAR 所在文件夹打开终端，执行相同命令。

启动完成后打开：

http://服务器IP:1991/survey/

本机访问可使用 http://127.0.0.1:1991/survey/。使用初始化脚本创建的默认账号 admin / 123456 登录后，应立即修改密码。

用途	路径示例
首页	`/survey/`
登录	`/survey/user/login`
问卷填写、分享链接	`/survey/s/问卷ID`
练习	`/survey/t/题库ID`
问卷编辑	`/survey/survey/问卷ID/edit`
后端接口	`/survey/api/...`
验证码	`/survey/captcha/...`

编辑页中出现两个 survey 是正常的：第一个是部署前缀，第二个是业务路由。前端页面可以直接打开或刷新。

配置文件、数据库和 files/ 附件目录需要一起保留。配置 systemd 或其他进程管理工具时，固定工作目录到部署目录，并使用上述 JAR 启动命令，不要添加标准包的 H2 参数。

4. 可选：接入已有域名

直接通过 Java 端口访问不需要 Nginx。如果已有网站，希望在相同域名下增加 /survey/，在该域名现有的 Nginx server 块中添加以下配置，保留原网站的其他路由：

location = /survey {
    return 302 /survey/$is_args$args;
}

location ^~ /survey/ {
    # 不加结尾斜线，保留完整的 /survey/... 请求路径。
    proxy_pass http://127.0.0.1:1991;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    client_max_body_size 21m;
    proxy_buffering off;
    proxy_read_timeout 3600s;
}

替换后端地址和端口，检查配置后重载：

sudo nginx -t
sudo systemctl reload nginx

随后通过 https://example.com/survey/ 访问，HTTPS 证书沿用该域名的配置。关闭代理缓冲可以让 AI 流式响应及时显示。

高级：Nginx 单独托管前端

只有需要独立托管静态文件时才使用此方式。前端必须来自与 JAR 配套的 /survey 构建，不能混用普通根目录前端包。

可以从本页的 JAR 提取已经适配的前端：

unzip surveyking-v1.13.0-survey.jar 'BOOT-INF/classes/static/*' -d extracted
mkdir -p /opt/surveyking/html/survey
cp -R extracted/BOOT-INF/classes/static/. /opt/surveyking/html/survey/

后端仍运行同一个 JAR。以下配置替换上一节的 /survey/ 代理配置，添加到现有 server 块中：

location = /survey {
    return 302 /survey/$is_args$args;
}

location ^~ /survey/api/ {
    proxy_pass http://127.0.0.1:1991;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    client_max_body_size 21m;
    proxy_buffering off;
    proxy_read_timeout 3600s;
}

location ^~ /survey/captcha/ {
    proxy_pass http://127.0.0.1:1991;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location ^~ /survey/ {
    root /opt/surveyking/html;
    index index.html;

    location ~* \.(js|css|png|jpg|jpeg|gif|svg|webp|ico|woff2?|ttf|eot|json)$ {
        try_files $uri =404;
    }

    try_files $uri $uri/ /survey/index.html;
}

这里 root 指向 /opt/surveyking/html，实际前端文件放在其 survey/ 子目录。后端请求继续保留 /survey，不要在代理中去掉该前缀。

部署后检查

从最终域名打开登录页，登录后刷新页面。
新建并保存问卷，复制分享地址，确认地址包含 /survey/s/。
在新窗口填写并提交问卷，确认能收到答卷。
检查图片、附件上传下载和验证码；浏览器中的本应用请求应使用 /survey/api/ 或 /survey/captcha/。
如果启用 OAuth，外部访问地址仍只填写域名，例如 https://example.com。到第三方平台登记设置页显示的完整回调地址，例如 https://example.com/survey/api/public/oauth/callback/google。

问卷提交后的自定义跳转如果使用根路径，应填写 /survey/...；完整的 HTTP(S) 外链仍跳转到对应外站。

常见问题

页面空白，或者 JS、CSS 请求没有 `/survey`

确认使用的是 surveyking-v1.13.0-survey.jar，并清理浏览器缓存。前后端分离时，重新提取与该 JAR 配套的静态文件。

首页正常，但登录、验证码或上传失败

检查 /survey/api/ 和 /survey/captcha/ 是否到达后端。proxy_pass http://127.0.0.1:1991; 不要写成带结尾斜线的形式，否则会移除匹配到的路径前缀。

刷新编辑页或问卷页返回 404

单 JAR 已处理页面路由回退；如果经过网关，确认它转发了完整的 /survey/...。静态前端由 Nginx 托管时，检查 try_files 是否回退到 /survey/index.html。

能否换成 `/questionnaire` 等其他目录

本页交付包固定为 /survey。其他前缀需要同时修改前端部署路径、原生跳转和后端上下文后重新构建，不能只修改 Java 启动参数。

二级目录部署

1. 下载二级目录专用 JAR​

2. 准备数据库​

3. 配置并启动​

4. 可选：接入已有域名​

高级：Nginx 单独托管前端​

部署后检查​

常见问题​

页面空白，或者 JS、CSS 请求没有 /survey​

首页正常，但登录、验证码或上传失败​

刷新编辑页或问卷页返回 404​

能否换成 /questionnaire 等其他目录​