Web 面板使用指南¶

Web 面板提供了一个可视化界面来管理 SSH 隧道配置，无需手动编辑 YAML 文件。

网页面板界面（浅色主题）

网页面板界面（深色主题）

功能特性¶

可视化配置编辑：通过友好的界面查看和编辑隧道配置
自动备份：每次保存更改时自动备份配置到 autossh 容器的 config/backups/ 目录
实时更新：配置更改后自动重载隧道，无需重启容器
多语言支持：支持中文、英文等多种语言
隧道状态监控：实时查看每个隧道的运行状态
单个隧道控制：独立启动、停止每个隧道
浏览器内交互式认证：通过 xterm.js 终端弹窗在浏览器中直接完成密码和 2FA/TOTP 认证，无需使用 CLI
深色/浅色主题：支持深色和浅色两种主题，并提供配色方案选择器
API 代理架构：所有 API 请求通过 Web 面板服务器代理到 autossh 后端，支持远程访问
无需配置卷挂载：Web 面板不再需要访问配置文件 - 所有操作通过 API 完成

访问 Web 面板¶

启动服务后，在浏览器中访问：

http://localhost:5000

如果您通过 PORT 环境变量修改了 Web 面板的监听端口，请使用相应的端口号。

界面说明¶

主页面¶

主页面以可编辑表格形式显示所有配置的隧道：

列	描述
控制	每行操作按钮：保存并重启、启动、重启、停止
名称	可编辑的隧道名称字段
状态	状态指示器图标（点击可打开隧道详情页）
远程主机	可编辑的远程主机字段
远程端口	可编辑的远程端口字段
本地端口	可编辑的本地端口字段
方向	选择隧道方向的下拉菜单
操作	交互认证切换和删除按钮

状态指示器：

🟢 绿色勾选：运行中
🔴 红色叉号：已停止/错误
🟠 橙色沙漏：启动中/加载中
⚪ 灰色停止：已停止

添加隧道¶

点击页面底部的"添加"按钮
表格中会出现一个新的空行
直接在表格中填写隧道配置：
名称：隧道的自定义名称
远程主机：SSH 主机配置名称（如 user@remote-host）
远程端口：远程服务器上的端口（支持 端口 或 主机名:端口 格式）
本地端口：本地机器上的端口（支持 端口 或 IP:端口 格式）
方向：选择 远程到本地 或 本地到远程
点击该行的"保存"按钮（💾）或全局的"保存并重启"按钮

编辑隧道¶

隧道可以直接在表格中编辑：

在隧道列表中找到要编辑的隧道
直接在表格行中修改配置字段
点击该行的"保存"按钮（💾）仅保存并重启该隧道
或点击全局的"保存并重启"按钮保存所有更改并重启所有隧道

单行保存

单行保存按钮（💾）允许您保存并重启单个隧道，而不影响其他隧道。当您只需要修改一个隧道时，这非常有用。

删除隧道¶

在隧道列表中找到要删除的隧道
点击"删除"按钮
确认删除操作

启动/停止隧道¶

每个隧道行都有控制按钮：

启动（▶️）：启动隧道
重启（🔄）：停止并重启隧道
停止（⏹️）：停止隧道

交互认证

点击指纹图标（🫆）可以切换交互认证模式。启用时（绿色），隧道需要进行密码或 2FA/TOTP 认证。

浏览器内认证（推荐）：当配置了 WebSocket 服务器（WS_BASE_URL）时，交互式隧道的启动/重启按钮会显示一个终端图标徽标。点击后会弹出一个 xterm.js 终端弹窗，您可以直接在浏览器中完成密码和 2FA 认证。认证成功后，弹窗会自动关闭，隧道状态随即刷新。

CLI 认证（备选）：如果未配置 WebSocket，您可以使用 CLI 命令进行认证：

docker compose exec -it -u myuser autossh autossh-cli auth <hash>

详情请参阅 CLI 参考 - 交互式认证。

隧道详情页¶

点击任意行的状态指示器图标可以打开该隧道的详情页面。

隧道详情页（浅色主题）

隧道详情页（深色主题）

详情页面提供：

完整配置视图：查看所有隧道设置
实时日志：查看隧道日志，支持自动刷新
控制按钮：启动、重启、停止隧道
交互式认证徽标：交互式隧道的启动/重启按钮带有终端图标，点击可打开终端弹窗
配置编辑：直接修改隧道设置
自动刷新：状态和日志每 5 秒自动更新

深色/浅色主题¶

Web 面板支持深色和浅色两种主题模式。您可以通过页面上的配色方案选择器切换主题。主题偏好会保存在浏览器本地存储中，下次访问时自动应用。

浏览器内交互式认证（终端弹窗）¶

当 WebSocket 服务器配置完成后，交互式隧道支持直接在浏览器中进行认证：

在隧道列表或详情页中，交互式隧道的启动和重启按钮会显示一个终端图标（🖥️）徽标
点击带有徽标的启动/重启按钮，会弹出一个 xterm.js 终端弹窗
终端通过 WebSocket 连接到 autossh 容器中的 ws-server
在终端中输入密码和/或 2FA/TOTP 验证码完成认证
认证成功后，终端弹窗自动关闭，隧道状态自动刷新

WebSocket 配置要求

要使用浏览器内交互式认证功能，需要同时配置：

autossh 容器：设置 WS_PORT 环境变量（默认值：8022）以启动 ws-server
Web 面板容器：设置 WS_BASE_URL 环境变量指向 ws-server 的可访问地址

详见下方 WebSocket 配置章节。

WebSocket 配置¶

WebSocket 服务器（ws-server）用于在浏览器中提供交互式认证终端。它运行在 autossh 容器内部，通过 WebSocket 协议与浏览器中的 xterm.js 终端进行通信。

环境变量¶

变量	容器	描述	默认值
`WS_PORT`	autossh	ws-server 的监听端口	`8022`
`WS_BASE_URL`	web	ws-server 的可访问地址（传递给浏览器）	未设置

配置示例¶

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
      - WS_PORT=8022        # 启动 ws-server，监听端口 8022
    network_mode: "host"
    restart: always

  web:
    image: oaklight/autossh-tunnel-web-panel:latest
    ports:
      - "5000:5000"
    environment:
      - TZ=Asia/Shanghai
      # API_BASE_URL 由 Web 服务器用于代理 API 请求到 autossh 后端
      # 这是一个服务端 URL，浏览器不会直接访问
      - API_BASE_URL=http://localhost:8080
      - WS_BASE_URL=ws://localhost:8022   # 指向 ws-server
    restart: always

WS_BASE_URL 格式

WS_BASE_URL 应使用 ws:// 或 wss://（TLS）协议前缀，指向 autossh 容器上 ws-server 的可访问地址。由于 autossh 容器通常使用 host 网络模式，地址一般为 ws://localhost:8022。

不配置 WebSocket

如果不设置 WS_PORT 和 WS_BASE_URL，WebSocket 功能将不会启用。交互式隧道仍然可以通过 CLI 的 autossh-cli auth 命令进行认证。

PORT 环境变量¶

Web 面板默认监听 5000 端口。您可以通过 PORT 环境变量自定义监听端口：

services:
  web:
    image: oaklight/autossh-tunnel-web-panel:latest
    ports:
      - "3000:3000"       # 端口映射需与 PORT 一致
    environment:
      - PORT=3000         # 自定义监听端口
      - API_BASE_URL=http://localhost:8080
    restart: always

配置备份¶

Web 面板每次保存更改时会自动创建配置备份：

备份位置：config/backups/
备份格式：config.yaml.backup.YYYYMMDD_HHMMSS
备份管理：需要手动清理旧备份以防止磁盘空间问题

恢复备份¶

如果需要恢复之前的配置：

# 查看可用备份
ls -la config/backups/

# 恢复特定备份
cp config/backups/config.yaml.backup.20240115_143022 config/config.yaml

# 重启服务以应用恢复的配置
docker compose restart autossh

高级配置¶

指定绑定地址¶

在 Web 面板中，您可以使用 ip:port 格式来指定绑定地址：

远程端口绑定到特定 IP：

远程端口: 192.168.45.130:22323

本地端口绑定到特定 IP：

本地端口: 192.168.1.100:18120

使用 SSH 配置别名¶

在"远程主机"字段中，您可以使用 ~/.ssh/config 中定义的主机别名：

远程主机: myserver

这将使用 SSH 配置文件中 myserver 的配置。

故障排除¶

Web 面板无法访问¶

检查容器是否运行：
```
docker compose ps
```
检查端口是否被占用：
```
netstat -tuln | grep 5000
```
查看 Web 面板日志：
```
docker compose logs web
```

配置保存后隧道未更新¶

检查 autossh 容器日志：
```
docker compose logs autossh
```
验证配置文件格式：
```
cat config/config.yaml
```
手动重启 autossh 服务：
```
docker compose restart autossh
```

备份目录占用过多空间¶

定期清理旧备份：

# 删除 7 天前的备份
find config/backups/ -name "*.backup.*" -mtime +7 -delete

# 或只保留最近 10 个备份
cd config/backups/
ls -t | tail -n +11 | xargs rm -f

架构说明¶

Web 面板使用 代理架构，Go Web 服务器作为反向代理转发 API 和 WebSocket 请求：

静态文件服务器：Go Web 服务器（默认端口 5000，可通过 PORT 环境变量自定义）提供 HTML、CSS 和 JavaScript 文件
API 代理：浏览器的所有 API 调用通过 Web 服务器的 /api/autossh/* 路径代理到 autossh 后端（API_BASE_URL）
- Config API：获取、创建、更新和删除隧道配置
- Control API：启动、停止和重启隧道
- Status API：获取隧道状态和日志
WebSocket 代理（可选）：当配置了 WS_BASE_URL 时，Web 服务器代理浏览器的 WebSocket 连接到 autossh 容器中的 ws-server 进行交互式认证

这种架构提供：

远程访问支持：Web 面板可从任意浏览器访问，即使 Docker 宿主机在远程机器上
单一入口点：浏览器只需访问端口 5000
简化网络配置：Web 容器不需要 host 网络模式或配置卷挂载
单一数据源：配置仅由 autossh 容器管理

+-------------------+     +-------------------+     +-------------------+
|      Browser      |---->|   Web Container   |---->| autossh Container |
|    (Frontend)     |     | (API + WS Proxy)  |     |  (Config API +    |
|                   |     |      :5000        |     |   ws-server)      |
+-------------------+     +-------------------+     +-------------------+
  所有请求都经过             /api/autossh/* ------>    :8080
  :5000                     /ws/auth/{hash} ----->    :8022

网络要求

浏览器只需访问 Web 面板（端口 5000）。Web 服务器会将所有 API 和 WebSocket 请求代理到 autossh 后端。API_BASE_URL 和 WS_BASE_URL 是服务端 URL，浏览器不会直接访问。

无需配置卷挂载

Web 容器不再需要配置卷挂载。所有配置操作都通过 autossh 容器的 Config API 完成。

安全建议¶

限制访问：默认情况下，Web 面板只监听 localhost。如果需要远程访问，请使用 SSH 隧道或 VPN。
使用防火墙：确保 Web 面板端口（默认 5000）、API 端口（默认 8080）和 WebSocket 端口（默认 8022）不对公网开放。
启用 API 认证：在 autossh 容器上设置 API_KEY 环境变量以要求 API 调用进行认证。
定期备份：虽然 Web 面板会自动备份，但建议定期手动备份重要配置。
审查更改：在保存配置前仔细检查，避免意外中断现有隧道。

下一步¶

了解 CLI 命令进行命令行管理
查看 HTTP API 进行程序化控制
阅读架构说明了解系统工作原理