# Docker 部署夭夭 Web

## 准备

- 安装 Docker Engine 和 Compose，或 Docker Desktop。
- 准备容器可访问的 Hermes Dashboard/Gateway，通常使用 9119 端口。
- 获取本项目源码，在仓库目录执行后续命令。

## 配置与启动

```sh
cp docker.env.example docker.env
```

编辑 `docker.env`：

| 配置 | 用途 |
| --- | --- |
| `HERMES_YAOYAO_UPSTREAM` | Hermes 上游地址，默认 `http://host.docker.internal:9119` |
| `HERMES_YAOYAO_BIND_ADDRESS` | Web 的宿主机发布地址，默认 `127.0.0.1`；局域网访问可设为 `0.0.0.0` |
| `HERMES_YAOYAO_PUBLISHED_PORT` | 宿主机 Web 端口，默认 `15300` |
| `HERMES_YAOYAO_ALLOWED_HOSTS` | 使用域名访问时填写对应域名，多个值用英文逗号分隔 |
| `HERMES_YAOYAO_CHAT_CACHE_MODE` | 普通聊天缓存策略，默认 `prefer-local` |

Docker Desktop 可通过 `host.docker.internal` 访问宿主机。Linux 上 Compose 将该名称映射到宿主机网关；Hermes 需要监听容器可访问的宿主机地址。远程 Hermes 直接填写其可访问地址。

```sh
docker compose --env-file docker.env config --quiet
docker compose --env-file docker.env up -d --build
docker compose --env-file docker.env ps
```

默认打开 `http://127.0.0.1:15300`。局域网设备使用宿主机 IP 和发布端口访问。首次打开页面创建管理员账号，再到系统设置配置 Hermes 连接凭据。通过域名提供公网访问时，在反向代理上配置 HTTPS，并将域名加入允许列表。

## 验证

以下命令使用默认发布端口；修改端口后同步调整 URL：

```sh
curl --fail http://127.0.0.1:15300/healthz
curl --fail http://127.0.0.1:15300/readyz
docker compose --env-file docker.env logs --tail=100 web
```

`healthz` 检查 Web 服务，`readyz` 检查 Hermes 上游。若上游不可达，检查 `HERMES_YAOYAO_UPSTREAM`、Hermes 监听地址及网络连通性；若需要认证，在 Web 系统设置中保存连接凭据。

登录后创建会话、收发消息、上传并下载附件，验证实际使用流程。

## 虚拟桌面与镜像准备

Docker 镜像运行 Web 服务，虚拟桌面由运行 Hermes 的电脑上的 Runner 提供。Web 容器不需要挂载 Docker socket、Hermes 源码或模型凭据。不要在 Web 容器里安装 Docker Desktop，也不要把宿主机的 Python 虚拟环境直接挂载进容器。

1. 在执行电脑安装 Hermes、Node.js 24 或更高版本，并启动 Docker/Podman。Hermes Dashboard 使用该电脑的回环地址。
2. 在 Web **设置 → 本地虚拟机 → 打开执行节点设置**，下载配套执行节点程序。填写节点名称、允许的 Profile、该电脑能够访问的 Web 地址；保持“启用隔离电脑 Worker”勾选。可信局域网 HTTP 需要明确勾选，其他场景使用 HTTPS。
3. Hermes 默认安装的三个路径可以留空，由 Runner 在执行电脑上查找 `~/.hermes/hermes-agent/venv/bin/python`。自定义安装再填写绝对路径。镜像 ID 留空，连接后由页面准备。
4. 注册并下载 `runner.json`，把程序包和配置放到执行电脑，执行：

```sh
mkdir -p yaoyao-runner
tar -xzf yaoyao-runner.tar.gz -C yaoyao-runner
chmod 600 runner.json
node yaoyao-runner/runner.mjs --config /完整路径/runner.json
```

整个程序目录须一起保留，包括 Python Worker、桌面构建资源和第三方许可证。Runner 凭据保存在配置文件内，不要发到聊天或提交到仓库。macOS 也可以使用配套 App 的“执行节点 → 导入节点配置…”，不需要另外安装 Node.js。

5. 回到本地虚拟机设置，等待节点连接，再点击 **准备本地虚拟机**。镜像检测、下载/构建、桌面验证全部在执行电脑上完成。
6. 在 Agent 聊天右上角打开 **电脑**，选择 **本地虚拟机**，创建桌面。可以预览、接管、启停，以及切换共享方式。

页面会区分“尚未连接执行节点”“节点未启用虚拟桌面”和“镜像尚未准备”。节点离线时，请检查执行电脑的 Runner；此时不能通过在 Web 容器内安装软件来修复。`HERMES_YAOYAO_LOCAL_VM_HOST=runner` 已作为镜像和 Compose 的默认值。

无法通过页面下载时，也可从已创建的 Web 容器取出同版本程序包：

```sh
docker compose --env-file docker.env cp web:/app/runner-bundle.tar.gz ./yaoyao-runner.tar.gz
```

验收截图：[Docker Web 的 Agent 桌面](screenshots/docker-vm/agent-desktop.png)。截图来自独立测试数据：真实容器 Web、下载的配套 Runner、Hermes Worker 和虚拟桌面；模型回复由测试服务提供。

## 数据与备份

Compose 使用 `yaoyao-data` 命名卷，挂载到 `/var/lib/hermes-yaoyao`。账号、SQLite 数据库、聊天缓存、文件及密钥随数据卷持久保存。

备份时先停止 Web，然后复制完整数据目录，再启动服务：

```sh
mkdir -p backups
docker compose --env-file docker.env stop web
docker compose --env-file docker.env cp web:/var/lib/hermes-yaoyao/. ./backups/
docker compose --env-file docker.env start web
```

为每次备份使用独立目录，并保留文件权限。恢复时将完整备份放回数据卷，确认容器内 `node` 用户可以读写后再启动服务。

## 升级与停止

更新仓库源码后重新构建和启动：

```sh
docker compose --env-file docker.env up -d --build
docker compose --env-file docker.env ps
```

新容器继续使用已有的命名卷。升级前完成备份，并按发布说明更新配套客户端。

```sh
docker compose --env-file docker.env down
```

上述停止命令保留数据卷；`down --volumes` 会删除数据，应仅在明确清空部署时使用。