MedGemma X-Ray部署指南：防火墙开放7860端口与HTTPS反向代理配置

MedGemma X-Ray部署指南：防火墙开放7860端口与HTTPS反向代理配置

1. 为什么需要这一步？——从本地调试到安全访问的跨越

你已经成功跑通了MedGemma X-Ray，浏览器里输入http://localhost:7860就能看到那个熟悉的医疗影像分析界面：上传X光片、提问、生成结构化报告……一切都很顺畅。但当你想让同事在另一台电脑上访问，或者把系统部署到医院内网供教学使用时，突然发现打不开页面了。

这不是模型出了问题，而是网络“门禁”没打开。

Gradio默认只监听0.0.0.0:7860，它像一个敞着门的小诊室，谁都能推门进来——这在本地开发时很方便，但在真实环境中却存在两个关键障碍：操作系统防火墙会默认拦截外部请求，而直接暴露HTTP服务在公网或内网中不符合基础安全规范。

所以这篇指南不讲模型原理，也不教你怎么写提示词，只聚焦两件必须做、且必须做对的事：
让服务器主动“放行”7860端口，允许局域网甚至公网访问；
把裸露的HTTP服务套上HTTPS“外衣”，用Nginx做反向代理，既解决浏览器“不安全连接”警告，又为后续集成单点登录、API网关等企业级能力打下基础。

整个过程不需要改一行Python代码，也不用重装环境。你只需要15分钟，几条命令，就能把一个本地Demo，变成一个可交付、可管理、符合IT运维习惯的轻量级AI服务节点。

2. 开放7860端口：让流量真正抵达应用

Gradio应用本身已配置为监听所有IP（0.0.0.0:7860），但它前面还隔着一层操作系统级的“守门人”——防火墙。Linux常见防火墙有iptables和firewalld，我们按主流发行版分情况处理，每种都给出验证方式，确保你不是“以为开了”，而是“确认通了”。

2.1 Ubuntu/Debian系统（ufw）

这是最友好的防火墙管理工具，命令简洁，状态一目了然：

# 查看当前防火墙状态（首次运行可能显示“inactive”） sudo ufw status verbose # 如果是inactive，先启用它（不影响现有服务） sudo ufw enable # 允许7860端口的TCP流量（仅限IPv4） sudo ufw allow 7860/tcp # 查看更新后的规则列表，确认7860已出现在“Allowed”列 sudo ufw status numbered

验证是否生效：在另一台同局域网的电脑上，用浏览器访问http://你的服务器IP:7860。如果能看到MedGemma界面，说明端口已通。

2.2 CentOS/RHEL/Rocky Linux（firewalld）

企业级系统更常用firewalld，它基于“区域（zone）”概念，推荐使用public区域（适用于大多数服务器场景）：

# 检查firewalld是否运行 sudo systemctl is-active firewalld # 永久添加7860端口（--permanent是关键，否则重启后失效） sudo firewall-cmd --permanent --add-port=7860/tcp # 重载配置，使规则立即生效 sudo firewall-cmd --reload # 查看当前开放的端口，确认7860在列表中 sudo firewall-cmd --list-ports

注意：如果你之前用iptables手动加过规则，firewalld启动后会接管并清空iptables规则。请统一使用firewall-cmd管理，避免冲突。

2.3 通用验证法：绕过浏览器，用命令行直击本质

有时候浏览器缓存或网络中间设备会干扰判断。最可靠的验证方式，是用curl或telnet从外部机器直连服务器端口：

# 在客户端机器（如你的笔记本）上执行： # 方式1：用curl尝试获取HTTP响应头（无需页面内容，只看是否连通） curl -I http://服务器IP:7860 # 方式2：用telnet测试TCP连接是否建立（更底层） telnet 服务器IP 7860 # 如果看到"Connected to..."或HTTP状态码（如"HTTP/1.1 200 OK"），说明端口已开放且服务可达 # 如果显示"Connection refused"或超时，则需回头检查防火墙或Gradio是否真的在运行

2.4 排查要点：当“开了”却“不通”时

记住：端口开放 ≠ 服务可用，服务可用 ≠ 应用健康。三者要逐层验证。

3. 配置HTTPS反向代理：用Nginx给Gradio穿上“安全外衣”

现在，局域网内的同事能访问你的MedGemma了。但如果你打算把它放在医院DMZ区、或通过域名提供给远程实习生使用，直接暴露http://ip:7860会遇到两个现实问题：
🔹 浏览器地址栏显示醒目的“不安全”警告，影响专业形象；
🔹 无法使用标准的https://medgemma-hospital.example.com这种易记域名，所有链接都得带端口号，体验割裂。

解决方案就是引入Nginx反向代理：它像一位专业的前台接待，对外只暴露443端口（HTTPS默认端口）和一个干净域名，对内则把所有请求原样转发给http://127.0.0.1:7860。你不用改Gradio一行代码，只需配置Nginx。

3.1 安装与基础配置（以Ubuntu为例）

# 安装Nginx（如已安装可跳过） sudo apt update && sudo apt install -y nginx # 启用并开机自启 sudo systemctl enable nginx sudo systemctl start nginx # 验证Nginx是否运行（访问服务器IP，应看到Nginx欢迎页） curl -I http://localhost

3.2 获取SSL证书：用Certbot免费搞定

我们推荐使用Let's Encrypt，它提供免费、自动续期的HTTPS证书。前提是你有一个可解析的域名（如medgemma.your-hospital.edu），并已将该域名A记录指向你的服务器IP。

# 安装Certbot及其Nginx插件 sudo apt install -y certbot python3-certbot-nginx # 自动获取证书并配置Nginx（替换your-domain.com为你的实际域名） sudo certbot --nginx -d medgemma.your-hospital.edu # 执行过程中，Certbot会自动修改Nginx配置，并帮你重载服务 # 完成后，访问 https://medgemma.your-hospital.edu 就能看到HTTPS绿色锁标

如果没有域名（例如仅内网使用），可生成自签名证书用于测试。但请注意：浏览器会提示“证书不受信任”，需手动确认。生产环境务必使用Let's Encrypt或企业CA签发的证书。

3.3 编写Nginx反向代理配置

Certbot生成的配置文件通常位于/etc/nginx/sites-enabled/。我们创建一个独立配置，便于管理和复用：

# 创建MedGemma专用配置文件 sudo nano /etc/nginx/sites-available/medgemma # 粘贴以下内容（请根据实际情况修改server_name和证书路径）

upstream medgemma_backend { server 127.0.0.1:7860; } server { listen 80; server_name medgemma.your-hospital.edu; # 强制HTTP跳转到HTTPS return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name medgemma.your-hospital.edu; # SSL证书路径（Certbot会自动生成，路径类似下方） ssl_certificate /etc/letsencrypt/live/medgemma.your-hospital.edu/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/medgemma.your-hospital.edu/privkey.pem; # 推荐的安全加固头 add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; add_header X-Frame-Options DENY; add_header X-Content-Type-Options nosniff; # 关键：反向代理设置 location / { proxy_pass http://medgemma_backend; 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; proxy_redirect off; # Gradio需要WebSocket支持，以下两行必不可少 proxy_set_header Sec-WebSocket-Extensions $http_sec_websocket_extensions; proxy_set_header Sec-WebSocket-Key $http_sec_websocket_key; } # 静态资源缓存（提升加载速度） location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 1y; add_header Cache-Control "public, immutable"; } }

# 启用该配置（创建软链接） sudo ln -sf /etc/nginx/sites-available/medgemma /etc/nginx/sites-enabled/ # 测试Nginx配置语法是否正确 sudo nginx -t # 无报错则重载配置 sudo systemctl reload nginx

3.4 为什么这些配置项不能少？

这不只是“能用”，而是“专业地、安全地、稳定地用”。

4. 启动与日常运维：让服务稳如磐石

配置完成，不代表万事大吉。一个生产级服务需要可观察、可控制、可恢复。MedGemma提供的三个脚本（start_gradio.sh、stop_gradio.sh、status_gradio.sh）就是你的运维杠杆。

4.1 启动流程再确认：顺序很重要

不要直接bash start_gradio.sh就完事。请严格按此顺序操作，避免因依赖未就绪导致失败：

# 步骤1：确保Nginx已运行（反向代理必须先于Gradio启动） sudo systemctl status nginx # 步骤2：启动Gradio应用 bash /root/build/start_gradio.sh # 步骤3：立即验证状态（三秒内出结果） bash /root/build/status_gradio.sh # 步骤4：打开浏览器，访问 https://medgemma.your-hospital.edu # 如果看到上传界面，恭喜，部署成功！

4.2 日志查看：故障排查的第一现场

所有线索都在日志里。学会高效读日志，比背一百条命令更有用：

# 实时追踪最新日志（推荐，Ctrl+C退出） tail -f /root/build/logs/gradio_app.log # 查看最后50行（快速定位最近错误） tail -50 /root/build/logs/gradio_app.log # 搜索关键词（如“error”、“CUDA”、“timeout”） grep -i "error\|cuda\|timeout" /root/build/logs/gradio_app.log | tail -20

日志阅读技巧：Gradio日志中，INFO是正常流程，WARNING需留意，ERROR或Traceback是明确故障点。重点看ERROR行上方3-5行，那里往往有触发错误的用户操作或输入。

4.3 进程守护：防止意外中断

Gradio进程是前台启动的，如果SSH断开，进程可能被挂起。虽然我们的start_gradio.sh已用nohup后台运行，但更稳妥的方式是用systemd托管（即文档末尾提到的“开机自启动”）：

# 创建服务文件（已提供完整内容，此处强调关键点） sudo nano /etc/systemd/system/gradio-app.service # [Service]段中，Type=forking 表示Gradio是后台守护进程 # ExecStart/ExecStop 指向你的脚本，确保路径绝对正确 # Restart=on-failure 让系统在崩溃后自动拉起 # 启用并启动服务 sudo systemctl daemon-reload sudo systemctl enable gradio-app.service sudo systemctl start gradio-app.service # 查看服务实时状态（比status_gradio.sh更全面） sudo systemctl status gradio-app.service -l

启用systemd后，你再也不用担心服务器重启后MedGemma“失踪”了。

5. 常见问题与避坑指南：那些踩过的坑，帮你绕开

部署看似简单，实则暗藏细节。以下是真实环境中高频出现的5个问题，附带根因和一招解：

5.1 问题：HTTPS访问白屏，控制台报WebSocket connection to 'wss://...' failed

根因：Nginx配置中缺失WebSocket透传头，或proxy_pass后缀多了斜杠（如http://127.0.0.1:7860/），导致Gradio路由错乱。

解法：
确认Nginx配置包含proxy_set_header Upgrade $http_upgrade;和Connection "upgrade";；
proxy_pass值必须是http://127.0.0.1:7860（结尾不能有/）；
执行sudo nginx -t && sudo systemctl reload nginx重载。

5.2 问题：上传X光片后无响应，日志显示CUDA out of memory

根因：GPU显存不足，模型加载失败。MedGemma X-Ray对显存有要求，尤其处理高分辨率X光时。

解法：
用nvidia-smi查看显存占用，确认是否有其他进程抢占；
临时降低Gradio并发数，在gradio_app.py中找到launch()调用，添加参数：

demo.launch( server_name="0.0.0.0", server_port=7860, share=False, max_threads=1 # 关键：限制为1，减少显存峰值 )

如需长期运行，考虑升级GPU或使用--no-gradio-queue参数（需修改启动脚本）。

5.3 问题：内网访问正常，但通过域名访问时图片上传失败

根因：浏览器同源策略（Same-Origin Policy）。当域名访问时，浏览器认为https://medgemma.xxx与http://127.0.0.1:7860是不同源，禁止跨域上传。

解法：
唯一正解：确保Nginx反向代理配置完整，所有请求（包括图片上传）都经由https://medgemma.xxx入口，Nginx再转发给后端。这样对浏览器而言，全程都是同源。
不要尝试在Gradio中加CORS头——Gradio不支持，且治标不治本。

5.4 问题：Certbot续期失败，HTTPS证书过期

根因：Let's Encrypt证书90天有效期，自动续期需满足：① 域名DNS解析正常；② 80端口可被公网访问（用于HTTP-01验证）。

解法：
手动测试续期：sudo certbot renew --dry-run；
如果失败，检查云服务器安全组是否开放了80端口（仅续期时需要，续期成功后可关闭）；
将续期加入crontab（Certbot通常已自动配置，检查/etc/cron.d/certbot）。

5.5 问题：修改了gradio_app.py，但重启后无变化

根因：Python模块缓存或进程未真正终止。

解法：
先彻底停止：bash /root/build/stop_gradio.sh；
强制清理残留：kill -9 $(cat /root/build/gradio_app.pid) 2>/dev/null; rm -f /root/build/gradio_app.pid；
再启动，并用ps aux | grep gradio_app.py确认只有一个进程；
修改Python文件后，必须重启Gradio，Nginx反向代理不缓存Python逻辑。

6. 总结：你已掌握一套可复用的AI服务交付方法论

回看这整篇指南，我们做的远不止是“开个端口、配个Nginx”。你实际上构建了一条从本地实验 → 局域网共享 → 安全交付的标准路径：

• 网络层：理解防火墙的本质是“流量过滤器”，掌握ufw/firewalld的核心命令，能自主判断是“服务没起来”还是“门没打开”；
• 协议层：明白HTTPS不仅是“加个锁”，更是建立信任链、规避中间人攻击、满足合规要求的基础设施；
• 架构层：用Nginx反向代理解耦了“用户访问入口”和“AI服务实现”，未来即使更换模型、升级框架，只要保持7860端口协议不变，对外服务就零感知；
• 运维层：通过systemd服务、结构化日志、标准化脚本，把一个Python脚本变成了一个可监控、可伸缩、可交接的IT资产。

这正是工程化思维的价值：不追求炫技，而专注让技术在真实场景中可靠、安全、可持续地创造价值。

下一步，你可以：
🔸 将此配置模板化，一键部署到多台教学服务器；
🔸 结合医院AD域，为MedGemma增加LDAP登录认证；
🔸 用Prometheus+Grafana监控GPU显存、API响应时间等核心指标。

技术落地的终点，从来不是“跑起来”，而是“稳得住、管得了、用得好”。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。