反向代理与前后端分离

SurveyKing v1.13.0 的标准交付物是单体 JAR：后端 API 和已经构建好的前端页面由同一个 1991 端口提供。大多数部署只需要配置 Nginx 反向代理，不需要单独部署前端。

推荐：代理整个应用

下面的 Nginx 配置把 HTTPS 域名转发到本机 SurveyKing：

server {
    listen 80;
    server_name survey.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name survey.example.com;

    ssl_certificate /etc/letsencrypt/live/survey.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/survey.example.com/privkey.pem;

    client_max_body_size 25m;

    location / {
        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;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
        proxy_buffering off;
    }
}

替换域名和证书路径后运行：

sudo nginx -t
sudo systemctl reload nginx

proxy_buffering off 可以避免 AI 流式响应被代理缓存；client_max_body_size 应大于系统允许上传的附件大小。

完成代理后，二维码、公开链接和邮件都使用最终的 HTTPS 域名。不要把 127.0.0.1、容器名或内网地址发给公网用户。

高级：单独构建前端

只有修改了 surveyking-admin 源码、希望由 Nginx 直接托管静态文件时，才需要前后端分离。

构建前端

cd surveyking-admin
npm install
npm run build

将生成的 dist/ 上传到例如 /var/www/surveyking。

前端 API 默认使用同源的 /api 路径，因此最简单的方式是让静态站点和后端 API 共用一个域名：

server {
    listen 443 ssl http2;
    server_name survey.example.com;

    ssl_certificate /etc/letsencrypt/live/survey.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/survey.example.com/privkey.pem;

    root /var/www/surveyking;
    index index.html;
    client_max_body_size 25m;

    location /api/ {
        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;
        proxy_read_timeout 300s;
        proxy_buffering off;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

同域部署不需要额外开启跨域。try_files 是单页应用刷新 /setup、/user/login 等前端路由时仍能返回 index.html 的关键。

注意

标准 JAR 已带前端资源。单独托管 dist/ 后，要确保前端和后端来自同一版本；版本不一致可能出现接口字段、路由或多语言资源不匹配。

常见故障

• 首页能打开，刷新子页面 404：检查是否配置 try_files $uri $uri/ /index.html。
• 页面打开但接口 404：检查 /api/ 是否代理到 1991，以及 proxy_pass 是否保留了原始 /api 路径。
• 上传返回 413：提高 client_max_body_size。
• AI 输出一次性出现或超时：关闭代理缓冲，并增加 proxy_read_timeout。
• 生成的链接仍是 HTTP：确认代理传递了 X-Forwarded-Proto $scheme，并从最终 HTTPS 域名访问系统。