docs: add SSH troubleshooting section for issue #1268

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

@@ -212,3 +212,198 @@ Tabby 是一款功能强大的跨平台串口调试工具，支持串口、SSH 
 </Tabs>
 
 SSH 登录成功后，你就可以通过 SSH 运行命令控制系统。
+
+## 故障排除
+
+如果 SSH 连接失败，可按以下步骤逐一排查。
+
+### 1. 确认 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
+sudo systemctl enable ssh
+```
+
+</NewCodeBlock>
+
+:::tip
+Debian/Ubuntu 中 `ssh` 是 `sshd` 的别名。如 `ssh` 服务名无效，可尝试 `sshd`。
+:::
+
+### 2. 确认网络连通性
+
+在 PC 上 ping 设备 IP，确认网络可达：
+
+<NewCodeBlock tip="PC$" type="host">
+
+```bash
+ping 192.168.x.x
+```
+
+</NewCodeBlock>
+
+若 ping 不通，请检查：
+- 设备与 PC 是否在同一局域网
+- 设备 IP 地址是否正确（避免使用 `127.0.0.1`）
+
+### 3. 检查防火墙
+
+Radxa OS 默认使用 `nftables`。执行以下命令确认端口 22 未被阻止：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo iptables -L -n | grep -E "22|ssh"
+sudo nft list ruleset 2>/dev/null | grep -E "22|ssh"
+```
+
+</NewCodeBlock>
+
+若防火墙规则阻塞了 SSH，可临时清除规则测试：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo iptables -F
+```
+
+</NewCodeBlock>
+
+### 4. 检查密码认证配置
+
+确认 SSH 服务允许密码认证：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo grep -v "^#" /etc/ssh/sshd_config | grep PasswordAuthentication
+```
+
+</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>
+
+### 5. 确认用户名和密码
+
+Radxa OS 默认用户名为 `radxa`，密码为 `radxa`。若密码错误，通过串口或连接显示器后重置：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo passwd radxa
+```
+
+</NewCodeBlock>
+
+### 6. 检查 SSH 日志
+
+查看 SSH 服务日志，获取具体错误信息：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo journalctl -u ssh -b --no-pager | tail -30
+```
+
+</NewCodeBlock>
+
+常见错误及含义：
+
+| 错误信息 | 可能原因 |
+|----------|----------|
+| `Connection refused` | SSH 服务未运行或端口 22 被阻止 |
+| `Permission denied` | 密码错误或公钥认证失败 |
+| `Connection timeout` | 网络不通或 IP 地址错误 |
+| `No route to host` | 网络层路由不可达 |
+
+### 7. Windows 客户端特殊问题
+
+若使用 Windows SSH 客户端遇到问题：
+
+1. 尝试使用 [Tabby](https://tabby.sh/)、[PuTTY](https://www.putty.org/) 或 [MobaXterm](https://mobaxterm.mobatek.net/) 替代
+2. 检查 Windows 防火墙是否阻止了 SSH 连接
+3. 确认使用的是密码认证而非仅公钥认证
+
+### 8. 公钥认证失败
+
+若配置了 SSH 公钥登录但失败，检查服务端权限：
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+# .ssh 目录权限应为 700
+chmod 700 ~/.ssh
+
+# authorized_keys 文件权限应为 600
+chmod 600 ~/.ssh/authorized_keys
+```
+
+</NewCodeBlock>
+
+### 9. 重置 SSH 配置
+
+:::warning
+以下操作会中断当前 SSH 连接。若远程操作，请确保有串口或显示器等备用接入方式后再执行。
+:::
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+# 备份当前配置
+sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.backup
+
+# 恢复默认配置
+sudo dpkg-reconfigure openssh-server
+
+# 重启服务
+sudo systemctl restart ssh
+```
+
+</NewCodeBlock>
+
+### 获取帮助
+
+如问题仍未解决，请在 GitHub 提交 Issue，并提供以下信息：
+
+- `sudo systemctl status ssh` 输出
+- `sudo grep -v "^#" /etc/ssh/sshd_config | grep PasswordAuthentication` 输出
+- SSH 日志 `sudo journalctl -u ssh -b --no-pager | tail -30`
+- 完整的连接错误信息

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

@@ -212,3 +212,198 @@ 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 SSH connection fails, follow these steps to diagnose the issue.
+
+### 1. Verify SSH Service is Running
+
+On the device, run:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo systemctl status ssh
+```
+
+</NewCodeBlock>
+
+If the service is not running:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo systemctl start ssh
+sudo systemctl enable ssh
+```
+
+</NewCodeBlock>
+
+:::tip
+On Debian/Ubuntu, `ssh` is an alias for `sshd`. If `ssh` does not work, try `sshd`.
+:::
+
+### 2. Verify Network Connectivity
+
+From your PC, ping the device IP to confirm it is reachable:
+
+<NewCodeBlock tip="PC$" type="host">
+
+```bash
+ping 192.168.x.x
+```
+
+</NewCodeBlock>
+
+If ping fails, check:
+- The device and PC are on the same LAN
+- The IP address is correct (avoid using `127.0.0.1`)
+
+### 3. Check Firewall
+
+Radxa OS uses `nftables` by default. Run the following to confirm port 22 is not blocked:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo iptables -L -n | grep -E "22|ssh"
+sudo nft list ruleset 2>/dev/null | grep -E "22|ssh"
+```
+
+</NewCodeBlock>
+
+To temporarily clear firewall rules for testing:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo iptables -F
+```
+
+</NewCodeBlock>
+
+### 4. Check Password Authentication Configuration
+
+Confirm SSH service allows password authentication:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo grep -v "^#" /etc/ssh/sshd_config | grep PasswordAuthentication
+```
+
+</NewCodeBlock>
+
+Expected output is `PasswordAuthentication yes`. If not, edit the configuration:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo nano /etc/ssh/sshd_config
+```
+
+</NewCodeBlock>
+
+Ensure the following line exists and is uncommented:
+
+```
+PasswordAuthentication yes
+```
+
+Then restart the SSH service:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo systemctl restart ssh
+```
+
+</NewCodeBlock>
+
+### 5. Confirm Username and Password
+
+Radxa OS default username is `radxa`, password is `radxa`. If the password is incorrect, reset it via serial connection or display:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo passwd radxa
+```
+
+</NewCodeBlock>
+
+### 6. Check SSH Logs
+
+View SSH service logs for detailed error information:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+sudo journalctl -u ssh -b --no-pager | tail -30
+```
+
+</NewCodeBlock>
+
+Common errors and their meanings:
+
+| Error Message | Possible Cause |
+|---------------|----------------|
+| `Connection refused` | SSH service not running or port 22 blocked |
+| `Permission denied` | Wrong password or public key authentication failed |
+| `Connection timeout` | Network unreachable or incorrect IP address |
+| `No route to host` | Network layer routing unreachable |
+
+### 7. Windows SSH Client Issues
+
+If using a Windows SSH client and encountering problems:
+
+1. Try [Tabby](https://tabby.sh/), [PuTTY](https://www.putty.org/), or [MobaXterm](https://mobaxterm.mobatek.net/) as alternatives
+2. Check Windows Firewall is not blocking SSH connections
+3. Confirm password authentication is enabled (not public-key-only)
+
+### 8. Public Key Authentication Fails
+
+If you configured SSH public key login but it fails, check server-side permissions:
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+# .ssh directory permissions should be 700
+chmod 700 ~/.ssh
+
+# authorized_keys file permissions should be 600
+chmod 600 ~/.ssh/authorized_keys
+```
+
+</NewCodeBlock>
+
+### 9. Reset SSH Configuration
+
+:::warning
+The following operations will interrupt your current SSH connection. If you are accessing remotely, ensure you have an alternative access method (such as serial connection) before proceeding.
+:::
+
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+
+```bash
+# Backup current configuration
+sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.backup
+
+# Restore default configuration
+sudo dpkg-reconfigure openssh-server
+
+# Restart service
+sudo systemctl restart ssh
+```
+
+</NewCodeBlock>
+
+### Get Help
+
+If the issue persists, please submit a GitHub Issue with the following information:
+
+- Output of `sudo systemctl status ssh`
+- Output of `sudo grep -v "^#" /etc/ssh/sshd_config | grep PasswordAuthentication`
+- SSH logs: `sudo journalctl -u ssh -b --no-pager | tail -30`
+- Complete error message when attempting to connect