一个基于 Cloudflare Workers 的 Serverless Web SSH 终端：通过浏览器直接连接和管理你的服务器。

极致轻量 · 开箱即用 · 赛博朋克 UI

核心优势 · 功能特性 · 部署指南 · 架构设计 · 更新日志 · 贡献者 · 开源协议

简体中文 | English

想象一下，随时随地打开浏览器，就能以极具科技感的赛博朋克 UI 连接你的服务器，无需安装任何 SSH 客户端。

_{视频时长 8:27 · 演示 CloudSSH 完整使用流程}

• 核心优势
• 核心特性
• 架构说明
• 快速部署
  • GitHub 绑定自动部署
  • 本地命令行部署
  • 配置 Turnstile
  • 配置 GitHub OAuth
• 开发说明
  • 本地开发
  • 技术栈
• 贡献者
• 开源协议

• 零服务器成本：纯前端部署 + Cloudflare Workers，无需自建后端服务器。
• 边缘加速：得益于 Cloudflare 的全球边缘网络，随时随地享受低延迟的 SSH 连接。

• 一键部署：通过 Wrangler 工具，一句命令即可完成项目构建与部署。
• 现代化前端技术栈：TypeScript + Vite + Tailwind CSS，配合 xterm.js 提供丝滑的终端体验。

• 分段加密传输：浏览器与 Cloudflare Worker 之间使用 HTTPS/WSS，Worker 与目标主机之间使用完整的 SSH-2.0 协议；SSH 段支持 Curve25519-SHA256（优先）和 ECDH-NISTP256 密钥交换、AES-256-GCM（优先）/ AES-128-GCM / AES-256-CTR 数据加密，以及 HMAC-SHA2-256/512 完整性校验。
• 多算法主机密钥验证：支持 Ed25519、ECDSA P-256/P-384/P-521、RSA 签名验证，首次连接展示 SHA-256 指纹（TOFU 模式）。
• 安全加固体系：内置针对 IPv6 与保留地址的 SSRF 防护；/api/ssh 使用有界的 Worker 实例内存限流进行流量削峰，连接授权仍由 Turnstile 或一次性连接令牌负责；已保存的服务器凭据在每用户 Durable Object SQLite 中使用 AES-256-GCM 加密存储。
• 人机验证：支持 Cloudflare Turnstile 验证，防止恶意机器人滥用。
• 隔离的会话状态：每个 SSH 终端会话由独立的 Cloudflare Durable Object 管理；浏览器侧 WebSocket 使用 Hibernation API 接入方式，但活动的 SSH 出站 TCP 连接会使该 Durable Object 在会话期间保持唤醒。
• 已保存凭据内部流转：一键连接已保存服务器时，凭据由 UserDBDO 在服务端解密，并通过一次性连接令牌在 Worker 与 SSHSessionDO 之间传递；浏览器不会收到明文凭据。匿名连接或首次保存服务器时，用户输入仍会通过 HTTPS/WSS 发送到 Worker。

• 纯 TypeScript SSH-2.0 实现：完全自研的 SSH 协议栈，不依赖任何第三方 SSH 库，基于 Web Crypto API 实现全部加密操作。
• 多算法密钥交换：支持 Curve25519-SHA256（优先）和 ECDH-NISTP256 两种 KEX 算法，适配各类 SSH 服务器（包括 Dropbear）。
• IPv4/IPv6 双栈：完整支持 IPv4 和 IPv6 地址连接，包括 IPv6 方括号格式自动处理。
• 多种认证方式：支持标准 SSH 密码认证，以及 OpenSSH 格式的 Ed25519、ECDSA P-256/P-384/P-521 和 RSA 私钥认证；RSA 默认使用 RSA-SHA2-256/512，只有显式兼容配置才允许旧 ssh-rsa SHA-1。
• 防范中间人攻击 (TOFU)：首次连接自动提取服务器 Host Key（SHA-256 指纹）并显示，支持 Ed25519/ECDSA/RSA 签名验证，并在本地及 API 持久化缓存已知主机指纹以防范二次连接的欺骗风险。
• 全功能极客终端：基于 @xterm/xterm 与 @xterm/addon-webgl 硬件加速渲染引擎，保证海量日志输出顺滑不卡顿。
• 个性化 UI：全站颜色基于 CSS 变量系统，提供 Standard Dark、Standard Light、Cyberpunk、Glacier、Gruvbox 五款内置主题一键切换。配套可视化主题编辑器使用下拉框选择预设主题，支持实时调色预览（覆盖登录页、服务器列表、终端 + SFTP、AI Agent 面板）、导出 JSON 主题文件；登录用户可一键同步至云端并跨浏览器生效。支持移动端适配。
• SFTP 图形化文件管理：集成完整的 SFTP v3 文件传输协议，提供图形化文件浏览器界面。支持目录浏览、文件上传/下载、新建文件夹、文件重命名与删除等操作；支持普通单选、Cmd/Ctrl 切换选择、Shift 连选、全选，以及批量下载文件和批量删除。基于 SSH 子系统实现，与终端会话并行运行，互不干扰，支持下载队列及上传取消。
• 原生文件传输：集成 trzsz.js，支持 trz（上传）/ tsz（下载）命令进行文件传输，兼容 tmux 会话。还支持拖拽文件到终端窗口直接上传、目录传输及断点续传等高级功能。（需远程服务器安装 trzsz）
• GitHub OAuth 集成：支持 GitHub 登录，用户可保存和管理常用 SSH 服务器，实现一键连接；服务器支持最多 10 个规范化标签，列表可按名称、主机地址、用户名即时搜索并按标签筛选，每页固定展示 9 张服务器卡片。
• 单页面多标签会话管理：支持在单个页面内开启与切换多个独立的 SSH 终端与 SFTP 文件管理器，各会话环境和状态完全隔离，并在个性化主题编辑器中进行了联动适配。
• 安全匿名历史记录：本地存储最近 5 条匿名连接，且敏感凭证可选使用本地派生的密钥进行 AES-256-GCM 安全加密存储至 localStorage，提供一键回填与清除。
• 双段延迟与 Colo 展示：状态栏即时且周期性地展示当前 RTT（客户端至 Cloudflare）、物理延迟（Cloudflare 至主机）以及 Cloudflare 当前服务的数据中心代码（如 CF-LAX），并通过绿、黄、红三色状态点提示网络质量。
• 智能区域调度（locationHint）：保存服务器时通过 IPinfo 查询目标主机的地理信息并持久化 DO 部署区域，连接时直接读取数据库，不再执行外部地理查询；查询失败时自动退化为 Cloudflare 默认调度，也可手动覆盖区域偏好。注意：自动推断会把目标主机信息发送给第三方 IPinfo；locationHint 是 Cloudflare 的 best-effort 特性，当目标区域 DO 容量不足时会 fallback 到最近可用区域。
• 终端文本检索：支持使用快捷键 Ctrl+Shift+F 呼出搜索框，实时检索终端历史日志。
• 终端日志一键导出：支持通过顶栏的下载按钮，将当前活跃会话终端的完整屏幕历史 buffer 一键导出并下载为 .txt 文本文件，解决长日志在浏览器下鼠标选取容易卡顿的痛点。
• AI 智能助手：内置 AI Agent 侧边栏，支持 BYOK（自带 API Key）接入 OpenAI 兼容接口（如 DeepSeek）。提供 8 个专业运维工具：执行命令、读取终端上下文、探测服务器环境、进程列表、systemctl 服务管理、Docker 容器管理、用户确认、结构化报告输出。选择终端内容后可在选区末端点击“询问 AI 助手”，将完整选区作为当前标签独立的待发送上下文附件；附件支持来源和行数展示、展开预览、替换与移除，只有用户补充问题后才会发送。终端选区会被明确标记为非可信分析数据，不代表操作授权，也不能覆盖用户指令。Agent 代码块支持一键复制，安全的 Shell 单行命令可填入当前终端且不会自动执行。支持 LLM 流式输出（逐字显示），危险命令自动拦截或通过默认拒绝的安全对话框确认。思考过程容器：多步骤任务执行时，实时预览最近 1-2 条命令，完成后自动折叠显示总步骤数，支持展开查看完整执行历史。
• 工程质量门禁：GitHub Actions 在 test 与 main 分支部署前依次执行冻结锁文件安装、Worker/前端类型检查、单元与集成测试、可复现前端构建、Playwright 浏览器 E2E 和 axe 无障碍回归；任一环节失败都会阻止部署。

flowchart TB
    subgraph "浏览器客户端"
        UI["前端 UI<br/>TypeScript + xterm.js"]
        SFTP["SFTP 文件管理器"]
        Agent["AI 智能助手"]
        Trzsz["trzsz 文件传输"]
    end

    subgraph "Cloudflare Edge Network"
        Worker["Worker<br/>路由 + API"]
        SSH_DO["SSHSessionDO<br/>SSH 会话管理"]
        User_DO["UserDBDO<br/>用户数据管理"]
        AgentCore["AgentCore<br/>AI 控制循环"]
    end

    subgraph "目标服务器"
        SSH["SSH 服务器<br/>(OpenSSH/Dropbear)"]
    end

    UI <-->|"WebSocket<br/>终端 I/O"| Worker
    SFTP <-->|"WebSocket<br/>SFTP 数据"| Worker
    Agent <-->|"WebSocket<br/>Agent 消息"| Worker
    Trzsz <-->|"trzsz 协议"| UI
    Worker <-->|"WebSocket"| SSH_DO
    Worker <-->|"Internal API"| User_DO
    SSH_DO <-->|"TCP Socket<br/>@cloudflare/sockets"| SSH
    SSH_DO <-->|"Exec Channel"| AgentCore
    AgentCore <-->|"LLM API"| External["外部 LLM 服务"]

本项目实现了完整的 SSH-2.0 协议栈：

1. 用户在前端输入主机 IP、账号和密码（或通过 GitHub OAuth 选择已保存的服务器）。
2. 前端与后端的 Durable Object 建立 WebSocket 连接。
3. SSHSessionDO 接收凭据，使用 @cloudflare/sockets 与目标 SSH 服务器建立 TCP 连接。
4. SSHSession 执行完整的 SSH 协议协商（版本交换→密钥交换→认证→打开通道→PTY→Shell）。
5. 终端数据在浏览器与 Worker 之间通过 WSS 传输，在 Worker 与目标服务器之间通过 SSH 加密传输；Worker 负责两段协议之间的转发和 SSH 协议处理。
6. SFTP 文件管理通过独立的 SSH 子系统通道运行，支持目录浏览、文件上传/下载等操作。
7. AI 助手通过 WebSocket 接收用户问题及可选的终端选区上下文；选区被标记为非可信分析数据后交给 AgentCore，后者调用外部 LLM API，通过 SSH exec 通道执行获准的命令，并将结果流式返回前端。

• 一个 Cloudflare 账号。
• Node.js 22 环境（与项目 CI 保持一致）。
• 启用 Cloudflare Workers 免费计划（TCP Sockets 和 Durable Objects 功能需要）。

点击按钮跳转至 Cloudflare 控制台，授权 GitHub 后即可自动完成部署（无需本地环境）

1. Fork 本仓库 到你的 GitHub 账号。
2. 创建 Worker 应用：登录 Cloudflare，进入 Workers & Pages，点击创建应用，绑定你的 GitHub 账号，选择 Fork 的仓库。
3. 填写构建命令：在部署设置中，将"构建命令"（Build command）填写为 pnpm run build:frontend，点击保存并部署。
4. 访问应用：部署成功后，可通过默认域名 https://cloudssh.<你的子域>.workers.dev 访问。
5. 绑定自定义域名（可选）：进入 Worker 的 Settings → Domains & Routes → Add，输入你的域名并确认。

说明：如需部署 test 环境，可 Fork 后在 test 分支上重复上述步骤，创建独立的 Worker（如 cloudssh-test）。两个环境的 Durable Objects 数据完全隔离，各自独立。

1. 克隆仓库

   git clone https://github.com/newbietan/CloudSSH.git
   cd CloudSSH

2. 安装依赖

   npm install -g pnpm
   pnpm install
   cd frontend && pnpm install

3. 登录 Cloudflare

   npx wrangler login

4. 部署生产环境

   pnpm run deploy

5. 部署测试环境（可选）

   pnpm run deploy:test

说明：两个环境的 Durable Objects 虽然绑定相同的 class_name，但因 Worker 名称不同，数据完全隔离。部署完成后可在 Cloudflare Dashboard 中分别绑定不同的自定义域名（Settings → Domains & Routes）。

为防止恶意机器人滥用，建议启用 Cloudflare Turnstile 验证：

1. 创建 Turnstile Widget：登录 Cloudflare Dashboard，进入 Turnstile 页面创建一个新的 Widget。
2. 获取密钥：创建后会获得一个 Site Key（公开）和一个 Secret Key（保密）。
3. 配置环境变量：在 Cloudflare Dashboard 的 Workers 设置中，进入 "Settings" → "Variables and Secrets"，添加以下环境变量：
   • TURNSTILE_SECRET = 你的 Secret Key
   • TURNSTILE_SITEKEY = 你的 Site Key
4. 重新部署：运行部署命令使配置生效。

环境变量类型建议：建议将所有环境变量都设置为 Secret 类型。Secrets 存储在 Cloudflare 加密存储中，与代码部署分离，重新部署时不会被覆盖或丢失。在 Dashboard 添加变量时，选择 "Secret" 类型即可。

说明：Turnstile 验证为会话级别，用户通过验证后当前会话内所有功能可用，关闭浏览器后需重新验证。

启用 GitHub 登录后，用户可以通过 GitHub 账号登录，并在个人空间中保存和管理常用的 SSH 服务器，实现一键连接。不配置时，此功能自动隐藏，不影响匿名 SSH 连接的正常使用。

1. 创建 GitHub OAuth App：

   • 登录 GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
   • Application name：CloudSSH（自定义）
   • Homepage URL：https://your-domain.com（你的部署域名）
   • Authorization callback URL：https://your-domain.com/api/auth/callback
   • 创建后获得 Client ID，点击 Generate a new client secret 生成 Client Secret（仅显示一次，请立即保存）

2. 配置环境变量：在 Cloudflare Dashboard 的 Workers 设置中，进入 "Settings" → "Variables and Secrets"，添加以下环境变量：

   • GITHUB_CLIENT_ID = 你的 Client ID
   • BASE_URL = https://your-domain.com（你的部署域名）
   • GITHUB_CLIENT_SECRET = 你的 Client Secret

3. 重新部署：保存环境变量后重新部署当前 Worker。仓库中的 Durable Object migration 会负责初始化所需类和数据库，不需要删除已有 Worker。

环境变量类型建议：建议将所有环境变量都设置为 Secret 类型。Secrets 存储在 Cloudflare 加密存储中，与代码部署分离，重新部署时不会被覆盖或丢失。在 Dashboard 添加变量时，选择 "Secret" 类型即可。

说明：服务器凭据（密码/私钥）在每用户 UserDBDO SQLite 中使用 AES-256-GCM 加密存储。当前加密密钥在首次使用时自动生成，并与密文保存在同一个 Durable Object 数据库中，主要用于避免凭据以明文存储，不能抵御整个数据库同时泄露的情况。一键连接已保存服务器时，浏览器不会收到明文凭据，服务端通过一次性连接令牌完成内部传递。

迁移注意：已有部署应通过 wrangler.toml 中递增且不可复用的 migration tag 演进 Durable Object。只有在确认环境中没有需要保留的数据、且明确要重建整个环境时，才应删除 Worker；生产环境不要把删除 Worker 当作常规初始化步骤。

本项目采用 pnpm monorepo 工作区结构：

CloudSSH/
├── src/                    # 后端源码 (Cloudflare Worker)
│   ├── ssh/                # SSH 协议纯实现层（传输、加密、认证、通道、SFTP）
│   └── worker/             # Worker 入口和 Durable Objects
│       └── agent/          # AI Agent 控制循环、工具、安全检测
├── frontend/               # 前端源码 (独立 workspace)
│   └── src/                # TypeScript + xterm.js + trzsz
│       └── agent/          # AI 助手侧边栏 UI
├── docs/                   # GitHub Pages 静态资源
│   └── theme-editor/       # 可视化主题编辑器
├── scripts/                # 构建脚本
├── tests/                  # Vitest、Playwright 与 axe 回归测试
├── .github/workflows/      # CI/CD 自动部署配置
├── pnpm-workspace.yaml     # pnpm 工作区配置
└── wrangler.toml           # Cloudflare 部署配置

1. Fork 并克隆仓库

   git clone https://github.com/<你的用户名>/CloudSSH.git
   cd CloudSSH

2. 安装依赖（需分别安装根目录和前端依赖）

   pnpm install
   cd frontend && pnpm install

3. 登录 Cloudflare（首次需要，后续会缓存凭据）

   npx wrangler login

   说明：本地开发使用 Wrangler Dev 时，会连接到你的 Cloudflare 账号以使用 Durable Objects 和 TCP Sockets。SSH 连接的真实 TCP 流量会通过 Cloudflare 的基础设施转发。

4. 配置 GitHub Actions（可选，如需自动部署）

   如果你希望通过 GitHub Actions 自动部署到自己的 Cloudflare 账号，需要修改 .github/workflows/deploy.yml 中的仓库所有者名称：

   if: github.repository_owner == '你的GitHub用户名'

   同时在仓库的 Settings → Secrets and variables → Actions 中配置以下 Secrets：

   • CLOUDFLARE_API_TOKEN：Cloudflare API Token
   • CLOUDFLARE_ACCOUNT_ID：Cloudflare 账号 ID

pnpm run dev

此命令将构建前端并启动 Wrangler 本地开发环境，支持：

• 前端代码变更自动重新构建
• Worker 代码变更自动重新加载
• 完整的 Durable Objects 和 TCP Sockets 功能

开发服务器启动后，访问终端输出的本地地址（通常为 http://localhost:8787）即可进行调试。

禁止创建特性分支（feature branch）。 所有变更必须直接提交到 test 分支，保持仓库分支结构整洁。

test 分支（开发/测试）  ──合并──>  main 分支（生产）

1. 切换到 test 分支：git checkout test
2. 拉取最新代码：git pull origin test
3. 进行开发并本地测试
4. 直接提交并推送：git push origin test
5. 测试通过后，维护者会将 test 分支合并到 main 分支

说明：main 分支设置了保护规则，禁止直接推送。所有变更必须先提交到 test 分支进行测试。请勿创建 feat/xxx、fix/xxx 等特性分支，直接在 test 分支上提交即可。

感谢以下贡献者对 CloudSSH 的代码、兼容性和用户体验所做的贡献：

名单依据 Git 提交历史整理，完整记录请参阅 GitHub Contributors。欢迎通过 Issue 和 Pull Request 参与项目建设。

本项目基于 Apache License 2.0 协议开源。

原作者与署名要求：CloudSSH 由 TanXin (@newbietan) 发起并完成核心架构设计，目前仍由原作者持续维护。任何基于本项目的二次修改、衍生开发或再发布，均须保留 LICENSE 与 NOTICE 中的许可证、版权和归属声明，并在项目文档或其他随附声明中明确注明“本项目基于 CloudSSH 修改，原作者为 TanXin (@newbietan)”及原项目链接。

商业使用、修改与再分发均以 Apache License 2.0 的条款为准；上述署名要求用于保留原项目来源和作者归属，不限制该许可证授予的其他权利。

欢迎提交 Issue 和 Pull Request 共建社区。如果这个项目对你有帮助，恳求大家给本项目点个 ⭐ Star 支持一下，非常感谢！