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

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

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

简体中文 | English

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

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

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

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

• 一键部署：仅需Fork本仓库，再在 Cloudflare Dashboard 点击几下即可完成项目构建与部署。
• 现代化前端技术栈：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 密码认证、RFC 4256 keyboard-interactive 多轮交互认证，以及 OpenSSH 格式的 Ed25519、ECDSA P-256/P-384/P-521 和 RSA 私钥认证。交互认证支持密码、OTP、多字段提示与公钥后的二次验证；服务器提示会在绑定当前连接的安全对话框中展示，已保存密码仅在用户明确选择后代填。RSA 默认使用 RSA-SHA2-256/512，只有显式兼容配置才允许旧 ssh-rsa SHA-1。
• SSH 跳板机/堡垒机：登录用户可以为已保存服务器选择另一台已保存服务器作为跳板。CloudSSH 使用标准 RFC 4254 direct-tcpip 通道逐层建立 SSH，不依赖远端安装 ssh、nc 或 socat；支持最多 3 级跳转，最终目标的终端、SFTP 与 AI Agent 均复用完整加密链路。每一跳独立认证和验证路径隔离的主机指纹。
• 一次性 SSH 授权分享：可选启用登录用户的服务器分享。链接只包含 256 位随机能力凭证，不携带主机、用户名、密码、私钥或跳板信息；凭证仅保存哈希、只能领取一次且具有独立的领取有效期与会话最长时间。分享会话允许终端和 SFTP，服务端强制禁用 AI Agent、OS 检测、主机指纹修改与自动重连；所有者可以实时撤销，并查看仅针对分享会话生成的生命周期、SFTP 操作与终端输出记录。
• 防范中间人攻击 (TOFU)：首次连接自动提取服务器 Host Key（SHA-256 指纹）并显示，支持 Ed25519/ECDSA/RSA 签名验证，并在本地及 API 持久化缓存已知主机指纹以防范二次连接的欺骗风险。
• 全功能极客终端：基于 @xterm/xterm 与 @xterm/addon-webgl 硬件加速渲染引擎，保证海量日志输出顺滑不卡顿。
• 可靠的终端剪贴板交互：鼠标完成终端选区后自动复制，右键可直接粘贴；触摸设备点击快捷键栏的复制按钮进入选择模式，拖动选择文本后再次点击完成复制，避免依赖不稳定的长按选区，粘贴则使用独立按钮。粘贴统一经过 xterm.js 原生输入管线，仅在远端应用启用 bracketed paste 模式时发送对应控制序列，并自动规范化换行，兼容 Vim 等交互式编辑器和普通 Shell。
• 移动端终端适配：针对手机和平板提供动态可视高度、软键盘与安全区适配、iOS 中文输入法兼容、紧凑工具栏、一次性 Ctrl/Alt、Esc/Tab/方向键/Home/End/PgUp/PgDn 等快捷键，以及移动端全屏 Agent/SFTP 面板。页面从后台返回后会主动验证 WebSocket，淘汰表面在线但已失效的连接；匿名会话使用当前内存凭据重新建立 SSH，登录用户的已保存服务器则重新申请一次性连接令牌，且只有收到 shell_ready 后才恢复“已连接”状态和终端输入。用户可主动尝试“全屏横屏”；浏览器不支持方向锁定时会回退为手动旋转提示，不会强制改变桌面端布局。移动系统若彻底回收网页，当前 Shell 仍无法无缝续接。
• 个性化 UI：Theme V2 系统提供 Standard Dark、Standard Light、Cyberpunk、Glacier、Gruvbox 五款内置主题。配套 GitHub Pages 主题编辑器可实时调整颜色、形状、密度、字体、阴影、动效及按钮/输入框/卡片/标签页样式，并预览登录页、服务器列表、终端 + SFTP 和 AI Agent 面板。主题通过 JSON 文件导入、导出、备份与分享；登录用户在应用中导入后会同步到账号并可跨浏览器恢复，匿名用户仅保存在当前浏览器。
• SFTP 图形化文件管理：集成完整的 SFTP v3 文件传输协议，提供图形化文件浏览器界面。支持目录浏览、文件上传/下载、新建文件夹、文件重命名与删除等操作；支持普通单选、Cmd/Ctrl 切换选择、Shift 连选、全选，以及批量下载文件和批量删除。基于 SSH 子系统实现，与终端会话并行运行，互不干扰，支持下载队列及上传取消。
• 原生文件传输：集成 trzsz.js，支持 trz（上传）/ tsz（下载）命令进行文件传输，兼容 tmux 会话。还支持拖拽文件到终端窗口直接上传、目录传输及断点续传等高级功能。（需远程服务器安装 trzsz）
• GitHub OAuth 集成：支持 GitHub 登录，用户可保存和管理常用 SSH 服务器，实现一键连接；服务器支持最多 10 个规范化标签，列表可按名称、主机地址、用户名即时搜索并按标签筛选，每页固定展示 9 张服务器卡片。
• 服务器系统自动识别：登录用户首次连接尚未识别的已保存服务器时，CloudSSH 会在终端就绪后通过独立 SSH exec 通道读取 /etc/os-release 或 uname，并在服务器卡片显示对应系统图标。检测在后台执行，不阻塞终端；只有成功识别的结果才会保存，未识别结果会留待下次连接重新探测，修改主机地址或端口也会清除旧结果。匿名连接不执行该检测。该只读命令可能出现在目标服务器的 SSH 审计日志中。
• IP 隐私展示与快捷复制：服务器列表和连接状态栏会对有效 IPv4/IPv6 地址进行视觉掩码，减少演示或截图时意外暴露完整地址的风险；可通过鼠标点击或键盘操作复制用于连接的完整 IP。域名保持原样显示，视觉掩码不等同于加密或访问控制。
• 单页面多标签会话管理：支持在单个页面内开启与切换多个独立的 SSH 终端与 SFTP 文件管理器，各会话环境和状态完全隔离，并在个性化主题编辑器中进行了联动适配。
• 安全匿名历史记录：本地存储最近 5 条匿名连接，且敏感凭证可选使用本地派生的密钥进行 AES-256-GCM 安全加密存储至 localStorage，提供一键回填与清除。
• 双段延迟与 Colo 展示：状态栏即时且周期性地展示当前 RTT（客户端至 Cloudflare）、物理延迟（Cloudflare 至主机）以及 Cloudflare 当前服务的数据中心代码（如 CF-LAX），并通过绿、黄、红三色状态点提示网络质量。
• 智能区域调度（locationHint）：保存直连服务器时通过 IPinfo 查询主机地理信息并持久化 DO 部署区域，连接时直接读取数据库，不再执行外部地理查询；使用 SSH 跳板时仅对 Cloudflare 直接连接的最外层入口进行推断，下游内网服务器不会触发查询，其区域设置由入口统一决定。查询失败时自动退化为 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/>用户数据管理"]
        Share_DO["SSHShareDO<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
    Worker <-->|"领取 / 撤销 / 查看审计"| Share_DO
    SSH_DO -->|"生命周期 / SFTP / 终端输出"| Share_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 与直连目标或最外层跳板建立 TCP 连接。
4. 如配置跳板，SSHSession 逐层认证并通过 RFC 4254 direct-tcpip 通道承载下一套 SSH；仅最终目标打开 PTY、Shell、SFTP 与 Agent exec 通道。
5. 终端数据在浏览器与 Worker 之间通过 WSS 传输，在 Worker 与目标服务器之间通过 SSH 加密传输；Worker 负责两段协议之间的转发和 SSH 协议处理。
6. SFTP 文件管理通过独立的 SSH 子系统通道运行，支持目录浏览、文件上传/下载等操作。
7. 对尚无 OS 记录的已保存服务器，SSHSession 在 Shell 就绪后通过独立 exec 通道进行一次只读系统识别；成功结果写入 UserDBDO 并通知前端更新卡片，未知结果不保存。
8. AI 助手通过 WebSocket 接收用户问题及可选的终端选区上下文；选区被标记为非可信分析数据后交给 AgentCore，后者调用外部 LLM API，通过 SSH exec 通道执行获准的命令，并将结果流式返回前端。
9. 一次性分享链接先由 SSHShareDO 原子领取并换取短期连接票据；分享会话的生命周期、SFTP 操作和终端输出写入独立审计库，失效、撤销或审计不可用时终止连接。

• 一个 Cloudflare 账号。
• 启用 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 数据完全隔离，各自独立。

Fork 仓库可以通过内置的 Sync upstream GitHub Actions 工作流，定时将本项目 main 分支的最新版本同步到自己的 main 分支。该功能默认关闭，开启后每天北京时间 04:20 检查一次；同步产生的分支更新会由 Cloudflare Git 集成自动构建并部署，无需额外配置部署开关。

1. 确认 Cloudflare Worker 连接的是你自己的 Fork 仓库，且 Production branch 设置为 main，自动构建处于开启状态。
2. 进入 Fork 仓库的 Actions 页面并启用工作流。已有 Fork 如果尚未包含 Sync upstream，请先通过 GitHub 的 Sync fork 功能手动同步一次。
3. 进入 Settings → Secrets and variables → Actions → Variables，创建 Repository variable：
   • Name：AUTO_SYNC_UPSTREAM
   • Value：true
4. 如需立即同步，进入 Actions → Sync upstream → Run workflow 手动执行；手动执行不要求设置上述变量。

同步说明：工作流使用 GitHub 提供的 Fork 同步接口，不需要 PAT，也不会强制覆盖分支。若你的 main 与上游存在无法自动合并的冲突，任务会失败并保留现有代码，需要手动解决冲突。建议不要直接修改部署用的 main 分支，并将域名、密钥及环境变量保存在 Cloudflare Dashboard 中。

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

   还可以按部署用途添加以下两个独立的可选配置：

   • GITHUB_ALLOWED_USER_IDS：允许登录的 GitHub 数字用户 ID，多个 ID 使用英文逗号分隔，例如 83105156,6236783。未配置时不限制 GitHub 账号；配置为空或包含非正整数时采用 fail-closed，拒绝所有 GitHub 登录。
   • REQUIRE_GITHUB_AUTH：设置为 true 时禁用匿名 SSH，所有 SSH WebSocket 都必须带有有效 GitHub session；未配置或设置为 false 时保留匿名连接。
   • ENABLE_SSH_SHARING：设置为 true 时允许登录用户为已保存服务器创建一次性分享链接；默认关闭。启用即表示管理员明确允许持有分享凭证的接收者在不登录 GitHub 的情况下建立受审计 SSH 会话。

   获取 GitHub 数字用户 ID：

   • 浏览器访问 https://api.github.com/users/octocat（将 octocat 替换为实际用户名），在返回的 JSON 中读取 id 字段。例如响应中的 "id": 583231 表示数字用户 ID 为 583231。

   • 或在命令行执行：

     curl -s https://api.github.com/users/octocat | jq '.id'

   请填写 id，不要填写用户名或 node_id。数字 ID 不会随用户名修改而变化；多个账号的 ID 使用英文逗号分隔。

   配置组合	GitHub 登录	匿名 SSH
   两项都不配置	所有 GitHub 用户	允许
   仅配置 GITHUB_ALLOWED_USER_IDS	仅白名单用户	允许
   仅配置 REQUIRE_GITHUB_AUTH=true	所有 GitHub 用户	禁止
   两项同时配置	仅白名单用户	禁止（私有实例模式）

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

环境变量类型建议：GITHUB_CLIENT_SECRET 必须使用 Secret 类型；GITHUB_ALLOWED_USER_IDS 和 REQUIRE_GITHUB_AUTH 不包含密钥，可使用普通文本变量。Secrets 存储在 Cloudflare 加密存储中，与代码部署分离，重新部署时不会被覆盖或丢失。

访问策略说明：修改 GITHUB_ALLOWED_USER_IDS 后，已签发 session 会在下一次请求时重新检查并立即失效；已建立的 SSH WebSocket 不会被主动中断。REQUIRE_GITHUB_AUTH=true 依赖 GitHub OAuth，请同时正确配置 Client ID、Client Secret 和 BASE_URL。

1. 配置 GitHub OAuth，并在 Worker 环境变量中设置 ENABLE_SSH_SHARING=true 后重新部署。
2. 所有者先通过普通连接成功连接目标服务器及全部跳板节点，使路径范围内的主机指纹完成验证。
3. 在服务器卡片点击分享按钮，选择链接领取有效期（5/15/30/60 分钟）和会话最长时间（15/30/60/120 分钟）。
4. 创建后立即复制链接并通过可信渠道发送。CloudSSH 不保存明文分享凭证，关闭创建结果后无法再次查看同一链接。
5. 接收者打开链接，确认终端输出和 SFTP 操作会被记录后领取授权。链接只能成功领取一次；刷新、断开或关闭页面后不能重新连接。
6. 所有者可再次打开服务器的分享管理，查看状态及审计记录，或撤销待领取/活动分享。撤销活动分享会同时关闭终端和 SFTP。

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

SSH 跳转不需要额外环境变量，但必须启用 GitHub OAuth 并使用已保存服务器：

1. 先保存最外层可由 Cloudflare 直接访问的公网跳板服务器 A。
2. 再保存目标服务器 B，在“跳板服务器”中选择 A；B 可以填写只能从 A 访问的内网地址。
3. 如需多级路径，例如 C → A → B，可先把 A 的跳板设置为 C，再让 B 选择 A。系统会递归解析路径，最多允许 3 台跳板服务器。
4. 从服务器列表连接 B。终端、SFTP 和 AI Agent 只在最终目标 B 上运行；任意一跳断开时会重建或关闭整条链路。

跳板关系必须位于同一 GitHub 用户空间，不能形成自引用或循环。正在被其他服务器引用的跳板不能直接删除。SSRF 公网检查与 Durable Object 区域调度均以 Cloudflare 直接连接的最外层入口为准；只有该入口会执行自动区域推断，选择跳板后下游服务器的区域选项会停用，也不会向 IPinfo 发送其内网主机信息。内网地址只能出现在由服务端解析的已保存跳板链中，匿名连接不能提交跳板配置。每一跳都会独立执行 TOFU 主机指纹验证，内网目标的记录按完整跳转路径隔离。

本项目采用 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 提交历史与已接收的 Pull Request 整理；同一贡献者在历史中可能使用过不同的 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 支持一下，非常感谢！