移动平台

# 高德地图服务替换工具操作文档

# 一、先判断版本

使用工具前，先确认客户 OA 版本。不同版本走不同页签，不要混用。

客户 OA 版本 使用页签 配置来源 说明
V8.2SP1 以下 替换高德服务KEY数据 客户自行在高德开放平台申请或购买的 Key、密钥 低版本不走本次地图代理方案，只替换客户自己的高德 Key 和安全密钥。
V8.2SP1 及以上 替换高德服务代理配置 本次补丁包要求的代理安全配置 这些版本走地图代理服务，不再让页面直接使用客户自购高德 Key。

重点说明：

  • V8.2SP1 以下客户：只能替换高德 Key。Web 端 Key、Web 服务 Key、安全密钥 都由客户自行在高德侧申请或购买。
  • V8.2SP1 及以上客户：使用代理方案，只处理代理配置，不需要在页面中替换成客户自购高德 Key。
  • 目标目录统一选择 ApacheJetspeed\webapps，不要选择整个 ApacheJetspeed 根目录。

# 二、工具包说明

工具目录位于补丁包根目录下：

高德地图服务替换工具

请保持目录结构完整：

高德地图服务替换工具/
├─ amap-key-replace-tool.jar
├─ 启动工具.bat
├─ 启动工具.sh
└─ runtime/
   └─ bin/
      └─ java.exe

说明：

  • Windows 可直接使用 启动工具.bat，工具包内已带 Windows Java。
  • Linux 不能使用 runtime/bin/java.exe，需要使用服务器上的 JDK。
  • 该工具是图形界面工具，Linux 纯命令行环境无法直接打开窗口。

# 三、启动工具

# 3.1 Windows 启动

进入：

高德地图服务替换工具

双击：

启动工具.bat

如果双击没有反应，在该目录打开命令行执行：

启动工具.bat

# 3.2 Linux 启动

Linux 启动时使用服务器 JDK。A8 安装包的 ApacheJetspeed 目录下通常自带 JDK，可优先使用。

先查找可用 Java：

find /实际路径/ApacheJetspeed -path "*/bin/java" -type f 2>/dev/null

常见路径示例：

/Seeyon/ApacheJetspeed/jdk/bin/java
/Seeyon/ApacheJetspeed/jdk/jre/bin/java

进入工具目录后启动：

cd /实际路径/高德地图服务替换工具
/Seeyon/ApacheJetspeed/jdk/bin/java -jar amap-key-replace-tool.jar

如果使用 MobaXterm 远程打开图形窗口，需要确认：

echo $DISPLAY

正常应输出类似：

localhost:10.0

1781492609101.png

如果客户 Linux 没有可视化环境，也不允许 X11 转发，推荐把 ApacheJetspeed/webapps 下载到 Windows，使用 Windows 工具处理后再上传回服务器相同目录。

# 四、选择目标目录

点击工具中的 浏览 后，目标目录选择：

ApacheJetspeed\webapps

Windows 示例：

D:ApacheJetspeed\webapps

Linux 下载到 Windows 后的示例：

D:\现场文件\ApacheJetspeed\webapps

不要选择：

ApacheJetspeed

原因是工具会递归扫描目标目录。选择整个 ApacheJetspeed 会扫描日志、临时目录、配置目录等无关文件，耗时更长，也更容易误选文件。

# 五、替换高德地图 KEY 数据

只需要替换key的客户使用 替换高德地图key数据 选项。

操作步骤：

  1. 打开工具。
  2. 选择 替换高德地图key数据 选项。
  3. 点击进入。
  4. 点击 浏览，选择 ApacheJetspeed\webapps。
  5. 填写客户自行申请或购买的 Web 端 Key。
  6. 填写客户自行申请或购买的 Web 服务 Key。
  7. 填写客户自行申请或购买的 私钥。
  8. 点击 开始扫描。
  9. 在列表中确认扫描出的文件。
  10. 勾选需要替换的文件。
  11. 点击 开始替换。
  12. 查看工具日志，确认替换成功。

字段说明：

字段 说明
Web 端 Key 高德 JS API 使用的 Web 端 Key。
Web 服务 Key 高德 Web 服务接口使用的 Key。
私钥 高德地图申请的服务key 私钥。

注意：

  • 这三个值不是补丁包提供的，由客户自行在高德开放平台申请或购买。
  • 如果客户没有提供完整的 Key 和密钥，不要执行替换。
  • 扫描结果为空时，优先确认目标目录是否选成了 ApacheJetspeed\webapps。

# 六、替换高德地图服务代理配置

V8.2SP1 及以上客户使用 替换高德服务代理配置 页签。

操作步骤：

  1. 打开工具。
  2. 选择 替换高德地图服务代理配置 选项。
  3. 点击进入。
  4. 点击 浏览，选择 ApacheJetspeed\webapps。
  5. 点击 开始扫描。
  6. 在列表中确认扫描出的文件。
  7. 勾选需要替换的文件。
  8. 点击 开始替换。
  9. 查看工具日志，确认替换成功。

注意：

  • 该版本段走地图代理服务，不要使用 替换高德服务KEY数据 页签把页面改成客户自购 Key。
  • 如果现场已安装补丁包，替换后需要确保处理后的 webapps 文件覆盖回现场对应目录。

# 七、备份与还原

工具替换前会在目标目录下自动创建备份目录：

back_yyyyMMdd_HHmmss

例如：

back_20260615_153000

替换完成后会在目标目录下生成结果文件，文件名类似：

高德地图定位服务key替换结果_yyyyMMdd_HHmmss.xlsx

如果替换不符合预期，可使用：

  • 还原当前勾选文件
  • 一键还原所有文件

替换验证完成前，不要删除 back_yyyyMMdd_HHmmss 备份目录。

# 八、执行后检查

替换完成后检查以下内容：

  1. 工具日志中没有失败记录。
  2. Excel 结果文件中替换前后内容符合预期。
  3. 抽查 ApacheJetspeed\webapps 下被替换的文件，确认值已经更新。
  4. 如果是在 Windows 离线处理，把处理后的 webapps 内容上传回服务器相同目录。
  5. 重启或清理缓存后重新进入地图相关页面验证。

# 九、Linux 常见问题

# 9.1 java: command not found

说明当前 shell 找不到 Java。使用 A8 安装目录中的 Java：

find /实际路径/ApacheJetspeed -path "*/bin/java" -type f 2>/dev/null

然后使用完整路径启动：

/Seeyon/ApacheJetspeed/jdk/bin/java -jar amap-key-replace-tool.jar

# 9.2 runtime/bin/java 不存在

说明工具包内置的是 Windows Java。Linux 不使用 runtime/bin/java，直接使用服务器 JDK：

/Seeyon/ApacheJetspeed/jdk/bin/java -jar amap-key-replace-tool.jar

# 9.3 No X11 DISPLAY variable was set

说明当前 Linux 会话不能打开图形窗口。使用 MobaXterm 时：

  1. 开启 MobaXterm 右上角 X server。
  2. SSH 会话勾选 Advanced SSH settings -> X11-Forwarding。
  3. 重新登录服务器。
  4. 执行：
echo $DISPLAY

正常应有：

localhost:10.0

如果仍为空，检查：

grep -i X11Forwarding /etc/ssh/sshd_config

需要存在：

X11Forwarding yes

# 9.4 缺少 xauth

如果：

which xauth

提示没有 xauth，安装：

yum install -y xorg-x11-xauth

安装后重新登录 SSH。

# 9.5 缺少 libXrender.so.1

说明服务器缺少 Java 图形界面依赖库，安装：

yum install -y libXrender libXtst libXi libXext fontconfig freetype

如果是在容器内执行，依赖要安装到容器内部。

# 9.6 中文显示为方块

说明服务器缺少中文字体，安装字体并刷新缓存：

yum install -y fontconfig freetype
yum install -y wqy-microhei-fonts wqy-zenhei-fonts
fc-cache -fv

如果没有 wqy-* 字体包，可安装系统可用的 CJK 字体包。

# 9.7 客户服务器完全没有可视化能力

当前工具不是纯命令行工具，不能在无图形 Linux 中直接交互运行。

处理方式：

  1. 从服务器下载 ApacheJetspeed/webapps。
  2. 在 Windows 电脑上运行工具。
  3. 目标目录选择下载后的 ApacheJetspeed\webapps。
  4. 完成替换和检查。
  5. 上传覆盖服务器对应目录。

这种方式是推荐方案，因为工具处理的是静态文件，不要求必须在 OA 服务器上执行。

# 十、常见操作错误

错误操作 正确做法
V8.2SP1 以下客户使用代理配置页签 使用 替换高德服务KEY数据，并填写客户自购 Key 和密钥。
目标目录选择整个 ApacheJetspeed 目标目录选择 ApacheJetspeed\webapps。
Linux 直接执行 ./runtime/bin/java 使用 A8 安装目录或服务器 JDK 的 bin/java。
无图形 Linux 强行运行工具 下载 webapps 到 Windows 处理后上传。
编撰人：tanghu、mashan

快速跳转

←