wehub-resource-sync
255 lines
10 KiB
Markdown
255 lines
10 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!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)
|
||
|
||
<img src="/assets/welcome_to_WebVM_alpine_2024.png" width="90%">
|
||
|
||
## 什么是 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=<your-ephemeral-key>
|
||
```
|
||
|
||
这等同于 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=<your-headscale-url>
|
||
```
|
||
|
||
## 开发与定制
|
||
|
||
> [!NOTE]
|
||
> 用户默认拥有 root 权限。不过 `sudo` 未预装，如有需要可轻松添加到 Dockerfile 中。
|
||
|
||
### 部署到 GitHub Pages
|
||
|
||
这是一种简单、适合初学者的流程。如需本地托管与定制，请参阅下文 [本地服务与镜像配置](#local-serving--image-configuration)。
|
||
|
||
Fork WebVM 仓库，将你自己的版本部署到 GitHub Pages：
|
||
|
||
<img src="/assets/fork_deploy_instructions.gif" alt="deploy_instructions_gif" width="90%">
|
||
|
||
1. **Fork 该仓库**
|
||
2. **启用 GitHub Pages** _通过 Fork 后的仓库_，在 Settings → Pages 中将来源设为“GitHub Actions”
|
||
3. **运行 `Deploy` 工作流**，在 Actions 中执行
|
||
4. 完成后，打开 `deploy_to_github_pages` 任务下显示的 URL
|
||
|
||
<img src="/assets/result.png" width="70%">
|
||
|
||
同一 `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 读取输入。"**
|
||
|
||
<img src="/assets/webvm_claude_ctf.gif" alt="deploy_instructions_gif" width="90%">
|
||
|
||
**重要提示：** 你的 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
|