架构说明¶

本文档描述了 SSH 隧道管理器的架构，包括 Docker 容器及其交互方式。

系统概述¶

SSH 隧道管理器提供两个 Docker 镜像：

1. autossh-tunnel（必需）- 核心隧道管理容器
2. autossh-tunnel-web-panel（可选）- 基于 Web 的管理界面

graph TB
    subgraph "宿主机"
        SSH[~/.ssh<br/>SSH 密钥和配置]
        CONFIG[./config<br/>config.yaml]
        BROWSER[浏览器]
    end

    subgraph "Docker 容器"
        subgraph "autossh 容器（必需）"
            ENTRY[entrypoint.sh]
            MONITOR[spinoff_monitor.sh]
            CLI[autossh-cli]
            API[API 服务器<br/>:8080]
            WSSERVER[ws-server<br/>:8022]
            AUTOSSH[autossh 进程]
            STATE[状态管理器]
        end

        subgraph "web 容器（可选）"
            WEBSERVER[Go Web 服务器<br/>:5000]
        end
    end

    subgraph "远程服务器"
        REMOTE1[远程主机 1]
        REMOTE2[远程主机 2]
    end

    SSH -->|只读挂载| ENTRY
    CONFIG -->|读写挂载| ENTRY
    BROWSER -->|静态文件| WEBSERVER

    ENTRY --> MONITOR
    MONITOR --> CLI
    CLI --> STATE
    CLI --> AUTOSSH
    API --> CLI
    WSSERVER --> CLI

    BROWSER -->|API + WebSocket| WEBSERVER
    WEBSERVER -->|API 代理| API
    WEBSERVER -->|WS 代理| WSSERVER

    AUTOSSH -->|SSH 隧道| REMOTE1
    AUTOSSH -->|SSH 隧道| REMOTE2

autossh-tunnel 容器¶

镜像： oaklight/autossh-tunnel:latest

使用 autossh 管理 SSH 隧道的核心容器。

组件¶

卷挂载¶

环境变量¶

API 端点（当 API_ENABLE=true 时）¶

最小 Docker Compose 示例¶

name: autotunnel
services:
  autossh:
    image: oaklight/autossh-tunnel:latest
    volumes:
      - ~/.ssh:/home/myuser/.ssh:ro
      - ./config:/etc/autossh/config:rw
    environment:
      - PUID=1000
      - PGID=1000
    network_mode: "host"
    restart: always

启用 API¶

name: autotunnel
services:
  autossh:
    image: oaklight/autossh-tunnel:latest
    volumes:
      - ~/.ssh:/home/myuser/.ssh:ro
      - ./config:/etc/autossh/config:rw
    environment:
      - PUID=1000
      - PGID=1000
      - API_ENABLE=true
      - API_PORT=8080
    network_mode: "host"
    restart: always

autossh-tunnel-web-panel 容器¶

镜像： oaklight/autossh-tunnel-web-panel:latest

可选的基于 Web 的管理界面，与 autossh 容器的 API 通信。

组件¶

卷挂载¶

环境变量¶

Docker Compose 示例¶

name: autotunnel
services:
  web:
    image: oaklight/autossh-tunnel-web-panel:latest
    ports:
      - "5000:5000"
    # 无需配置卷挂载 - Web 面板使用 autossh 容器的配置 API
    environment:
      - TZ=Asia/Shanghai
      # API_BASE_URL 由 Web 服务器用于代理 API 请求（服务端 URL）
      - API_BASE_URL=http://localhost:8080
      - WS_BASE_URL=ws://localhost:8022     # 可选：启用浏览器内交互式认证
    restart: always

完整部署¶

同时使用两个容器时：

name: autotunnel
services:
  autossh:
    image: oaklight/autossh-tunnel:latest
    volumes:
      - ~/.ssh:/home/myuser/.ssh:ro
      - ./config:/etc/autossh/config:rw
    environment:
      - PUID=1000
      - PGID=1000
      - AUTOSSH_GATETIME=0
      - API_ENABLE=true
      - API_PORT=8080
      - WS_PORT=8022          # 可选：启动 ws-server 用于浏览器内交互式认证
    network_mode: "host"
    restart: always

  web:
    image: oaklight/autossh-tunnel-web-panel:latest
    ports:
      - "5000:5000"
    # 无需配置卷挂载 - Web 面板使用 autossh 容器的配置 API
    environment:
      - TZ=Asia/Shanghai
      # API_BASE_URL 由 Web 服务器用于代理 API 请求（服务端 URL）
      - API_BASE_URL=http://localhost:8080
      - WS_BASE_URL=ws://localhost:8022   # 可选：指向 ws-server 以启用终端弹窗
    restart: always

通信流程¶

Web 面板到隧道控制（代理架构）¶

Web 面板使用 代理架构，所有浏览器请求都通过 Go Web 服务器代理到 autossh 后端。这确保了即使 Docker 宿主机在远程机器上，Web 面板也能正常工作。

sequenceDiagram
    participant User as 用户
    participant Browser as 浏览器
    participant WebServer as Go Web 服务器 (:5000)
    participant API as API 服务器 (:8080)
    participant CLI as autossh-cli
    participant Tunnel as autossh 进程

    Note over Browser,WebServer: 初始页面加载
    User->>Browser: 打开 Web 面板
    Browser->>WebServer: GET / (静态文件)
    WebServer-->>Browser: HTML/CSS/JS
    Browser->>WebServer: GET /api/config/api
    WebServer-->>Browser: {ws_enabled}

    Note over Browser,API: API 调用通过 Web 服务器代理
    User->>Browser: 点击"启动隧道"
    Browser->>WebServer: POST /api/autossh/start/{hash}
    WebServer->>API: POST /start/{hash}（反向代理）
    API->>CLI: autossh-cli start-tunnel {hash}
    CLI->>Tunnel: 启动 autossh 进程
    Tunnel-->>CLI: PID
    CLI-->>API: 成功 + 输出
    API-->>WebServer: JSON 响应
    WebServer-->>Browser: JSON 响应
    Browser-->>User: 更新 UI

配置变更检测¶

sequenceDiagram
    participant User as 用户
    participant WebUI as Web UI
    participant Config as config.yaml
    participant Monitor as spinoff_monitor.sh
    participant CLI as autossh-cli
    participant Tunnels as autossh 进程

    User->>WebUI: 保存配置
    WebUI->>Config: 写入 config.yaml
    Monitor->>Config: 检测文件变化 (inotify)
    Monitor->>CLI: autossh-cli start
    CLI->>Tunnels: 智能重启
    Note over CLI,Tunnels: 仅重启变更的隧道

网络模式¶

容器根据其需求使用不同的网络模式：

autossh 容器（Host 网络）¶

autossh 容器使用 network_mode: "host" 以：

1. 允许直接访问宿主机网络接口
2. 使隧道能够绑定到特定 IP 地址
3. 简化端口转发配置

web 容器（Bridge 网络）¶

Web 容器使用 bridge 网络和端口映射：

ports:
  - "5000:5000"

这是可行的，因为：

1. Web 服务器代理所有 API 和 WebSocket 请求到 autossh 后端
2. 浏览器只需访问 Web 面板（端口 5000）
3. API_BASE_URL 和 WS_BASE_URL 是服务端代理 URL，非浏览器可见

文件结构¶

/home/myuser/                    # 容器内
├── .ssh/                        # SSH 密钥和配置（来自宿主机）
│   ├── config                   # SSH 主机配置
│   ├── id_ed25519              # 私钥
│   └── known_hosts             # 已知主机
└── config/                      # 隧道配置（web 容器）
    └── config.yaml             # 隧道定义

/etc/autossh/config/             # autossh 容器内
└── config.yaml                  # 隧道定义

/tmp/                            # 运行时文件
├── autossh_tunnels.state       # 隧道状态跟踪
└── autossh-logs/               # 隧道日志文件
    └── tunnel-{hash}.log       # 每个隧道的日志

安全考虑¶

1. SSH 密钥：以只读方式挂载以防止修改
2. 非 root 用户：容器以 myuser 运行（可通过 PUID/PGID 配置）
3. 状态隔离：每个隧道都有独立的状态和日志
4. API 访问：API 服务器默认仅在 localhost 上可访问（宿主机网络模式）
5. WebSocket 安全：ws-server 默认仅在 localhost 上可访问，建议在非本地环境中使用 wss:// 协议