Docker 问题

Docker 面板会明确说出是哪一种失败，下面每一种状态都对应一个修法。 SwiftServer 通过 SSH 连到引擎，走的是 socket 转发或 CLI 隧道， 因此大多数问题出在 socket 的访问权限上，而不是 Docker 本身。

「Docker socket 权限不足」

你的 SSH 用户读不到 Docker socket。在服务器上执行 Docker 标准的安装后步骤：

sudo usermod -aG docker <your-user>

退出登录再重新登录（或者运行 newgrp docker），然后确认：

docker ps

只要 docker ps 不加 sudo 也能跑通，SwiftServer 就能连上。SwiftServer 从不自动加 sudo， 「我在终端里加 sudo 就能用」说的正是这种情况。rootless Docker 会被自动支持。

「无法访问 Docker 守护进程」

Docker 已安装，但没有运行：

sudo systemctl start docker     # server distros

桌面系统上则启动 Docker Desktop / Colima / OrbStack，然后点重试。

「未安装 Docker」

既没有找到 socket，也没有找到命令行。如果你的引擎装在不常见的位置， SwiftServer 会读取该 SSH 用户的 DOCKER_HOST 和 DOCKER_CONTEXT， 并探测 rootless、Colima、OrbStack 和 Rancher Desktop 的 socket 路径。

徽章显示「CLI 隧道」而不是「Socket：…」

这不是错误，面板功能完整。它表示 socket 转发被拒绝了（最常见的原因是 sshd_config 里禁用了 AllowStreamLocalForwarding），于是 SwiftServer 退回到通过服务器上的 docker 命令行中转。连接日志里的 Effective socket failed: 那一行记录着服务器 给出的确切拒绝原因。想升级到更快的 socket 模式，按连接模式 走一遍，然后重新连接。

「不支持 Docker 守护进程 API 版本 …」

引擎版本太旧，面板用不了：把 Docker 升级到当前版本。

Compose 项目缺失或操作失败

项目是从这台机器上的容器标签里发现的：在别处启动的项目，或者容器已经被删掉的项目， 要等你在这台机器上跑过一次 docker compose up 才会出现。SwiftServer 用的是新版 docker compose 插件，不支持旧的独立 docker-compose 程序。

Windows 服务器

Windows 上的 Docker 通过命名管道暴露引擎，而 OpenSSH 无法转发命名管道， 因此 Windows 机器上没有 Docker 面板。

该发什么

面板上错误标题的原文、服务器的操作系统，以及下面这几条命令的输出：

docker version
id
ls -l /var/run/docker.sock

请在终端会话里以同一个 SSH 用户的身份运行。这三行几乎能定位所有 Docker 连接问题。