故障排除¶

本指南帮助您解决使用 SSH 隧道管理器时可能遇到的常见问题。

SSH 连接问题¶

隧道无法建立连接¶

症状：隧道启动失败或立即断开

可能原因和解决方案：

SSH 密钥权限不正确

确保 .ssh 目录及其内容具有适当的权限：

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/*.pub
chmod 644 ~/.ssh/config
chmod 644 ~/.ssh/known_hosts

SSH 配置文件缺失或错误

检查 ~/.ssh/config 文件是否存在并正确配置：

cat ~/.ssh/config

参考 SSH 配置指南进行正确配置。

远程主机无法访问

测试 SSH 连接：

ssh user@remote-host

防火墙阻止连接

检查本地和远程防火墙设置，确保允许 SSH 连接。

权限被拒绝 (Permission Denied)¶

症状：SSH 连接时提示权限被拒绝

解决方案：

确认使用正确的 SSH 密钥：

ssh -i ~/.ssh/id_ed25519 user@remote-host

检查远程服务器的 authorized_keys 文件：

cat ~/.ssh/authorized_keys  # 在远程服务器上执行

确保公钥已添加到远程服务器：

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@remote-host

Docker 相关问题¶

容器无法启动¶

症状：docker compose up 失败

解决方案：

检查 Docker 服务状态：
```
sudo systemctl status docker
```

检查端口冲突：

# 检查 5000 端口（Web 面板）
netstat -tuln | grep 5000

# 检查 8080 端口（API 服务器）
netstat -tuln | grep 8080

# 检查 8022 端口（WebSocket 服务器）
netstat -tuln | grep 8022

查看容器日志：
```
docker compose logs
```

Docker 权限问题¶

症状：运行 Docker 命令时提示权限不足

解决方案：

将用户添加到 docker 组：
```
sudo usermod -aG docker $USER
```
重新登录或运行：
```
newgrp docker
```

文件权限问题¶

症状：容器内无法访问挂载的文件

解决方案：

检查 PUID 和 PGID 设置：

id  # 查看当前用户的 UID 和 GID

在 compose.yaml 中设置正确的值：

environment:
  - PUID=1000  # 替换为您的 UID
  - PGID=1000  # 替换为您的 GID

重启容器：

docker compose down
docker compose up -d

配置问题¶

配置文件格式错误¶

症状：隧道无法启动，日志显示 YAML 解析错误

解决方案：

验证 YAML 语法：

# 使用 Python 验证
python3 -c "import yaml; yaml.safe_load(open('config/config.yaml'))"

检查常见错误：
缩进必须使用空格，不能使用制表符
确保冒号后有空格
字符串值如果包含特殊字符需要用引号包围
参考示例配置：
```
cat config/config.yaml.sample
```

配置更改未生效¶

症状：修改配置后隧道未更新

解决方案：

检查配置文件监控是否正常：

docker compose logs autossh | grep inotify

手动重启服务：
```
docker compose restart autossh
```

验证配置文件路径：

docker compose exec autossh cat /etc/autossh/config/config.yaml

交互式认证问题¶

交互式隧道无法启动¶

症状：运行 autossh-cli auth <hash> 失败或显示错误，或者浏览器终端弹窗无法完成认证

解决方案：

确保使用正确的用户上下文：

auth 命令必须以 myuser 用户身份运行：

docker exec -it -u myuser <容器名称> autossh-cli auth <hash>

如果不使用 -u myuser，可能会看到访问 SSH 配置文件的权限错误。

验证隧道是否标记为交互式：

检查隧道配置中是否有 interactive: true：

docker exec -it autossh-1 autossh-cli show-tunnel <hash>

检查 SSH 主机配置：

确保远程主机在 ~/.ssh/config 中正确配置：

docker exec -it autossh-1 cat /home/myuser/.ssh/config

认证失败¶

症状：2FA 验证码或密码被拒绝

解决方案：

验证凭据：
确保输入正确的 2FA 验证码或密码
检查 2FA 令牌是否已过期（TOTP 验证码有时间限制）
检查 SSH 服务器配置：
验证远程服务器是否支持键盘交互式认证
检查您的账户在远程服务器上是否被锁定或禁用

测试手动 SSH 连接：

docker exec -it -u myuser autossh-1 ssh <远程主机>

交互式隧道认证后显示 STOPPED¶

症状：隧道认证成功但立即显示为 STOPPED

解决方案：

检查隧道日志：

docker exec -it autossh-1 autossh-cli logs <hash>

验证端口可用性：

确保本地/远程端口未被占用：

netstat -tuln | grep <端口号>

检查 SSH 控制套接字：

docker exec -it autossh-1 ls -la /tmp/ssh_control_*

隧道运行问题¶

隧道频繁断开重连¶

症状：隧道不稳定，频繁断开

解决方案：

检查网络连接稳定性

调整 autossh 参数：

environment:
  - AUTOSSH_GATETIME=30  # 增加连接稳定时间

检查远程服务器负载和网络状况

端口已被占用¶

症状：隧道启动失败，提示端口已被使用

解决方案：

查找占用端口的进程：

# Linux
sudo lsof -i :端口号

# 或使用
sudo netstat -tulpn | grep 端口号

停止占用端口的进程或更改隧道配置使用其他端口

无法访问隧道服务¶

症状：隧道显示运行中，但无法访问服务

解决方案：

检查隧道方向：
local_to_remote：在远程服务器上访问
remote_to_local：在本地机器上访问

验证端口绑定：

# 在相应的机器上检查端口监听
netstat -tuln | grep 端口号

检查防火墙规则：

# 查看防火墙状态
sudo ufw status  # Ubuntu/Debian
sudo firewall-cmd --list-all  # CentOS/RHEL

测试连接：

# 本地测试
curl http://localhost:端口号

# 远程测试
curl http://远程主机:端口号

Web 面板问题¶

无法访问 Web 面板¶

症状：浏览器无法打开 http://localhost:5000

解决方案：

检查 Web 容器状态：
```
docker compose ps web
```
查看 Web 容器日志：
```
docker compose logs web
```
验证端口映射：
```
docker compose port web 5000
```

如果使用了 PORT 环境变量自定义端口，请确保端口映射与 PORT 值一致：

environment:
  - PORT=3000
ports:
  - "3000:3000"   # 必须与 PORT 值匹配

检查 API 连接：

# 在 compose.yaml 中确认 API_BASE_URL 设置正确
docker compose exec web env | grep API_BASE_URL

Web 面板显示空白或错误¶

症状：Web 面板加载但显示异常

解决方案：

清除浏览器缓存
检查浏览器控制台错误（F12）
验证 API 服务器是否运行：
```
curl http://localhost:8080/status
```

交互式认证终端弹窗无法打开¶

症状：点击交互式隧道的启动/重启按钮时，没有弹出终端弹窗

解决方案：

确认 WebSocket 已配置：

检查 Web 面板容器是否设置了 WS_BASE_URL 环境变量：

docker compose exec web env | grep WS_BASE_URL

确认 ws-server 已启动：

检查 autossh 容器是否设置了 WS_PORT 环境变量：

docker compose exec autossh env | grep WS_PORT

检查 ws-server 端口是否可访问：

# 默认端口为 8022
netstat -tuln | grep 8022

检查浏览器控制台：

打开浏览器开发者工具（F12），查看 Console 和 Network 标签中是否有 WebSocket 连接错误。

终端弹窗连接失败¶

症状：终端弹窗打开但显示连接错误或无法输入

解决方案：

验证 WS_BASE_URL 地址格式：

确保使用正确的协议前缀：

# 正确
- WS_BASE_URL=ws://localhost:8022

# 如果使用 TLS
- WS_BASE_URL=wss://localhost:8022

检查防火墙规则：

确保 WebSocket 端口（默认 8022）未被防火墙阻止。

检查 autossh 容器日志：

docker compose logs autossh | grep ws-server

测试 WebSocket 连接：

在浏览器开发者工具的 Console 中：

const ws = new WebSocket('ws://localhost:8022');
ws.onopen = () => console.log('Connected');
ws.onerror = (e) => console.log('Error', e);

API 问题¶

API 请求失败¶

症状：CLI 命令或 HTTP API 请求返回错误

解决方案：

确认 API 已启用：
```
environment:
  - API_ENABLE=true
```
检查 API 服务器日志：
```
docker compose logs autossh | grep api
```
测试 API 连接：
```
curl http://localhost:8080/list
```

日志和调试¶

查看日志¶

# 查看所有容器日志
docker compose logs

# 查看特定容器日志
docker compose logs autossh
docker compose logs web

# 实时跟踪日志
docker compose logs -f

# 查看最近 100 行日志
docker compose logs --tail=100

进入容器调试¶

# 进入 autossh 容器
docker compose exec autossh sh

# 进入 web 容器
docker compose exec web sh

# 在容器内检查进程
ps aux

# 检查网络连接
netstat -tuln

启用详细日志¶

在 compose.yaml 中添加调试环境变量：

environment:
  - DEBUG=true
  - VERBOSE=true

性能问题¶

容器占用资源过高¶

解决方案：

检查资源使用情况：
```
docker stats
```

限制容器资源：

services:
  autossh:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

清理未使用的 Docker 资源：
```
docker system prune -a
```

获取帮助¶

如果以上方法都无法解决您的问题：

查看项目文档：
快速入门
架构说明
API 文档
提交 Issue：访问 GitHub Issues 提交问题
提供信息：
操作系统和版本
Docker 和 Docker Compose 版本
完整的错误日志
配置文件内容（隐藏敏感信息）
重现问题的步骤