# 高德地图向下兼容补丁包部署前配置操作文档

# 操作总览

当前补丁包为一个通用补丁包，覆盖 V8.2SP1 到 10.0SP1 系列环境。补丁包安装后，地图插件会在 OA 启动时自动完成以下事项：

创建或复用三方互信账号“高德地图API代理服务”。
自动补齐地图代理 REST 接口授权。
自动写入 _AMapService 代理配置中的 mapservice.channel-id 和 mapservice.channel-secret。
自动追加“系统定位服务设置”菜单，并删除旧的 M3“定位服务设置”菜单。
自动恢复本地扣减运行态，并注册运行态同步、订单维护、流量预警 Quartz。

现场部署前只需要确认代理配置文件中的 OA 地址和连接池等级，然后重启 OA/Tomcat。

# 一、修改代理配置

配置文件位置：

ApacheJetspeed/webapps/_AMapService/WEB-INF/classes/amap-gateway.properties

重点确认以下两项：

# OA 和 _AMapService 同机部署时使用 127.0.0.1。
# 只填写协议、IP 和 OA 实际 HTTP 端口，不要带 /seeyon。
mapservice.base-url=http://127.0.0.1:OA实际HTTP端口

# 连接池等级。不确定时使用 high；高并发客户可调整为 large。
mapservice.oapi.http.pool-level=high

示例：如果现场 OA 访问地址是：

http://10.2.178.15:80/seeyon

则配置为：

mapservice.base-url=http://127.0.0.1:80

mapservice.channel-id 和 mapservice.channel-secret 不需要手工填写。首次重启 OA 后会自动写入。

连接池等级说明：

等级	单路由最大连接数	总最大连接数	建议场景
`standard`	50	100	小客户、低并发。
`high`	150	300	推荐默认值，适合大多数客户。
`large`	300	600	大客户或地图调用并发较高。
`stress`	800	1600	压测或专项保障，不建议长期默认使用。

集群环境要求：

每个节点都要修改本节点 _AMapService 下的 amap-gateway.properties。
每个节点的 mapservice.base-url 建议都配置为本机 OA 地址，例如 http://127.0.0.1:80。
集群各节点 OA/代理服务端口建议保持一致，避免三方互信回调在不同节点表现不一致。

# 二、安装补丁并重启

使用补丁安装工具安装当前通用补丁包。
确认上一步的 amap-gateway.properties 已配置正确。
重启 OA/Tomcat。

重启后地图插件会自动完成：

三方互信账号创建或复用。
V8.2SP1 老机制 dataSynchronizationAccessInfo.properties 授权补齐，或高版本 dataSynchronizationInterfaces.txt + ctp_rest_access 授权补齐。
REST 资源组授权补齐。
channel-id / channel-secret 写入代理配置。
系统定位服务菜单调整。
本地扣减副本恢复和 Quartz 注册。

不需要手工创建三方互信，不需要手工执行 SQL，不需要手工修改 dataSynchronizationInterfaces.txt 或 dataSynchronizationAccessInfo.properties。

# 三、检查并修正三方互信回调地址

补丁首次重启后，系统会自动创建或复用三方互信账号“高德地图API代理服务”。当前补丁代码创建账号时的默认回调地址为：

http://127.0.0.1/_AMapService/_callback/channel-token

该地址等价于访问本机 80 端口。若现场 Tomcat/OA 的实际 HTTP 端口不是 80，例如 8081、8080、8088，必须在 OA 后台把该三方互信账号的“回调地址”改成带真实端口的地址。

# 3.1 确认 OA/Tomcat 实际 HTTP 端口

查看 Tomcat 配置文件：

ApacheJetspeed/conf/server.xml

找到 HTTP Connector：

<Connector port="8081" protocol="HTTP/1.1" ... />

这里的 8081 才是 OA/Tomcat 的 HTTP 服务端口。

注意不要填错以下端口：

配置项	示例	是否填写到回调地址	说明
`Server port`	`8105`	否	Tomcat shutdown 端口，不是访问端口。
`Connector protocol="HTTP/1.1"`	`8081`	是	OA/Tomcat HTTP 访问端口。
`Connector protocol="AJP/1.3"`	`8009`	否	AJP 转发端口，不是浏览器访问端口。
Nginx/负载均衡外部端口	`80` / `443`	看部署方式	同机回调优先填 OA 本机可访问的 Tomcat HTTP 端口。

# 3.2 修改三方互信回调地址

进入 OA 后台：

系统管理员登录
信息集成配置
三方互信访问授权
授权设置
选择“高德地图API代理服务”
点击“修改”

将“回调地址”修改为：

http://127.0.0.1:OA实际HTTP端口/_AMapService/_callback/channel-token

示例：如果 server.xml 中 HTTP Connector 是 8081，则填写：

http://127.0.0.1:8081/_AMapService/_callback/channel-token

如果现场 HTTP Connector 是 80，以下两种写法等价，但建议也显式写端口，便于排查：

http://127.0.0.1:80/_AMapService/_callback/channel-token

同机部署时，其它字段建议保持：

校验IP：勾选
绑定IP：127.0.0.1
状态：启用

保存后再进行地图功能验证。

# 3.3 与代理配置保持一致

amap-gateway.properties 中的 mapservice.base-url 和三方互信页面的“回调地址”必须使用同一套本机协议、IP、端口。

例如现场 Tomcat HTTP 端口为 8081 时，应保持一致：

mapservice.base-url=http://127.0.0.1:8081

三方互信回调地址=http://127.0.0.1:8081/_AMapService/_callback/channel-token

不要出现以下配置不一致的情况：

mapservice.base-url=http://127.0.0.1:8081

三方互信回调地址=http://127.0.0.1/_AMapService/_callback/channel-token

上面第二行没有端口，实际会访问 127.0.0.1:80，在 Tomcat 只监听 8081 时会导致 channel token 回调失败。

# 四、启动日志检查

重启后查看 OA 日志，优先搜索统一关键字：

AMAP_PATCH_STARTUP

Linux 示例：

grep -n "AMAP_PATCH_STARTUP" ApacheJetspeed/logs/ctp.log

如果日志按日期或大小滚动，扩大到日志目录搜索：

grep -R -n "AMAP_PATCH_STARTUP" ApacheJetspeed/logs

正常情况下，应能看到以下启动检查日志。SUCCESS_EXISTING、SUCCESS_DUPLICATED 表示任务已存在或重复注册被幂等处理，也属于正常。

模块	关键日志	正常状态	说明
菜单 metadata	`module=mapservice-menu stage=finish`	`SUCCESS`	自动追加“系统定位服务设置”并删除旧 M3 定位菜单。
三方互信	`module=mapservice-channel stage=finish`	`SUCCESS`	创建或复用三方互信账号，并写入代理配置。
授权机制	`module=mapservice-channel stage=access-mode`	`mode=LEGACY` 或 `mode=MODERN`	`LEGACY` 表示旧 properties 机制，`MODERN` 表示高版本 ctp_rest_access 机制。
代理配置写入	`module=mapservice-channel stage=gateway-config`	`SUCCESS`	确认 `channel-id` / `channel-secret` 已同步到 `_AMapService` 配置。
REST 资源授权	`module=mapservice-rest-auth stage=finish`	`SUCCESS`	低版本 REST 资源组和三方互信资源授权补齐。
地图配置启动	`module=mapservice-config stage=finish`	`SUCCESS`	原 M3 配置迁移、License 初始化等启动流程完成。
流量预警 Quartz	`module=mapservice-warning stage=finish`	`SUCCESS` / `SUCCESS_DUPLICATED`	注册每天 9 点流量预警任务。
本地扣减装配	`module=flowmanagement-license stage=finish`	`SUCCESS`	本地扣减运行态恢复和后台任务装配完成。
四副本恢复	`module=license-restore stage=finish`	`SUCCESS`	启动时完成运行态副本恢复，集群环境会走锁保护。
运行态同步 Quartz	`module=license-runtime-sync stage=finish`	`SUCCESS` / `SUCCESS_EXISTING`	注册四副本同步任务。
订单维护 Quartz	`module=license-order-maintenance stage=finish`	`SUCCESS` / `SUCCESS_EXISTING`	注册云联订单/免费订单维护任务。

重点确认以下几类日志：

AMAP_PATCH_STARTUP module=mapservice-channel stage=finish status=SUCCESS
AMAP_PATCH_STARTUP module=mapservice-config stage=finish status=SUCCESS
AMAP_PATCH_STARTUP module=flowmanagement-license stage=finish status=SUCCESS

如果某个模块出现 FAILED、PARTIAL_FAILED、FAILED_FALLBACK_LEGACY，继续查看同一行的 reason=，再结合该行前后的完整异常栈定位。

# 五、功能验证

登录 OA 后台，确认菜单中存在“系统定位服务设置”。
打开“系统定位服务设置”，保存 A 模式或 B 模式配置。
触发一次真实地图定位，确认请求地址走 _AMapService。
查看代理日志。

代理日志默认目录：

ApacheJetspeed/temp/_AMapService/logs

如果现场配置了 JVM 参数 -Damap.log.home，则查看该参数指定的目录。

常用日志文件：

amap-network.log
amap-exception.log

# 六、常见问题定位

现象 / 启动日志	优先检查项
`module=mapservice-channel stage=finish status=FAILED`	三方互信账号创建失败。检查 OA 三方互信相关表是否可写、`systemChannelManager` 是否正常装配。
`module=mapservice-channel stage=gateway-config status=FAILED`	`_AMapService/WEB-INF/classes/amap-gateway.properties` 不存在或无写权限；确认补丁目录和文件权限。
`module=mapservice-channel stage=access-modern status=FAILED_FALLBACK_LEGACY`	高版本授权写入失败并回退旧机制。检查 `dataSynchronizationInterfaces.txt`、`ctp_rest_access` 表、相关权限和完整异常栈。
`module=mapservice-channel stage=access-legacy status=FAILED`	旧版本授权文件写入失败。检查 `ApacheJetspeed/webapps/seeyon/WEB-INF/cfgHome/base/dataSynchronizationAccessInfo.properties` 所在目录权限。
`module=mapservice-rest-auth stage=authorize status=SKIPPED reason=NO_CHANNEL`	没读取到三方互信 channelId。优先看 `mapservice-channel` 是否成功，以及授权映射是否写入。
`module=mapservice-menu stage=finish status=PARTIAL_FAILED`	菜单 metadata 部分文件调整失败。查看失败文件路径和异常栈，重点检查 XML 格式和文件权限。
后台没有“系统定位服务设置”菜单	搜索 `module=mapservice-menu`；如果 metadata 文件缺失较多，确认现场版本目录结构是否和补丁适配范围一致。
`module=mapservice-config stage=license-init status=FAILED`	A 模式 License 初始化失败。继续搜索 `module=flowmanagement-license`、`module=license-restore` 和完整异常栈。
`module=flowmanagement-license stage=finish status=FAILED`	本地扣减启动装配失败。重点看四副本恢复、订单维护、Quartz 注册相关异常。
`module=license-restore stage=finish status=FAILED`	运行态四副本恢复失败。检查数据库副本、文件副本目录权限、副本是否不一致。
`module=license-runtime-sync stage=finish status=SKIPPED reason=GATE_NOT_READY`	License 门禁未 READY，运行态同步任务不会注册。继续看 `license-restore` 是否失败或 A 模式是否尚未初始化。
`module=license-order-maintenance stage=finish status=SKIPPED reason=GATE_BLOCKED`	订单维护被门禁阻断。先处理 License 恢复/初始化问题。
页面一直转圈或提示缺少代理会话	OA 日志中是否出现 `mapservice-channel status=SUCCESS`；`amap-gateway.properties` 中 `channel-id/secret` 是否已自动写入。
返回“接口访问未授权”	三方互信自动初始化是否成功；确认 `mapservice-channel`、`mapservice-rest-auth` 都是正常状态。
channel token 回调超时	`mapservice.base-url` 的端口是否正确；从 OA 服务器本机访问 `_AMapService/_callback/channel-token` 是否可达。
代理访问 OA 失败	`mapservice.base-url` 是否只填写到端口，且不要带 `/seeyon`。
地图定位仍未走代理	确认补丁包已覆盖 `_AMapService` 和微协同中转页面；清理移动端/H5 缓存后重新进入页面。

编撰人：het

快速跳转

高德地图向下兼容补丁包部署前配置操作文档

← 音视频服务部署维护手册 (最新)Puppeteer打印部署手册 →