BeavBeav
1.7K
EN登录
浏览文档

文档

网页访问

在可信局域网或 Linux 服务器上通过浏览器使用 Beav，并完成安装、登录、安全访问和日常运维。

网页访问让 Beav 的同一个工作空间出现在浏览器中。你可以在桌面端打开网页访问，供本机、手机或可信局域网设备使用；也可以把 Beav 安装在一台持续运行的 Linux 服务器上，再从浏览器访问。

当前对外开放的是网页访问模式。设置中的 API 和频道功能尚未作为公开接入方式提供，不需要配置它们。

选择部署方式

使用场景推荐方式适用范围
自己电脑上临时使用，或用手机访问同一局域网内的 Beav桌面端网页访问模式本机和可信局域网
希望 Beav 持续运行，在另一台电脑上随时访问Linux 服务器一键安装Debian / Ubuntu x86_64 + systemd
需要用自己的域名从互联网访问Linux 服务器 + HTTPS 反向代理有域名、TLS 证书和服务器防火墙管理权限

在桌面端开启网页访问

  1. 保持 Beav 桌面端运行，进入“设置”→“远程接入”。
  2. 在“网页访问模式”打开开关，等待状态显示“网页已开启”。
  3. 在页面中复制“本机地址”或“局域网地址”。
  4. 在目标设备的浏览器打开该地址。

首次开启时，页面会提供管理员账号和登录密码。请立即保存密码，不要把它发送到不受信任的聊天、文档或群组中。之后可以在同一页面查看、复制或修改凭据；修改账号或密码后，已登录的网页会退出。

管理员账号必须为 3–64 个非空白字符；密码必须为 12–256 个字符，且首尾不能有空白字符。

用手机扫码登录

开启后，桌面端会显示登录二维码。用同一可信网络中的手机扫码即可打开浏览器会话：

  1. 确认状态显示“网页已开启”，并且已显示局域网地址。
  2. 用手机相机或浏览器扫描二维码，或复制“扫码链接”发送到自己的设备。
  3. 在二维码的有效期内打开链接。二维码 5 分钟内有效，且只能使用一次。

二维码仅用于把你带到当前网页会话，不能替代管理员密码的保管。需要重新授权时，在桌面端点击“重新生成”。

本机与局域网地址

  • 本机地址只用于安装 Beav 的这台电脑。
  • 局域网地址用于同一可信网络的手机、平板或电脑。
  • Beav 会选择一个私有的物理局域网网卡，不会为了网页访问而监听所有虚拟网卡、隧道或容器网卡。
  • 如果 Windows 或系统防火墙询问是否允许访问，只允许“专用网络”或你确认可信的网络；不要为公共网络放行。

访问不到局域网地址时，先确认两台设备在同一网络，再回到桌面端点击“刷新状态”。如果没有显示局域网地址，检查电脑是否已连接 Wi-Fi 或网线，以及系统防火墙是否允许可信网络的入站连接。

请不要把桌面端显示的局域网端口直接映射到公网。需要互联网访问时，请使用下面的 Linux 服务器和 HTTPS 反向代理方式。

在 Linux 服务器上一键安装

官方一键安装目前支持 Debian 或 Ubuntu 的 x86_64 服务器，并要求系统使用 systemd、可使用 sudo、可访问 HTTPS 网络。它会安装 Beav、Xvfb、FFmpeg 和 systemd 服务；不需要手动下载 DEB 或配置桌面环境。

通过 SSH 登录服务器后，运行这一条命令：

curl -fsSL https://www.getbeav.com/install.sh | bash

安装器会请求 sudo 权限，并依次完成以下工作：

  1. 获取当前正式发布的 Linux 服务包。
  2. 校验服务包的 SHA-256 和文件大小；校验失败会停止安装。
  3. 安装匹配版本的 Beav、Xvfb 和 FFmpeg 依赖。
  4. 创建权限受限的 beav 系统账号，并启用 beav-web.service。
  5. 等待 http://127.0.0.1:31938/health/ready 就绪后输出访问地址。

首次安装完成时，终端会显示管理员账号 admin 和自动生成的初始密码。这个初始密码只会在首次安装时显示一次；请使用密码管理器保存。以后更新会保留现有密码。忘记密码时不要重装，直接执行 sudo beavctl reset-admin 重设。

首次登录与连通性检查

在服务器上运行：

beavctl url
beavctl status

用 beavctl url 显示的地址在浏览器中打开 Beav，输入管理员账号和密码。服务器的可用性可由以下命令检查：

curl --fail http://127.0.0.1:31938/healthz
curl --fail http://127.0.0.1:31938/health/ready

/healthz 表示服务仍在运行，/health/ready 还会确认工作空间和网页资源可用。安装器本身使用后者作为完成条件。

日常运维

目标命令
查看服务状态beavctl status
查看本机和局域网访问地址beavctl url
查看最近日志beavctl logs
持续查看日志beavctl logs --follow
启动、停止或重启服务sudo beavctl start / stop / restart
重设管理员密码sudo beavctl reset-admin
更新到当前正式版本beavctl update
卸载服务但保留数据sudo beavctl uninstall

beavctl update 会重新执行官方安装器，并保留已有的数据和管理员密码。遇到无法访问或更新失败时，先运行 beavctl status 和 beavctl logs，不要重复执行多次安装。

如果明确要同时删除服务、工作空间和服务器密钥，才运行下面的命令：

sudo beavctl uninstall --purge

这会删除 /etc/beav 和 /var/lib/beav，无法撤销。

数据与备份

服务器上的持久化内容位于以下路径：

内容路径
Beav 数据、加密凭据、工作空间与媒体/var/lib/beav
服务主密钥/etc/beav/server-master.key
网页管理员密码/etc/beav/webui-admin-password

备份时必须把 /var/lib/beav 与 /etc/beav/server-master.key 一起保存到受访问控制的加密备份中。主密钥丢失后，已加密保存的第三方凭据无法恢复，只能重新连接。管理员密码文件同样属于敏感信息，不应复制到代码仓库、镜像或普通云盘。

用域名和 HTTPS 从互联网访问

公网部署至少需要三层边界：域名与 TLS 由反向代理负责，Beav 的 31938 端口只允许反向代理访问，浏览器只连接你的 HTTPS 域名。不要直接把 31938 暴露到互联网。

1. 先限制 Beav 端口

在云安全组和服务器防火墙中，禁止互联网直接访问 31938。如果反向代理与 Beav 在同一台服务器，端口只应允许本机或该服务器的可信私有地址访问。

2. 让受控反向代理转发 HTTPS

以 Nginx 为例，把 <beav-private-ip>、beav.example.com 和证书路径替换成自己的值：

server {
    listen 443 ssl http2;
    server_name beav.example.com;

    ssl_certificate     /etc/letsencrypt/live/beav.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/beav.example.com/privkey.pem;

    location / {
        proxy_pass http://<beav-private-ip>:31938;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

保留 X-Forwarded-Proto: https、关闭代理缓冲并保持较长的读取超时，网页的登录 Cookie 和实时事件连接才能按 HTTPS 正常工作。

3. 只信任自己的代理

确认 31938 已经不能被公网直连后，为 Beav 服务添加 systemd 覆盖配置：

sudo systemctl edit beav-web

在打开的编辑器中加入：

[Service]
Environment=REDBOX_WEBUI_TRUST_PROXY=1

然后应用配置：

sudo systemctl daemon-reload
sudo systemctl restart beav-web

最后只通过 https://beav.example.com 登录，并从另一条网络验证 31938 不能直接访问。开启 REDBOX_WEBUI_TRUST_PROXY 后，Beav 会信任反向代理传入的 HTTPS 标记；因此绝不能在允许任意公网客户端直连 31938 时开启它。

需要帮助？

桌面端无法打开或局域网设备连不上时，先按本文的网络检查步骤处理；服务器问题先收集 beavctl status 和 beavctl logs 的输出。其他安装和桌面端问题见常见问题。