> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trae.cn/llms.txt
> Use this file to discover all available pages before exploring further.

本文档记录在使用 Remote SSH 时可能遇到的问题并提供解决方法。
## 错误码 {#1ac21232}
<!-- @cols-width: 100,153,618 -->
| | | | \
|**错误码** |**错误内容** |**解决方案** |
|---|---|---|
| | | | \
|1001 |创建目录失败 |可能是因为磁盘空间不足或无目录的写入权限。解决方案如下： |\
| | | |\
| | |* 检查磁盘剩余空间，确保有足够的空间用于创建目录。 |\
| | |* 确保有 `~/.trae-cn-server` 目录的写入权限。 |
| | | | \
|1002 |创建目录失败 |同 1001 错误码。 |
| | | | \
|1003 |远程主机上启动 TRAE CN 服务端失败 |检查远程主机的系统版本是否满足要求。 |
| | | | \
|2001 |下载安装包失败 |检查网络联通性，然后重试。 |
| | | | \
|2002 |解压安装包失败 |可能是由于安装包的下载过程被截断，导致下载的文件异常，重新安装后再尝试解压。 |
| | | | \
|3001 |远程主机上启动 TRAE CN 服务端失败 |检查远程主机的系统版本是否满足要求。 |

## 连接超时问题 {#88292c35}
<!-- @cols-width: 244,500 -->
| | | \
|**连接超时原因** |**解决方案** |
|---|---|
| | | \
|服务器未启动，或网络无法连接 |在本地终端执行 `ssh <host>` 测试远程连接： |\
| | |\
| |* **若连接失败**： |\
| |   * 检查远程主机的 TRAE CN 服务端是否正常运行。 |\
| |   * 确认网络连接无异常。 |\
| |* **若连接成功**：继续排查其他潜在问题。 |
| | | \
|远程主机名称包含大写字母 |部分 TRAE CN 客户端版本存在兼容性问题：当 `~/.ssh/config` 文件中远程主机名称包含大写字母时，可能导致连接超时。解决方案如下： |\
| | |\
| |* **升级客户端**：将 TRAE CN 客户端更新至最新版本。 |\
| |* **修改主机名**：将配置文件中的主机名称全部改为小写字母。 |
| | | \
|不支持服务器的默认 shell  |目前，一些 shell 会导致连接异常，比如 fish。将用户的默认 shell 改成 bash 和 zsh 以解决该问题。 |
| | | \
|本地 `~/.ssh/config` 文件位置变动 |如果挪动过本地的 `~/.ssh/config` 文件的位置，可能会遇到这个问题。将 `~/.ssh/config` 文件放回原先的位置以解决该问题。 |

若以上解决方案仍无法解决你的问题，可以通过《[支持](/ide/support)》中提供的渠道联系我们。请在问题反馈中提供以下信息，以便我们尽快定位问题并协助你解决:

* IDE 截图（尽量截取完整的 IDE 界面图，以便我们分辨异常信息）。
* 日志（从输出面板复制 Remote-SSH 相关的完整日志）。
   ![Image=2034x434](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/231947d282bd44f2a24b9ac1fad903e9~tplv-goo7wpa0wc-image.image)
* 如果是连接超时问题，附上 `ssh -vvv <host>` 命令的完整输出结果，我们会根据此信息定位超时的原因。
   ```Bash
   ssh -vvv test
   
   # 此处会输出大量日志，请复制完整的日志
   ```


## 网络问题 {#8d3fafe8}
如果 AI 报告 997 错误，这通常表示你的服务器存在网络连接问题。
执行以下命令，确认你的服务器是否能成功连接到 TRAE CN 的服务：
```Bash
curl -vvv "https://trae.cn"
```

如果以上 `curl` 命令在执行时报错，请先解决网络问题。
## 环境兼容性问题 {#8f2fc5f8}
在 Linux 上，可能会由于 GLIBC 问题导致进程无法启动。
**问题现象**

* 你无法在对话面板中与 AI 对话。
* 服务器端存在全局注入的动态库（如安全软件、监控组件，例如 `/etc/thunder/libthunder.so`）。

**根本原因**
TRAE CN Server 为了保证在老旧系统上的兼容性，自带了一个较旧版本的 `libstdc++.so.6`。
当系统环境中有程序（或被强制注入的库）由新版编译器编译，并依赖新版 `GLIBCXX` 符号时，TRAE CN 自带的旧库无法满足需求，从而导致加载失败。
**解决方案**

1. 在 Linux 服务器上执行以下命令，检查是否存在 `libstdc++` 版本冲突。
   ```Bash
   grep -r "version \`GLIBCXX_.*' not found" ~/.trae-cn-server/manager-logs/
   ```

   如果命令输出类似以下内容，说明确实存在 `libstdc++` 版本冲突，继续完成以下步骤来解决该冲突。
   ```Plain Text
   .../libstdc++.so.6: version `GLIBCXX_3.4.30' not found (required by /etc/thunder/libthunder.so)
   ```

2. 找到 TRAE CN Server 的安装目录。
   :::tip 提示
   该目录通常在 `~/.trae-cn-server/bin/stable-<commit-id>-debian10/` 下。你也可以从报错日志中提取准确的路径。
   :::
3. 重命名自带的 `libstdc++.so.6`：
   1. 进入 `lib/trae-helper` 目录（或报错日志中指示的包含 `libstdc++.so.6` 的目录）。
   2. 重命名自带的库文件。
   ```Bash
   # 示例路径，请根据实际的路径调整
   cd ~/.trae-cn-server/bin/stable-*-debian10/lib/trae-helper/
   # 备份并重命名自带的库文件，迫使程序使用系统的 libstdc++.so.6
   mv libstdc++.so.6 libstdc++.so.6.bak
   ```

4. 重启服务：
   1. 完全退出本地的 TRAE CN。
   2. 重启 TRAE CN。
   3. 尝试重新连接远程服务器。

## 如何使用 TRAE 连接到 Devbox 启动的 Docker？ {#003e388e}
![Image=600x103](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/e04c1fc4db99476a835de706bd7c2832~tplv-goo7wpa0wc-image.image)
若要在 Devbox（远程 Linux 开发机）上启动 Docker 容器，并在本地电脑的 TRAE 中通过 Remote SSH 进入该容器进行开发，可以按照以下步骤操作。
:::tip 提示
代码块中的内容为示例，你需要将粗体内容替换为自己的实际配置。
:::

1. 确保容器内已安装并启用 OpenSSH 服务。
   如果基础镜像未包含 SSH 服务，可以构建一个支持 SSH 登录（root + 密码）的镜像：
   ```Bash
   mkdir -p temp_docker
   cat > temp_docker/Dockerfile <<'EOF'
   FROM <your_image>
   RUN apt-get update && apt-get install -y openssh-server
   RUN mkdir /var/run/sshd
   RUN echo 'root:password' | chpasswd
   RUN sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config
   EXPOSE 22
   CMD ["/usr/sbin/sshd", "-D"]
   EOF
   cd temp_docker
   docker build -t ssh01 .
   ```

   字段说明：
   * `<your_image>`：你的基础镜像（如 `ubuntu:20.04`） 
   * `root:password`：容器内 root 用户的密码（后续用于 SSH 登录容器） 
2. 在 Devbox 上启动容器，并将容器的 SSH 端口映射到 Devbox 本机的端口。
   以下命令中，容器的 `22` 端口（SSH）被映射到 Devbox 的 `2222` 端口。
   ```Bash
   docker run -d -p 2222:22 ssh01
   ```

3. 在本地电脑中，编辑 SSH 配置文件：
   ```Bash
   ~/.ssh/config
   ```

   写入以下内容：
   ```Plain Text
   Host devbox
       HostName 10.x.x.x
       User root
   
   Host docker-container
       HostName localhost
       User root
       Port 2222
       ProxyJump devbox
       StrictHostKeyChecking no
       UserKnownHostsFile /dev/null
   ```

   字段说明：
   * `devbox`：远程开发机（跳板机） 
   * `docker-container`：运行在 `devbox` 上的容器 
   * `ProxyJump devbox`：表示先连接 `devbox`，再从 `devbox` 访问 `docker-container`
   * `HostName localhost`：这里的 `localhost` 指的是 Devbox 本机（因为连接已跳转到 `devbox` 上执行）
4. 在本地电脑的终端中，依次测试连接：
   1. 执行以下命令，测试 `devbox` 是否可被连接。`password` 为第一步中配置的密码。
      ```Bash
      ssh devbox
      ```

      由于 `devbox` 是代理 SSH，因此必须首先确保 `devbox` 的 SSH 服务已正确配置并运行，且本地电脑到 `devbox` 的网络连接畅通。
   2. 执行以下命令，测试 `docker-container` 是否可被连接。
      ```Bash
      ssh docker-container
      ```

      此时，会先连接 `devbox`，再连接 `localhost:2222`（即 `devbox` 上的容器）。使用的是容器中设置的 `root:password`。
5. 在 TRAE 中通过 Remote SSH 连接 `docker-container`，即可进入容器进行远程开发。详细步骤参考[连接远程主机](/ide/ssh-remote#76a28db2)。