ternssh 详细部署教程

ternssh 是一个基于 Web 的 SSH 管理工具，它可以运行在 Cloudflare Workers 上，让您通过浏览器即可安全访问和管理 SSH 服务器。它提供了终端、SFTP 文件管理和状态监控等功能。

本教程将指导您通过 Docker（推荐方式）和 Cloudflare Workers 两种方式进行部署。

1. 准备工作

1.1 部署前准备

Docker 部署：需要安装 Docker 和 Docker Compose。
Cloudflare Workers 部署：需要一个 Cloudflare 账户，并安装好 Wrangler CLI 工具。
目标 SSH 服务器：确保您有可访问的 SSH 服务器地址、端口、用户名和密码/密钥。

1.2 获取项目文件 (可选)

如需从源码构建，可克隆项目：

1 2	git clone https://github.com/HaradaKashiwa/ternssh.git cd ternssh

2. 使用 Docker 部署（推荐）

这是最快捷的启动方式，适合个人或小团队快速搭建。

2.1 使用预构建镜像（最简单）

在终端中执行以下命令，即可一键启动：

docker run -d \
  --name ternssh \
  -p 8787:8787 \
  -v ternssh-data:/app/.wrangler \
  --restart unless-stopped \
  ghcr.io/haradakashiwa/ternssh:latest

-p 8787:8787：将容器的 8787 端口映射到主机的 8787 端口。
-v ternssh-data:/app/.wrangler：创建一个数据卷，用于持久化存储配置和状态。
--restart unless-stopped：设置容器在退出时自动重启。

2.2 使用 Docker Compose

项目提供了 docker-compose.ghcr.yml 文件，更便于管理。

创建 docker-compose.ghcr.yml 文件，内容参考项目根目录下的示例。

在文件所在目录执行：

1	docker compose -f docker-compose.ghcr.yml up -d

2.3 从源码构建镜像

如果您想使用最新源码或进行二次开发，可以构建自己的镜像：

1	docker compose up -d --build

2.4 验证与访问

启动成功后，打开浏览器访问 http://localhost:8787，即可看到 ternssh 的 Web 界面。

3. 部署到 Cloudflare Workers

这种方式可以让您利用 Cloudflare 的全球网络，获得更低的延迟和更高的可用性。

3.1 安装 Wrangler CLI

如果您尚未安装，请参考 Cloudflare Workers 官方文档进行安装。

3.2 配置项目

在项目根目录下，复制示例配置文件：

1	cp wrangler.production.jsonc.example wrangler.jsonc

编辑 wrangler.jsonc 文件，配置您的 Cloudflare 账户信息（如 account_id）和项目名称。
（可选）根据需要设置环境变量，例如 ACCESS_TEAM_DOMAIN 和 ACCESS_AUD 以启用 Cloudflare Access 认证。

3.3 部署

在项目目录下执行部署命令：

1	npx wrangler deploy

部署完成后，Wrangler 会输出一个 *.workers.dev 的域名，您可以通过该域名访问您的 ternssh 服务。

4. 基本配置与使用

4.1 连接到 SSH 服务器

打开 ternssh 的 Web 界面。
在连接面板中输入您的 SSH 服务器信息：
- Host：服务器 IP 或域名。
- Port：SSH 端口（默认为 22）。
- Username：登录用户名。
- 认证方式：支持密码或 SSH 密钥（粘贴私钥内容）。
点击连接，即可打开一个新的终端标签页。

4.2 功能概览

Draggable Dashboard (可拖拽仪表盘)：您可以自由调整和管理多个终端、SFTP 窗口的布局。
Terminal (终端)：提供完整的远程命令行操作体验。
SFTP：通过图形化界面进行文件上传、下载和管理。
Status Monitoring (状态监控)：查看服务器的基本运行状态。

4.3 启用 Cloudflare Access 认证（可选）

如果您将 ternssh 部署在 Cloudflare Workers 上，并希望使用 Cloudflare Access 进行身份验证，需要在部署时设置以下环境变量：

ACCESS_TEAM_DOMAIN：您的 Cloudflare Access 团队域名。
ACCESS_AUD：您的 Cloudflare Access 应用程序的 Audience (受众) 标签。
设置后，用户在访问 ternssh 前将被重定向到 Cloudflare Access 登录页面。

5. 配置与运维参考

5.1 Docker 部署的更新

# 停止并移除旧容器
docker stop ternssh
docker rm ternssh

# 拉取最新镜像并重新运行（使用之前的 run 命令）
docker pull ghcr.io/haradakashiwa/ternssh:latest
docker run -d ... (与之前相同的参数)

5.2 查看日志

Docker：docker logs ternssh -f
Cloudflare Workers：通过 Cloudflare 仪表盘或 Wrangler 命令查看。

5.3 数据持久化

Docker 部署中，使用 -v ternssh-data:/app/.wrangler 创建的数据卷会保存您的配置和会话数据。您可以通过 docker volume inspect ternssh-data 查看其实际存储位置。

6. 常见问题与提示

无法连接到 SSH 服务器：请检查服务器地址、端口和防火墙设置，确保 ternssh 容器或 Workers 环境能够访问到目标 SSH 服务。
认证失败：确认用户名、密码或私钥内容是否正确。如果使用密钥，请确保粘贴了完整的私钥（包括 -----BEGIN OPENSSH PRIVATE KEY----- 等头部信息）。
WebSocket 连接错误：ternssh 依赖 WebSocket 进行实时通信。请确保您的网络环境（如代理、防火墙）允许 WebSocket 连接，或检查 Cloudflare Workers 的路由配置。
字体或图标显示异常：尝试清除浏览器缓存或使用隐私/无痕模式访问。