صفحهٔ اصلی گشت‌و‌گذار راهنما
ورود
samien
/
yaoyao
1
0
انشعاب 0
پرونده‌ها مشکلات 0 درخواست واکشی 0 ویکی
درخت: 3ae168d325
شاخه‌ها تگ‌ها
yaoyao
/
docs
/
docker-install.md

docker-install.md 5.6 KB
تاريخچه خام

Docker 部署夭夭 Web

准备

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

配置与启动

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 直接填写其可访问地址。

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：

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，把程序包和配置放到执行电脑，执行：

    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。

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

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

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

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

验收截图：Docker Web 的 Agent 桌面。截图来自独立测试数据：真实容器 Web、下载的配套 Runner、Hermes Worker 和虚拟桌面；模型回复由测试服务提供。

数据与备份

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

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

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 用户可以读写后再启动服务。

升级与停止

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

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

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

docker compose --env-file docker.env down

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