Inicio Explorar Axuda
Iniciar sesión
samien
/
yaoyao
1
0
Fork 0
Ficheiros Incidencias 0 Pull Requests 0 Wiki
Árbore: e26699c133
Ramas Etiquetas
yaoyao
/
docs
/
docker-install.md

docker-install.md 13 KB
Histórico Raw

Docker 部署夭夭 AI

准备

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

已发布的远程镜像

镜像仓库：samienluo/yaoyao。

标签 架构
v0.4.16-amd linux/amd64
v0.4.16 linux/amd64、linux/arm64，拉取时自动匹配
latest 最新稳定通用镜像，当前指向与 v0.4.16 相同的镜像 
docker pull samienluo/yaoyao:v0.4.16
# 需要固定 AMD64 时：
docker pull samienluo/yaoyao:v0.4.16-amd

每次新版本发布都会更新 latest，旧版本标签继续保留。需要固定部署版本时使用具体版本标签。

配置与启动

cp docker.env.example docker.env

编辑 docker.env：

配置 用途
HERMES_YAOYAO_IMAGE 远程镜像可设为 samienluo/yaoyao:v0.4.16 或 samienluo/yaoyao:latest；未设置时使用本地构建名称
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.env 设置上述镜像标签后执行：

docker compose --env-file docker.env config --quiet
docker compose --env-file docker.env pull web
docker compose --env-file docker.env up -d --no-build web
docker compose --env-file docker.env ps

从本地源码构建时执行：

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 系统设置中保存连接凭据。

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

随 Web 一起部署固定共享桌面

samienluo/yaoyao 是 Web 服务镜像；共享桌面使用独立的桌面镜像。

使用配套的 单个 compose.desktops.yaml 部署文件，同时创建 Web 和共享桌面容器。默认示例为两台桌面；不是在 Web 页面里临时创建虚拟机。

cp docker.env.example docker.env
# 配置 Web 发布地址、端口和已有 Hermes 的 9119 地址。
docker compose --env-file docker.env -f compose.desktops.yaml up -d --build
docker compose --env-file docker.env -f compose.desktops.yaml ps
  • Compose 创建几台，页面就显示几台；没有数量修改、镜像准备、创建、删除或重建按钮。
  • Agent 聊天右上角 电脑 → 此 Agent 使用的电脑，选择已有的“共享桌面 1 / 共享桌面 2”等目标。多个 Agent 可以连接同一台共享桌面，复用文件和浏览器资料。
  • 桌面连接使用专用 Unix socket 数据卷。Web 容器不挂载宿主 Docker socket，桌面也不发布 VNC、HTTP 或控制端口。
  • 每台桌面的工作文件放在独立的 desktop-*-workspace 命名卷内。Compose 桌面统一使用 /home/cua/workspace，不会更改基础 Profile 的工作目录配置。
  • 示例桌面使用 network_mode: none，默认没有桌面外网。网络、资源额度、镜像版本和服务数量均由部署者在 Compose 中管理；本机 App 的动态虚拟机模式保持原有方式。

如部署前要调整数量、名称或镜像，编辑 deploy/compose-desktops.json，保留已有桌面 ID，重新生成配套文件：

node scripts/generate-desktop-compose.mjs
node scripts/generate-desktop-compose.mjs --check
docker compose --env-file docker.env -f compose.desktops.yaml up -d --build

生成器会把 Web 连接清单、桌面服务和数据卷同步写入同一个 Compose 文件。运行中不能通过 Web API 扩容。不要用 down --volumes 更新部署，否则会删除工作文件。

Cursor Universal 可选配置

新部署可直接选择仓库中的 compose.desktops.cursor.yaml，同时启动 Web 和一台“Cursor 开发桌面”。这是完整部署文件，单独使用；与 compose.yaml、compose.desktops.yaml 三选一，不要叠加启动。电脑环境是共享宿主内核的 Linux 桌面容器。

项目 配置
上游基础镜像 public.ecr.aws/k0i0n2g5/cursorenvironments/universal:sand-box-latest
构建固定版本 sha256:858b6df5d0aeffd5db0e20c81553e98f84b07e9c700a13fcd1febac0e8c54830
兼容镜像 yaoyao-desktop:cursor，通过 deploy/computer/Dockerfile.cursor 在本地构建
已发布兼容镜像 samienluo/yaoyao-desktop:v0.4.12-cursor-amd
架构 linux/amd64；ARM64 宿主需要 Docker 的 amd64 模拟支持
桌面资源 2 CPU、4 GB 内存、512 MB 共享内存、512 个进程
持久工作目录 desktop-cursor-workspace 卷 → /home/cua/workspace，含浏览器资料
Web 连接 desktop-cursor-ipc 卷中的私有 Unix socket，Web 只读挂载
桌面网络 默认 network_mode: none，不发布任何桌面端口

上游标签会变化，Dockerfile 固定已适配的 digest，加入 CUA 驱动、浏览器启动器和夭夭私有桥接协议。因此不能把上游原始镜像直接填到 YAOYAO_CURSOR_DESKTOP_IMAGE；该变量只用于指定构建后的兼容镜像名称。

首次配置（已有 docker.env 时直接编辑）：

cp -n docker.env.example docker.env

docker.env 的相关配置示例：

HERMES_YAOYAO_IMAGE=yaoyao:local
HERMES_YAOYAO_UPSTREAM=http://host.docker.internal:9119
HERMES_YAOYAO_BIND_ADDRESS=127.0.0.1
HERMES_YAOYAO_PUBLISHED_PORT=15300
YAOYAO_CURSOR_DESKTOP_IMAGE=yaoyao-desktop:cursor

使用本次源码构建 Web 与桌面镜像，然后启动：

docker compose --env-file docker.env -f compose.desktops.cursor.yaml config --quiet
docker compose --env-file docker.env -f compose.desktops.cursor.yaml build web desktop-cursor
docker compose --env-file docker.env -f compose.desktops.cursor.yaml up -d --no-build
docker compose --env-file docker.env -f compose.desktops.cursor.yaml ps
curl --fail http://127.0.0.1:15300/healthz

使用 Docker Hub 发布镜像时，在 docker.env 设置：

HERMES_YAOYAO_IMAGE=samienluo/yaoyao:v0.4.16
YAOYAO_CURSOR_DESKTOP_IMAGE=samienluo/yaoyao-desktop:v0.4.12-cursor-amd

直接拉取并启动，无需本地编译：

docker compose --env-file docker.env -f compose.desktops.cursor.yaml pull web desktop-cursor
docker compose --env-file docker.env -f compose.desktops.cursor.yaml up -d --no-build

Web 镜像自动匹配 AMD64 / ARM64；Cursor 桌面为 AMD64。已有标准桌面仍沿用其镜像配置。

随后按下方“Hermes 执行连接”注册或连接执行节点，再在 Agent 聊天的 电脑 → 此 Agent 使用的电脑 中选择“Cursor 开发桌面”。

需要浏览外网或下载依赖时，创建 compose.desktops.network.yaml：

services:
  desktop-cursor:
    network_mode: bridge

之后启动、查看和停止均带上两个文件：

docker compose --env-file docker.env -f compose.desktops.cursor.yaml -f compose.desktops.network.yaml up -d --no-build

bridge 允许桌面通过宿主 Docker 网络出站，也可能访问宿主及局域网；它不提供本机动态桌面的受控外网代理策略。仅在部署网络允许时启用，并通过宿主防火墙管理访问范围。桌面仍不映射 VNC 或控制端口。网络模式语义见 Docker Compose 服务配置。

调整这套配置的桌面数量或名称时，编辑 deploy/compose-desktops.cursor.json，然后运行 node scripts/generate-desktop-compose.mjs；生成器同时更新两套部署文件，--check 同时检查它们。已有标准桌面的部署若只想切换一台镜像，应按下一节保留原有 ID、service 和工作卷。

同时部署两种镜像

在 deploy/compose-desktops.json 的每个桌面条目增加 imageKey：standard 为现有标准桌面（不填写时的默认值），cursor 为 Cursor Universal 兼容桌面。例如保留已有 ID 和 service，将第二台配置为：

{"id":"eba5caaf-744e-4f27-bcdd-1f1f35d05a42","service":"desktop-2","name":"Cursor 开发桌面","imageKey":"cursor"}

然后运行上述生成和部署命令。生成器为 Cursor 桌面指定 Dockerfile.cursor 和 platform: linux/amd64；镜像名可通过 YAOYAO_CURSOR_DESKTOP_IMAGE 设置，标准桌面继续使用 YAOYAO_DESKTOP_IMAGE。两种变量应指向对应的夭夭兼容镜像，不能将上游原始 Cursor 镜像直接作为运行镜像。

聊天电脑面板显示每台桌面的镜像名称，机器人通过选择已有桌面来选择环境。不同桌面各自使用独立数据卷，可同时使用不同镜像；共享同一桌面的成员只能使用该桌面的一个镜像。改变现有条目的镜像会在下次 Compose 部署时重建该实例，请先结束使用它的任务，保留原有 ID、service 和数据卷。

Hermes 执行连接

Compose 管理桌面，Hermes 执行连接负责模型运行和工具调用。沿用已有执行节点；新部署可在 设置 → 本地虚拟机 → 打开执行节点设置 下载程序和注册配置。此部署生成的配置自动带 managedBy: compose，执行节点不再创建桌面，也不需要安装 Docker。

执行节点只需已有 Hermes 和 Node.js 24+。默认 Hermes 路径可留空；自定义安装填写绝对路径。把下载的程序和 runner.json 放在运行 Hermes 的电脑：

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

整份程序目录须保留。节点配置包含私有凭据，不要提交到仓库。运行中的任务或接管操作仍有独占授权；交还后其他成员才能操作。取消无法确认结束的命令时，会重置对应桌面服务来终止旧程序，数量与数据卷保持不变。

只需要 Web 服务、继续使用既有外部动态桌面的部署仍可使用 compose.yaml；三种部署文件任选其一，不要让两套 Web 同时写同一数据卷。

验收截图：Docker Web 的 Agent 桌面。验收使用独立数据和测试模型服务，桌面与容器连接是真实运行。

数据与备份

Compose 使用 yaoyao-data 命名卷，挂载到 /home/node/.yaoyao。账号、SQLite 数据库、聊天缓存、文件及密钥随数据卷持久保存。固定桌面部署还必须备份每台桌面的 desktop-*-workspace 卷；desktop-*-ipc 卷只是连接通道。

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

mkdir -p backups
docker compose --env-file docker.env stop web
docker compose --env-file docker.env cp web:/home/node/.yaoyao/. ./backups/
docker compose --env-file docker.env start web

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

升级与停止

使用远程镜像时，更新 docker.env 中的固定版本标签，或继续使用 latest，然后拉取并重新创建 Web 容器：

docker compose --env-file docker.env pull web
docker compose --env-file docker.env up -d --no-build web
docker compose --env-file docker.env ps

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

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 会删除数据，应仅在明确清空部署时使用。