QGIS Server 3.44 在 Ubuntu 22.04 部署：Apache 配置与 3 个常见错误排查

QGIS Server 3.44 在 Ubuntu 22.04 部署Apache 配置与 3 个常见错误排查1. 环境准备与基础安装在Ubuntu 22.04上部署QGIS Server需要先确保系统环境满足基本要求。建议使用至少4GB内存的服务器并预留20GB以上的磁盘空间用于存储地理数据。以下是完整的依赖安装步骤# 更新系统包索引 sudo apt update sudo apt upgrade -y # 安装QGIS Server核心组件不包含推荐和可选包以减少体积 sudo apt install qgis-server --no-install-recommends --no-install-suggests # 安装Python插件支持可选 sudo apt install python3-qgis # 验证安装位置 ls -l /usr/lib/cgi-bin/qgis_mapserv.fcgi安装完成后通过以下命令验证QGIS Server版本/usr/lib/cgi-bin/qgis_mapserv.fcgi --version典型输出应包含类似信息QGIS 3.44.4 Solothurn Qt version 5.15.3 Python version 3.10.6注意生产环境中不建议在同一台服务器上同时安装QGIS Desktop和QGIS Server这可能导致资源冲突和安全隐患。2. Apache服务器深度配置2.1 基础模块安装与激活QGIS Server作为FastCGI应用运行需要Apache的fcgid模块支持# 安装Apache和fcgid模块 sudo apt install apache2 libapache2-mod-fcgid # 启用必要模块 sudo a2enmod rewrite headers fcgid2.2 虚拟主机配置文件创建专用配置文件/etc/apache2/sites-available/qgis-server.conf内容如下VirtualHost *:80 ServerAdmin adminyour-domain.com ServerName qgis.your-domain.com DocumentRoot /var/www/html # 日志单独存放 ErrorLog ${APACHE_LOG_DIR}/qgis-server-error.log CustomLog ${APACHE_LOG_DIR}/qgis-server-access.log combined # QGIS Server配置 ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/ Directory /usr/lib/cgi-bin AllowOverride None Options ExecCGI -MultiViews FollowSymLinks Require all granted SetHandler fcgid-script /Directory # 性能调优参数 FcgidMaxRequestLen 10MB FcgidConnectTimeout 60 FcgidIOTimeout 120 /VirtualHost启用配置并重启服务sudo a2ensite qgis-server.conf sudo systemctl restart apache22.3 防火墙设置如果使用UFW防火墙需要放行HTTP流量sudo ufw allow Apache Full sudo ufw enable3. 服务验证与功能测试3.1 基础功能验证通过curl测试服务是否正常运行curl http://localhost/cgi-bin/qgis_mapserv.fcgi?SERVICEWMSVERSION1.3.0REQUESTGetCapabilities正常响应应返回XML格式的WMS服务能力文档。如果返回404错误请检查/usr/lib/cgi-bin/qgis_mapserv.fcgi文件是否存在Apache配置中ScriptAlias路径是否正确文件权限是否为可执行7553.2 项目文件部署创建项目存储目录并设置权限sudo mkdir -p /var/www/qgis-projects sudo chown -R www-data:www-data /var/www/qgis-projects测试项目可通过以下URL访问http://yourserver/cgi-bin/qgis_mapserv.fcgi?MAP/var/www/qgis-projects/test.qgsSERVICEWMSREQUESTGetCapabilities4. 常见错误排查指南4.1 错误1404 Not Found症状访问服务URL返回404状态码排查步骤检查文件是否存在ls -l /usr/lib/cgi-bin/qgis_mapserv.fcgi验证Apache配置sudo apache2ctl configtest检查模块是否加载sudo apache2ctl -M | grep fcgid解决方案重新安装qgis-server包确保ScriptAlias指向正确路径检查SELinux/AppArmor是否阻止访问4.2 错误2权限错误典型报错Failed to load project file: /path/to/project.qgs Permission denied权限修复命令sudo chown www-data:www-data /var/www/qgis-projects/* sudo chmod 755 /var/www/qgis-projects重要如果项目使用数据库连接确保www-data用户有数据库访问权限4.3 错误3服务无法启动日志分析位置tail -n 50 /var/log/apache2/error.log常见原因及解决错误类型检测方法解决方案端口冲突ss -tulnp修改Apache监听端口内存不足free -h增加swap空间依赖缺失ldd /usr/lib/cgi-bin/qgis_mapserv.fcgi安装缺失库5. 性能优化与安全加固5.1 性能调优参数编辑/etc/apache2/mods-available/fcgid.confIfModule mod_fcgid.c FcgidMaxProcesses 10 FcgidMinProcessesPerClass 1 FcgidMaxProcessesPerClass 5 FcgidConnectTimeout 30 FcgidIOTimeout 300 FcgidBusyTimeout 300 /IfModule5.2 安全配置建议启用HTTPS加密sudo apt install certbot python3-certbot-apache sudo certbot --apache限制IP访问Directory /usr/lib/cgi-bin Require ip 192.168.1.0/24 /Directory禁用敏感信息泄露ServerTokens Prod ServerSignature Off6. 高级功能扩展6.1 插件安装与管理服务器插件需安装在特定目录sudo mkdir -p /usr/lib/qgis/server/plugins sudo chown www-data:www-data /usr/lib/qgis/server/plugins通过环境变量指定插件路径SetEnv QGIS_PLUGINPATH /usr/lib/qgis/server/plugins6.2 日志分析配置定制化日志格式记录GIS操作LogFormat %h %l %u %t \%r\ %s %b \%{Referer}i\ \%{User-Agent}i\ %{QGIS_PROJECT}e qgis_combined CustomLog ${APACHE_LOG_DIR}/qgis-access.log qgis_combined6.3 负载均衡配置多节点部署示例架构客户端 → 负载均衡器 (Nginx) ├─ QGIS Server节点1 ├─ QGIS Server节点2 └─ QGIS Server节点3Nginx配置片段upstream qgis_cluster { server 192.168.1.101:80; server 192.168.1.102:80; server 192.168.1.103:80; } server { location /qgis/ { proxy_pass http://qgis_cluster/cgi-bin/qgis_mapserv.fcgi; } }