下文介绍了如何排查在配置 Google Cloud Directory Sync (GCDS) 时可能遇到的问题。
设置和配置 | 模拟和同步 | 错误 | 用户和群组 | 联系人和日历 | 规则
试用日志分析器
此工具在您提交日志后的一段时间内即可确定大部分问题。
- 将您的轨迹日志（采用未压缩文件或 ZIP 文件形式）提交至您的 Google 管理员工具箱日志分析器中。
- 如您需要日志高级分析数据，请将未压缩的文件提交至日志分析器 2 中。
详细了解如何启用跟踪记录级别的日志记录。
设置和配置
使用配置管理器排查配置问题如果您遇到问题，无法正常运行同步，请确认配置管理器中的配置信息正确无误，并注意失败的测试：
- 在配置管理器中，打开您用来配置同步的 XML 文件。
- 点击 LDAP 连接页面上的测试连接，以确认您可以连接到 LDAP 服务器。
- 点击通知页面上的测试通知，以确认您可以发送测试通知。
- 点击同步页面上的模拟同步，以确认您已填写所有必填字段并确认同步正常运行。
在极少数情况下，除了在 GCDS 中启用跟踪级别的日志记录外，Google Cloud 支持团队还可能要求您启用完整的 HTTP 日志记录。完整的 HTTP 日志记录可用于查看 GCDS 发出的确切 API 请求以及 Google API 提供的回复。
重要提示：完整的 HTTP 日志可能包含高度敏感信息。请先移除所有敏感信息（例如当前的 refresh_token 或 access_token 字段），然后再将日志发送给支持团队。
要启用完整的 HTTP 日志记录，请执行以下操作：
- 确保 GCDS 既没有使用 sync-cmd 也没有使用配置管理器运行。
- 转到 GCDS 安装文件夹。
-
修改文件 jre/lib/logging.properties。
- 将以下代码行添加到文件末尾：
java.util.logging.FileHandler.pattern = %h/gcdshttp%u.%g.log
java.util.logging.FileHandler.limit = 5000000
java.util.logging.FileHandler.count = 100
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
handlers = java.util.logging.FileHandler
com.google.api.client.http.level = CONFIG
com.google.gdata.client.http.HttpGDataRequest.level = ALL
sun.net.www.protocol.http.HttpURLConnection.level = ALL - 保存文件。
- 再次运行 GCDS 同步（将日志记录设为跟踪）。
系统会在 homedir (Linux) 或配置文件所属文件夹 (Microsoft Windows) 中创建名为 gcdshttp*.log 的日志文件。这些文件可能比较大，请将它们一起归档。
- 删除第 4 步中添加的代码行，以防止系统在日后创建大型日志文件。
接下来，向支持人员提供以下文件：
- 所用的 XML 文件。
- 最新一次同步的跟踪级别日志。
-
同步生成的 gcdshttp*.log 文件。
借助这些日志，支持人员可以看到 Directory API 向 GCDS 提供的信息以及 GCDS 是如何回复的。
所记录的请求和回复的文件大小均不得超过 16 KB。如果您看到日志条目被截断，这是因为它超出了该上限。请按如下建议使用 Fiddler。
注意：如果您想将调试代理（如 Fiddler）与 GCDS 搭配使用，您需要更新 .vmoptions 文件，将 GCDS 设置为使用 Windows 受信任的证书存储区，并停用 CRL 检查。之后，您可以在 GCDS 中将 Fiddler 设为代理服务器（通常为 127.0.0.1，端口号为 8888），Fiddler 将记录相应连接。如果您在 Linux 上使用 GCDS，则无法使用 Windows 受信任的证书存储，因此您需要将 Fiddler 根证书导入 GCDS 的 Java 受信任存储区。有关详情，请参阅导入服务器证书。
请参阅使用配置文件，了解如何打开保存在其他计算机上的 XML 文件，或在同一计算机上以其他用户身份打开 XML 文件。
如果 GCDS 跟踪级别的日志中的 LDAP 数据与 LDAP 服务器上的预期数据不一致（例如，找不到用户或者某个属性没有正确的值），请采用 LDIF 格式从 LDAP 目录导出相应数据。支持团队可以将数据与 GCDS 日志中的 LDAP 数据进行比较。
导出数据时，请使用 LDAP 查询工具（例如 ldapsearch (Linux) 或 ldifde (Windows)）来模拟 GCDS 运行时所遵循的条件：
- 使用与 GCDS 配置相同的连接设置。
- 在运行 GCDS 的那台计算机上运行查询工具。
- 使用同一用户名进行 GCDS LDAP 身份验证。
示例
您的 GCDS 日志没有显示用户的 mail 属性，而您的 GCDS 搜索规则设置如下：
- 基本 DN：ou=Ireland,dc=altostrat,dc=com
- 范围：子树 (Subtree)
- 搜索过滤条件：(&(objectCategory=person)(objectClass=user))
- 服务器：dc01.altostrat.com
- 端口：636
- 协议：LDAP+SSL
- 身份验证用户 DN：cn=GCDS,ou=Users,dc=altostrat,dc=com
使用以下命令：
- Linux：
ldapsearch -v -b "ou=Ireland,dc=altostrat,dc=com" -s sub -h dc01.altostrat.com -p 636 -x -Z -D "cn=GCDS,ou=Users,dc=altostrat,dc=com" "(&(objectCategory=person)(objectClass=user))" mail givenname uniqueidentifier sn > out.ldif（您可能需要修改命令，具体取决于您的系统。） - Windows：
ldifde -f out.ldif -s dc01.altostrat.com -v -t 636 -d "ou=Ireland,dc=altostrat,dc=com" -r "(&(objectCategory=person)(objectClass=user))" -p SubTree -l mail,givenname,uniqueidentifier,sn -a "cn=GCDS,ou=Users,dc=altostrat,dc=com" PASSWORD（将PASSWORD替换为您在 GCDS 中设置的 LDAP 用户的密码）。
如果输出 (out.ldif) 不包含受影响用户的 mail 属性，则表示 LDAP 基础架构存在问题。这可能与您用于访问 LDAP 的用户的权限有关（例如，OpenLDAP 和 Active Directory 都允许设置属性级权限）。或者，如果您使用的是 3268 或 3269 等全局目录端口，则系统可能无法将该属性复制到全局目录中。
如果输出包含受影响用户的 mail 属性，请向 Google Workspace 支持团队提供以下详细信息：
- out.ldif 文件
- 运行命令时的命令提示符或终端窗口的屏幕截图
（请务必先移除密码。） - GCDS 跟踪级别的日志
模拟和同步
我是否需要通知服务器来运行模拟同步？要运行模拟同步，您需要能够发送邮件的服务器。如果您在邮件服务器上运行 GCDS，则可以使用 127.0.0.1 作为您的邮件服务器的 IP 地址。如果不是，请与您的邮件管理员联系，获取正确的邮件信息。
如果您使用命令行运行同步，但同步没有运行，请检查您是否在命令行中使用了 -o 或 --oneinstance 参数。
如果您使用其中一个参数，GCDS 会创建一个与 XML 配置文件关联的 LOCK (.lock) 文件。如果在同一服务器上还发现了其他 LOCK 文件，则 GCDS 将不会运行同步以避免多个 GCDS 实例同时运行。
如果没有其他 GCDS 实例正在运行，请检查服务器上是否有其他 LOCK 文件。请手动删除相应文件，然后尝试重新运行同步。
如果您的同步未完成，例如群组的完整成员资格未同步，那么 Directory API 可能存在问题。若要验证问题是否与 API 而非 GCDS 产品相关，请手动调用 Directory API 并查看结果。如需手动调用该 API，请从以下两种方法中选择一种方法。
方法 1：使用 API 参考文档页面
- 转到 Admin SDK API 参考文档概览。
- 在左侧，点击 Directory API，然后在 REST 资源部分中，转到您要查询的 REST 资源。
- 在右侧，点击您想尝试的方法，然后点击试试看。
如果 API 参考文档页面未显示试用，请前往“方法 2：使用 OAuth 2.0 Playground”。
- 输入您用于授权 GCDS 的管理员凭据。
有关详情，请转到定义您的 Google 网域设置。
- 查看相关信息，确保 API 按预期响应。
方法 2：使用 OAuth 2.0 Playground
- 打开 OAuth 2.0 Playground。
- 根据需要选择操作步骤：
- 从列表中选择一个范围。
- 从 API 参考文档页面的授权范围列表中复制范围。然后，将范围粘贴到输入您自己的范围字段中。
- 点击授权 API。
- 输入您用于授权 GCDS 的管理员凭据。
有关详情，请转到定义您的 Google 网域设置。
- 点击将授权代码转换为令牌。
如果此过程成功，系统会将您重定向至“第 3 步：配置对 API 的请求”。
- 填写请求的信息。
提示：您可以在 API 方法参考文档网页中找到大部分信息。
- 点击发送请求。
- 查看相关信息，确保 API 按预期响应。
错误
哪些原因会导致 EntityIsNotExist/EntityExists 错误或冲突？在您的 XML 配置文件中，设置 useDynamicMaxCacheLifetime 选项。该选项可以将 GCDS 配置为将数据缓存长达 8 天，并且更频繁地清理中小型数据集中的缓存，从而降低缓存数据过期或与新数据冲突的可能性。在使用 GCDS 3.2.1 或更高版本创建的配置中，系统会自动选择 useDynamicMaxCacheLifetime 选项。
注意：这些错误通常出现在直接在您的 Google 网域中进行修改的情况下。使用 GCDS 进行同步时，您不应直接对 Google 网域进行更改，而应对 LDAP 目录中的用户、群组和其他实体进行更改，然后使用 GCDS 将这些更改同步到 Google 网域中。
如果您遇到了与内存空间相关的错误，则需要增加 Java 虚拟机的堆大小以解决此问题。要增加堆大小，请修改 GCDS 安装目录中的 sync-cmd.vmoptions 和 config-manager.vmoptions 文件。相关条目大致如下：
- -Xmx1000m（分配给堆大小的内存空间的最大值）
- -Xms64m（分配给堆大小的内存空间的最小值）
同时修改 sync-cmd.vmoptions 和 config-manager.vmoptions 文件，以将更改同时应用于 sync-cmd 和配置管理器版本。
修改 -Xmx 数值，以增加内存空间值。数值后的“m”表示内存空间的测量单位是兆字节 (MB)。内存空间值是否合适取决于 GCDS 服务器上可用的内存空间以及 GCDS 需要多少内存空间才能运行同步。您可能需要多次修改数值以设置合适的大小。要详细了解运行 GCDS 所需的空闲内存大小，请参阅 GCDS 的系统要求。
该错误可能是由于配置问题（例如排除规则配置错误）造成的，而 GCDS 缓存会隐藏这类配置错误。
GCDS 会将 Google 服务（例如 Google Workspace 或 Cloud Identity）的数据缓存保留最多 8 天。GCDS 清理缓存的频率也可能会更高，具体取决于所缓存数据的大小。不过，如果缓存未被清除，您可能在长达 8 天内无法看到更新。
举例来说，您可以同步 LDAP 数据并为您的 Google 服务（例如 Google Workspace 或 Cloud Identity）创建新的群组，然后创建排除规则，将相应群组从后续同步中排除。该排除规则配置错误，并会出现故障。不过，后续同步会调用已缓存的数据，而群组会保留在您的 Google 服务中。当您再次同步并选择清除缓存时，系统就会因为这一配置错误将该群组从 Google 服务中移除。
要手动清理缓存，可执行以下操作：
- 从“配置管理器”中运行同步，并选择在同步时清除缓存的选项。
- 使用命令运行同步，并使用参数 -f 强制清除缓存。
- 修改 XML 配置文件，将 maxCacheLifetime 值设为 0。
重要提示：强制清除缓存可能会大幅增加同步所需的时间。
用户和群组
为什么 GCDS 会尝试创建已存在的 Google 用户？如果您看到“409：实体已存在”这一错误，则表示 GCDS 正尝试创建已存在的 Google 用户。如果您在后续同步中未看到该错误，则表示 GCDS 缓存可能已过期，您可以放心地忽略该错误。
如果该问题在每次同步时或每隔几天出现一次，最可能的原因是：
- Google 用户排除规则过于宽泛 - 该规则会匹配同样存在于 LDAP 目录中的部分 Google 用户。
- 查询范围过窄 - 该查询不会匹配同样存在于 LDAP 目录中的部分 Google 用户。
这两种情况都可能导致 GCDS 忽略已存在的 Google 用户。如果 LDAP 用户搜索规则结果中存在这些用户，则 GCDS 会尝试在 Google 账号中创建这些用户。
若要解决此问题，请调整排除规则或搜索查询。或者，如果您希望 GCDS 完全忽略您 LDAP 目录中的用户，请调整您的 LDAP 用户搜索规则或创建 LDAP 用户排除规则。如需了解详情，请参阅使用排除规则和查询省略数据。
为了在同步群组成员时不受任何用户搜索规则结果的影响，GCDS 会默认启用 INDEPENDENT_GROUP_SYNC。如果您使用成员引用属性来同步群组，那么 GCDS 会尝试解析 LDAP 目录中每位用户的电子邮件地址，不考虑任何用户搜索规则。
要仅根据用户搜索规则的结果来同步群组成员，请从配置 XML 文件中移除 INDEPENDENT_GROUP_SYNC。这样一来，GCDS 就会：
- 使用用户搜索规则的结果来解析群组成员资格
- 仅将用户同步范围内的用户同步为群组成员
- 执行用户搜索规则，即使您在常规设置中停用了用户账号同步功能也不例外
（不过，如果符合条件的用户同时也满足群组成员资格条件，系统会将他们同步为群组成员，而不是用户。）
通常情况下，这并非理想的同步运行方式，尤其是在您同步共享联系人且联系人中也有群组成员时。在这种情况下，系统不会将联系人同步为群组成员。
当配置为群组名称属性的 LDAP 属性没有包含完整的电子邮件地址时，就会出现此问题。要解决此问题，请检查您的群组搜索规则，并确保 GCDS 使用完整的电子邮件地址作为群组名称。请采用以下方法之一：
- 将群组名称属性设为不同的 LDAP 属性，其中指明每个群组（例如邮件）的完整电子邮件地址。
- 启用 Google 网域设置中的替换 LDAP 电子邮件地址中的域名，这样您的群组名称属性即可匹配 Google 方的群组名称。
- 在您的群组搜索规则中指定群组名称后缀，将域名添加到群组名称中。
确保您已在 LDAP 配置部分的服务器类型字段中选择 MS Active Directory。
如果 LDAP 目录中的电子邮件地址所属的网域与您的 Google 网域不同，则可以使用该选项（在 XML 文件中显示为 SUPPRESS_DOMAIN）。如果您启用了该选项，GCDS 会将该域名部分从读取的所有电子邮件地址中剥离。
所有处理都是在不带域名的情况下完成的。如果您基于电子邮件地址使用排除规则，则只需要针对排除规则考虑电子邮件地址的本地部分。
例如，如果您停用了替换 LDAP 电子邮件地址中的域名选项，那么在创建完全匹配排除规则时，就需要以 luka@example.com 的形式输入要匹配的用户电子邮件地址。如果您启用了替换 LDAP 电子邮件地址中的域名选项，请输入 luka。系统在比对之前会去除 @example.com，因此无法匹配 luka@example.com。
使用 GCDS 配置群组时，您无法在静态群组下嵌套动态群组（或在动态群组下嵌套静态群组）。GCDS 需要单独查询静态群组和动态群组，而所有嵌套的群组都需包含在相同查询中。
以下方法可能可以将动态群组用作静态群组：自动执行定期查询每个动态群组的任务，以便在目录中填充静态群组。然后，GCDS 可以使用静态群组（通过动态群组创建）进行配置，而非配置动态群组。
LDAP 查询的结果取决于配置管理器设置和 LDAP 服务器。如果您的 LDAP 搜索规则返回意外结果，请参考以下问题排查提示。请务必确保：
- LDAP 查询在配置管理器中正确设置 - 设置搜索规则时，请点击测试 LDAP 查询进行确认。有关详情，请参阅使用 LDAP 搜索规则同步数据。
- 多个查询互不冲突 - 请确保您未设置用于更改查询结果的搜索或排除规则。
- LDAP 服务器的授权用户拥有足够的权限 - 请确保用于验证 LDAP 服务器的管理员可以在同一个服务器上使用该命令行。尝试在 LDAP 服务器上进行查询并验证结果。
您可能会在 GCDS 日志中遇到以下错误消息：“无法创建群组 ...。消息：无权访问此资源/API”。
若要进行问题排查，请检查包含用户和群组电子邮件地址域名的 Active Directory (AD) 属性是否与您的超级用户账号使用的域名一致。
联系人和日历
为什么在使用 GCDS 同步后，我在自己的网域目录中看到了重复的联系人？如果您同步了共享联系人但没有正确构建搜索规则，通常会出现此问题。
您可以使用 GCDS 同步以下 2 类相关对象：
- 用户个人资料：您的 Google 网域中拥有电话号码或地址等其他数据的用户。您只能为您网域中的每位用户同步一份个人资料。
- 共享联系人：包含您网域中需要联系的外部各方联系人。
要解决此问题，请更正您的共享联系人搜索规则，以排除自己网域中的用户。这样下次同步时，GCDS 将尝试删除重复的联系人。您可能需要为第一次同步调整共享联系人删除限制。
在某些情况下，用户在安排会议时，无法在 Google 日历中看到自己的主要工作地点。
如果您遇到此问题，请确保将地点类型属性和区域属性设置为“办公桌”。
规则
为什么应用搜索规则后，没有搜索到任何内容？如果您的搜索结果有问题，请检查：
- 规则的范围。您可能需要将范围设置为 Sub-tree。
- 您使用的搜索规则正确无误。
- 使用的属性存在且可见。
您的 LDAP 查询。确认您 LDAP 服务器上的查询使用的管理员用户名与 GCDS 中配置的管理员用户名相同。
有关详情，请参阅使用 LDAP 搜索规则同步数据。
您使用的字体可能过大，不适合相应的屏幕。该对话框不适用于大号或超大号字体。请更改字体大小或直接修改 XML 文件。
相关主题
“Google”、Google Workspace 以及相关标志和徽标是 Google LLC 的商标。其他所有公司名和产品名是其各自相关公司的商标。
