znlgis 博客

GIS开发与技术分享

第二章：环境准备与安装部署

2.1 引言

在上一章中，我们了解了 GeoServer Cloud 的架构设计和核心概念。本章将进入实践环节，详细介绍如何搭建运行 GeoServer Cloud 所需的环境，并完成首次安装部署。无论您是在本地开发环境进行测试，还是准备部署到生产环境，本章的内容都将为您提供必要的指导。

GeoServer Cloud 作为容器化的微服务应用，主要依赖 Docker 技术栈。我们将从基础的系统要求开始，逐步介绍 Docker 和 Docker Compose 的安装配置，然后演示如何获取和运行 GeoServer Cloud 的 Docker 镜像。

2.2 系统要求

2.2.1 硬件要求

GeoServer Cloud 的硬件需求取决于您的使用场景和负载规模。以下是不同场景的推荐配置：

开发/测试环境（单机 Docker Compose）

资源 最低要求 推荐配置
CPU 4 核 8 核或更多
内存 8 GB 16 GB 或更多
存储 50 GB SSD 100 GB SSD
网络 100 Mbps 1 Gbps

生产环境（Kubernetes 集群）

资源 单节点最低 推荐（3节点集群）
CPU/节点 4 核 8 核
内存/节点 16 GB 32 GB
存储/节点 100 GB SSD 500 GB SSD
网络 1 Gbps 10 Gbps

2.2.2 操作系统要求

GeoServer Cloud 的 Docker 镜像基于 Linux，可以在以下操作系统上运行：

Linux（推荐）

macOS

Windows

2.2.3 软件依赖

软件 版本要求 用途
Docker Engine 20.10+ 容器运行时
Docker Compose 2.0+ 容器编排（单机）
Git 2.0+ 版本控制（可选）
curl/wget 任意版本 下载文件

对于开发者还需要： | 软件 | 版本要求 | 用途 | |——|———-|——| | JDK | 21+ | Java 开发 | | Maven | 3.6.3+ | 项目构建 | | GNU Make | 3.8+ | 构建自动化 |

2.3 Docker 安装与配置

2.3.1 Linux 系统安装 Docker

以 Ubuntu 为例，使用官方脚本快速安装：

# 1. 更新包索引
sudo apt-get update

# 2. 安装必要的依赖
sudo apt-get install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# 3. 添加 Docker 官方 GPG 密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
    sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 4. 设置 Docker 仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. 安装 Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 6. 将当前用户添加到 docker 组（避免每次使用 sudo）
sudo usermod -aG docker $USER

# 7. 重新登录或执行以下命令使组权限生效
newgrp docker

# 8. 验证安装
docker --version
docker compose version

对于 CentOS/RHEL 系统：

# 1. 安装必要工具
sudo yum install -y yum-utils

# 2. 添加 Docker 仓库
sudo yum-config-manager --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo

# 3. 安装 Docker
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 4. 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker

# 5. 将用户添加到 docker 组
sudo usermod -aG docker $USER

2.3.2 macOS 安装 Docker Desktop

  1. 访问 Docker Desktop for Mac 下载安装包

  2. 打开下载的 .dmg 文件，将 Docker 拖拽到应用程序文件夹

  3. 从应用程序启动 Docker Desktop

  4. 等待 Docker 启动完成（菜单栏显示 Docker 图标）

  5. 打开终端验证：

docker --version
docker compose version

资源配置建议（Docker Desktop 设置）：

2.3.3 Windows 安装 Docker Desktop

  1. 确保已启用 WSL2（Windows Subsystem for Linux 2）：
# 以管理员身份运行 PowerShell
wsl --install
# 重启电脑

  1. 下载并安装 Docker Desktop for Windows

  2. 安装时确保勾选 “Use WSL 2 instead of Hyper-V”

  3. 安装完成后重启电脑

  4. 启动 Docker Desktop，等待初始化完成

  5. 打开 PowerShell 或命令提示符验证：

docker --version
docker compose version

2.3.4 Docker 配置优化

配置 Docker 守护进程

创建或编辑 /etc/docker/daemon.json（Linux）或通过 Docker Desktop 设置（Windows/macOS）：

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  },
  "storage-driver": "overlay2",
  "live-restore": true,
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 65536,
      "Soft": 65536
    }
  }
}

重启 Docker 服务使配置生效：

sudo systemctl restart docker

配置镜像加速（中国大陆用户）

由于网络原因，直接从 Docker Hub 拉取镜像可能较慢。可以配置镜像加速器：

{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

验证配置：

docker info | grep -A 5 "Registry Mirrors"

2.4 获取 GeoServer Cloud Docker 镜像

2.4.1 官方镜像仓库

GeoServer Cloud 的所有 Docker 镜像都托管在 Docker Hub 的 geoservercloud 组织下。

主要镜像列表：

镜像名称 说明 用途
geoservercloud/geoserver-cloud-gateway API 网关 必需
geoservercloud/geoserver-cloud-discovery 服务发现 Docker Compose
geoservercloud/geoserver-cloud-config 配置服务 Docker Compose
geoservercloud/geoserver-cloud-wms WMS 服务 核心服务
geoservercloud/geoserver-cloud-wfs WFS 服务 核心服务
geoservercloud/geoserver-cloud-wcs WCS 服务 核心服务
geoservercloud/geoserver-cloud-wps WPS 服务 可选
geoservercloud/geoserver-cloud-gwc GeoWebCache 可选
geoservercloud/geoserver-cloud-rest REST API 核心服务
geoservercloud/geoserver-cloud-webui Web 管理界面 核心服务
geoservercloud/geoserver-acl 访问控制服务 可选

2.4.2 镜像版本选择

查看可用版本：

# 以 WMS 镜像为例
docker search geoservercloud/geoserver-cloud-wms

# 或访问 Docker Hub 页面查看所有标签
# https://hub.docker.com/r/geoservercloud/geoserver-cloud-wms/tags

版本标签说明：

生产环境建议：始终使用具体版本号，避免使用 latest 标签。

2.4.3 拉取镜像

拉取单个镜像：

docker pull geoservercloud/geoserver-cloud-wms:2.28.1.0

批量拉取所有核心镜像：

#!/bin/bash
VERSION="2.28.1.0"
IMAGES=(
  "geoserver-cloud-gateway"
  "geoserver-cloud-discovery"
  "geoserver-cloud-config"
  "geoserver-cloud-wms"
  "geoserver-cloud-wfs"
  "geoserver-cloud-wcs"
  "geoserver-cloud-rest"
  "geoserver-cloud-webui"
  "geoserver-cloud-gwc"
)

for img in "${IMAGES[@]}"; do
  echo "Pulling geoservercloud/${img}:${VERSION}"
  docker pull "geoservercloud/${img}:${VERSION}"
done

2.4.4 镜像签名验证

从版本 1.8.6 开始，所有 Docker 镜像都使用 cosign 签名。验证镜像签名的步骤：

  1. 安装 cosign：
# macOS (使用 Homebrew)
brew install cosign

# Linux
curl -sSLO https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64
chmod +x cosign-linux-amd64
sudo mv cosign-linux-amd64 /usr/local/bin/cosign
  1. 下载公钥并验证：
# 下载公钥
curl -sSLO https://raw.githubusercontent.com/geoserver/geoserver-cloud/main/docs/cosign/cosign.pub

# 验证镜像签名
cosign verify --key cosign.pub geoservercloud/geoserver-cloud-wms:2.28.1.0

成功验证后会显示签名信息。

2.5 快速启动

2.5.1 下载 Docker Compose 文件

GeoServer Cloud 提供了预配置的 Docker Compose 文件，支持不同的目录后端配置。

使用 pgconfig（PostgreSQL）后端（推荐）

# 创建工作目录
mkdir geoserver-cloud && cd geoserver-cloud

# 下载 compose 文件
wget "https://geoserver.org/geoserver-cloud/deploy/docker-compose/stable/pgconfig/compose.yml"

# 或使用 curl
curl -O "https://geoserver.org/geoserver-cloud/deploy/docker-compose/stable/pgconfig/compose.yml"

使用 datadir（数据目录）后端

wget "https://geoserver.org/geoserver-cloud/deploy/docker-compose/stable/datadir/compose.yml"

2.5.2 理解 Compose 文件结构

以 pgconfig 版本为例，compose.yml 的主要结构如下：

version: '3.8'

services:
  # 基础设施服务
  rabbitmq:
    image: rabbitmq:3-management
    # RabbitMQ 消息队列，用于服务间事件通信
    
  database:
    image: postgres:15
    # PostgreSQL 数据库，存储 Catalog 配置
    
  discovery:
    image: geoservercloud/geoserver-cloud-discovery:${TAG}
    # Eureka 服务发现
    
  config:
    image: geoservercloud/geoserver-cloud-config:${TAG}
    # Spring Cloud Config 配置服务
    
  # GeoServer 核心服务
  gateway:
    image: geoservercloud/geoserver-cloud-gateway:${TAG}
    # API 网关，统一入口
    ports:
      - "9090:8080"
    
  wms:
    image: geoservercloud/geoserver-cloud-wms:${TAG}
    # Web Map Service
    
  wfs:
    image: geoservercloud/geoserver-cloud-wfs:${TAG}
    # Web Feature Service
    
  wcs:
    image: geoservercloud/geoserver-cloud-wcs:${TAG}
    # Web Coverage Service
    
  rest:
    image: geoservercloud/geoserver-cloud-rest:${TAG}
    # REST API
    
  webui:
    image: geoservercloud/geoserver-cloud-webui:${TAG}
    # Web 管理界面
    
  gwc:
    image: geoservercloud/geoserver-cloud-gwc:${TAG}
    # GeoWebCache 瓦片缓存

2.5.3 配置环境变量

在 compose.yml 同目录下创建 .env 文件进行自定义配置：

# .env 文件内容
# GeoServer Cloud 版本
TAG=2.28.1.0

# 运行用户（避免权限问题）
GS_USER=1000:1000

# 管理员账户
GEOSERVER_ADMIN_USERNAME=admin
GEOSERVER_ADMIN_PASSWORD=geoserver

# 数据库配置
PGCONFIGDB_HOST=database
PGCONFIGDB_PORT=5432
PGCONFIGDB_DATABASE=geoserver
PGCONFIGDB_USERNAME=geoserver
PGCONFIGDB_PASSWORD=geo5erver

2.5.4 启动服务

# 拉取所有镜像
docker compose pull

# 后台启动所有服务
docker compose up -d

# 查看服务状态
docker compose ps

# 查看启动日志
docker compose logs -f

启动过程可能需要几分钟时间，服务会按依赖顺序启动：

1. rabbitmq, database    （基础服务）
2. discovery             （服务发现）
3. config                （配置服务）
4. gateway, wms, wfs, wcs, rest, webui, gwc （业务服务）

2.5.5 验证部署

等待所有服务变为 healthy 状态：

# 检查容器状态
docker compose ps

# 期望输出类似：
NAME                     STATUS                   PORTS
gscloud-config-1         Up (healthy)
gscloud-database-1       Up (healthy)
gscloud-discovery-1      Up (healthy)             0.0.0.0:8761->8761/tcp
gscloud-gateway-1        Up (healthy)             0.0.0.0:9090->8080/tcp
gscloud-gwc-1            Up (healthy)
gscloud-rabbitmq-1       Up (healthy)
gscloud-rest-1           Up (healthy)
gscloud-webui-1          Up (healthy)
gscloud-wcs-1            Up (healthy)
gscloud-wfs-1            Up (healthy)
gscloud-wms-1            Up (healthy)

测试服务可用性：

# 测试 WMS GetCapabilities
curl "http://localhost:9090/geoserver/cloud/ows?service=WMS&request=GetCapabilities"

# 测试 WFS GetCapabilities
curl "http://localhost:9090/geoserver/cloud/ows?service=WFS&request=GetCapabilities"

# 测试 REST API（需要认证）
curl -u admin:geoserver "http://localhost:9090/geoserver/cloud/rest/workspaces.json"

2.5.6 访问 Web 界面

部署完成后，可以通过浏览器访问以下地址：

服务 地址 说明
GeoServer 主页 http://localhost:9090/geoserver/cloud/ GeoServer Web 管理界面
Eureka Dashboard http://localhost:8761 服务注册情况
RabbitMQ 管理界面 http://localhost:15672 消息队列监控（guest/guest）

默认管理员账户：

2.6 基本配置

2.6.1 修改管理员密码

首次部署后，强烈建议立即修改默认管理员密码：

方法一：通过 Web 界面

  1. 登录 GeoServer Web 管理界面
  2. 点击左侧菜单的 “安全” -> “用户、组和角色”
  3. 选择 “用户” 标签
  4. 点击 “admin” 用户
  5. 修改密码并保存

方法二：通过环境变量

在 .env 文件中设置：

GEOSERVER_ADMIN_USERNAME=admin
GEOSERVER_ADMIN_PASSWORD=your_strong_password_here

然后重启服务：

docker compose down
docker compose up -d

2.6.2 配置服务路径

默认情况下，GeoServer Cloud 的服务路径为 /geoserver/cloud/。如果需要修改：

修改 .env 文件

GEOSERVER_BASE_PATH=/gis

重启后访问地址变为 http://localhost:9090/gis/

2.6.3 配置数据卷

为了持久化数据，需要配置 Docker 数据卷。编辑 compose.yml：

services:
  database:
    volumes:
      - pgdata:/var/lib/postgresql/data
      
  # 如果使用 datadir 后端
  wms:
    volumes:
      - geoserver-data:/opt/app/data_directory

volumes:
  pgdata:
  geoserver-data:

2.6.4 配置日志

调整日志级别，在服务的环境变量中添加：

services:
  wms:
    environment:
      - LOGGING_LEVEL_ORG_GEOSERVER=INFO
      - LOGGING_LEVEL_ORG_GEOTOOLS=WARN

日志级别选项：TRACE, DEBUG, INFO, WARN, ERROR

2.6.5 配置 JVM 参数

为各服务配置 JVM 内存参数：

services:
  wms:
    environment:
      - JAVA_OPTS=-Xms512m -Xmx2g -XX:+UseG1GC

推荐的内存配置：

服务 最小内存 最大内存
gateway 256m 512m
discovery 256m 512m
config 256m 512m
wms 512m 2g
wfs 512m 2g
wcs 512m 2g
webui 512m 1g
rest 256m 1g
gwc 512m 2g

2.7 服务管理

2.7.1 启动和停止服务

# 启动所有服务
docker compose up -d

# 停止所有服务（保留容器和数据）
docker compose stop

# 停止并删除容器（保留数据卷）
docker compose down

# 停止并删除所有内容（包括数据卷）
docker compose down -v

# 重启特定服务
docker compose restart wms

# 只启动特定服务（及其依赖）
docker compose up -d wms

2.7.2 服务扩缩容

GeoServer Cloud 支持动态扩缩容服务实例：

# 扩展 WMS 服务到 3 个实例
docker compose up -d --scale wms=3

# 缩减 WCS 服务到 0（禁用）
docker compose up -d --scale wcs=0

# 同时调整多个服务
docker compose up -d --scale wms=3 --scale wfs=2 --scale wcs=0

验证扩缩容结果：

docker compose ps

# 访问 Eureka 查看已注册的实例
# http://localhost:8761

2.7.3 查看日志

# 查看所有服务日志
docker compose logs

# 实时跟踪日志
docker compose logs -f

# 只看特定服务
docker compose logs -f wms

# 显示最近 100 行
docker compose logs --tail=100 wms

# 带时间戳
docker compose logs -t wms

2.7.4 进入容器调试

# 进入运行中的容器
docker compose exec wms /bin/bash

# 查看环境变量
docker compose exec wms env

# 查看进程
docker compose exec wms ps aux

# 查看网络配置
docker compose exec wms cat /etc/hosts

2.7.5 更新镜像版本

# 1. 修改 .env 文件中的版本号
TAG=2.28.2.0

# 2. 拉取新镜像
docker compose pull

# 3. 重新创建容器
docker compose up -d

# 或者一步完成
docker compose up -d --pull always

2.8 常见安装问题排除

2.8.1 服务启动失败

问题：服务反复重启

检查日志确定原因：

docker compose logs wms | tail -50

常见原因和解决方案：

原因 症状 解决方案
内存不足 OutOfMemoryError 增加 Docker 内存限制
依赖服务未就绪 Connection refused 等待或检查依赖服务状态
端口冲突 Address already in use 修改端口映射
配置错误 各种配置相关错误 检查环境变量和配置文件

问题：等待依赖服务超时

增加等待超时时间，在 compose.yml 中：

services:
  wms:
    environment:
      - SPRING_CLOUD_CONFIG_RETRY_MAXATTEMPTS=20

2.8.2 网络连接问题

问题：无法拉取镜像

# 检查 Docker Hub 连接
docker pull hello-world

# 使用镜像加速器（参见 2.3.4 节）

# 或配置代理
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

问题：服务间无法通信

# 检查 Docker 网络
docker network ls
docker network inspect geoserver-cloud_default

# 测试容器间连通性
docker compose exec wms ping discovery

2.8.3 数据库连接问题

问题：无法连接 PostgreSQL

# 检查数据库容器状态
docker compose logs database

# 测试数据库连接
docker compose exec database psql -U geoserver -d geoserver -c "SELECT 1"

# 检查数据库是否已初始化
docker compose exec database psql -U geoserver -d geoserver -c "\dt"

问题：数据库初始化失败

# 删除数据卷重新初始化
docker compose down -v
docker compose up -d

2.8.4 权限问题

问题：Permission denied

通常是因为容器内用户与宿主机卷权限不匹配：

# 检查 .env 中的 GS_USER 设置
# 确保与宿主机用户一致
echo "GS_USER=$(id -g):$(id -u)"

# 或修改目录权限
sudo chown -R 1000:1000 ./data

2.8.5 健康检查失败

问题：容器一直处于 unhealthy 状态

# 查看健康检查日志
docker inspect --format='' gscloud-wms-1

# 手动测试健康检查端点
docker compose exec wms curl -f http://localhost:8080/actuator/health

# 增加健康检查超时时间
# 在 compose.yml 中修改
healthcheck:
  timeout: 30s
  retries: 10

2.8.6 内存问题

问题：Out of Memory

# 检查容器内存使用
docker stats

# 增加 Docker 可用内存（Docker Desktop 设置）
# 或调整 JVM 参数
environment:
  - JAVA_OPTS=-Xms256m -Xmx1g

2.8.7 端口冲突

问题：端口已被占用

# 查找占用端口的进程
sudo lsof -i :9090

# 修改 compose.yml 中的端口映射
ports:
  - "9091:8080"  # 改用 9091

2.9 升级与版本管理

2.9.1 版本升级策略

GeoServer Cloud 的版本升级建议遵循以下策略：

  1. 阅读发布说明：每次升级前查看 Release Notes

  2. 测试环境验证：先在测试环境完成升级和验证

  3. 备份数据：升级前备份数据库和配置

  4. 滚动升级：生产环境采用滚动升级减少停机时间

2.9.2 升级步骤

# 1. 备份当前配置
docker compose exec database pg_dump -U geoserver geoserver > backup.sql

# 2. 更新版本号
# 编辑 .env 文件
TAG=2.28.2.0

# 3. 拉取新镜像
docker compose pull

# 4. 滚动更新服务
# 先更新无状态服务
docker compose up -d --no-deps wms wfs wcs rest

# 再更新其他服务
docker compose up -d

# 5. 验证服务正常
curl "http://localhost:9090/geoserver/cloud/ows?service=WMS&request=GetCapabilities"

2.9.3 版本回滚

如果升级后出现问题，可以快速回滚：

# 1. 停止当前服务
docker compose down

# 2. 恢复旧版本号
TAG=2.28.1.0

# 3. 启动旧版本
docker compose up -d

# 4. 如果需要，恢复数据库备份
docker compose exec -T database psql -U geoserver geoserver < backup.sql

2.10 本章小结

本章详细介绍了 GeoServer Cloud 的环境准备和安装部署过程，主要内容包括：

  1. 系统要求：了解了硬件、操作系统和软件依赖的具体要求。

  2. Docker 安装：在 Linux、macOS 和 Windows 系统上安装和配置 Docker。

  3. 获取镜像：从 Docker Hub 获取官方镜像，并学习了镜像签名验证方法。

  4. 快速启动：使用 Docker Compose 文件快速部署 GeoServer Cloud。

  5. 基本配置：修改管理员密码、配置服务路径、数据卷和日志等。

  6. 服务管理：启动、停止、扩缩容和查看日志等操作命令。

  7. 故障排除：常见问题的诊断和解决方法。

  8. 版本管理：升级策略和回滚步骤。

通过本章的学习，您应该能够成功部署一个可运行的 GeoServer Cloud 环境。在下一章中，我们将深入了解 GeoServer Cloud 的各个核心服务组件及其功能。

2.11 思考题

  1. Docker Compose 和 Kubernetes 在部署 GeoServer Cloud 时各有什么优缺点？什么场景下应该选择哪种方式？

  2. 为什么建议使用 pgconfig（PostgreSQL）后端而不是 datadir（数据目录）后端？两者的主要区别是什么？

  3. 如何设计一个零停机时间的 GeoServer Cloud 升级方案？

  4. 在生产环境中，应该如何配置 Docker 日志以便于故障排查？

  5. 如果需要在防火墙严格的环境中部署 GeoServer Cloud，需要开放哪些端口？各端口的用途是什么？