Qwen-Image-2512-SDNQ WebUI部署教程Nginx反向代理域名访问配置指南你是不是也遇到过这样的问题本地跑通了Qwen-Image-2512-SDNQ-uint4-svd-r32的Web服务但只能用http://0.0.0.0:7860或临时域名访问想把它变成一个像https://image.yourdomain.com这样干净、专业、带HTTPS的入口却卡在Nginx配置和SSL证书这一步别急这篇教程就是为你写的——不讲抽象概念不堆参数说明只说你真正需要的操作步骤。从零开始手把手带你把Qwen-Image-2512-SDNQ WebUI稳稳地“搬”到自有域名下全程可复制、可验证、无坑可踩。本教程基于已预装模型与Web服务的镜像环境如CSDN星图镜像重点聚焦服务暴露层的工程化改造如何用Nginx做反向代理、如何申请并自动续期免费SSL证书、如何让浏览器信任你的站点、以及最关键的——怎么确保图片生成请求不被代理中断、进度条不卡死、下载不失败。所有操作均已在真实GPU实例上反复验证适配主流Linux发行版Ubuntu 22.04 / CentOS 7。1. 理解当前服务状态与改造目标在动手前先确认你手上的服务是什么样、我们要改成什么样。这不是重复劳动而是避免后续踩坑的关键一步。1.1 当前服务运行方式你当前使用的是一个基于Flask的轻量级WebUI服务核心特点很明确它默认监听0.0.0.0:7860即所有网络接口的7860端口它不是为公网直连设计的——没有内置HTTPS、没有路径重写、没有跨域防护它依赖长连接实现生成进度实时推送通过Server-Sent Events或轮询这对反向代理的超时设置极其敏感它的静态资源HTML/CSS/JS和API接口共用同一端口但路径不同/是页面/api/generate是接口简单说它是个“好用但裸奔”的服务。我们接下来要给它穿上HTTPS外套、配上智能路由、再加一道安全门。1.2 改造后的理想状态完成本教程后你将拥有一个可公开访问的域名例如https://qwen-image.example.com全站强制HTTPS浏览器地址栏显示绿色锁标志所有请求页面加载、API调用、图片下载、进度流全部正常无报错、无中断、无超时Nginx自动处理SSL证书申请与续期无需人工干预服务仍由Supervisor管理Nginx仅作流量入口不影响原有逻辑注意本教程不涉及模型重训练、不修改app.py源码、不替换Web框架所有改动都在Nginx和系统服务层面安全、可逆、零侵入。2. 前置准备域名、服务器与基础环境这一步看似简单却是整个流程能否走通的基石。请逐项确认不要跳过。2.1 域名解析必须到位你需要一个已备案如适用且能自主管理DNS的域名例如example.com。然后在DNS服务商后台添加一条A记录qwen-image.example.com → 你的GPU服务器公网IP重要提醒DNS生效通常需要几分钟到几小时请耐心等待可用ping qwen-image.example.com或dig qwen-image.example.com验证不要用二级泛解析如*.example.com因为Let’s Encrypt对泛域名证书有额外验证要求初学者易出错如果你只有内网环境或测试机可临时用hosts文件模拟仅限本地浏览器测试不适用于他人访问2.2 确保基础软件已安装以Ubuntu为例执行以下命令确保必要工具就位sudo apt update sudo apt install -y nginx curl wget gnupg2 ca-certificates lsb-releaseCentOS用户请替换为sudo yum install -y epel-release nginx curl wget gnupg2 ca-certificates验证Nginx是否可用sudo systemctl start nginx sudo systemctl enable nginx然后在浏览器访问http://你的IP应看到Nginx欢迎页。2.3 确认WebUI服务正在运行执行以下命令检查Qwen-Image服务是否健康curl -s http://127.0.0.1:7860/api/health | jq .预期输出{status: ok}如果返回Connection refused请先检查Supervisor状态sudo supervisorctl status # 应看到 qwen-image-sdnq-webui RUNNING若未运行手动启动sudo supervisorctl start qwen-image-sdnq-webui3. 配置Nginx反向代理不止是转发更是适配Nginx在这里不只是“把请求转给7860端口”它要解决三个关键问题WebSocket兼容性、长连接保持、静态资源路径修正。直接套用默认proxy配置会失败。3.1 创建专属站点配置文件新建配置文件路径统一规范便于管理sudo nano /etc/nginx/sites-available/qwen-image粘贴以下完整配置已针对Qwen-Image-2512-SDNQ WebUI深度优化upstream qwen_image_backend { server 127.0.0.1:7860; } server { listen 80; server_name qwen-image.example.com; # Lets Encrypt ACME挑战专用路径 location ^~ /.well-known/acme-challenge/ { root /var/www/letsencrypt; default_type text/plain; } # 其他所有HTTP请求重定向到HTTPS location / { return 301 https://$server_name$request_uri; } } server { listen 443 ssl http2; server_name qwen-image.example.com; # SSL证书路径稍后由certbot自动生成 ssl_certificate /etc/letsencrypt/live/qwen-image.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/qwen-image.example.com/privkey.pem; # 推荐的安全头 add_header Strict-Transport-Security max-age31536000; includeSubDomains always; add_header X-Frame-Options DENY; add_header X-Content-Type-Options nosniff; # 关键适配Qwen-Image的长连接与SSE proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; 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; # 关键防止生成过程因超时中断默认60秒太短 proxy_read_timeout 600; proxy_send_timeout 600; proxy_connect_timeout 600; # 根路径Web界面 location / { proxy_pass http://qwen_image_backend/; # 修正Flask应用中可能存在的相对路径问题 proxy_redirect http://127.0.0.1:7860/ /; } # API路径确保/api/generate等接口正常 location /api/ { proxy_pass http://qwen_image_backend/api/; proxy_redirect http://127.0.0.1:7860/api/ /api/; } # 静态资源如有可额外配置本项目暂不需要 }配置说明为什么这么写proxy_http_version 1.1Upgrade头支持Server-Sent EventsSSE这是进度条实时更新的技术基础proxy_read_timeout 600将超时从默认60秒延长至10分钟覆盖图片生成全过程尤其高步数场景proxy_redirect修正后端返回的302跳转Location头避免浏览器跳转到http://127.0.0.1:7860这种错误地址location /api/单独配置确保API路径精准映射避免/api/generate被误匹配到/规则3.2 启用配置并测试语法# 创建软链接启用站点 sudo ln -sf /etc/nginx/sites-available/qwen-image /etc/nginx/sites-enabled/ # 测试Nginx配置语法 sudo nginx -t若输出syntax is ok和test is successful说明配置无误。3.3 重启Nginx生效sudo systemctl restart nginx此时访问http://qwen-image.example.com会自动跳转到https://...但因SSL证书尚未生成浏览器会显示“不安全”警告——这是正常现象下一步将解决。4. 自动获取并部署SSL证书我们使用Certbot Nginx插件全程自动化无需手动下载证书、无需重启Nginx。4.1 安装CertbotUbuntusudo apt install -y certbot python3-certbot-nginxCentOSsudo yum install -y certbot python3-certbot-nginx4.2 创建ACME验证目录sudo mkdir -p /var/www/letsencrypt sudo chown -R $USER:$USER /var/www/letsencrypt4.3 一键申请并部署证书sudo certbot --nginx -d qwen-image.example.com --non-interactive --agree-tos -m your-emailexample.com参数说明--nginxCertbot自动修改Nginx配置注入证书路径-d指定域名必须与DNS解析一致--non-interactive静默模式适合脚本化-m接收证书到期提醒的邮箱务必真实有效成功后你会看到类似提示Congratulations! You have successfully enabled HTTPS on https://qwen-image.example.com此时再次访问https://qwen-image.example.com浏览器应显示绿色锁标志页面正常加载。4.4 验证自动续期关键Let’s Encrypt证书90天过期Certbot已自动配置systemd timersudo systemctl list-timers | grep certbot应看到certbot.timer每天凌晨自动运行。你也可以手动测试续期逻辑sudo certbot renew --dry-run输出The dry run was successful.即表示续期机制就绪。5. 最终验证全流程端到端测试配置完成≠万事大吉。必须亲自走一遍用户会做的每一步确保无死角。5.1 页面功能验证打开https://qwen-image.example.com检查[ ] 页面完全加载无控制台报错F12 → Console[ ] Prompt输入框、宽高比下拉菜单、高级选项折叠面板均响应正常[ ] 点击“ 生成图片”后进度条开始流动非卡在0%[ ] 图片生成完成后自动触发下载文件名为generated_image.png或类似5.2 API接口验证命令行在服务器终端执行curl -X POST https://qwen-image.example.com/api/generate \ -H Content-Type: application/json \ -d {prompt:a cat wearing sunglasses, cartoon style} \ -o test_cat.png检查test_cat.png是否成功生成且可正常查看。5.3 并发与稳定性验证可选但推荐用两个浏览器标签页同时发起生成请求观察第二个请求是否排队等待符合线程锁设计预期两个下载是否都成功无文件损坏Nginx日志中无502 Bad Gateway或504 Gateway Timeout查看日志命令sudo tail -f /var/log/nginx/qwen-image.error.log6. 常见问题速查与修复方案即使严格按步骤操作也可能遇到个别环境差异问题。这里列出高频case及一招解法。6.1 访问HTTPS页面显示“您的连接不是私密连接”原因证书未正确加载或浏览器缓存旧证书解决# 强制重新加载证书Certbot内部命令 sudo certbot renew --force-renewal sudo systemctl restart nginx # 清除浏览器SSL状态Chrome地址栏点击锁图标 → 连接 → 证书 → 删除6.2 进度条不动、生成卡在“Processing…”、最终超时原因proxy_read_timeout不足或后端未正确响应SSE解决检查Nginx配置中proxy_read_timeout是否为600非60查看Nginx error logsudo tail -50 /var/log/nginx/error.log确认有无upstream timed out临时降低num_steps至20测试排除硬件瓶颈6.3 下载的图片打不开提示“文件已损坏”原因Nginx默认对二进制流处理不当缺少类型声明解决在Nginxlocation /api/块内追加proxy_set_header Accept-Encoding ; proxy_buffering off; proxy_cache off;然后sudo nginx -t sudo systemctl restart nginx6.4 Certbot申请失败提示“Failed to connect to host”原因防火墙阻止80/443端口或DNS未生效解决# 检查端口开放 sudo ufw status # Ubuntu sudo firewall-cmd --list-ports # CentOS # 临时放行生产环境请按需配置 sudo ufw allow 80,443 # 或 sudo firewall-cmd --permanent --add-port80/tcp sudo firewall-cmd --permanent --add-port443/tcp sudo firewall-cmd --reload7. 总结你已掌握AI服务工程化部署的核心能力回顾整个过程你实际完成的远不止“配个Nginx”你理解了AI Web服务的网络特性知道为什么SSE需要特殊代理头、为什么超时要设10分钟、为什么路径重写必不可少你掌握了生产环境必备技能域名解析、HTTPS全链路配置、证书自动续期、日志排查方法你构建了一个可交付的AI产品入口不再是http://xxx:7860这种开发地址而是https://qwen-image.example.com这样可分享、可嵌入、可集成的专业端点。下一步你可以轻松扩展为多个模型服务配置不同子域名sd.example.com,qwen.example.com添加基础认证auth_basic限制访问权限对接企业微信/钉钉机器人生成完成自动推送通知将API接入低代码平台如飞书多维表格实现零代码业务集成技术的价值永远在于它能解决什么问题、带来什么便利。你现在拥有的已经是一个随时可投入真实使用的AI图像生成门户。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。