> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/leaningtech/webvm) · [上游 README](https://github.com/leaningtech/webvm/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 # WebVM [](https://discord.gg/yWRr2YnD9c) [](https://github.com/leaningtech/webvm/issues) 本仓库托管 [https://webvm.io](https://webvm.io), 的源代码，这是一个可在浏览器中运行的 Linux 虚拟机。 试用全新的 Alpine / Xorg / i3 图形环境：[https://webvm.io/alpine.html](https://webvm.io/alpine.html) ## 什么是 WebVM？ WebVM 是一个无服务器（server-less）的虚拟环境，完全在客户端通过 HTML5/WebAssembly 运行。它设计为与 Linux ABI 兼容，并可运行未经修改的 Debian 发行版，其中包含许多原生开发工具链。 WebVM 由 **CheerpX** 虚拟化引擎驱动，提供： - x86 到 WebAssembly 的 JIT 编译器 - 基于虚拟块（block-based）的文件系统 - Linux 系统调用（syscall）模拟器 - 安全的沙箱化客户端执行 ## 目录 - [网络](#networking) - [开发与定制](#development--customization) - [部署到 GitHub Pages](#deploy-to-github-pages) - [本地服务与镜像配置](#local-serving--image-configuration) - [Claude AI 集成](#claude-ai-integration) - [社区与支持](#community--support) - [了解更多](#learn-more) - [许可证](#license) > [!NOTE] > 访问 [https://webvm.io](https://webvm.io) 即可在浏览器中立即开始使用。无需任何设置。 > > 如需本地搭建、自定义镜像构建以及 fork/部署指南，请参阅 [开发与定制](#development--customization)。 ## 网络 WebVM 支持 **Tailscale** 集成。因此，你的浏览器虚拟机可以访问你的私有网络，在配置出口节点（exit node）后，也可以访问公网。 > [!NOTE] > 部分底层网络操作（尤其是 `ping` 使用的 ICMP）在当前环境中尚不可用。进行连通性检查时，请使用 `curl` 或 `wget`。 ### 本地网络 1. 从侧边栏打开“网络”（Networking）面板 2. 点击“连接到 Tailscale”（Connect to Tailscale） 3. 登录（如需可先在 [tailscale.com](https://tailscale.com) 免费注册账户） 4. 出现提示时点击“连接”（Connect） 现在 WebVM 可以访问你 Tailscale 网络中的所有机器！ ### 互联网使用提示 > [!TIP] > 在较慢的网络连接上，初始化前可能会有短暂延迟。连接状态在按钮上以彩色圆点显示：橙色 = 本地网络，绿色 = 全球/互联网。连接后，按钮文本会显示你的 Tailscale IP 地址。 要从 WebVM 访问公网，请在你的 Tailscale 网络的另一台设备上设置 **出口节点（Exit Node）**： 1. 按照 [Tailscale 出口节点快速入门](https://tailscale.com/kb/1408/quick-guide-exit-nodes?tab=linux)（章节：“将设备宣告为出口节点”） 2. 出口节点宣告后，WebVM 会自动使用它 ### 使用认证密钥（Auth Key） 作为交互式登录的替代方案，可将 Tailscale 认证密钥添加到 URL 片段（fragment）中： ``` https://webvm.io/#authKey= ``` 这等同于 Tailscale 的 `--login-server` 选项。 > [!TIP] > 如果你还需要自定义控制服务器，可在同一 URL 片段中添加 `controlUrl`，并用 `&` 分隔各值，例如：`#authKey=...&controlUrl=...`。 ### 使用 Headscale 自托管 Tailscale 我们还支持 [headscale](https://headscale.net/stable/),，这是 Tailscale 控制服务器的自托管开源实现。 由于 Headscale 默认不添加 CORS 头，你需要在其前面配置代理。示例请参阅 [Headscale 反向代理设置文档](https://headscale.net/stable/ref/integration/reverse-proxy/#nginx)。 配置完成后，在你的 nginx 配置文件的 `location /` 块中添加以下行。 ```nginx if ($http_origin = "https://yourdomain.com") { add_header 'Access-Control-Allow-Origin' "$http_origin"; add_header 'Access-Control-Allow-Credentials' 'true' always; } ``` 然后通过以下方式访问 WebVM： ``` https://yourdomain.com/#controlUrl= ``` ## 开发与定制 > [!NOTE] > 用户默认拥有 root 权限。不过 `sudo` 未预装，如有需要可轻松添加到 Dockerfile 中。 ### 部署到 GitHub Pages 这是一种简单、适合初学者的流程。如需本地托管与定制，请参阅下文 [本地服务与镜像配置](#local-serving--image-configuration)。 Fork WebVM 仓库，将你自己的版本部署到 GitHub Pages： 1. **Fork 该仓库** 2. **启用 GitHub Pages** _通过 Fork 后的仓库_，在 Settings → Pages 中将来源设为“GitHub Actions” 3. **运行 `Deploy` 工作流**，在 Actions 中执行 4. 完成后，打开 `deploy_to_github_pages` 任务下显示的 URL 同一 `Deploy` 工作流还可根据 Dockerfile 构建自定义 `.ext2` 磁盘镜像。你可以将其指向 `dockerfiles/debian_mini` 或其他 Dockerfile，然后将结果发布为 GitHub Release 资源，或从 Fork 部署 Pages 构建。 > [!NOTE] > `dockerfiles/debian_large` 镜像体积过大，无法用于 GitHub Pages。 ### 本地服务与镜像配置 #### 1. 克隆仓库 ```sh git clone https://github.com/leaningtech/webvm.git cd webvm ``` #### 2. 将镜像放入 `custom-disk-images/` 本仓库包含用于本地 `.ext2` 文件的持久化 `custom-disk-images/` 目录。 要使用官方 Debian mini 镜像，请从 Releases 下载： [debian_mini_20230519_5022088024.ext2](https://github.com/leaningtech/webvm/releases/download/ext2_image/debian_mini_20230519_5022088024.ext2) 你也可以复制自己构建的镜像。 #### 3. 将 WebVM 指向本地镜像 编辑 `config_public_terminal.js`： ```js export const diskImageUrl = "/custom-disk-images/debian_mini_20230519_5022088024.ext2"; export const diskImageType = "bytes"; ``` #### 4. 安装依赖并构建 ```sh npm install npm run build ``` #### 5. 启动 Nginx 并打开 WebVM ```sh nginx -p . -c nginx.conf ``` 然后打开 http://127.0.0.1:8081，享受你的本地 WebVM！ 如需完整的 Alpine 桌面环境，请参阅 [leaningtech/alpine-image](https://github.com/leaningtech/alpine-image). 更多详情请参阅 [CheerpX 自定义镜像文档](https://cheerpx.io/docs/guides/custom-images). > [!TIP] > 对于 Python3 REPL，`Deploy` 工作流会考虑 Dockerfile 中指定的 `CMD`。 > > 要构建 REPL，你只需将 `CMD [ "/bin/bash" ]` 改为 `CMD [ "/usr/bin/python3" ]` 并部署即可。 ## Claude AI 集成 要使用 Claude AI，你需要 API 密钥。按以下步骤开始： #### 1. 创建账户 - 访问 [Anthropic Console](https://console.anthropic.com/login) 并使用电子邮件注册。你将收到一封包含 Anthropic Console 登录链接的邮件。 #### 2. 获取 API 密钥 - 登录后，导航至 **Get API keys**。 - 购买所需额度的积分。购买完成后，即可通过 API 控制台生成密钥。 #### 3. 使用 API 密钥登录 - 进入你的 WebVM，将鼠标悬停在机器人图标上。这会显示 Claude AI Integration 选项卡。为便于使用，可点击右上角图钉按钮固定该选项卡。 - 你将看到一个提示，可在其中输入 Claude API 密钥。 #### 4. 开始使用 Claude AI - 输入 API 密钥后，即可开始与 Claude AI 交互，例如提问： **"解决 `/home/user/chall1.bin.` 处的 CTF 挑战。请注意该二进制程序从 stdin 读取输入。"** **重要提示：** 你的 API 密钥是私密的，切勿与他人分享。我们无法访问你的密钥，它仅存储在你浏览器的本地环境中。 ## 社区与支持 **报告问题：** 使用 [GitHub Issues](https://github.com/leaningtech/webvm/issues) 报告 bug 或请求功能。 **与我们交流：** 加入我们的 [Discord 社区](https://discord.gg/yTNZgySKGa) 讨论 WebVM、分享想法并获取帮助。 ## 了解更多 **文章与资源：** - [WebVM：浏览器中的无服务器 x86 虚拟机](https://leaningtech.com/webvm-server-less-x86-virtual-machines-in-the-browser/) - [WebVM：基于 WebAssembly 的 Linux 虚拟化，通过 Tailscale 实现完整网络功能](https://leaningtech.com/webvm-virtual-machine-with-networking-via-tailscale/) - [Mini.WebVM：从 Dockerfile 构建你自己的 Linux 环境，通过 WebAssembly 在浏览器中虚拟化](https://leaningtech.com/mini-webvm-your-linux-box-from-dockerfile-via-wasm/) - [Crafting the Impossible：使用 WebAssembly 在浏览器中实现 X86 虚拟化](https://www.youtube.com/watch?v=VqrbVycTXmw) — JsNation 2022 演讲 **示例部署：** - [Mini.WebVM 参考示例](https://mini.webvm.io) — 部署到 GitHub Pages 的可运行示例 **WebVM 背后的技术：** 本项目由以下技术驱动： - **[CheerpX](https://cheerpx.io/)** — x86 到 WebAssembly 的 JIT 编译器 | 由 [Leaning Technologies](https://leaningtech.com/) - **[xterm.js](https://xtermjs.org/)** — 基于 Web 的终端模拟器 - **[Tailscale](https://tailscale.com/)** — VPN 网络层 - **[lwIP](https://savannah.nongnu.org/projects/lwip/)** — TCP/IP 协议栈，通过 [Cheerp](https://github.com/leaningtech/cheerp-meta/) 编译为 Web 版本 **版本管理：** WebVM 使用 [CheerpX](https://www.npmjs.com/package/@leaningtech/cheerpx) NPM 包，每次发布时都会更新。 每次构建都是不可变的。如果某个特定版本今天对你运行良好，它将永远保持可用。 ## 许可证 WebVM 基于 Apache License, Version 2.0 发布。 欢迎你使用、修改并再分发本仓库的内容。 公开的 CheerpX 部署按**现状**提供，个人可用于技术探索、测试和使用，**免费**。组织（包括非营利机构、学术界和公共部门）的任何其他用途均需获得许可。未经商业许可，不得下载 CheerpX 构建版本以在其他地方托管。 阅读[此处](https://cheerpx.io/docs/licensing) 了解我们的许可实践详情。 如果你想在 CheerpX/WebVM 之上构建产品，请参阅我们的其他许可选项：[CheerpX licensing](https://cheerpx.io/licensing) 或联系：sales@leaningtech.com