符号服务器

了解符号服务器及其如何与你的 Sentry 项目配置。

Sentry 可以从外部存储库下载调试信息文件。这使你可以停止上传调试文件，而是配置一个公共符号服务器或运行你自己的符号服务器。也可以同时配置外部存储库并上传调试文件。

要配置外部存储库，请进入 项目设置 > 调试文件。在已上传文件列表上方，有两个设置用于配置外部存储库：

自定义存储库（Custom Repositories）: 配置包含调试文件的自定义存储库。你可以选择配置 HTTP 符号服务器、Amazon S3 存储桶或 Google Cloud Storage 存储桶。这需要 Business 或 Enterprise 计划。
内置存储库（Built-In Repositories）: 允许从预配置的符号服务器列表中选择。默认情况下，在 SaaS 中启用了 iOS 和 Microsoft。由于 Apple 不提供公共符号服务器，也不允许我们分发调试信息文件（DIFs），因此 iOS 存储库在自托管环境中不可用。

Sentry 按照配置的顺序查询外部存储库以获取调试信息文件。如果配置了自定义存储库，则会首先查询这些存储库。只有在自定义存储库中未找到的调试信息文件才会从内置存储库中查询。

要启用内置存储库，请从下拉列表中选择它。这会立即添加存储库，并使用其调试信息文件对新的崩溃报告进行符号化。同样，点击名称旁边的 X 即可禁用任何内置存储库。

添加或移除外部存储库会立即生效。因此，事件可能会因新信息而不同地分组，并创建新的问题。请注意，这可能会触发发送给团队成员的通知。

注意

自定义存储库适用于处于 Business 和 Enterprise 计划的组织。

无论内部格式如何，Sentry 支持三种类型的自定义存储库：

HTTP 符号服务器：一个在可配置路径上提供调试文件的 HTTP 服务器。服务器中的查找通常应不区分大小写，尽管可以在设置中配置明确的大小写。请注意，Sentry 要求从自定义 HTTP 符号服务器下载 DIF 的最小下载速度为 4Mb/s。
Amazon S3 存储桶：可以是整个 S3 存储桶或子目录。这需要为配置的访问密钥授予 s3:GetObject 权限，并可选地授予 s3:ListBucket 权限。存储桶中的查找是区分大小写的，因此我们建议将所有文件以小写形式存储，并使用小写路径配置。
Google Cloud Storage 存储桶：可以是整个 GCS 存储桶或子目录。这需要为配置的服务账户授予 storage.objects.get 和 storage.objects.list 权限。存储桶中的查找是区分大小写的，因此我们建议将所有文件以小写形式存储。

除了身份验证配置外，所有类型都有共同的配置参数：

名称（Name）：用于标识存储库的名称。
路径大小写（Path Casing）：覆盖 Sentry 查询调试信息文件时使用的大小写。默认是混合大小写，将使用下一节中描述的大小写。当被覆盖时，所有访问要么是小写，要么是大写，默认为 "混合大小写"。
目录布局（Directory Layout）：存储桶的内部结构或符号服务器的协议。有三种布局可供选择，将在下一节中讨论，默认为 "平台特定"。

Sentry 支持从外部来源下载调试信息文件时使用以下压缩方法：Gzip、zlib（带或不带头）、Zstandard 和 Cabinet (CAB)。

在 Microsoft 的符号服务器协议中，惯例是将这些文件的扩展名最后一个字符替换为 _。一个完整的示例是：KERNEL32.dll/590285E9e0000/KERNEL32.dl_。在你自己的存储库中这不是必需的，因为 Sentry 会在所有路径上检测压缩。

从 NuGet 符号服务器下载 Portable PDB 需要通过 SymbolChecksum 头提供调试校验和。

Sentry 支持多种外部存储库布局。根据所选布局和文件类型，我们尝试从特定路径下载文件。

下表包含支持的布局与特定文件路径模式的映射：

布局	Mach-O	ELF	PE	PDB	PPDB	Breakpad	WASM
平台特定	LLDB	BuildID	SymStore	SymStore	SymStore	Breakpad	BuildID
Microsoft SymStore	-	-	SymStore	SymStore	SymStore	-	-
Microsoft SymStore (index2.txt)	-	-	Index2	Index2	Index2	-	-
Microsoft SSQP	SSQP	SSQP	SSQP	SSQP	SSQP	-	-
NuGet	-	-	-	-	SymStore	-	-
Debuginfod	-	Debuginfod	-	-	-	-	-
统一布局	Unified	Unified	Unified	Unified	Unified	Unified	Unified

上表中的路径模式定义如下：

路径：<DebugName>/<BREAKPADid>/<SymName>

Breakpad 始终使用 Breakpad ID 来存储符号。这些标识符可以从 调试标识符 计算得出，方法是移除破折号并应用以下大小写规则：

标识符的签名部分（前 32 个字符）为大写。
标识符的年龄部分（剩余字符）为小写。

符号文件的名称取决于平台。在 Windows 上，文件扩展名（如 .exe、.dll 或 .pdb）会被替换为 .sym。在所有其他平台上，.sym 扩展名会附加到完整文件名（包括可能的扩展名）。

示例：

wkernel32.pdb/FF9F9F7841DB88F0CDEDA9E1E9BFF3B51/wkernel32.sym
MyFramework.dylib/5E012A646CC536F19B4DA0564049169B/MyFramework.dylib.sym

路径：XXXX/XXXX/XXXX/XXXX/XXXX/XXXXXXXXXXXX[.app]

macOS 上的 LLDB 调试器可以从 File Mapped UUID 目录中读取调试符号。UUID 的前 20 个十六进制数字被分成 4 个字符的块，每个块创建一个目录。在最终目录中，LLDB 通常期望有一个由最后 12 个十六进制数字命名的符号链接，它会跟随该链接到实际的 dSYM 文件。

这实际上不是 LLVM 的特性。这是 CoreFoundation 的特性，并且仅在 macOS 上通过 Spotlight 实现。Spotlight 索引这些路径，私有 API DBGCopyFullDSYMURLForUUID 被 lldb 用于定位符号。macOS 使用这些位置的符号链接。

由于可执行文件或库与 dSYM 文件共享相同的 UUID，前者通过添加 .app 后缀来区分。

十六进制数字为大写，应用程序后缀为小写。

示例：

5E01/2A64/6CC5/36F1/9B4D/A0564049169B（调试伴随文件）
5E01/2A64/6CC5/36F1/9B4D/A0564049169B.app（可执行文件或库）

路径：nn/nnnnnnnnnnnnnnnn...[.debug]

GDB 支持多种查找方法，具体取决于调试信息文件的指定方式。Sentry 使用 [Build ID 方法]：假设 GNU 构建 ID 注释或部分已写入 ELF 文件，这指定了一个可执行文件的唯一标识符，并且该标识符也保留在调试文件中。

GNU 构建 ID 是一个变长的二进制字符串，通常由 20 字节的 SHA1 哈希（代码段 .text）组成。查找路径是 pp/nnnnnnnn.debug，其中 pp 是构建 ID 位字符串的前 2 个十六进制字符，nnnnnnnn 是其余的十六进制字符串。对于可执行文件的查找，省略 .debug 后缀。

示例：

b5/381a457906d279073822a5ceb24c4bfef94ddb（可执行文件或库）
b5/381a457906d279073822a5ceb24c4bfef94ddb.debug（剥离的调试文件）

路径：nn/nnnnnnnnnnnnnnnn.../type

统一路径布局是 Sentry 特有的，它为所有调试文件提供了一个独立于平台的一致结构。它可以存储 Breakpad 文件、PDB、PE 和其他所有文件。symsorter 工具可以自动将调试符号分类为这种格式，并自动生成源代码包。

路径基于使用小写字母格式化的 build_id。取该 ID 的前两个字节作为根文件夹。

不同文件格式的 build_id 构造方式有所不同：

PE: <Signature><Age>（年龄为十六进制，不补零）
PDB: <Signature><Age>（年龄为十六进制，不补零）
Portable PDB: <Signature><Age>（年龄为十六进制，不补零）
ELF: gnu-build-id 代码注释字节序列
Mach-O: LC_UUID 字节
WASM: build_id 部分的字节

示例：

b5/381a457906d279073822a5ceb24c4bfef94ddb/executable（可执行文件或库）
b5/381a457906d279073822a5ceb24c4bfef94ddb/debuginfo（调试文件）
b5/381a457906d279073822a5ceb24c4bfef94ddb/breakpad（Breakpad 文件）
b5/381a457906d279073822a5ceb24c4bfef94ddb/sourcebundle（源代码包）

路径：<file_name>/<prefix>-<identifier>/<file_name>

SSQP 密钥约定是对原始 Microsoft 符号服务器协议的扩展，专用于 .NET。它指定了 PE、PDB、Mach-O 和 ELF 文件的查找路径。所有查找路径的大小写通常为小写，但 PDB 标识符的年龄字段应为大写。

对于 Mach-O 文件和 ELF 文件，SSQP 规定使用 LLDB 和 GNU 构建 ID 方法中使用的相同标识符。更多信息请参阅上述部分。这导致了以下所有可能文件类型的路径：

<code_name>/<timestamp><size_of_image>/<code_name>（PE 文件）
<debug_name>/<signature><AGE>/<debug_name>（PDB 文件）
<debug_name>/<signature>FFFFFFFF/<debug_name>（Portable PDB 文件）
<code_name>/elf-buildid-<buildid>/<code_name>（ELF 二进制文件）
_.debug/elf-buildid-sym-<buildid>/_.debug（ELF 调试文件）
<code_name>/mach-uuid-<uuid>/<code_name>（Mach-O 二进制文件）
_.dwarf/mach-uuid-sym-<uuid>/_.dwarf（Mach-O 二进制文件）

SSQP 还规定了一种通过文件内容的 SHA1 校验和进行查找的附加方法，通常用于源文件查找。Sentry 不支持此查找方法。

示例：

wkernel32.pdb/ff9f9f7841db88f0cdeda9e1e9bff3b5A/wkernel32.pdb
kernel32.dll/590285e9e0000/kernel32.dll
libc-2.23.so/elf-buildid-b5381a457906d279073822a5ceb24c4bfef94ddb/libc-2.23.so
_.debug/elf-buildid-sym-b5381a457906d279073822a5ceb24c4bfef94ddb/_.debug
CoreFoundation/mach-uuid-36385a3a60d332dbbf55c6d8931a7aa6/CoreFoundation
_.dwarf/mach-uuid-sym-36385a3a60d332dbbf55c6d8931a7aa6/_.dwarf

路径：<FileName>/<SIGNATURE><AGE>/<FileName>（对于 Portable PDB 为 <FileName>/<SIGNATURE>FFFFFFFF/<FileName>）

Microsoft 提供的公共符号服务器以前只托管 Windows 平台的 PDB 文件。这些文件使用 签名-年龄 调试标识符和文件名来定位符号。文件路径与 SSQP 相同，但默认大小写规则有所不同：

文件名保持原样。
PDB 标识符的签名部分为大写，年龄部分为小写。
PE 标识符的时间戳为大写，大小为小写。

由于原始的 Microsoft 符号服务器不提供 ELF 或 Mach-O 文件，我们不建议对这些类型使用此约定。然而，当选择此布局时，Sentry 将支持带有调整后大小写规则的 SSQP 约定。

示例：

wkernel32.pdb/FF9F9F7841DB88F0CDEDA9E1E9BFF3B5A/wkernel32.pdb
KERNEL32.dll/590285E9e0000/KERNEL32.dll

路径：<Fi>/<FileName>/<SIGNATURE><AGE>/<FileName>（对于 Portable PDB 为 <Fi>/<FileName>/<SIGNATURE>FFFFFFFF/<FileName>）

此布局与 SymStore 相同，唯一的区别是文件名的前两个字符作为附加文件夹添加到路径中。

示例：

wk/wkernel32.pdb/FF9F9F7841DB88F0CDEDA9E1E9BFF3B5A/wkernel32.pdb
KE/KERNEL32.dll/590285E9e0000/KERNEL32.dll

路径：<build id>/<type>

Debuginfod 仅支持 ELF 二进制文件和 DWARF 调试文件。

<build id> 是 gnu-build-id 代码注释字节序列，与统一路径模式中的 ELF 情况相同。

注意：文件需要存放在服务器的 buildid/ 目录下。

示例：

69389d485a9793dbe873f0ea2c93e02efaa9aa3d/executable（可执行文件或库）
69389d485a9793dbe873f0ea2c93e02efaa9aa3d/debuginfo（调试文件）

上传文件

源代码上下文