cloud-browser/DEPLOY.md

云端浏览器部署文档

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

• 安装目录：/opt/cloud-browser
• 运行用户：root
• 默认端口：32450
• 默认账号：admin / admin
• 代码仓库：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 登录服务器，执行：

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

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

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. 克隆代码

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

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

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. 启动服务

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

4. 验证

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 头）。

---

六、运维命令

cd /opt/cloud-browser

# 查看运行状态
docker compose ps

# 查看日志
docker compose logs -f app

# 重启
docker compose restart

# 停止
docker compose down

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

---

七、防火墙

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

# 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 上会报错。修复：

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

或重新拉取最新代码：

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

---

sudo su -
bash deploy.sh

端口被占用

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

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

画面卡顿

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

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

修改后执行：

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

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

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

页面黑屏

docker compose logs -f app

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

WebSocket 连接失败

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

忘记密码

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

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

---

九、卸载

cd /opt/cloud-browser
docker compose down
cd /
rm -rf /opt/cloud-browser