这几年做GIS项目交付，验收现场被问得最多的一类问题，几乎都绕不开信创环境部署。尤其是SuperMap GIS平台软件这套东西——iServer、iDesktopX、iPortal这些组件，放到国产CPU加国产操作系统的机器上，跟在普通x86服务器上装，完全是两种手感。前者你可能十分钟就搞定了，后者可能折腾两天还在查日志。这篇东西就是把我自己在多个信创项目里踩过的坑、总结出来的排查路径、以及那些官方文档里写得比较"含蓄"的细节，一次性摊开来讲清楚。不管你是刚接触SuperMap GIS的新手，还是已经做过几个信创项目的老人，这篇SuperMap GIS平台软件在信创环境部署的实操问答记录，应该都能帮你少走点弯路。它不讲空泛的概念，只讲你真正会碰到的问题：环境怎么盘、依赖怎么补、服务为什么起不来、地图为什么出不了字、许可为什么激活不了。适合做GIS平台实施、运维、二次开发的朋友参考。

1. 信创环境下部署SuperMap GIS，难点究竟卡在哪

1.1 环境组合的碎片化，是最先要接受的现实

在普通项目里，我们说"部署一套GIS服务"，心里基本有谱：x86服务器，装个Linux发行版，JDK装好，解压iServer，配个许可，启动。整个过程是线性的。但到了信创环境，这个线性流程会被彻底打散。你要面对的是CPU架构、操作系统、JDK、数据库、中间件这五个维度各自都有多个国产选项，而且它们之间的兼容性并不是天然对齐的。龙芯是LoongArch架构，鲲鹏和飞腾是ARM，海光和兆芯是x86，光是CPU架构这一层，就决定了你下载的安装包、JDK、加密狗驱动都要分开准备。操作系统这边有麒麟、统信UOS，又分服务器版和桌面版，底层glibc版本、包管理命令、默认字体配置都可能不一样。这就导致一个很尴尬的情况：同事在麒麟加鲲鹏上跑得好好的部署脚本，你拿到统信加海光上就报glibc symbol not found。这不是谁能力不行，是环境本身就是碎的。

我一般建议团队在做信创项目时，第一件事是把环境组合固定下来，形成一份内部的兼容清单。比如某个项目确定用鲲鹏920 + 麒麟V10 SP2 + 达梦DM8 + 毕昇JDK这套组合，那后续所有部署文档、脚本、依赖包都围绕这一套走，不轻易替换。因为每换一个变量，你都要重新验证一遍iServer能不能起、数据源能不能连、出图正不正常。这种验证成本在信创项目里特别高，能省就省。

1.2 为什么普通x86的部署经验直接搬过来会翻车

很多人第一反应是，Linux都差不多嘛，命令一样，路径一样，应该能通用。这个想法非常危险。我列几个真实会翻车的点，你感受一下。

第一个是JDK。SuperMap iServer基于Java，对JDK版本和实现比较敏感。普通环境你装个OpenJDK或者Oracle JDK就完事，但在信创环境，往往要求用国产JDK，比如毕昇、腾讯Kona、龙井、龙芯JDK等。这些JDK虽然都兼容Java规范，但个别版本在特定CPU上对某些类库的实现有差异，可能导致iServer启动时报奇怪的异常，或者运行一段时间后内存回收异常。

第二个是本地库依赖。GIS软件大量使用本地库，比如投影转换、图形渲染、GDAL相关的读写。这些库在x86上通常有预编译好的so文件，但在ARM或者LoongArch上，如果安装包里没有对应架构的版本，就会出现加载失败。表现就是服务能启动，但一旦做某个具体操作，比如坐标转换、栅格切片，就抛UnsatisfiedLinkError。

第三个是字体和编码。这个后面会详细讲，但简单说，普通环境你可能从来没关心过系统字体，因为中文显示一直是正常的。到了精简安装的国产服务器系统上，中文字体库经常是缺的，地图上的标注直接变成方块或者乱码。

提示：不要假设"Linux都一样"。在信创项目里，把每一个环境变量都当成需要重新确认的对象，而不是可以默认继承的常识。

1.3 部署前必须先确认的几件事

动手之前，我习惯做一份部署前检查清单，把不确定的东西提前锁定。这份清单大概包括下面这些内容，你可以直接拿去用。

• CPU架构和操作系统版本：执行uname -m看架构（aarch64、loongarch64、x86_64），cat /etc/os-release看系统发行版和版本号。
• glibc版本：ldd --version，这个直接决定你能不能跑官方预编译的二进制。
• JDK信息：java -version，确认厂商、版本，并把JAVA_HOME记下来。
• 内存与磁盘：free -h和df -h，GIS服务吃内存，缓存吃磁盘，别到部署一半发现空间不够。
• 数据库版本与字符集：达梦、人大金仓的版本，以及建库时的字符集是不是UTF-8。
• 许可类型：是软许可还是硬件加密狗，加密狗在信创平台上的驱动是否到位。
• 网络与端口：iServer默认用8090，数据库、许可服务各占什么端口，防火墙要不要放行。

这里面最容易被忽略的是glibc版本和加密狗驱动。glibc低了，安装包直接跑不起来；加密狗驱动不对，许可能读到硬件但识别不了，服务照样起不来。这两个问题我在项目里都遇到过，下面会细说。

2. 部署前的环境盘点与选型决策

2.1 硬件架构与安装包的对应关系

SuperMap官方针对信创环境会提供不同架构的安装包，这一点必须先搞清楚。你在官网或者服务渠道拿到安装包时，一定要核对包名里或者说明里的架构标识。ARM架构（aarch64）的包不能拿到LoongArch上跑，x86的包也不能拿到ARM上跑。我见过有人图省事，直接把x86的iServer包扔到鲲鹏机器上解压，结果启动脚本里调用的本地库全是x86的so，报错信息还特别隐晦，找了半天才发现是包拿错了。

选型上，我的经验是优先选项目组已经有成功案例的组合。比如某个区域的项目普遍用鲲鹏+麒麟+达梦，那就跟着用，遇到问题也容易找到人问。如果必须用比较新的组合，比如LoongArch平台，那就提前留出验证时间，别等到交付前一周才开始试。

数据库这块同样要对应。达梦、人大金仓、openGauss、GBase这些国产数据库，SuperMap iServer通常通过JDBC驱动连接。你要确认驱动包的版本和数据库版本匹配，并且驱动要放到iServer的lib目录下。驱动版本不对，典型表现是能连上但执行某些空间查询SQL时报错，或者空间数据读出来是乱码。

2.2 中间件、数据库与JDK的取舍逻辑

很多信创项目会要求用国产中间件，比如把iServer部署在东方通TongWeb或者宝兰德BES上运行。这里有个取舍：是把iServer作为独立进程跑（自带内置容器），还是部署成war包放进国产中间件。两种方式各有适用场景。

独立进程方式简单、排查方便，适合大多数GIS服务场景。部署成war包则适合需要和已有Java应用统一管理、统一做会话和安全的场景。我个人的倾向是，除非有硬性要求，否则优先用独立进程方式，因为GIS服务本身对内存和线程的调度有自己的诉求，塞进通用中间件反而容易在性能和排查上增加复杂度。

JDK的选择逻辑类似。优先用SuperMap官方文档里明确验证过的JDK版本和厂商。如果文档没写，就选主流的国产JDK稳定版本，不要一上来就用最新版。JDK这东西，新版本带来新特性，但也可能带来新的兼容问题，GIS平台不一定跟得那么快。

2.3 依赖包的离线准备清单

信创环境很多是内网，不能联网装包，所以依赖必须提前准备齐全。我一般会整理一个离线依赖包目录，包含以下内容。

把这些东西提前拷到内网机器上，能省掉大量来回折腾的时间。尤其是字体和加密狗驱动，缺了它们，服务要么显示不正常，要么根本起不来。

3. iServer与iDesktopX在信创环境的实操部署流程

3.1 系统基础环境的配置动作

部署从系统层面的准备开始。我通常按下面的顺序做。

第一步，创建专用运行用户。不要用root跑iServer，一方面是安全规范，另一方面是用root跑时产生的一些文件权限会很麻烦。命令大致如下。

useradd -m -s /bin/bash gisuser passwd gisuser

第二步，设置locale和时区。中文环境建议设置成UTF-8，否则中文路径、中文数据都可能出问题。

localectl set-locale LANG=zh_CN.UTF-8 timedatectl set-timezone Asia/Shanghai

如果系统里没有zh_CN.UTF-8这个locale，需要先生成：

localedef -i zh_CN -f UTF-8 zh_CN.UTF-8

第三步，安装中文字体。这是信创服务器上极其常见的一个坑。做法是把字体文件拷贝到系统字体目录，然后刷新字体缓存。

mkdir -p /usr/share/fonts/chinese cp simsun.ttc simhei.ttf /usr/share/fonts/chinese/ chmod 644 /usr/share/fonts/chinese/* fc-cache -fv

刷新完成后，用fc-list :lang=zh看一下能不能列出中文字体。如果列不出来，地图标注就会出问题。

第四步，时间同步。GIS服务里很多缓存、切片、日志都依赖时间准确，把chrony配好，指向内网的时间源。

3.2 安装包解压与依赖补齐

环境准备好之后，切换到gisuser用户，解压iServer安装包。假设包名叫supermap_iserver_11i_linux_aarch64.tar.gz，操作如下。

su - gisuser tar -zxvf supermap_iserver_11i_linux_aarch64.tar.gz cd supermap_iserver_11i

解压之后，先别急着启动，检查一下关键目录。通常会有bin、lib、webapps、support这几个目录。bin下面是启动脚本，lib下面放依赖和数据库驱动，support下面可能有一些工具。

接下来把数据库驱动放到lib目录。以达梦为例，把DmJdbcDriver18.jar拷过去。

cp DmJdbcDriver18.jar ./lib/

如果你用的是硬件加密狗，这一步还要装驱动。驱动一般是按架构分的，插上加密狗之后，用厂商提供的检测工具确认系统能不能识别到硬件。识别不到的话，先排查USB或者并口、驱动是否加载、以及是否需要在虚拟机里做USB直通。

关于JVM参数，这一步要提前规划好，别用默认值。默认参数在实际项目里往往偏小，服务一上压力就出问题。我通常会在启动脚本或者配置里显式设置堆内存。

3.3 JVM内存参数怎么算才不吃亏

GIS服务是典型的内存密集型应用，切片、缓存、并发请求都吃内存。给太小，频繁Full GC，服务卡顿；给太大，可能把系统内存挤爆，导致数据库或者系统本身不稳定。我的算法是这样的。

假设单机64GB内存，这台机器上同时跑达梦数据库和iServer。那么先给操作系统和后台进程预留6GB左右，给达梦预留16GB到20GB，剩下的留给iServer。这样iServer大概能分到 64 - 6 - 18 = 40GB 左右。堆内存不建议把可用内存全吃掉，留20%到30%给堆外内存、线程栈、本地库。所以-Xmx大概设到28g到30g比较稳妥。

对应的一组参数大致是这样：

JAVA_OPTS="-Xms28g -Xmx28g -XX:MetaspaceSize=512m -XX:MaxMetaspaceSize=1024m -XX:+UseG1GC"

这里Xms和Xmx设成一样，是为了避免运行期堆反复伸缩带来的抖动。GC算法选G1在大多数场景下比较均衡。如果你的场景是超大内存、超低延迟要求，可以再评估其他收集器。这些参数要写进启动脚本或者专门的环境变量文件里，别临时手敲，容易漏。

注意：改了JVM参数之后，一定要观察一段时间的GC日志。可以在参数里加上-Xlog:gc*:file=gc.log:time之类的选项，把GC情况记录到文件里，出问题时这是最重要的线索之一。

3.4 许可配置与服务启动验证

SuperMap iServer的许可可以走软许可，也可以用硬件加密狗。软许可一般需要在许可中心里激活，信创内网环境通常是离线激活：在一台能联网的机器上生成申请文件，拿到许可文件后拷回内网导入。

软许可的配置大致是把许可文件放到指定目录，或者通过许可服务配置。具体路径和方式依版本略有不同，按你所用版本的部署文档来。这里要强调的是，许可服务的进程要能正常起来，如果许可起不来，iServer启动时会在日志里明确提示许可相关的错误，这时候先别看iServer，先去看许可服务。

一切就绪后启动iServer。

cd bin ./startup.sh

启动之后看日志，日志一般在logs目录下。看到类似"Server startup in xxx ms"这样的输出，基本就是起来了。然后用浏览器或者curl访问一下。

curl http://127.0.0.1:8090/iserver/

能返回页面就说明服务正常。接下来是登录管理页面，配置数据源、发布服务。到这里，部署的主流程就走完了。但真正耗时间的，往往是下面这些"起来了但用不了"的问题。

4. 常见问题排查与避坑经验实录

4.1 启动失败类问题的速查表

服务起不来，是最让人焦虑的场景。我整理了一份常见问题速查表，遇到问题可以先对号入座。

这份表里，我最想强调的是本地库问题和许可问题。本地库问题隐蔽，因为它的报错往往只是一行异常堆栈，不仔细看根本注意不到架构不对。许可问题则是信创项目的高发区，尤其是加密狗，在ARM平台上驱动的成熟度参差不齐，遇到识别不了，先确认驱动版本对不对，再确认硬件本身在别的机器上能不能用。

4.2 中文乱码与地图出图异常的解决

服务起来了，数据也挂了，结果地图上中文标注显示成方块，这是信创环境里出现频率极高的问题，根源就在前面说的字体缺失。解决办法前面已经讲了，补字体、刷缓存。但要补一个细节：iServer有自己的字体配置，有时候系统字体补了，iServer还需要重启，甚至需要在配置里指定字体目录，才能生效。所以补完字体后，重启一次服务再验证。

另一个常见的是"图层放大不显示"。这个问题不一定是环境问题，很多时候是地图文档里的比例尺范围设置导致的——某个图层只在特定比例尺区间显示，超出范围就不画。排查时先看图层属性里的最大最小可见比例尺，再看是不是缓存问题。如果确认是环境相关的显示异常，再去看渲染相关的本地库和字体。

还有在线地图加载的问题。信创内网环境往往不能直接访问公网地图服务，需要提前把底图数据本地化，或者通过内网的地图服务发布。这个不是部署环节能解决的，属于方案设计阶段就要考虑的问题，但部署时经常被翻出来，所以顺便提醒一句。

4.3 迁移交付阶段的实操心得

部署完只是开始，交付阶段还有几件事决定成败。

第一，做一次完整的功能回归。别只看服务起来了就交差，要实际发布一个地图服务，打开看看，做一次空间查询，导出一个图片，把主要功能都过一遍。信创环境里"能启动但某个功能不可用"太常见了。

第二，把依赖和配置固化下来。包括JDK版本、JVM参数、字体、数据库驱动、许可文件，全部整理成一份部署清单和一套可复用的脚本。下次遇到同样的环境组合，直接跑脚本，效率天差地别。

第三，留好日志和排查入口。GC日志、iServer运行日志、数据库日志、系统日志，都确认能正常输出并保留。出问题时，日志就是命根子。

第四，关于性能，别在交付前临时调优。信创平台的性能特征和x86不完全一样，尤其ARM平台上的CPU调度和内存带宽表现，需要在项目前期就做压测。压测时关注并发请求下的响应时间和GC频率，根据结果反推JVM参数和线程配置，而不是拍脑袋。

最后说一个我自己踩过的坑。有一次在统信UOS上部署，服务一切正常，但导出地图图片时中文全部变成方块，查了半天系统字体明明是有的。后来发现是iServer的运行用户和字体缓存权限不匹配——字体是root拷进去的，缓存刷新的记录普通用户读不到。把字体目录权限放开，重新用运行用户刷一遍缓存，问题就没了。这种问题没有任何文档会写，只能靠自己一点点试出来。

我在实际操作中的体会是，信创环境部署SuperMap GIS，拼的不是谁技术多高深，而是谁对环境细节更较真。把每一个依赖、每一项权限、每一个参数都当成需要确认的对象，而不是想当然地继承x86时代的经验，你会发现那些看似诡异的报错，其实都有清晰的因果。这套平台本身是成熟的，难的是让它在一个全新的、碎片化的基础环境里稳稳落地。