docs: add SSH troubleshooting section based on issue #1268

docs/common/radxa-os/system-config/_ssh_remote.mdx

@@ -212,3 +212,186 @@ Tabby 是一款功能强大的跨平台串口调试工具，支持串口、SSH 
 </Tabs>
 
 SSH 登录成功后，你就可以通过 SSH 运行命令控制系统。
+
+## 故障排除
+
+如果你在 SSH 连接过程中遇到问题，可以尝试以下故障排除步骤：
+
+### 1. 检查 SSH 服务状态
+
+确保 SSH 服务正在运行：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo systemctl status ssh
+```
+
+</NewCodeBlock>
+
+如果服务未运行，启动它：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo systemctl start ssh
+```
+
+</NewCodeBlock>
+
+### 2. 检查 SSH 配置
+
+确保 SSH 配置允许密码认证（默认已开启）：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo grep -E "^PasswordAuthentication" /etc/ssh/sshd_config
+```
+
+</NewCodeBlock>
+
+如果输出不是 `PasswordAuthentication yes`，可以编辑配置文件：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo nano /etc/ssh/sshd_config
+```
+
+</NewCodeBlock>
+
+找到 `PasswordAuthentication` 行，确保设置为 `yes`，然后重启 SSH 服务：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo systemctl restart ssh
+```
+
+</NewCodeBlock>
+
+### 3. 检查防火墙设置
+
+确保防火墙没有阻止 SSH 连接（默认端口 22）：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo ufw status
+```
+
+</NewCodeBlock>
+
+如果防火墙已启用，确保 SSH 端口已开放：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo ufw allow ssh
+```
+
+</NewCodeBlock>
+
+### 4. 验证 IP 地址
+
+确保你使用了正确的 IP 地址。在设备上运行：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+ip addr show
+```
+
+</NewCodeBlock>
+
+或在 Windows 上使用 `arp -a` 命令查看网络中的设备。
+
+### 5. 检查 SSH 日志
+
+查看 SSH 服务日志以获取更多信息：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo journalctl -u ssh -b --no-pager | tail -20
+```
+
+</NewCodeBlock>
+
+### 6. 常见问题
+
+#### 问题：SSH 连接被拒绝（Permission denied）
+
+**可能原因和解决方案：**
+
+1. **密码错误**：确保使用正确的用户名和密码。默认用户名为 `radxa`，密码为 `radxa`。
+2. **用户账户问题**：尝试重置密码：
+
+   <NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+   ```bash
+   sudo passwd radxa
+   ```
+
+   </NewCodeBlock>
+
+3. **SSH 密钥问题**：如果你之前设置了 SSH 密钥但忘记了，可以尝试删除现有密钥并重新生成：
+
+   <NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+   ```bash
+   rm -rf ~/.ssh
+   ```
+
+   </NewCodeBlock>
+
+#### 问题：Windows SSH 客户端问题
+
+如果使用 Windows SSH 客户端遇到问题：
+
+1. **尝试使用 WSL（Windows Subsystem for Linux）**：在 WSL 终端中尝试 SSH 连接
+2. **使用其他 SSH 客户端**：如 Tabby、PuTTY、MobaXterm 等
+3. **检查 Windows 防火墙**：确保 Windows 防火墙没有阻止 SSH 连接
+
+#### 问题：连接超时
+
+**可能原因和解决方案：**
+
+1. **网络连接问题**：确保设备在同一网络下
+2. **IP 地址错误**：重新检查 IP 地址
+3. **路由器/防火墙阻止**：检查路由器设置
+
+### 7. 重置 SSH 配置
+
+如果以上步骤都无法解决问题，可以尝试重置 SSH 配置：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+# 备份当前配置
+sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.backup
+
+# 重新安装 SSH 服务
+sudo apt remove --purge openssh-server -y
+sudo apt install openssh-server -y
+
+# 重启 SSH 服务
+sudo systemctl restart ssh
+```
+
+</NewCodeBlock>
+
+### 8. 获取更多帮助
+
+如果问题仍然存在，请提供以下信息以获取进一步帮助：
+
+1. SSH 服务状态输出
+2. SSH 配置中 `PasswordAuthentication` 的设置
+3. 防火墙状态
+4. 从客户端尝试连接时的完整错误信息
+5. 设备上的 SSH 日志（使用 `sudo journalctl -u ssh -b`）
+
+:::tip
+大多数 SSH 连接问题可以通过检查服务状态、配置和网络连接来解决。如果问题持续存在，考虑重新安装系统镜像或联系技术支持。
+:::

i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_ssh_remote.mdx

@@ -212,3 +212,186 @@ After a successful connection, the remote interface will appear.
 </Tabs>
 
 After successfully logging in via SSH, you can run commands to control the system through the SSH connection.
+
+## Troubleshooting
+
+If you encounter issues during SSH connection, try the following troubleshooting steps:
+
+### 1. Check SSH Service Status
+
+Ensure the SSH service is running:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo systemctl status ssh
+```
+
+</NewCodeBlock>
+
+If the service is not running, start it:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo systemctl start ssh
+```
+
+</NewCodeBlock>
+
+### 2. Check SSH Configuration
+
+Ensure SSH configuration allows password authentication (enabled by default):
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo grep -E "^PasswordAuthentication" /etc/ssh/sshd_config
+```
+
+</NewCodeBlock>
+
+If the output is not `PasswordAuthentication yes`, edit the configuration file:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo nano /etc/ssh/sshd_config
+```
+
+</NewCodeBlock>
+
+Find the `PasswordAuthentication` line, ensure it's set to `yes`, then restart SSH service:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo systemctl restart ssh
+```
+
+</NewCodeBlock>
+
+### 3. Check Firewall Settings
+
+Ensure firewall is not blocking SSH connections (default port 22):
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo ufw status
+```
+
+</NewCodeBlock>
+
+If firewall is enabled, ensure SSH port is open:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo ufw allow ssh
+```
+
+</NewCodeBlock>
+
+### 4. Verify IP Address
+
+Ensure you are using the correct IP address. Run on the device:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+ip addr show
+```
+
+</NewCodeBlock>
+
+Or use `arp -a` command on Windows to see devices on the network.
+
+### 5. Check SSH Logs
+
+View SSH service logs for more information:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo journalctl -u ssh -b --no-pager | tail -20
+```
+
+</NewCodeBlock>
+
+### 6. Common Issues
+
+#### Issue: SSH Connection Rejected (Permission denied)
+
+**Possible causes and solutions:**
+
+1. **Incorrect password**: Ensure using correct username and password. Default username is `radxa`, password is `radxa`.
+2. **User account issue**: Try resetting password:
+
+   <NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+   ```bash
+   sudo passwd radxa
+   ```
+
+   </NewCodeBlock>
+
+3. **SSH key issue**: If you previously set up SSH keys but forgot, try removing existing keys and regenerating:
+
+   <NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+   ```bash
+   rm -rf ~/.ssh
+   ```
+
+   </NewCodeBlock>
+
+#### Issue: Windows SSH Client Problems
+
+If experiencing issues with Windows SSH client:
+
+1. **Try using WSL (Windows Subsystem for Linux)**: Attempt SSH connection in WSL terminal
+2. **Use alternative SSH clients**: Such as Tabby, PuTTY, MobaXterm, etc.
+3. **Check Windows Firewall**: Ensure Windows firewall is not blocking SSH connections
+
+#### Issue: Connection Timeout
+
+**Possible causes and solutions:**
+
+1. **Network connectivity issue**: Ensure devices are on the same network
+2. **Incorrect IP address**: Re-check the IP address
+3. **Router/firewall blocking**: Check router settings
+
+### 7. Reset SSH Configuration
+
+If none of the above steps resolve the issue, try resetting SSH configuration:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+# Backup current configuration
+sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.backup
+
+# Reinstall SSH service
+sudo apt remove --purge openssh-server -y
+sudo apt install openssh-server -y
+
+# Restart SSH service
+sudo systemctl restart ssh
+```
+
+</NewCodeBlock>
+
+### 8. Get More Help
+
+If the issue persists, please provide the following information for further assistance:
+
+1. SSH service status output
+2. `PasswordAuthentication` setting in SSH configuration
+3. Firewall status
+4. Complete error information when attempting to connect from client
+5. SSH logs on the device (using `sudo journalctl -u ssh -b`)
+
+:::tip
+Most SSH connection issues can be resolved by checking service status, configuration, and network connectivity. If the problem persists, consider reinstalling the system image or contacting technical support.
+:::