跳到主要内容

二级目录部署

本页以 https://survey.example.com/survey/ 为例,使用 admin、public 双入口前端包。有上游网关时,由网关接收 HTTPS 并把完整的 /survey 路径转给卷王 Nginx。卷王 Nginx 提供前端页面和静态资源,只在请求 Java 接口时去掉此前缀。

前端交付包须与二级目录匹配

根目录版本的资源路径为 /adm/ 和 /pub/。二级目录交付包的页面路由、资源和接口请求都应包含部署前缀。使用其他目录名时,请获取对应的前端包,并同步调整下方两层 Nginx 的路径。

路径约定​

内容浏览器或客户端访问路径卷王 Nginx 对应目标
系统入口、管理页面/survey/、/survey/minedist/admin/index.html
填写、查询、登录页面/survey/s/问卷ID、/survey/user/logindist/public/index.html
手机扫码预览/survey/preview?key=...dist/admin/index.html
admin 构建资源/survey/adm/dist/admin/
public 构建资源/survey/pub/dist/public/
后端接口及验证码/survey/admin-api/、/survey/captcha/Java /admin-api/、/captcha/
应用接口及文件/survey/app-api/、/survey/files/Java /app-api/、/files/
智能体 MCP 和私有导出/survey/open-api/Java /open-api/

adm、pub 是静态资源路径。发布填写链接时,使用 /survey/s/问卷ID。

Java 保持默认上下文路径。例如卷王 Nginx 将 /survey/admin-api/system/auth/get-sys-info 转为 /admin-api/system/auth/get-sys-info,查询参数继续保留。仍请求根目录 /admin-api/ 或 /captcha/ 的旧交付包需要按该版本的路径约定部署。

部署前检查​

示例将前端 ZIP 解压到 /opt/surveyking/client,卷王 Nginx 监听 80,Java 后端监听 127.0.0.1:48080。部署时按实际目录和端口调整。

/opt/surveyking/client/dist/
├── admin/index.html
└── public/index.html

检查两个入口 HTML 中的资源路径。

grep -o '/survey/adm/' /opt/surveyking/client/dist/admin/index.html | head
grep -o '/survey/pub/' /opt/surveyking/client/dist/public/index.html | head

两条命令应分别输出对应的资源前缀。如果缺少前缀,先核对交付包。登录跳转、分享链接、流式接口和打印地址还需在部署后通过浏览器验证。

Nginx 生产配置​

卷王 Nginx​

将下方 map 和 server 放到 http {} 中,也可以从 http {} 中引入配置文件。同名 map 在每个 Nginx 实例中只定义一次。

  • 如果已有监听 80 的卷王站点,用下方规则更新现有的 server。在 server_name 中保留原有的 localhost,并加入用户访问的域名,使网关保留原始 Host 时也能选中该站点。
  • 示例使用 192.168.10.10 作为可信网关的来源 IP。将它换成卷王 Nginx 实际看到的来源 IP,才能在转发 Java 请求时保留外部 HTTPS 协议。
  • 在主配置的 http {} 中引入 mime.types。如果 JavaScript 映射只有 js,将该行补为 application/javascript js mjs;,使 PDF worker 等 .mjs 文件返回 JavaScript 内容类型。
map $http_upgrade $survey_connection_upgrade {
default upgrade;
'' close;
}

map "$remote_addr:$http_x_forwarded_proto" $survey_forwarded_proto {
default $scheme;
"192.168.10.10:https" https;
"192.168.10.10:http" http;
}

map $uri $survey_static_cache_control {
default "no-cache";
"~^/survey/(pub|adm)/.+[.][0-9a-fA-F]{8,}[.](js|css)$" "public, max-age=31536000, immutable";
}

server {
listen 80;
server_name localhost survey.example.com;
# 相对重定向由浏览器按原有 HTTPS 域名和端口解析。
absolute_redirect off;

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

# 仅转发给 Java 时去掉外部站点前缀。
location ~ ^/survey/(admin-api|app-api|open-api|captcha|files)(/|$) {
rewrite ^/survey(/.*)$ $1 break;
proxy_pass http://127.0.0.1:48080;
client_max_body_size 100m;
proxy_http_version 1.1;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-Proto $survey_forwarded_proto;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $survey_connection_upgrade;
proxy_intercept_errors off;
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 1800s;
proxy_send_timeout 1800s;
}

location = /survey/adm {
return 308 /survey/adm/$is_args$args;
}

location = /survey/pub {
return 308 /survey/pub/$is_args$args;
}

location = /survey/adm/index.html {
alias /opt/surveyking/client/dist/admin/index.html;
etag off;
expires off;
add_header Cache-Control "no-cache, no-store, must-revalidate" always;
}

location = /survey/pub/index.html {
alias /opt/surveyking/client/dist/public/index.html;
etag off;
expires off;
add_header Cache-Control "no-cache, no-store, must-revalidate" always;
}

# 静态文件缺失时返回 404,避免把 HTML 当作脚本加载。
location ^~ /survey/adm/ {
alias /opt/surveyking/client/dist/admin/;
index index.html;
expires off;
add_header Cache-Control $survey_static_cache_control;
try_files $uri $uri/ =404;
}

location ^~ /survey/pub/ {
alias /opt/surveyking/client/dist/public/;
index index.html;
expires off;
add_header Cache-Control $survey_static_cache_control;
try_files $uri $uri/ =404;
}

location ~ ^/survey/(favicon[.]ico|logo[.]png)$ {
alias /opt/surveyking/client/dist/admin/$1;
expires off;
add_header Cache-Control "no-cache";
}

# 答题、练习、公开查询、分享和兑换页面使用 public 入口。
location ~ ^/survey/(e|s|t|q|share|redeem)(/|$) {
rewrite ^ /survey/pub/index.html last;
}

location ~ ^/survey/user/(login|register|binding)/?$ {
rewrite ^ /survey/pub/index.html last;
}

# 预览和管理页面使用 admin 入口。
location /survey/ {
rewrite ^ /survey/adm/index.html last;
}

location / {
return 404;
}
}

单层部署时,使用上述卷王站点配置,并按实际对外入口设置监听端口和 HTTPS。合并到已有网站时,将 /survey 对应的 location 加入现有 server,保留原有的 location /。将卷王的页面和接口正则放在可能冲突的通用正则之前。管理端回退使用普通的 location /survey/,这样答题页和接口的正则仍能匹配。Nginx location 匹配顺序

上游网关转发​

如果已有统一门户或 HTTPS 网关,示例中的网关将整个站点转发到 192.168.10.20:80。将该地址替换为卷王 Nginx 的实际内网地址。整站转发包含管理页面和管理 API。外网仅需开放填写时,使用内外网分离部署的白名单方式。

在网关的 http {} 中定义以下映射。同一 Nginx 实例中已有该定义时直接复用。

map $http_upgrade $survey_connection_upgrade {
default upgrade;
'' close;
}

将以下规则加到网关现有的 HTTPS server。两个 proxy_pass 都只填写协议、主机和端口,让卷王 Nginx 收到完整的 /survey 路径和查询参数。Nginx proxy_pass 路径规则

location = /survey {
proxy_pass http://192.168.10.20:80;
proxy_set_header Host $http_host;
proxy_intercept_errors off;
}

location ^~ /survey/ {
proxy_pass http://192.168.10.20:80;
proxy_http_version 1.1;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $survey_connection_upgrade;
proxy_intercept_errors off;
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 1800s;
proxy_send_timeout 1800s;
client_max_body_size 100m;
}

网关统一转发路径,卷王 Nginx 再区分静态资源和 API。两层配置都关闭了响应缓冲,并为流式响应设置了读写超时。WebSocket 升级头也需要逐层转发。Nginx WebSocket 代理说明

验证部署​

在使用配置的每一台 Nginx 上检查语法,通过后再重载。先验证卷王站点,再验证正式入口。

nginx -t && systemctl reload nginx

# 在卷王服务器本机验证 80 监听和站点名称。
curl -I -H 'Host: survey.example.com' http://127.0.0.1/survey/

# 正式入口应返回 308,Location 应保留查询参数。
curl -I 'https://survey.example.com/survey?source=check'

# 填写页加载 public 入口,预览页加载 admin 入口。
curl -fsS 'https://survey.example.com/survey/s/route-check' | grep -o '/survey/pub/' | head
curl -fsS 'https://survey.example.com/survey/preview' | grep -o '/survey/adm/' | head

# 系统信息接口应返回 JSON,缺失的脚本应返回 404。
curl -i 'https://survey.example.com/survey/admin-api/system/auth/get-sys-info'
curl -I 'https://survey.example.com/survey/pub/__missing_route_check__.js'

将命令中的域名和端口换成实际部署值。单层部署时,使用对外 Nginx 的正式地址验证。两个入口 HTML 应返回 200 及禁止缓存的响应头。route-check 只用于检查 Nginx 返回的入口 HTML,实际填写和扫码预览需要有效的项目 ID 或预览 key。

浏览器中继续验证以下流程。

  • 登录和退出后仍在 /survey/ 下。管理后台、填写页和扫码预览页直接打开或刷新时,均能加载对应的 /survey/adm/ 或 /survey/pub/ 资源。
  • 问卷、考试、练习、公开查询和分享链接都包含 /survey/。
  • 普通 API、验证码、AI 流式响应和考试监考请求使用约定的接口前缀,返回 JSON 或事件流。
  • 上传、图片预览、文件下载、报表打印,以及邮件、短信和嵌入代码中的链接都可通过正式地址访问。

如果只有部分功能仍请求根目录 /admin-api/、/captcha/,或链接缺少 /survey/,请让交付方核对该功能是否已适配二级目录。

系统初始化​

系统地址与分享链接​

在 基础设施 → 配置管理 → 界面配置 → 系统地址 填写用户实际访问的完整入口。本例为 https://survey.example.com/survey。如果外部入口使用非标准端口,一并填写外部端口。

保存并刷新后,确认发布链接类似 https://survey.example.com/survey/s/问卷ID,且前缀只出现一次。如果使用会自动追加前缀的旧版交付包,按该版本约定填写系统地址,再核对实际发布链接。

文件存储​

在 基础设施 → 文件管理 → 文件配置 设置文件存储,页面路径为 /survey/infra/file/file-config。使用本地磁盘时,将“基础路径”设为后端运行用户可读写的绝对目录,并确保文件 URL 可以通过正式入口访问。

分别验证新上传和历史图片、附件的预览与下载。对象存储或独立文件域名按自身地址访问。已保存的文件 URL 和第三方登录回调地址需要分别核对。

智能体接入(按需)​

使用支持 MCP 的版本时,在 配置管理 → 智能体接入 中将“对外站点地址”填为 https://survey.example.com/survey。“远程 MCP 地址”可留空,默认得到 https://survey.example.com/survey/open-api/agent/mcp。保存后核对 MCP 和导出下载 URL 是否都经过 /survey/open-api/。

常见问题​

网关转发后命中了其他站点​

检查网关上游是否指向卷王 Nginx 的监听端口,并确认网关转发的 Host 在卷王站点的 server_name 中。卷王的 Java 端口填写在卷王站点的接口代理里。

页面能打开,但 JavaScript 和 CSS 返回 404​

查看失败请求的路径。如果仍引用根目录 /pub/ 或 /adm/,核对交付包的部署前缀。如果路径已有 /survey/,核对 alias 指向的目录、文件是否完整及 Nginx 的读取权限。

PDF 预览提示模块类型错误​

检查 .mjs 请求是否返回 JavaScript 内容类型。如果是 application/octet-stream,补齐 mime.types 中的 mjs 映射。如果是 text/html,排查静态资源路径是否落入页面回退。

登录后跳回域名根目录​

核对前端路由前缀、登录后跳转地址和第三方登记的回调 URL。第三方要求填域名时填写域名,要求填完整回调 URL 时保留部署路径。

接口或分享链接重复出现 /survey/survey/​

检查上游 proxy_pass 是否重复拼接路径,以及前端 API 前缀和系统地址是否符合交付包的约定。

接口返回 HTTP 200,但页面提示解析失败​

检查 Content-Type 和正文。如果响应是 text/html,核对 API 的请求前缀及卷王 Nginx 的接口规则是否匹配,避免请求落入管理端页面回退。

流式响应积压、监考连接断开或上传失败​

确认每层代理都关闭了接口响应缓冲,设置了合适的读写超时,并传递 WebSocket 升级头。上传返回 413 时,核对每层代理的 client_max_body_size 和后端上传限制。

修改 Nginx 后仍显示旧页面​

检查 index.html 的缓存响应头,以及浏览器、CDN 或统一门户缓存。本页只对带内容哈希的 JS 和 CSS 设置长期缓存,logo.png、favicon.ico、PDF worker 等同名文件仍需重新校验。