# 云端浏览器部署文档

本文档说明如何在 Linux 服务器（含宝塔面板环境）上部署云端浏览器。

- 安装目录：`/opt/cloud-browser`
- 运行用户：`root`
- 默认端口：`32450`
- 默认账号：`admin` / `admin`
- 代码仓库：[https://git.bz121.com/dekun/cloud-browser.git](https://git.bz121.com/dekun/cloud-browser.git)

---

## 一、环境要求

| 项目 | 要求 |
|------|------|
| 系统 | Ubuntu 20.04+ / Debian 11+ / CentOS 7+ |
| 内存 | 最低 1GB，推荐 2GB |
| Docker | 20.10+ |
| Docker Compose | v2+ |
| 端口 | 32450（或自定义，需在 `.env` 中修改） |

> 服务器已安装宝塔面板、Docker、Nginx 均可，**无需额外配置 Nginx**，服务直接监听端口，反向代理请自行操作。

---

## 二、一键部署（推荐）

以 **root** 用户 SSH 登录服务器，执行：

```bash
curl -fsSL https://git.bz121.com/dekun/cloud-browser/raw/branch/main/deploy.sh -o /tmp/deploy.sh
bash /tmp/deploy.sh
```

若仓库尚未推送或 curl 不可用，也可手动克隆后执行：

```bash
git clone https://git.bz121.com/dekun/cloud-browser.git /opt/cloud-browser
bash /opt/cloud-browser/deploy.sh
```

### 一键脚本会自动完成

1. 检测并安装 Docker（如未安装）
2. 克隆/更新代码到 `/opt/cloud-browser`
3. 创建 `.env` 和 `data/` 数据目录
4. 构建并启动 Docker 容器
5. 等待健康检查通过
6. 输出访问地址和默认账号

### 部署成功示例输出

```
==========================================
  云端浏览器部署完成
==========================================
  访问地址: http://1.2.3.4:32450
  默认账号: admin
  默认密码: admin
  安装目录: /opt/cloud-browser
==========================================
```

---

## 三、手动部署

### 1. 克隆代码

```bash
git clone https://git.bz121.com/dekun/cloud-browser.git /opt/cloud-browser
cd /opt/cloud-browser
```

### 2. 配置环境变量（可选）

```bash
cp .env.example .env
nano .env
```

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `APP_PORT` | 宿主机端口 | `32450` |
| `MAX_SESSIONS` | 最大并发会话 | `1` |
| `SESSION_IDLE_TIMEOUT` | 空闲超时（秒） | `1800` |
| `VIEWPORT_WIDTH` | 浏览器宽度 | `1280` |
| `VIEWPORT_HEIGHT` | 浏览器高度 | `720` |
| `SCREENCAST_QUALITY` | 画面质量 10-100 | `80` |

### 3. 启动服务

```bash
mkdir -p data
docker compose up -d --build
```

### 4. 验证

```bash
curl http://127.0.0.1:32450/api/health
# {"status":"ok","sessions":0}
```

浏览器访问 `http://服务器IP:32450`，使用 `admin` / `admin` 登录。

---

## 四、登录与修改密码

1. 打开首页，输入默认账号 `admin`、密码 `admin` 登录
2. 登录后点击右上角 **「账号设置」**
3. 填写当前用户名、当前密码、新用户名、新密码
4. 保存后自动退出，使用新凭据重新登录

账号信息保存在 `/opt/cloud-browser/data/auth.json`，容器重启后不会丢失。

---

## 五、反向代理（自行配置）

服务默认监听 `32450` 端口。若需通过域名 + HTTPS 访问，请在宝塔/Nginx 中自行配置反向代理。

目标地址：

```
http://127.0.0.1:32450
```

**注意**：浏览页面使用 WebSocket（路径 `/ws/`），反代时需开启 WebSocket 支持（Upgrade 头）。

---

## 六、运维命令

```bash
cd /opt/cloud-browser

# 查看运行状态
docker compose ps

# 查看日志
docker compose logs -f app

# 重启
docker compose restart

# 停止
docker compose down

# 更新代码并重新部署
bash deploy.sh
```

---

## 七、防火墙

确保服务器防火墙 / 安全组放行 **32450** 端口（若直接通过 IP 访问）：

```bash
# ufw 示例
ufw allow 32450/tcp

# firewalld 示例
firewall-cmd --permanent --add-port=32450/tcp
firewall-cmd --reload
```

若仅通过 Nginx 反代访问，可不对公网开放 32450，仅本机 `127.0.0.1` 访问即可。

---

## 八、常见问题

### 部署脚本报错 `set: pipefail: invalid option`

脚本在 Windows 编辑后可能带 CRLF 换行符，在 Linux 上会报错。修复：

```bash
sed -i 's/\r$//' /opt/cloud-browser/deploy.sh
bash /opt/cloud-browser/deploy.sh
```

或重新拉取最新代码：

```bash
cd /opt/cloud-browser && git pull && bash deploy.sh
```

---

```bash
sudo su -
bash deploy.sh
```

### 端口被占用

修改 `/opt/cloud-browser/.env` 中的 `APP_PORT`，然后：

```bash
cd /opt/cloud-browser
docker compose down
docker compose up -d
```

### 画面卡顿

这是 JPEG 画面流方案的正常现象，可调整 `/opt/cloud-browser/.env`：

```env
VIEWPORT_WIDTH=960
VIEWPORT_HEIGHT=540
SCREENCAST_QUALITY=45
SCREENCAST_MAX_FPS=12
SCREENCAST_EVERY_NTH_FRAME=3
```

修改后执行：

```bash
cd /opt/cloud-browser
docker compose up -d --build
```

浏览页右上角会显示当前 fps，便于判断网络是否跟得上。

其他原因：VPS 内存不足、跨境带宽延迟、Nginx 反代未开 WebSocket。

### 页面黑屏

```bash
docker compose logs -f app
```

常见原因：内存不足（建议 ≥ 2GB）、Chromium 启动失败。

### WebSocket 连接失败

若使用了 Nginx 反代，检查是否配置了 WebSocket Upgrade 支持。

### 忘记密码

```bash
cd /opt/cloud-browser
docker compose down
rm -f data/auth.json data/secret.key
docker compose up -d
```

将恢复为默认账号 `admin` / `admin`（**会清除已修改的密码**）。

---

## 九、一键卸载

```bash
bash /opt/cloud-browser/uninstall.sh
```

按提示输入 `yes` 确认。将自动：

1. 停止并删除 Docker 容器
2. 删除本地构建的镜像
3. 删除 `/opt/cloud-browser` 目录（含账号数据）

跳过确认直接删除：

```bash
bash /opt/cloud-browser/uninstall.sh -y
```

若目录已被删，可从仓库单独下载脚本执行（需指定安装路径时手动删除 `/opt/cloud-browser`）。

重新安装：

```bash
git clone https://git.bz121.com/dekun/cloud-browser.git /opt/cloud-browser
bash /opt/cloud-browser/deploy.sh
```