调试连接器

为了快速有效地排除故障，强烈建议您将 Satellite Connector 实例连接到 IBM Cloud Logs 实例。

从控制台访问 Satellite 连接器实例。如果在您创建 Satellite 连接器的地区，您的账户中没有 IBM Cloud Logs 实例，请单击“链接登录”部分下的“连接”。您将进入目录页面，在此创建 IBM Cloud Logs 实例。如果已有 IBM Cloud Logs 实例，请单击“链接日志记录”部分下的“配置”。然后，选择现有日志记录实例。将 IBM Cloud Logs 实例连接到 Satellite Connector 后，可以使用“链接的日志记录”部分打开“日志记录实例”仪表板，输出将针对 Connector 进行过滤。

日志记录实例必须启用 接收平台日志。要启用此选项，请从日志记录实例列表中选择选项-> 编辑平台。

通常有两种类型的错误:

隧道无法建立。代理程序不会显示在控制台上的“活动代理程序”选项卡中。
已建立隧道，您可以在“活动代理程序”列表中看到代理程序，但无法使用端点从 IBM Cloud 访问本地应用程序。

无法建立隧道-代理程序未显示在活动代理程序列表上

隧道未建立，并且您不会看到 Satellite 连接器代理程序显示在 UI 的“活动代理程序”选项卡下的列表中。

从连接器代理程序启动到在列表中显示时，大约有 2 分钟的延迟。

2 分钟后，如果代理程序仍未显示，请执行以下调试步骤:

请验证是否正确指定了连接器标识和区域。

打开日志记录仪表板并查看连接器日志。通常，问题在于 IAM API 密钥，您会看到类似以下示例的消息。有关更多信息，请参阅为什么我的 API 密钥无法工作。

Failed to get configuration from API /v1/connectors/U2F0ZWxsaXRlQ29ubmVjdG9yOiJjaTExMGxpdzFwazluMGdybXUyMCI, region us-east, code: 401. IAM Error: "status code: 400. Provided API key could not be found.", API Error: "null", hostname: "482bddf6c60b"

请检查代理程序容器上的日志。如果 IBM Cloud Logs 控制面板中没有错误，这意味着在代理与隧道服务器通信之前出现了问题。您可以通过查看代理程序容器上的日志文件来获取更多信息。该命令因容器平台而异。如果您正在使用 Docker，那么可以使用以下命令:
```
docker logs <container id>
```
您应该能够从日志消息中确定问题是什么。发生错误的最常见原因是代理程序没有公共出站访问权，无法与 IBM 隧道服务器进行通信。请参阅为什么我的连接器代理程序无法使用 IBM Cloud 建立隧道。
验证您是否正在使用正确的容器硬件平台。例如，您正在尝试在 arm64 平台上运行代理程序映像。连接器代理程序将仅在 linux/amd64 平台或可以仿真 amd64的平台上运行。如果是这样，您将看到类似如下的错误:
```
{"msg":"exec container process `/usr/local/bin/node`: Exec format error","level":"error","time":"2023-06-16T14:37:54.000567792Z"}
```
针对 Apple Mac 硅用户的注意: 如果要在使用 ARM64 处理器的具有 Apple silicon 的 Mac 上试用连接器，那么如果已安装 Rosetta2，那么容器代理程序将运行。这通常随 Docker一起安装。运行连接器代理程序时，您将看到以下警告:
```
icr.io/ibm/satellite-connector/satellite-connector-agent:v1.0.3 WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 43064456c42434f056348a32773a732d02d4a68690fc6b2b36790be8daa49bb2
```
在这种情况下，这只是一个警告，连接器代理程序正在运行。如果不想看到警告，可以在 docker run 命令上指定 --platform linux/amd64 选项。
验证容器平台是否可以拉取映像。该映像位于 IBM Container Registry 中的 icr.io/ibm/satellite-connector/satellite-connector-agent:<version>。确保正确指定了图像。运行代理程序的机器具有对 icr.io 的网络访问权，并且您已登录到 IBM Container Registry。有关更多信息，请参阅拉取代理程序映像。

请注意 Docker Swarm 用户: 如果看到有关“无此类映像”的以下错误:

icr.io/ibm/satellite-connector/satellite-connector-agent:v1.0.4   swarm-worker1   Shutdown    Rejected 5 minutes ago   "No such image: icr.io/ibm/sat…"

这意味着 Docker Swarm 无法拉取映像。这可能是由于 IBM Container Registry 凭证无效所致。要解决此问题，请完成下列步骤：

除去服务。
登录 IBM Container Registry。
重新启动堆栈。

已建立隧道-代理程序容器列示在控制台上的“活动代理程序”选项卡中

如果您的代理程序容器列示在控制台上的“活动代理程序”选项卡中，请执行以下调试步骤:

转至连接器实例并打开“日志记录仪表板”。这将自动过滤连接器标识的日志记录输出。
查看错误消息。

隧道建立后，任何错误都将出现在 IBM Cloud Logs 实例和代理的容器平台日志中。现在，大多数错误将是尝试从 IBM Cloud 中访问端点到通过隧道在本地运行的应用程序的错误。访问端点时，在连接启动时，会将 flowlog 条目写入日志记录实例。例如：
```
flowlog: start for client 10.249.96.47:1206 connect to postgres.apps.wdc6.toddjohn.net:5432, conn_type: location
```
关闭连接后，将写入另一个 flowlog 条目，其中包含有关连接的一些详细信息。例如：
```
flowlog: end for client 10.249.96.47:1206 connect to postgres.apps.wdc6.toddjohn.net:5432, conn_type: location, duration 387 ms, BytesToCloud 2444, BytesFromCloud 168
```
持续时间是打开连接的时间，而不是请求的往返时间。

如果尝试连接到端点时发生任何错误，那么将写入包含错误详细信息的 flowlog 条目。例如：
```
flowlog: error when client 10.249.96.47:1209 connecting to postgres.apps.wdc6.toddjohn.net:5433, conn_type: location, detail: connect ECONNREFUSED 192.168.3.84:5433
```
如果未看到任何 flowlog 条目，请确保 IBM Cloud 应用程序有权访问 CSE 端点，并且正在使用正确的端点地址和端口。例如，如果您正在使用 VPC 实例或 VPC Kubernetes 集群，那么安全组可能阻止访问。确保安全组允许从 VPC 到 CSE 端点 IP 和端口的流量。
验证是否正确配置了端点，以及本地应用程序是否正在侦听已配置的目标 FQDN 或 IP 和目标端口。如果本地应用程序正在使用容器，那么其 IP 地址可能已更改。有关更多信息，请参阅为什么无法从 IBM Cloud访问端点。
如果要对同一连接器运行多个代理程序，请确保所有代理程序都具有对端点的网络访问权。每个连接请求都路由到随机代理程序，因此所有代理程序都必须具有与所有内部部署端点的网络连接。没有针对特定连接器的单个代理程序的机制。