> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/tinycomputer-docker.md).

# Linux 和 Docker 上的 TinyComputer 浏览器

在 Linux 容器中以无头模式运行 TinyComputer 浏览器，使用本地构建的模块和无人值守自动化。

该 `browser` 工具通过 TinyComputer 模块（`libtinycomputer.so`）驱动 Chromium。已编译的模块注册表只会为实际发布了 TinyComputer 的平台固定其版本。如果你的 Linux 主机没有对应的固定版本，或者你需要使用与你的核心构建所依据的确切 `vendor/tinycomputer` gitlink 构建的模块，请自行构建，并通过模块覆盖配置让核心使用它。

本页介绍容器构建配方、加载器的目录规则、无头研究代理所需的浏览器设置，以及如何让由 cron 驱动的轮次在没有交互式批准的情况下点击和输入。

{% hint style="warning" %}
本地构建产物由操作者自行负责。切勿将其 SHA-256 写入 `crates/openhuman-core/src/modules/registry/` 作为发布版本固定值：固定值只能来自已发布的版本。
{% endhint %}

## 1. 在构建器阶段构建模块

`vendor/tinycomputer/scripts/build-module` 会完成加载器所需的一切操作。它会运行 `cargo build --locked --release -p tinycomputer --lib` 并将 `libtinycomputer.so` 安装到 `TINYCOMPUTER_MODULE_DIR` （权限模式 `644`，目录 `755`）。它会在 `modules.toml` 中记录该库的 SHA-256，并将文件放在库文件旁边；随后逐级检查所有父目录，如果加载器会拒绝其中任何一个目录，就会提前报错。

先初始化嵌套子模块（`git submodule update --init --recursive vendor/tinycomputer`）。TinyComputer 自带 TinyBus、agent-browser 和 agent-desktop。请使用与核心相同的代码检出版本进行构建：如果模块的 TinyComputer 契约版本与核心自身的版本不兼容，主机将拒绝加载该模块。

```dockerfile
# 根据此代码检出记录的 gitlink 构建 libtinycomputer.so。
FROM rust:1.99.1-bookworm AS tinycomputer
RUN apt-get update && apt-get install -y --no-install-recommends \
        build-essential pkg-config ca-certificates \
        libasound2-dev libxdo-dev libxtst-dev libx11-dev \
    && rm -rf /var/lib/apt/lists/*
WORKDIR /src/tinycomputer
COPY vendor/tinycomputer/ ./
# 始终由 root 拥有且权限为 755：这是加载器接受的设置。
ENV TINYCOMPUTER_MODULE_DIR=/opt/tinycomputer
RUN scripts/build-module
```

然后，将它添加到仓库 `Dockerfile` 的运行时阶段（其中已包含模块链接所需的运行时库 `libasound2`, `libxdo3`, `libxtst6` 和 `libx11-6` ），并一并添加 Chromium：

```dockerfile
RUN apt-get update && apt-get install -y --no-install-recommends \
        chromium fonts-liberation \
    && rm -rf /var/lib/apt/lists/*
# 同时复制库文件及其 modules.toml 证明文件。
COPY --from=tinycomputer /opt/tinycomputer/ /opt/tinycomputer/
RUN chown -R root:root /opt/tinycomputer \
 && chmod 755 /opt/tinycomputer \
 && chmod 644 /opt/tinycomputer/libtinycomputer.so /opt/tinycomputer/modules.toml
```

### 加载器检查的内容

TinyBus 加载器（`vendor/tinybus/crates/tinybus/src/module/host.rs`）会拒绝不满足以下所有条件的构件：

* **从 `/` 到模块自身** 的每个目录，都必须归 root 或核心程序运行用户（镜像中的 uid `10001` ）所有。除非设置了粘滞位，否则这些目录都不得允许组或其他用户写入。路径中的符号链接组件会被拒绝，库文件本身则使用 `O_NOFOLLOW`打开。不要将模块放在绑定挂载或命名卷中：这些位置通常归其他用户所有，或允许组用户写入。
* **文件** 必须是一个小于 512 MiB 的普通 `.so` 文件。
* **`modules.toml` 与库文件放在一起时**，其中必须记录该库准确的 SHA-256 值。若校验值不匹配，加载器就会拒绝该库，因此重新构建库后需要重新生成 `modules.toml` 由 `build-module` 生成的文件。请将两者放在一起。若没有此证明，模块仍会加载，但不会被视为经过证明的接收方，因此不会向它发送诸如 `StartTask` （ `task` 操作）之类的机密调用。

模块一旦被拒绝或发生故障，就会一直处于拒绝状态，直到核心程序重启。

## 2. 使用模块覆盖项加载

```toml
[modules]
overrides = [{ id = "tinycomputer", path = "/opt/tinycomputer/libtinycomputer.so" }]
```

`id` 是注册表 ID（`tinycomputer`），而 `path` 是库文件的绝对路径。覆盖项会优先于搜索路径和发布缓存进行检查，并绕过已编译的发布版摘要，因此只有操作者自己的配置可以指定覆盖项（`config/schema/modules.rs`, `modules::ops::local_override`). `[modules] enabled` 必须保持为 `true` （默认值）。

## 3. 无头研究代理的浏览器设置

```toml
[browser]
enabled = true
headless = true
chrome_path = "/usr/bin/chromium"
# 保留 Cookie 和登录状态，以便跨会话和重启后继续使用。
profile_mode = "persistent"
profile_path = "/home/openhuman/.openhuman/browser-profile"
download_dir = "/home/openhuman/.openhuman/browser-downloads"
# 选择启用：参见下文“无人值守操作”。
unattended_actions = ["click", "press"]

[http_request]
# 浏览器共享此列表；浏览器会剔除 "*"。
allowed_domains = ["example.com", "docs.example.org"]
```

* `chrome_path` 会作为浏览器可执行文件传递给模块。Debian 的 `chromium` 软件包会安装 `/usr/bin/chromium`.
* `profile_mode = "persistent"` 需要一个 **绝对路径** `profile_path`，而且 `download_dir` 也必须是绝对路径。否则会拒绝该会话。请将二者放在工作区卷（镜像中的`/home/openhuman/.openhuman` ）下；入口点会将其所有者改为核心程序的用户，因此容器重启后这些文件仍会保留。
* 导航遵循 `[http_request].allowed_domains`的设置。列表为空时会拒绝所有会话。若要允许浏览器访问任意位置，请在容器环境中设置 `OPENHUMAN_BROWSER_ALLOW_ALL=1` ，而不要添加 `"*"`.
* agent-browser 检测到容器、root 用户或较小的 `--no-sandbox` 和 `--disable-dev-shm-usage` 时，会自动添加这两个参数。 `/dev/shm`.

## 4. 无人值守操作

默认情况下，每次单击、双击、填充、输入、按键、选择和勾选操作都必须通过强制的主机审批关卡。浏览器任务暂停在 `needs_approval`时也一样。强制关卡只会在实时 WebChat 轮次中等待审批，其他情况一律拒绝；因此，若不设置下文所述选项，cron 作业可以打开并读取页面，却无法点击“下一页”链接。

`[browser] unattended_actions` 指定 **受信任的无人值守轮次** 无需审批即可执行的操作类型：

| 名称                      | 涵盖的操作                                                           |
| ----------------------- | --------------------------------------------------------------- |
| `click`, `double_click` | 单击元素，包括使用 `find` 并设置 `find_action = "click"`                    |
| `fill`, `type`          | 在字段中输入文本                                                        |
| `press`                 | 按下按键，例如 `Enter`                                                 |
| `select`, `check`       | 选择选项、勾选复选框                                                      |
| `task_step`             | 浏览器 `task` 暂停于 `needs_approval` 在执行不可逆步骤前，并通过 `confirm_pending` |

* 该工具从每个回合的 `CoreContext` 中读取回合来源；cron、后台任务和工作流入口会在各自回合的作用域内设置该上下文。
* **只有** 来源为 `TrustedAutomation` 且来源类型为 `Cron`, `CronActions` （其代理已选择启用 `scheduled_actions`), `Background`，或 `Workflow { require_approval: false }` 的 cron 回合才符合条件。无论是否启用了该选项，cron 回合都会经过此检查： `browser` 工具声明自身不会产生外部影响，因此安全门的只读 cron 阶段会放行调用，而是否执行该操作则由此处决定。
* WebChat、外部渠道（Telegram、Slack 等）、CLI 和直接聊天、未标记的回合，以及设置了 `require_approval = true` 的工作流，仍会像之前一样强制通过安全门，即使操作在允许列表中也不例外。
* 默认列表为空，因此不会改变任何行为。
* 未知名称不会放行任何操作。加载时，核心会记录一条警告，其中包含未知条目的数量（绝不包含其文本）以及已知名称列表。
* 每个获准操作都会以 `info` 级别记录，包含操作类型、摘要的前 12 个十六进制字符以及来源类别。不会记录选择器、输入值、页面内容或任务 ID。搜索 `[browser] unattended action allowed`.
* 付款检查点不会 `needs_approval` 暂停。无论此列表如何设置，任务到达该处时仍会停止。

`task_step` 会放行任务控制器自身标记为不可逆的步骤，例如发送、提交或删除。仅将其列入适用于提示词和允许访问网站均由你控制的任务。

## 5. 拒绝数据中心地址的网站

有些网站会屏蔽整个数据中心网段。例如，Reddit 会对来自云虚拟机的所有页面请求返回“你已被网络安全系统屏蔽”。要解决这个问题， `[browser] upstream_proxies` 可将选定域名的流量经由上游 HTTP 代理路由，例如住宅或移动网络出口：

```toml
[browser]
upstream_proxies = [
  { domains = ["reddit.com", "redd.it", "redditstatic.com", "redditmedia.com"], url = "http://user:password@proxy.example:8000" },
]
```

* 域名匹配自身及其所有子域名。其他所有主机仍会直接连接。
* 路由不会绕过策略。TinySecurity 会像授权直接访问的页面一样，逐一授权每个经路由访问的页面；禁止访问列表仍然适用。TinyComputer 打开套接字连接到代理之前，代理自身的主机和端口也必须通过 TinySecurity 的浏览器拨号授权。随后，TinyComputer 会要求代理建立一个 `CONNECT` 隧道，连接到 TinySecurity 为该页面主机批准的地址，因此代理不会进行任何解析。浏览器的 `Host` 标头和 TLS SNI 会原样通过隧道。普通的 `http://` 页面也使用同一隧道。
* 仅支持 `http://` 代理 URL。用户名或密码中的 `@`, `:` 或 `/` 都必须进行百分号编码。凭据会以 `Proxy-Authorization: Basic`.
* URL 本身就是凭据。它只会通过 TinyComputer 的主机私有 `browser.egress` 部分传递给 TinyComputer。配置快照和调试输出中会对其进行遮蔽，且绝不会记录到日志中。请确保只有核心程序的用户可以读取 `config.toml` 。
* 只有启用了浏览器出口流量强制管控时，此功能才有效；默认构建已启用该功能，并包含 `security-module`。更改列表后，须等核心程序下次启动才会生效。
* 如果代理拒绝凭据（`407`）或拒绝建立隧道，页面将失败并显示 `502`。核心日志中只会记录状态。
