Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

10.2 KB
Raw Blame

title: Docker description: 运行官方 Adelie 镜像,一个容器加一个数据卷,就在 7364 端口提供完整的 Web App。

官方镜像运行的就是 penguin server 启动的那个服务端,Web App 也在其中。整套部署只有一个容器和一个数据卷,所以要把 Adelie 装到自己电脑以外的机器上,Docker 是最短的一条路。

开始之前

  • 在要运行 Adelie 的机器上装好 Docker。下面的示例同时给出 Docker Compose 和 docker run 两种写法。
  • 一个模型供应商的 API Key。

启动容器

在下面两个标签页中任选一种:保存 compose 文件,或者直接执行命令。

services:
  penguin:
    image: hiyouga/penguinharness:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:7364:7364"
    volumes:
      - penguin-data:/data
    stop_grace_period: 30s

volumes:
  penguin-data:
docker volume create penguin-data
docker run -d --name penguin \
  -p 127.0.0.1:7364:7364 \
  -v penguin-data:/data \
  --restart unless-stopped \
  hiyouga/penguinharness:latest

把 compose 文件保存在当前目录后,执行 docker compose up -d 启动。无论用哪种方式,启动后都能在运行 Docker 的那台机器上通过 http://localhost:7364 打开 Web App。

从其他机器访问

两个示例都把端口发布在运行 Docker 那台机器的回环接口上,所以新部署的服务从别处访问不到。要在另一台机器上使用,可以用 ssh 转发端口:ssh -L 7364:127.0.0.1:7364 <host>。

对外开放需要你主动去做:改为把端口发布到所有网络接口,docker run 用 -p 7364:7364 或 -p 0.0.0.0:7364:7364,compose 里写 "7364:7364"。最好再放到一个终结 TLS 的反向代理之后,见在反向代理后运行。

在容器自己的网络命名空间里,服务始终监听 0.0.0.0,端口发布正是靠这一点才能生效。-p 里的地址决定的是宿主机这一侧。

首次登录

新的数据目录还没有密码。在设置密码之前,服务端每次启动都会以带边框的提示打印一条登录链接。从容器日志里找到它:

docker compose logs penguin        # or: docker logs penguin

提示如下:

+----------------------------------------------------------------------------------------------+
|   This server has no admin password yet. Open this link to claim it:                         |
|                                                                                              |
|     http://localhost:7364/api/auth/claim?token=GSiEDYM8MbsrqtMj7ofq7klUyXcfQNwt3oUriUHiBI8   |
|                                                                                              |
|   The link lasts 30 days or until a password is set; restarting prints a fresh one.          |
+----------------------------------------------------------------------------------------------+

链接里的 localhost 是服务端对自己的称呼。按上面的方式发布在回环接口上时,它对你来说也是同一台机器,所以在运行 Docker 的机器上原样打开链接即可。如果已经把容器发布到网络上,就把 localhost 换成你访问它时用的主机名。两种情况下都要保留完整的 ?token=...。

打开链接即以 admin 身份登录,然后设置密码。每次启动都会重新生成链接,所以重启之后,你手上那条链接就失效了,日志里会打印一条新的。

提前设置密码

如果不方便从日志里读取链接,可以直接固定密码,但要在首次启动之前设置:

environment:
  ADELIE_SEED_ADMIN_PASSWORD: "choose-something-long"

服务端会用这个密码(至少 8 个字符)创建内置的 admin 账号,并且不再打印登录提示。这个变量只在还没有任何用户时生效,也就是空数据目录第一次启动的时候。给已经认领过的数据目录加上它不会有任何效果,事后修改同样无效。

配置模型

Adelie 不内置任何模型凭据。可以在 Web App 的模型库页面添加模型,也可以在容器里用 CLI 添加:

docker compose exec -u penguin penguin \
  penguin config model add --provider deepseek --model-id deepseek-flash --api-key sk-... --set-default

命令中的 -u penguin 不能省略。docker exec 默认以 root 身份执行,写进 /data 的文件会归 root 所有,而服务端是以 uid 1000 运行的。

内置分组见模型与 Provider。

跑通第一个 Task

在 Web App 的侧边栏点击新建对话,然后发送第一条消息,例如「创建 hello.txt,内容为 Hello, Penguin」。Agent 执行的命令都在容器内运行;怎样把宿主机上的目录交给 Agent,见 Agent 能访问什么。对话页面的完整说明见对话。

选择镜像 tag

镜像名为:

hiyouga/penguinharness

tag 分为两类:

  • latest 跟随 main 分支,每次推送都会重新构建。
  • X.Y.Z 是正式发布版,用这个 tag 自身的源码构建。

没有 main-<sha>、X.Y 或 stable 这类 tag,因此不存在换个名字跟着变动的别名。每个 tag 都是覆盖 linux/amd64 与 linux/arm64 的多平台 manifest,同一个引用在 x86 VPS 和 arm64 VPS 上都能用。本页示例使用 latest;如果希望部署只在发布新版本时才更新,就固定到具体版本号。

镜像里有什么

项目 说明
基础镜像 Ubuntu 24.04,加上官方 Node.js 运行时,版本与发布包内置的一致
启动命令 penguin server,监听 0.0.0.0:7364
数据目录 /data,声明为数据卷,存放模型配置、Session、Trace 和 SQLite 数据库
运行用户 penguin,uid/gid 1000。入口脚本以 root 启动,只为接管数据目录的所有权,随后降权为 penguin 用户
健康检查 每 30 秒请求一次 GET /api/install
工具 git、curl 与 Ubuntu 标准用户态工具,供 Agent 执行命令

Agent 能访问什么

Agent 通过 exec_command 执行的一切都发生在这个容器里,用的是容器的文件系统和网络。这是隔离边界,也是能力的上限:容器能访问到的,Agent 都能访问到,除此之外一概访问不到。

要给 Agent 一个 Workspace,就挂载一个目录,例如 -v /srv/project:/srv/project。挂载的目录必须允许 uid 1000 写入。

给镜像添加工具

镜像里没有编译器,除 Node 之外也没有其他语言运行时。在容器里执行 apt-get install 可以应付一次性的需要,但下一次 docker pull 之后装过的包就没了。长期依赖的工具,请构建一个派生镜像:

FROM hiyouga/penguinharness:latest
USER root
RUN apt-get update && apt-get install -y --no-install-recommends python3 ripgrep \
    && rm -rf /var/lib/apt/lists/*
USER penguin

运行时镜像刻意不带 C/C++ 工具链:工具链只存在于构建阶段,构建完就丢弃了。

环境变量

下表列出容器部署会用到的变量,完整列表见配置参考。

变量 在本镜像中
ADELIE_HOME /data。除非同时移动数据卷,否则不要修改
HOST 0.0.0.0,作用于容器自己的网络命名空间。宿主机一侧由 -p 决定,示例都保持在回环接口上
PORT 7364。修改后,健康检查会随之改用新端口
ADELIE_SEED_ADMIN_PASSWORD 固定初始管理员密码,仅在首次启动时生效,见提前设置密码
ADELIE_TRUST_PROXY 放在终结 TLS 的反向代理之后时设为 1,会话 Cookie 才会带上 Secure 标记
ADELIE_PREVIEW_ORIGIN 路由到同一容器的第二个主机名,用于 Workspace 中的 HTML 预览
ADELIE_UPDATE_CHECK 设为 off 关闭自动的版本检查。模型请求、远程控制连接、Key 授权和代理测试照常出站

在反向代理后运行

把容器发布在回环接口上,在它前面终结 TLS,并设置 ADELIE_TRUST_PROXY=1。反向代理必须自己设置或清除 x-forwarded-proto:这个请求头由调用方提供,服务端正因如此,在你明确开启之前一直不采信它。HTTPS 部署如果不设置 ADELIE_TRUST_PROXY,签发的会话 Cookie 就不带 Secure 标记。

提供 Workspace 预览

Task 生成的 HTML 在有独立来源时,会从独立的来源提供预览。绑定在非回环地址上时,推导不出对应的回环地址,预览会退回同源沙箱,这时 Cookie、localStorage 和第三方嵌入内容都不能用。要恢复隔离的预览,把 ADELIE_PREVIEW_ORIGIN 指向路由到同一容器的第二个主机名。它必须在主机名上有所不同,只换端口不行。

升级容器

拉取更新的 tag,然后重建容器。数据目录在数据卷上,会原样保留:

docker compose pull && docker compose up -d

[!WARNING] 不要在容器内更新。更新弹窗会提示当前安装无法自行更新,而 penguin update 在容器里装下的任何东西,都会在下次重建容器时丢失。

服务端会平稳停止:收到 SIGTERM 后,它先中断正在运行的 Task,等它们收尾,再关闭数据库。空闲时不到一秒就能停下,繁忙时可能要几秒,所以 compose 示例调大了 Docker 默认 10 秒的宽限期。

重置忘记的管理员密码

先停止服务端,因为一个数据目录同一时刻只能有一个写入者。然后重置密码,再重新启动:

docker compose stop penguin
docker compose run --rm penguin penguin server reset-admin-password
docker compose start penguin

重置不需要其他授权:数据目录本身就是授权,能执行这条命令的人本来就拥有这个数据库。admin 账号会回到未认领状态,已有的登录会话全部失效。之后按照首次登录的做法,用日志里的首次登录链接重新登录。

下一步