Lychee Rerank MM部署教程：Nginx反向代理+HTTPS配置企业级访问安全
1. 为什么需要企业级访问安全？
你已经成功跑通了 Lychee Rerank MM 的本地服务——http://localhost:8080，界面流畅、多模态重排序效果惊艳。但当它要接入真实业务系统、供团队协作使用、或对外提供 API 接口时，一个绕不开的问题就浮现出来：如何让这个本地服务变成可信赖、可管理、可审计的企业级服务？
这不是“能用就行”的问题，而是“能不能放心用”的问题。
- 客户通过公网访问时，HTTP 明文传输意味着查询内容、图片数据、甚至模型返回的敏感相关性得分，都可能被中间节点截获；
- 内部系统集成时，没有统一域名和 TLS 加密，会触发浏览器安全警告，影响前端调用稳定性；
- 运维层面缺乏请求日志、访问控制、负载均衡能力，一旦并发量上升或出现异常请求，难以定位与拦截；
- Streamlit 默认不支持生产环境的用户认证、权限分级和会话管理，直接暴露在公网存在风险。
本教程不讲“怎么启动模型”，而是聚焦你真正卡在落地最后一公里的实操环节：
如何用 Nginx 将localhost:8080变成https://rerank.yourcompany.com
如何自动申请并续期免费 HTTPS 证书（Let’s Encrypt）
如何配置反向代理、请求头透传、超时优化与静态资源缓存
如何添加基础访问控制（IP 白名单 / 基础认证），满足内部系统最小权限原则
所有配置均经过生产环境验证，适配 A10/A100 服务器常见部署结构
全程无需修改 Lychee Rerank MM 源码，不依赖 Docker Compose 编排，纯 Linux 原生配置，小白可逐行复制执行。
2. 环境准备与前置确认
在开始配置前，请确保以下基础条件已满足。这一步看似简单，却是后续所有配置稳定运行的前提。
2.1 确认 Lychee Rerank MM 已稳定运行
请先验证你的服务已在本地正常启动：
# 检查进程是否存活（假设你使用默认端口） ps aux | grep "streamlit run" | grep -v grep # 或直接 curl 测试响应（返回 HTML 即表示服务就绪） curl -s http://localhost:8080 | head -n 5 | grep -i "<title>"预期输出应包含类似<title>Lychee Rerank MM</title>的内容。若无响应，请先回到官方start.sh脚本排查 GPU 显存、模型路径、依赖版本等问题。
注意：本教程不覆盖模型部署本身。我们默认你已完成模型加载、Streamlit 启动，并确认
http://localhost:8080可正常交互。
2.2 系统与网络要求
| 项目 | 要求 | 说明 |
|---|---|---|
| 操作系统 | Ubuntu 22.04 LTS 或 CentOS 7+ | 推荐 Ubuntu，Nginx 和 Certbot 支持最完善 |
| 域名解析 | 已绑定到服务器公网 IP | 如rerank.yourcompany.com→203.205.xxx.xxx |
| 防火墙 | 开放80（HTTP）、443（HTTPS）端口 | 若使用云服务器（阿里云/腾讯云），需同步配置安全组 |
| root 权限 | 必须 | Nginx 配置、证书申请、端口绑定均需 sudo |
2.3 安装核心工具链
在服务器终端中一次性执行以下命令（Ubuntu 示例）：
# 更新源并安装 Nginx + Certbot（Let's Encrypt 客户端） sudo apt update && sudo apt install -y nginx certbot python3-certbot-nginx # 启动并启用 Nginx 开机自启 sudo systemctl enable nginx sudo systemctl start nginx # 验证 Nginx 是否运行 curl -I http://localhost | head -n 1 # 应返回 HTTP/1.1 200 OK提示：CentOS 用户请替换为
sudo yum install epel-release && sudo yum install nginx certbot python3-certbot-nginx。
此时，访问http://<你的服务器IP>应看到 Nginx 默认欢迎页。这是你搭建反向代理的第一块基石。
3. Nginx 反向代理配置详解
Nginx 不是简单的“端口转发器”，而是你面向外部流量的第一道网关。正确配置它，才能让 Lychee Rerank MM 在生产环境中既安全又高效。
3.1 创建专用配置文件
避免直接修改/etc/nginx/sites-enabled/default，我们为 Lychee Rerank MM 创建独立配置：
sudo nano /etc/nginx/conf.d/lychee-rerank-mm.conf粘贴以下完整配置（请将rerank.yourcompany.com替换为你自己的域名）：
upstream lychee_backend { server 127.0.0.1:8080; keepalive 32; } server { listen 80; server_name rerank.yourcompany.com; # 强制跳转 HTTPS（启用 HTTPS 后取消注释此行） return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name rerank.yourcompany.com; # SSL 证书路径（由 Certbot 自动填充，暂留空，后续生成） ssl_certificate /etc/letsencrypt/live/rerank.yourcompany.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/rerank.yourcompany.com/privkey.pem; # 推荐的安全加固头 add_header X-Frame-Options "DENY" always; add_header X-XSS-Protection "1; mode=block" always; add_header X-Content-Type-Options "nosniff" always; add_header Referrer-Policy "no-referrer-when-downgrade" always; add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline' 'unsafe-eval';" always; # 关键：透传原始 Host 和协议，确保 Streamlit 正确生成 URL 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_set_header X-Forwarded-Host $server_name; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # 关键：调整超时，适配多模态推理耗时（图片上传+模型计算） proxy_connect_timeout 300; proxy_send_timeout 300; proxy_read_timeout 300; send_timeout 300; # 关键：处理 WebSocket（Streamlit 实时 UI 交互依赖） location / { proxy_pass http://lychee_backend; proxy_http_version 1.1; proxy_buffering off; } # 关键：静态资源缓存（Streamlit 前端 JS/CSS） location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ { expires 1y; add_header Cache-Control "public, immutable"; } }3.2 配置说明：为什么每一行都不可省略？
| 配置项 | 作用 | 不配置的风险 |
|---|---|---|
upstream lychee_backend | 定义后端服务地址，便于未来横向扩展 | 硬编码地址导致维护困难 |
keepalive 32 | 复用 TCP 连接，降低 Streamlit 频繁请求开销 | 并发高时连接数暴涨，触发系统限制 |
X-Forwarded-*系列头 | 告诉 Streamlit “用户真实访问的是 HTTPS” | Streamlit 生成的链接仍为http://，导致混合内容错误或重定向循环 |
Upgrade&Connection | 启用 WebSocket 升级 | UI 卡顿、按钮无响应、实时日志不刷新 |
proxy_read_timeout 300 | 允许最长 5 分钟等待模型返回 | 图片重排序超时中断，前端报 504 Gateway Timeout |
Cache-Control静态资源 | 减少重复下载，提升二次访问速度 | 每次刷新都重新拉取 5MB+ JS 包，首屏慢 |
小技巧：配置完成后，用
sudo nginx -t检查语法。若提示syntax is ok，再执行sudo systemctl reload nginx生效。
4. HTTPS 证书自动申请与续期
Let’s Encrypt 提供完全免费、自动化、受信任的 TLS 证书。Certbot 工具能一键完成申请、部署与续期。
4.1 申请证书（首次）
确保你的域名已正确解析到服务器 IP 后，执行：
sudo certbot --nginx -d rerank.yourcompany.com按提示操作：
- 输入邮箱（用于证书到期提醒）
- 同意 Let’s Encrypt 协议
- 选择是否重定向 HTTP → HTTPS（强烈建议选 2：Redirect）
成功后，Certbot 会：
- 自动修改
/etc/nginx/conf.d/lychee-rerank-mm.conf中的证书路径 - 重启 Nginx 加载新配置
- 输出证书路径与下次续期时间（通常为 90 天后）
4.2 验证 HTTPS 是否生效
打开浏览器，访问https://rerank.yourcompany.com：
- 地址栏显示 锁形图标
- 页面正常加载，无“不安全”警告
- F12 控制台无 Mixed Content 报错
4.3 设置自动续期（关键！）
Let’s Encrypt 证书有效期仅 90 天。必须配置自动续期，否则某天凌晨服务会静默失效。
Certbot 安装时已自动创建 systemd timer（Ubuntu 22.04+）：
# 查看定时任务状态 sudo systemctl list-timers | grep certbot # 手动测试续期（无输出即成功） sudo certbot renew --dry-run验证通过后，你无需再手动干预。系统将在证书到期前 30 天自动尝试续期。
5. 企业级增强：访问控制与日志审计
仅靠 HTTPS 还不够。真实企业场景中，你还需回答：“谁在什么时候访问了什么？”
5.1 方案一：IP 白名单（适合内网/固定办公网络）
在server { ... }块内添加：
# 只允许公司办公网段访问（示例：192.168.10.0/24） allow 192.168.10.0/24; deny all;注意：若你通过云厂商 NAT 网关访问，需填写网关出口 IP，而非本地局域网 IP。
5.2 方案二：HTTP Basic 认证（轻量级登录门禁）
生成密码文件（首次运行）：
sudo apt install -y apache2-utils sudo htpasswd -c /etc/nginx/.htpasswd your_username # 按提示输入密码在location / { ... }块内添加两行：
auth_basic "Lychee Rerank MM Access"; auth_basic_user_file /etc/nginx/.htpasswd;重启 Nginx 后，访问页面将弹出标准浏览器登录框。
5.3 启用详细访问日志（审计必备）
默认 Nginx 日志不记录 POST 请求体（即你提交的 Query 文本或图片 Base64）。如需审计输入内容，需开启：
# 在 http { ... } 块顶部（非 server 块）添加 log_format main_ext '$remote_addr - $remote_user [$time_local] ' '"$request" $status $body_bytes_sent ' '"$http_referer" "$http_user_agent" ' '"$http_x_forwarded_for" "$request_body"'; # 在 server 块中指定使用该格式 access_log /var/log/nginx/lychee-access.log main_ext;日志示例：
"POST /_stcore/stream?... HTTP/1.1" 200 1234 ... "{'query': '红色连衣裙', 'documents': ['doc1.jpg', 'doc2.jpg']}"
警告：开启request_body会显著增大日志体积，且可能记录敏感数据，请评估合规要求。
6. 故障排查与性能调优实战
即使配置完全正确，生产环境仍可能遇到“理论可行，实际报错”的情况。以下是高频问题与一线解决方案。
6.1 常见报错速查表
| 现象 | 可能原因 | 快速验证命令 | 解决方案 |
|---|---|---|---|
| 访问 HTTPS 页面空白 / 502 Bad Gateway | Nginx 无法连接localhost:8080 | curl -v http://127.0.0.1:8080 | 检查 Lychee 是否运行；确认start.sh未被 kill；检查netstat -tuln | grep :8080 |
| 页面加载但按钮无响应 / WebSocket 断开 | Upgrade头未透传 | curl -I -H "Connection: upgrade" -H "Upgrade: websocket" https://rerank.yourcompany.com | 确认 Nginx 配置中proxy_set_header Upgrade和Connection存在 |
| 上传图片后卡住，最终 504 | proxy_read_timeout过短 | tail -f /var/log/nginx/error.log | 将proxy_read_timeout提至600，观察日志是否仍有upstream timed out |
| 浏览器提示“您的连接不是私密连接” | 证书未生效或域名不匹配 | openssl s_client -connect rerank.yourcompany.com:443 -servername rerank.yourcompany.com 2>/dev/null | openssl x509 -noout -text | grep "Subject:" | 确认证书Subject CN=与访问域名一致；检查 DNS 解析是否生效 |
6.2 性能压测建议（可选）
对稳定性要求高的场景，建议用ab或wrk进行轻量压测：
# 模拟 10 并发、持续 60 秒的 GET 请求（首页） ab -n 1000 -c 10 https://rerank.yourcompany.com/ # 观察 Nginx error.log 与 Streamlit 日志是否有 OOM 或 timeout tail -f /var/log/nginx/error.log /root/build/logs/streamlit.log健康指标：99% 请求耗时 < 3s，错误率 < 0.1%，无
worker_connections耗尽告警。
7. 总结：从本地 Demo 到可信服务的关键跨越
回顾整个流程，你完成的不只是“加了个 HTTPS”：
- 你构建了一条加密隧道：所有 Query、Document、图片数据、相关性得分，都在 TLS 保护下传输，满足等保 2.0 对数据传输安全的基本要求；
- 你定义了一个标准入口：统一域名、统一协议、统一访问策略，为后续接入 API 网关、统一身份认证（OAuth2/SAML）、审计平台打下基础；
- 你获得了可观测性：Nginx 日志成为第一手运维依据，配合 Streamlit 自身日志，可快速定位是网络层、代理层还是模型层的问题；
- 你保留了演进弹性：Nginx 配置天然支持灰度发布（
split_clients）、A/B 测试、上游集群负载均衡，未来升级 Qwen2.5-VL 新版本时，只需改upstream，零用户感知。
这正是工程化与 Demo 的本质区别：前者关注“如何长期可靠地交付价值”，后者只关心“此刻能否跑起来”。
下一步，你可以：
- 将 Nginx 配置纳入 Ansible/Terraform 管理，实现基础设施即代码（IaC）；
- 为
/healthz路径添加健康检查端点，接入 Prometheus + Grafana 监控； - 结合企业 AD/LDAP，用 Nginx Plus 或 Keycloak 实现 SSO 单点登录。
但无论走多远，今天这一步——让 Lychee Rerank MM 真正走出实验室，走进业务线——已经完成。
--- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
