---
order: 5
navTitle: 截图服务
---
# 截图服务配置

SuccBI 的缩略图生成和后端导出功能依赖截图服务。当前产品实现中，Java 侧不会再直接启动本机
Chrome，而是通过系统设置中的 Browserless 地址连接截图运行时。

\[\[toc]]

## 运行环境要求

截图服务需要以下运行环境：

| 依赖 | 说明 |
| --- | --- |
| **Browserless 服务** | 截图服务实际连接的浏览器运行时 |
| **Node.js** | Browserless 运行所需环境 |
| **Chromium 浏览器** | Browserless 底层使用的浏览器内核 |

## 部署 Browserless{#install-browserless}

安装前确认 Node.js 已安装（参见 [Node.js 安装配置](../basic-install/Nodejs.md)）。

产品绿色包会通过 `packagefiles/server/playwright` 下的脚本启动 Browserless。日常部署时，需要保证：

1. Browserless 已随产品包正确部署并成功启动。
2. Browserless 使用的 Node.js 与浏览器运行时可正常访问。
3. Browserless 与 BI 服务之间网络互通。

如果是开发环境，也可以使用工作区中的 Browserless 启停入口进行调试。

## 配置截图服务地址{#configure-browserless}

启动 Browserless 后，需要在系统设置中配置截图服务地址。

位置：

- **系统设置** > **更多** > **远程服务** > **文档转换**

配置项：

- `sys.basic.browserServerUrl`

示例：

```text
ws://127.0.0.1:3000/chromium/playwright
```

系统前后端都基于这个地址访问 Browserless。详见[文档转换](../../../sys-settings/more/remote-services/doc-converter.md)。

## 配置 BI 回连地址{#configure-local-web-address}

当 Browserless 与 BI 服务不在同一台机器上时，需要额外配置 JVM 启动参数 `-Dsucc.localWebAddress`，
让 Browserless 能访问到 BI 当前服务地址，例如：

```properties
-Dsucc.localWebAddress=http://192.168.7.128:8080
```

如果 Browserless 与 BI 服务同机部署，通常无需额外配置。

## Linux 字体安装{#linux-fonts}

在 Linux 服务器上，如果截图中出现乱码或方块字，需安装中文字体，参见[Linux 安装中文字体](./linux-fonts.md)。

## 问题排查{#troubleshooting}

1. 检查 Browserless 是否已成功启动，并确认服务地址可访问。
2. 检查系统设置中的 `sys.basic.browserServerUrl` 是否填写正确。
3. 如果 Browserless 独立部署，检查 `-Dsucc.localWebAddress` 是否已正确配置为 Browserless 可访问的 BI 地址。
4. 检查 BI 服务日志，`Screenshotter` 相关日志包含详细的初始化和执行信息。