脚本上传 SourceMap¶

如果您的 RUM 应用使用的是公网 DataWay 接入方式，那么应用运行数据会直接上报到公网 DataWay；对应的 SourceMap 文件可通过对应站点的 OpenAPI 接口使用脚本上传。

也就是说：

RUM 数据上报时，使用的是应用接入页中的 datawayUrl 和 clientToken；
SourceMap 文件上传时，使用的是站点的 OpenAPI 地址和 OPEN_API_KEY。

本文介绍公网 DataWay 场景下通过脚本上传 SourceMap 的方式。

准备工作¶

确保当前应用已经按对应端的接入文档完成公网 DataWay 初始化；
获取当前站点对应的 OpenAPI 地址；
获取当前站点对应的 OPEN_API_KEY；
- 进入观测云工作空间后，点击管理 > API Key 管理 > 新建 Key；
- 创建成功后，在 API Key 详情页获取 Key，并将其作为脚本中的 DF_API_KEY 使用；
获取目标 RUM 应用的 app_id、env、version；
- app_id 为当前 RUM 应用的唯一标识；
- env、version 需要与 SDK 初始化或实际报错数据中的对应字段保持一致；
- 如未区分环境或版本，可只传 app_id，但命中范围会更宽，排查时不如同时传入 env、version 精确；
按照 SourceMap 配置中的要求，提前打包好 sourcemap.zip。
如使用 Shell 版本，请确保环境中已安装 bash、curl、jq、split、mktemp、wc；
如使用 Python 版本，请确保环境中已安装 python3。

脚本上传¶

脚本上传通过 OpenAPI 完成，适用于公网 DataWay 接入场景下的自动化上传。

脚本说明¶

上传脚本仓库地址：sourcemap-upload-scripts。

当前提供两种上传脚本：

Shell 版本：upload-sourcemap.sh
Python 版本：upload_sourcemap.py

两种脚本都用于上传已经打包完成的 sourcemap.zip 文件，本身不负责生成或压缩 SourceMap。

在执行示例命令前，请先从上述仓库获取对应脚本，并放到当前命令执行目录，或在命令中填写脚本的实际路径。

参数说明¶

必填参数¶

--endpoint：站点对应的 OpenAPI 地址；
--api-key：站点对应的 OPEN_API_KEY，请求时会写入 DF-API-KEY 请求头；
--app-id：RUM 应用的 app_id；
--file：待上传的 sourcemap.zip 文件路径，文件大小不能超过 500 MB。

可选参数¶

--version：应用版本号；
--env：应用环境标识，例如 daily、gray、prod；
--need-cover：是否覆盖同名文件，可选值为 true 或 false，默认 false；
--chunk-size-mb：分片上传大小，单位 MB，默认 10，最大 10；
--merge-path：自定义合并接口路径，仅当当前站点的合并接口路径与脚本默认值不一致时使用；
--cancel-path：自定义取消上传接口路径，仅当当前站点的取消接口路径与脚本默认值不一致时使用。

使用方式¶

Shell 方式¶

sh ./upload-sourcemap.sh \
  --endpoint https://openapi.guance.com \
  --api-key "$DF_API_KEY" \
  --app-id app_id_from_studio \
  --version 1.0.2 \
  --env daily \
  --file ./sourcemap.zip \
  --need-cover true

Python 方式¶

python3 ./upload_sourcemap.py \
  --endpoint https://openapi.guance.com\
  --api-key "$DF_API_KEY" \
  --app-id app_id_from_studio \
  --version 1.0.2 \
  --env daily \
  --file ./sourcemap.zip \
  --need-cover true

预期输出¶

执行成功后，您会看到类似日志：

Init succeeded, uploadId=...
Uploading part x/y
Merge succeeded via /api/v1/rum_sourcemap/part_merge
Upload complete

环境变量方式¶

您也可以通过环境变量传入相同参数：

export DF_OPENAPI_ENDPOINT="https://openapi.guance.com"
export DF_API_KEY="your-api-key"
export DF_APP_ID="app_id_from_studio"
export DF_VERSION="1.0.2"
export DF_ENV="daily"
export DF_SOURCEMAP_FILE="./sourcemap.zip"
export DF_NEED_COVER="true"

其中环境变量与命令行参数的对应关系如下：

DF_OPENAPI_ENDPOINT 对应 --endpoint
DF_API_KEY 对应 --api-key
DF_APP_ID 对应 --app-id
DF_VERSION 对应 --version
DF_ENV 对应 --env
DF_SOURCEMAP_FILE 对应 --file
DF_NEED_COVER 对应 --need-cover

之后执行：

sh ./upload-sourcemap.sh

或者：

python3 ./upload_sourcemap.py

注意事项¶

脚本上传适用于公网 DataWay 接入场景；
上传脚本使用的是 OpenAPI + DF-API-KEY 鉴权方式，而不是 datawayUrl + clientToken；
sourcemap.zip 解压后的目录结构，必须与错误堆栈中的文件路径保持一致；
上传文件必须为 .zip 格式，且文件大小不能超过 500 MB；
若 version 与 env 只填写其中一个，上传目标可能不够精确，建议成对填写；
分片上传单片大小最大为 10 MB；
若上传流程在初始化后失败，脚本会自动尝试取消本次分片上传任务。
Python 版本仅使用 Python 标准库，无需额外安装 pip 依赖。

常见问题¶

`uploadId is empty`¶

通常表示服务端已存在同名 SourceMap，且未开启覆盖。

可重试并添加以下参数：

--need-cover true

`Missing required command`¶

表示 Shell 版本缺少依赖命令。请安装对应工具后重试。

`Merge endpoint ... returned HTTP 404`¶

通常表示当前站点使用了不同的合并接口路径。

可联系对应站点管理员确认接口路径后，重新指定：

--merge-path <your-path>

上传成功但错误堆栈未解析¶

请优先检查以下内容：

app_id、version、env 是否与实际报错数据一致；
sourcemap.zip 解压后的目录结构是否与 error_stack 中的资源路径一致；
当前应用是否确实为需要上传 SourceMap 的目标应用。