Ubuntu 22.04 安装 Apache Sedona 1.9.1 指南

Ubuntu 22.04 安装 Apache Sedona 1.9.1 空间数据分析引擎指南：JDK 17 与 Spark 3.5.9 环境准备、版本选型对照、Spark binary 加 jar 与 pip Python 两种安装方案、Sedona SQL 注册验证与卸载，全程实测。

Apache SedonaApache Sedona2026/10/12

Ubuntu 22.04 安装 Apache Sedona 1.9.1 指南

目标：在 Ubuntu 22.04 服务器上完成 Apache Sedona 1.9.1（Spark 地理空间数据分析引擎）的安装与验证。Sedona 以 jar 库形态叠加在 Apache Spark 之上，安装本质是「Spark 运行时 + Sedona jar + GeoTools wrapper jar」的组合装配。本文给出 JDK 17 环境准备、版本选型对照，以及「Spark binary + Sedona jar」「pip 安装 pyspark + apache-sedona」两种安装方案与验证回显。所有命令与回显均在 Ubuntu 22.04.5 + JDK 17 + Spark 3.5.9 环境实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（VERSION_CODENAME=jammy）
  • 架构：x86_64
  • Java：OpenJDK 17.0.20.1（openjdk-17-jdk-headless，Ubuntu 官方源）
  • Spark：3.5.9（spark-3.5.9-bin-hadoop3.tgz，Scala 2.12.18，local 模式）
  • Sedona 版本：1.9.1（当前最新稳定版，sedona-spark-shaded-3.5_2.12-1.9.1.jar）
  • GeoTools wrapper：org.datasyslab:geotools-wrapper:1.9.1-33.5
  • Python：3.10.12（Ubuntu 官方源）；pyspark 3.5.9、apache-sedona 1.9.1（pip）
  • 演示账号：root
  • 软件目录：/opt/spark、/opt/sedona-jars/

💡 说明：Apache Sedona 不是独立守护进程，没有服务端口；它是一组叠加在 Spark 上的空间 SQL 扩展（ST_* 函数 + 空间类型 + 空间索引 join），「安装」即准备好 Spark 与 Sedona jar 并完成注册。

二、前置条件

2.1 更新软件源

sudo apt-get update

2.2 安装 JDK 17 与基础工具

Sedona 1.9.x 支持 Spark 3.4/3.5/4.0/4.1，对应 JDK 8/11/17（Spark 4.x 需 JDK 17/21）。本指南按 Spark 3.5.9 + JDK 17 实测，Ubuntu 22.04 官方源已内置：

sudo apt-get install -y openjdk-17-jdk-headless python3 python3-pip wget curl tar

验证 JDK：

/usr/lib/jvm/java-17-openjdk-amd64/bin/java -version

实测回显：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

三、版本选型说明

通过 Maven Central 元数据确认 Sedona 最新版本：

curl -s https://repo.maven.apache.org/maven2/org/apache/sedona/sedona-spark-shaded-3.5_2.12/maven-metadata.xml | grep -E "latest|release"

实测回显：

<latest>1.9.1</latest>
<release>1.9.1</release>

Sedona 按 Spark 大版本提供不同 artifact，选型对照如下：

Sedona artifact适用 Spark本指南选用
sedona-spark-shaded-3.4_2.12Spark 3.4.x不用（3.4 已较旧）
sedona-spark-shaded-3.5_2.12Spark 3.5.x✔（Spark 3.5.9 + Scala 2.12）
sedona-spark-shaded-4.0_2.13Spark 4.0.x仅当已用 Spark 4.0
sedona-spark-shaded-4.1_2.13Spark 4.1.x仅当已用 Spark 4.1

💡 版本选择建议：artifact 名中的 3.5_2.12 表示 Spark 3.5 + Scala 2.12，必须与 Spark 发行版和 Scala 版本严格匹配；shaded 版把依赖打进单 jar，部署最省心，本指南全程使用 sedona-spark-shaded-3.5_2.12-1.9.1.jar。

四、方案 A：Spark binary + Sedona jar（Java/Scala 路线，官方推荐）

该方案安装 Spark 3.5.9 官方二进制包，再从 Maven Central 下载 Sedona shaded jar 与 GeoTools wrapper jar，通过 spark-defaults.conf 全局引入，spark-shell/spark-submit 均自动加载。

4.1 下载并安装 Spark 3.5.9

从官方下载目录（或国内加速源）下载官方 tar 包并校验 sha512：

cd /opt
wget -q https://mirrors.tuna.tsinghua.edu.cn/apache/spark/spark-3.5.9/spark-3.5.9-bin-hadoop3.tgz -O spark-3.5.9-bin-hadoop3.tgz
stat -c %s spark-3.5.9-bin-hadoop3.tgz
sha512sum spark-3.5.9-bin-hadoop3.tgz

实测回显（大小与 sha512 与官方 dlcdn.apache.org 上的 .sha512 文件完全一致）：

401379923
66097faf48b12f8673dc13256a44d731c27c86a5831cd8ca930c6fd9dd9bdf31d40593095e959461351d55da1a8e3ad5ed95e0b4b51bea87ca3989ab002ea8ce  spark-3.5.9-bin-hadoop3.tgz

解压、重命名并写入环境变量：

cd /opt && tar -xzf spark-3.5.9-bin-hadoop3.tgz
mv spark-3.5.9-bin-hadoop3 spark
printf "export SPARK_HOME=/opt/spark\nexport JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64\nexport PATH=\$SPARK_HOME/bin:\$JAVA_HOME/bin:\$PATH\n" > /etc/profile.d/spark.sh
source /etc/profile.d/spark.sh

4.2 下载 Sedona 与 GeoTools wrapper jar

从 Maven Central 下载两个 jar（两者缺一不可：前者提供 ST_* SQL 扩展，后者支撑 ST_Transform 等 CRS 坐标系变换）：

mkdir -p /opt/sedona-jars && cd /opt/sedona-jars
wget -q https://repo.maven.apache.org/maven2/org/apache/sedona/sedona-spark-shaded-3.5_2.12/1.9.1/sedona-spark-shaded-3.5_2.12-1.9.1.jar
wget -q https://repo.maven.apache.org/maven2/org/datasyslab/geotools-wrapper/1.9.1-33.5/geotools-wrapper-1.9.1-33.5.jar
ls -lh /opt/sedona-jars

实测回显：

total 110M
-rw-r--r-- 1 root root 31M Aug  1 06:25 geotools-wrapper-1.9.1-33.5.jar
-rw-r--r-- 1 root root 79M Aug  2 06:37 sedona-spark-shaded-3.5_2.12-1.9.1.jar

⚠️ 注意：GeoTools wrapper 的 Maven 坐标是 org.datasyslab:geotools-wrapper（不是 org.apache.sedona 组），版本号格式为 <Sedona 版本>-<GeoTools 版本>，务必与 Sedona 主版本配套（1.9.1 配 1.9.1-33.5）。

4.3 配置 spark-defaults.conf 引入 jar

从模板生成配置并追加 Sedona 相关键：

cp /opt/spark/conf/spark-defaults.conf.template /opt/spark/conf/spark-defaults.conf
cat >> /opt/spark/conf/spark-defaults.conf << 'EOF'
spark.jars                /opt/sedona-jars/sedona-spark-shaded-3.5_2.12-1.9.1.jar,/opt/sedona-jars/geotools-wrapper-1.9.1-33.5.jar
spark.driver.memory       512m
spark.serializer          org.apache.spark.serializer.KryoSerializer
EOF

4.4 验证安装

先看 Spark 版本：

/opt/spark/bin/spark-shell --version

实测回显：

Welcome to
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /___/ .__/\_,_/_/ /_/\_\   version 3.5.9
      /_/

Using Scala version 2.12.18, OpenJDK 64-Bit Server VM, 17.0.20.1
Branch HEAD
Compiled by user holden on 2026-07-12T18:40:50Z
Revision 7c14a3c28b141cc97a330c4d0f5d2a6da7267f85
Url https://github.com/apache/spark
Type --help for more information.

再在 spark-shell 中注册 Sedona 并执行一条空间 SQL（注册方式 SedonaContext.create 自 Sedona 1.4 起为官方推荐）：

/opt/spark/bin/spark-shell --master "local[*]"

在交互提示符中依次输入：

import org.apache.sedona.spark.SedonaContext
val sedona = SedonaContext.create(spark)
sedona.sql("SELECT ST_AsText(ST_Point(1.0, 2.0)) AS point").show(false)

实测回显（启动横幅关键行 + 查询结果）：

Spark context available as 'sc' (master = local[*], app id = local-1791810790684).
Spark session available as 'spark'.
+-----------+
|point      |
+-----------+
|POINT (1 2)|
+-----------+

输出 POINT (1 2) 即 Sedona SQL 函数注册成功。

五、方案 B：Python 路线（pip 安装 pyspark 与 apache-sedona）

不装 Spark binary，仅用 pip 安装 pyspark（内含 Spark 发行包）与 apache-sedona（Python 封装），适合 Python 数据分析场景。

5.1 配置 pip 源并安装

pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip3 install pyspark==3.5.9 apache-sedona==1.9.1

实测回显（安装完成行）：

Installing collected packages: py4j, pyspark, numpy, attrs, shapely, apache-sedona
Successfully installed apache-sedona-1.9.1 attrs-26.1.0 numpy-2.2.6 py4j-0.10.9.9 pyspark-3.5.9 shapely-2.1.2

5.2 补装 pandas 与 pyarrow

sedona.spark 的向量化 UDF 模块依赖 pandas，缺省会报 ModuleNotFoundError（见「九、常见问题」Q1），一并补齐：

pip3 install pandas pyarrow

5.3 验证安装

Python 路线同样需要 Sedona jar。方案 B 已装 pyspark，但 Sedona jar 仍建议从 Maven Central 下载到本地（命令见 4.2 节），再在代码里用 spark.jars 注入。创建验证脚本 /opt/sedona_verify.py：

from sedona.spark import SedonaContext
from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .master("local[*]") \
    .appName("SedonaVerify") \
    .config("spark.jars", "/opt/sedona-jars/sedona-spark-shaded-3.5_2.12-1.9.1.jar,/opt/sedona-jars/geotools-wrapper-1.9.1-33.5.jar") \
    .config("spark.driver.memory", "512m") \
    .config("spark.log.level", "WARN") \
    .getOrCreate()
sedona = SedonaContext.create(spark)
sedona.sql("SELECT ST_AsText(ST_Point(1.0, 2.0)) AS point").show(truncate=False)
spark.stop()

运行：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PYSPARK_PYTHON=python3
python3 /opt/sedona_verify.py

实测回显：

+-----------+
|point      |
+-----------+
|POINT (1 2)|
+-----------+

确认 Python 包版本：

pip3 show apache-sedona pyspark | grep -E "^(Name|Version)"

实测回显：

Name: apache-sedona
Version: 1.9.1
Name: pyspark
Version: 3.5.9

六、多方案对比与选择建议

维度方案 A：Spark binary + jar方案 B：pip 安装
需下载Spark tar 包 383M + 两个 jarpyspark wheel 317.9M + apache-sedona 394KB
使用入口spark-shell / spark-submit / pysparkpython3（或 spark-submit）
Sedona jar 引入spark-defaults.conf 全局生效代码内 spark.jars 或 SparkConf 配置
适用场景生产作业、Scala/Java 开发、多机部署数据分析脚本、Notebook、原型验证
升级 Sedona替换 jar 文件 + 改配置pip 升级 apache-sedona

选择建议：生产集群作业与 Scala/Java 工程选方案 A；以 Python 为主的数据分析选方案 B。两方案的 Sedona 版本必须一致（本文均按 1.9.1）。

七、配置说明

7.1 环境变量

/etc/profile.d/spark.sh（方案 A）：

export SPARK_HOME=/opt/spark
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$SPARK_HOME/bin:$JAVA_HOME/bin:$PATH

7.2 JVM 堆内存

Spark 驱动进程堆内存统一限制为 512m（见 4.3/5.3 节 spark.driver.memory 512m）。运行期验证生效值：

/usr/lib/jvm/java-17-openjdk-amd64/bin/jps -v | grep -oE "\-Xmx[0-9]+m"

实测回显：

-Xmx512m

7.3 Sedona 注册方式

  • Spark 1.4 以上版本统一用 SedonaContext.create(spark)（Scala）或 SedonaContext.create(spark)（Python）完成 SQL 函数与类型注册；
  • 旧式的 SedonaRegistrator.registerAll(spark) 仍可用但已不推荐；
  • Python 路线导入入口为 from sedona.spark import SedonaContext。

八、注意事项

⚠️ 注意：

  1. Sedona artifact 必须与 Spark、Scala 版本三方匹配（Spark 3.5 + Scala 2.12 → sedona-spark-shaded-3.5_2.12），错配会在注册或查询时报 ClassNotFoundException。
  2. geotools-wrapper 与 Sedona 主版本配套（1.9.1 ↔ 1.9.1-33.5）；不装它则 ST_Transform 等 CRS 变换函数运行时报错，基础几何函数不受影响。
  3. Python 路线必须补装 pandas/pyarrow，否则 import sedona.spark 直接失败。
  4. 所有演示均按 local 模式、驱动堆 512m 实测；生产集群请按数据规模另行规划 spark.driver.memory/spark.executor.memory。

九、常见问题

Q1：import sedona.spark 报 ModuleNotFoundError: No module named 'pandas'？ sedona.spark.sql.functions 模块顶层 import pandas。执行 pip3 install pandas pyarrow 补齐后重试（实测装 pandas 2.3.3、pyarrow 25.0.1 后恢复正常）。

Q2：spark-shell -i 加载含中文注释的脚本报 java.nio.charset.MalformedInputException: Input length = 1？ 终端 locale 为 POSIX 时 REPL 按 ASCII 解码脚本文件。两种解决：脚本注释只用 ASCII 字符（本指南实测可行），或启动前 export LANG=C.UTF-8。

Q3：SELECT SedonaVersion() 报 UNRESOLVED_ROUTINE？ Sedona 1.9.1 的 SQL 函数集中没有版本号函数（实测 SHOW FUNCTIONS LIKE '%version%' 仅返回 Spark 内置 version）。版本确认用 pip3 show apache-sedona 或直接看 jar 文件名。

Q4：官方 dlcdn.apache.org 下载 Spark 很慢？ 可换国内加速源下载同一文件（文件名与字节数完全一致），下载后务必用官方 .sha512 文件校验，见 4.1 节实测回显。

Q5：如何确认 Sedona jar 已被 Spark 加载？ spark-shell 启动后执行 SedonaContext.create(spark) 不抛异常、且 SELECT ST_AsText(ST_Point(1.0, 2.0)) 返回 POINT (1 2) 即加载成功；若报 UNRESOLVED_ROUTINE: Cannot resolve function ST_AsText，检查 spark.jars 路径与文件名。

十、卸载方式

方案 A（移除 Spark 与 Sedona jar）：

rm -rf /opt/spark /opt/sedona-jars /opt/spark-3.5.9-bin-hadoop3.tgz /etc/profile.d/spark.sh

方案 B（移除 pip 包）：

pip3 uninstall -y apache-sedona pyspark py4j shapely

连同 JDK 一起移除：

sudo apt-get remove -y openjdk-17-jdk-headless
sudo apt-get autoremove -y

十一、参考链接

  • Apache Sedona 官网：https://sedona.apache.org/
  • Sedona Maven Central 目录：https://repo.maven.apache.org/maven2/org/apache/sedona/
  • Spark 下载目录：https://downloads.apache.org/spark/（历史版本 https://archive.apache.org/dist/spark/）
  • Sedona 安装文档：https://sedona.apache.org/latest-snapshot/setup/overview/