# 网页访问

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

- 原文: https://www.getbeav.com/docs/remote-access

网页访问让 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 登录服务器后，运行这一条命令：

```bash
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` 重设。

### 首次登录与连通性检查

在服务器上运行：

```bash
beavctl url
beavctl status
```

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

```bash
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`，不要重复执行多次安装。

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

```bash
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` 和证书路径替换成自己的值：

```nginx
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 覆盖配置：

```bash
sudo systemctl edit beav-web
```

在打开的编辑器中加入：

```ini
[Service]
Environment=REDBOX_WEBUI_TRUST_PROXY=1
```

然后应用配置：

```bash
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` 的输出。其他安装和桌面端问题见[常见问题](https://www.getbeav.com/docs/troubleshooting)。