GIS研习社 GIS研习社
GIS基础理论 Apache配置 GIS部署

QGIS Server如何部署?WMS服务怎么发布?

GIS基础理论
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

QGIS Server如何部署?WMS服务怎么发布? 这是很多 QGIS 用户从桌面制图走向 WebGIS 服务发布时遇到的第一个问题：在 QGIS Desktop 里地图能正常显示，但一到服务器上就不知道项目文件放哪里、WMS 地址怎么拼、图层为什么不显示、坐标系为什么不对。

本文以“部署 QGIS Server 并发布一个 WMS 服务”为主线，说明从环境准备、项目配置、服务器发布到结果验证的完整流程。适合 GIS 学生、初级 GIS 工程师、WebGIS 开发者和正在从 QGIS Desktop 迁移到服务端发布的用户。

QGIS Server如何部署与QGIS Server发布WMS服务流程图
QGIS Desktop 项目文件通过 QGIS Server 发布为 WMS 服务的基本流程。

引言：QGIS Server 部署和 WMS 发布到底解决什么问题

QGIS Desktop 主要用于桌面端数据编辑、符号化和制图；QGIS Server 则用于把 QGIS 项目发布成 OGC 标准服务，例如 WMS、WFS、WCS 等。这里的 WMS 是 Web Map Service，即网络地图服务，主要用于按范围、图层、坐标系和样式请求地图图片。

如果你的需求是“让别人通过浏览器、QGIS、ArcGIS Pro、OpenLayers 或 Leaflet 访问一张地图”，那么 QGIS Server 发布 WMS 服务就是常见方案之一。

本文不讨论复杂集群和云原生部署，而是聚焦一个可落地的入门方案：在服务器上安装 QGIS Server，配置 Web 服务，把一个 QGIS 项目文件发布为 WMS，并验证服务是否可访问。

背景：QGIS Server 如何部署时最容易卡在哪里

很多用户部署 QGIS Server 失败，并不是因为 QGIS Server 本身很难，而是没有区分清楚三个角色：

  • QGIS Desktop：用于制作地图项目，设置图层、样式、坐标系和服务发布参数。
  • QGIS Server：读取 QGIS 项目文件，响应 WMS、WFS 等 OGC 请求。
  • Web Server：通常是 Apache 或 Nginx，负责接收 HTTP 请求，并把请求转发给 QGIS Server。

因此，QGIS Server 如何部署并不是只安装一个软件包就结束，还包括项目文件路径、Web Server 转发、环境变量、数据访问权限和 WMS 参数配置。

一个典型访问地址通常类似下面这样：

https://example.com/qgisserver?
SERVICE=WMS&
REQUEST=GetCapabilities&
MAP=/data/qgis/project/demo.qgz

其中 SERVICE=WMS 表示请求 WMS 服务，REQUEST=GetCapabilities 表示获取服务能力文档，MAP 指向服务器上的 QGIS 项目文件。

原理：QGIS Server 发布 WMS 服务的工作机制

理解 QGIS Server 发布 WMS 服务的原理，可以帮助你快速定位问题。一次 WMS 请求大致经历以下过程：

  1. 客户端发送 WMS 请求，例如 GetCapabilities 或 GetMap。
  2. Web Server 接收请求，并转发给 QGIS Server。
  3. QGIS Server 根据 MAP 参数或默认项目路径读取 QGIS 项目文件。
  4. QGIS Server 加载项目中的图层数据、符号系统、坐标系和服务设置。
  5. QGIS Server 返回 XML 能力文档或地图图片。

所以，当 WMS 服务无法访问时，常见问题通常集中在这几个环节：

  • QGIS Server 没有正确安装或无法被 Web Server 调用。
  • Web Server 转发规则错误。
  • 项目文件路径错误。
  • 服务器进程没有权限读取项目文件或数据文件。
  • QGIS 项目没有启用 WMS 相关配置。
  • 图层坐标系、范围或数据源路径不适合服务端环境。

步骤：QGIS Server 如何部署并发布 WMS 服务

步骤一：准备服务器环境

建议先选择一种相对稳定的 Linux 服务器环境，例如 Ubuntu Server 或 Debian。QGIS Server 在 Linux 上部署资料更多，也更适合长期运行。

部署前确认以下条件：

  • 服务器可以访问外网或可用的软件源。
  • 已安装并配置 Apache 或 Nginx。
  • 具备 sudo 权限。
  • 准备好用于发布的 QGIS 项目文件，例如 demo.qgz。
  • 项目中的数据路径在服务器上可访问。

如果是生产环境，建议将 QGIS 项目文件和数据统一放到固定目录，例如：

/data/qgis/projects/demo.qgz
/data/qgis/data/

这样后续权限配置、备份和迁移都会更清晰。

步骤二：安装 QGIS Server

在 Debian 或 Ubuntu 系统中，通常可以通过软件包安装 QGIS Server。不同系统版本的软件源配置略有差异，正式部署前建议参考 QGIS 官方安装文档确认当前可用源。

sudo apt update
sudo apt install qgis-server

安装完成后，可以检查 QGIS Server 可执行程序是否存在：

which qgis_mapserv.fcgi

如果能看到类似下面的路径，说明 QGIS Server 主程序已经安装：

/usr/lib/cgi-bin/qgis_mapserv.fcgi

注意：不同发行版和安装方式下，路径可能不同。后续 Web Server 配置时应使用你服务器上的真实路径。

步骤三：配置 Web Server 访问 QGIS Server

以 Apache 为例，可以通过 CGI 或 FastCGI 方式调用 QGIS Server。入门测试时，Apache CGI 配置相对直观。

先启用相关模块：

sudo a2enmod cgi
sudo systemctl restart apache2

如果 QGIS Server 程序位于 /usr/lib/cgi-bin/qgis_mapserv.fcgi，常见测试地址类似：

http://your-server/cgi-bin/qgis_mapserv.fcgi

直接访问该地址时，可能不会返回完整地图，但至少可以用于判断 Web Server 是否能调用 QGIS Server。真正发布 WMS 时，还需要传入 SERVICE、REQUEST 和 MAP 等参数。

如果使用 Nginx，通常需要结合 FastCGI 转发到 QGIS Server 或使用容器化方案。Nginx 的性能和反向代理能力更强，但初学者更容易在 FastCGI 参数上出错。建议先用 Apache 跑通基础流程，再根据实际生产需要迁移到 Nginx。

步骤四：在 QGIS Desktop 中配置项目

QGIS Server 发布 WMS 服务时读取的是 QGIS 项目文件，因此桌面端项目配置非常关键。

在 QGIS Desktop 中打开项目后，重点检查以下内容：

  • 项目坐标系：设置为适合业务的 CRS，例如 EPSG:3857、EPSG:4326 或本地投影坐标系。
  • 图层名称：避免使用过长、含特殊符号或重复的图层名。
  • 符号样式：确认颜色、线宽、标注在目标比例尺下可读。
  • 数据源路径：尽量使用服务器可识别的路径，不要依赖本机桌面路径。
  • 项目范围：设置合理的地图范围，避免 WMS GetMap 请求看不到数据。

然后进入项目属性中的服务相关设置，配置 WMS 元数据，例如服务标题、摘要、联系人、可发布图层和坐标参考系统。

建议至少配置：

  • WMS 服务标题。
  • WMS 服务摘要。
  • 允许发布的图层。
  • 支持的 CRS。
  • 项目范围或图层范围。

保存项目为 .qgz 文件，并上传到服务器目录，例如：

/data/qgis/projects/demo.qgz

步骤五：确认服务器可以读取项目和数据

这是 QGIS Server 发布 WMS 服务最常见的失败点。Apache 或 Nginx 通常以独立用户运行，例如 www-data。如果该用户没有权限读取项目文件和数据文件，WMS 服务就会报错或返回空白图。

可以检查文件权限：

ls -l /data/qgis/projects/demo.qgz
ls -ld /data/qgis/projects
ls -ld /data/qgis/data

如果使用 Apache 的 www-data 用户，可以根据实际安全策略调整权限。例如测试环境可使用：

sudo chown -R www-data:www-data /data/qgis
sudo chmod -R 755 /data/qgis

生产环境不建议盲目开放写权限。更推荐只给 Web 服务进程读取权限，并由专门的发布流程更新项目文件。

步骤六：请求 GetCapabilities 验证 WMS 服务

QGIS Server WMS 服务发布后，第一步不要急着看地图，而是先请求能力文档。

http://your-server/cgi-bin/qgis_mapserv.fcgi?SERVICE=WMS&REQUEST=GetCapabilities&MAP=/data/qgis/projects/demo.qgz

如果配置正常，浏览器会返回一段 XML，其中包含服务标题、图层列表、支持的坐标系和请求地址。

重点检查 XML 中是否包含：

  • <WMS_Capabilities> 或类似 WMS 能力文档根节点。
  • 你在 QGIS Desktop 中设置的服务标题。
  • 项目中的图层名称。
  • 支持的 CRS 信息。
  • GetMap 请求地址。

如果 GetCapabilities 都无法返回，说明问题多半在 QGIS Server 调用、Web Server 配置、项目路径或文件权限上。

步骤七：请求 GetMap 验证地图图片

能力文档正常后，再测试 GetMap 请求。示例：

http://your-server/cgi-bin/qgis_mapserv.fcgi?
SERVICE=WMS&
VERSION=1.3.0&
REQUEST=GetMap&
MAP=/data/qgis/projects/demo.qgz&
LAYERS=your_layer_name&
STYLES=&
CRS=EPSG:4326&
BBOX=116,39,117,40&
WIDTH=800&
HEIGHT=600&
FORMAT=image/png

实际使用时需要替换：

  • your_layer_name：能力文档中的真实图层名。
  • CRS：项目或图层支持的坐标系。
  • BBOX：图层实际范围。
  • MAP：服务器上的项目文件路径。

如果返回的是一张空白图片，不一定表示服务坏了。更常见的原因是 BBOX 范围不包含数据，或者 CRS 和 BBOX 坐标顺序不匹配。

步骤八：在 QGIS Desktop 中加载 WMS 服务

为了排除浏览器 URL 拼写错误，建议用 QGIS Desktop 作为 WMS 客户端进行验证。

  1. 打开 QGIS Desktop。
  2. 进入 WMS/WMTS 数据源管理器。
  3. 新建连接。
  4. 填写 GetCapabilities 地址。
  5. 点击连接，查看是否能列出图层。
  6. 选择图层并添加到地图。

如果 QGIS Desktop 能正常加载，说明 WMS 服务基本可用。后续再接入 OpenLayers、Leaflet 或其他 WebGIS 前端。

常见坑：QGIS Server 发布 WMS 服务失败的排查重点

1. MAP 参数路径写错

MAP 参数必须是服务器上的真实路径，而不是你本机电脑上的路径。例如下面这种路径通常是错误的：

C:UsersGISDesktopdemo.qgz

在 Linux 服务器上应使用类似：

/data/qgis/projects/demo.qgz

2. 项目文件能读，但图层数据读不到

QGIS Server 可以打开 .qgz 项目，不代表项目里的 Shapefile、GeoPackage、PostGIS 图层都能访问。尤其是从 Windows 电脑上传项目到 Linux 服务器时，数据路径经常失效。

建议在 QGIS Desktop 中使用相对路径管理项目，或者在服务器上保持和项目一致的数据目录结构。

3. WMS 1.3.0 的坐标轴顺序导致空白图

WMS 1.3.0 对某些坐标系的坐标轴顺序更严格，例如 EPSG:4326 常见经纬度顺序问题。你以为 BBOX 是 minx,miny,maxx,maxy，但服务可能按纬度、经度解释。

排查方法：

  • 先用 QGIS Desktop 加载 WMS，避免手写 BBOX。
  • 尝试 WMS 1.1.1 与 1.3.0 对比。
  • 确认能力文档中 CRS 和 BoundingBox 的顺序。

4. 图层名称和 LAYERS 参数不一致

LAYERS 参数必须使用 GetCapabilities 中暴露的图层名称，而不是你自己猜的文件名。图层名里有中文、空格或特殊符号时，更容易出现编码和拼写问题。

发布服务前建议把图层名整理为简洁英文或拼音，例如：

roads
buildings
landuse

5. 服务器字体缺失导致标注异常

桌面端地图标注正常，但 WMS 图片中中文变成方框，通常是服务器没有安装相应字体。解决方法是安装中文字体，并重启 Web Server 或 QGIS Server 相关进程。

6. 数据量太大导致 GetMap 很慢

WMS 返回的是渲染后的图片。数据量大、符号复杂、标注密集、请求范围过大都会影响响应速度。

可以从以下方向优化：

  • 为 PostGIS 图层建立空间索引。
  • 减少不必要的复杂符号和透明叠加。
  • 设置合理的比例尺可见范围。
  • 用 GeoPackage 或 PostGIS 替代大量零散 Shapefile。
  • 对底图或静态专题图使用缓存服务。

方法比较：QGIS Server、GeoServer 和 ArcGIS Server 怎么选

方案 适合场景 优势 注意事项
QGIS Server 已有 QGIS 项目，需要快速发布 WMS 直接复用 QGIS Desktop 样式和项目配置，开源免费 部署和性能优化需要理解 Web Server、权限和项目路径
GeoServer 需要集中管理多种 OGC 服务和数据源 管理界面成熟，WMS/WFS/WMTS 生态常用 QGIS 样式不能完全直接复用，复杂制图需要重新配置
ArcGIS Server 企业级 Esri 技术栈和 ArcGIS Pro 制图发布 与 ArcGIS 生态集成度高，管理体系完整 商业授权成本较高，部署体系相对重

如果你的地图主要在 QGIS Desktop 中制作，并希望尽量保留 QGIS 的符号化效果，QGIS Server 发布 WMS 服务是很自然的选择。如果你更重视图层集中管理和标准服务管理界面，GeoServer 也很常见。如果单位已经全面使用 Esri 体系，则 ArcGIS Server 更容易融入现有流程。

检查清单：发布前后逐项确认

部署 QGIS Server 并发布 WMS 服务时，可以按下面清单排查：

  • 服务器已安装 QGIS Server。
  • Web Server 能访问 qgis_mapserv.fcgi。
  • QGIS 项目文件已经上传到服务器固定目录。
  • MAP 参数使用服务器真实路径。
  • Web Server 运行用户有权限读取项目文件。
  • Web Server 运行用户有权限读取所有图层数据。
  • QGIS Desktop 中已配置 WMS 服务标题、图层和 CRS。
  • GetCapabilities 能返回 XML 能力文档。
  • 能力文档中能看到目标图层。
  • GetMap 使用正确的 LAYERS、CRS 和 BBOX。
  • 中文标注所需字体已在服务器安装。
  • 大数据图层已建立索引或设置比例尺可见范围。

实务建议：先用一个很小的点图层测试 QGIS Server WMS 发布流程，确认服务链路没问题后，再替换成正式项目。这样排错效率会高很多。

FAQ：QGIS Server 如何部署和 WMS 服务发布常见问题

QGIS Server 必须和 QGIS Desktop 安装在同一台机器上吗？

不必须。常见做法是在本地电脑用 QGIS Desktop 制作项目文件，然后把 .qgz 项目和数据上传到服务器，由 QGIS Server 负责发布。关键是服务器上的数据路径和权限必须正确。

QGIS Server 发布 WMS 服务一定要写 MAP 参数吗？

不一定。可以通过环境变量或 Web Server 配置设置默认项目路径。但入门阶段建议显式使用 MAP 参数，方便确认当前请求使用的是哪个 QGIS 项目文件。

为什么 GetCapabilities 正常，但 GetMap 是空白图？

常见原因包括 BBOX 不包含数据、CRS 不匹配、WMS 1.3.0 坐标轴顺序问题、图层比例尺不可见、样式透明或图层名称错误。建议先在 QGIS Desktop 中加载 WMS，再根据能力文档复制图层名和范围。

QGIS Server 可以发布 PostGIS 图层吗？

可以。只要 QGIS 项目中的 PostGIS 连接在服务器环境下可用，且 QGIS Server 运行用户能够访问数据库，就可以通过 WMS 发布 PostGIS 图层。生产环境中应注意数据库账号权限、空间索引和连接安全。

QGIS Server 发布的 WMS 能被 OpenLayers 或 Leaflet 调用吗？

可以。OpenLayers 和 Leaflet 都可以加载 WMS 图层。前端调用时需要填写 WMS 服务地址、图层名、版本、坐标系和图片格式。若前端地图使用 EPSG:3857，而服务只支持其他 CRS，需要在 QGIS 项目中配置相应坐标系支持。

QGIS Server 适合发布高并发在线地图吗？

QGIS Server 可以用于正式服务，但高并发场景需要额外设计，例如反向代理、缓存、负载均衡、数据索引、比例尺控制和静态瓦片缓存。不要直接把复杂项目裸露给大量用户访问后再临时优化。

结论：先跑通链路，再优化 QGIS Server WMS 服务

QGIS Server如何部署?WMS服务怎么发布? 这个问题的核心不是单个命令，而是一条完整链路：QGIS Desktop 制作项目，服务器安装 QGIS Server，Web Server 转发请求，项目和数据路径可访问，然后通过 GetCapabilities 和 GetMap 验证结果。

实际工作中，建议先用小数据项目跑通 QGIS Server 发布 WMS 服务，再逐步加入正式图层、样式、标注和性能优化。只要把项目路径、文件权限、WMS 参数和坐标系这几个关键点检查清楚，大多数部署问题都能快速定位。

对于 GIS 学习和中小型 WebGIS 项目来说，QGIS Server 是一个非常实用的开源发布方案。它最大的价值在于可以复用 QGIS Desktop 的制图成果，让桌面地图更自然地进入 Web 服务和业务系统。