Paseo 官方 Docker 镜像部署指南：自托管 daemon 与 Web UI 的容器化实践-育师

Paseo 官方 Docker 镜像部署指南：自托管 daemon 与 Web UI 的容器化实践

【免费下载链接】paseoOrchestrate multiple coding agents from desktop and mobile项目地址: https://gitcode.com/gh_mirrors/pa/paseo

导读

Paseo 是一个从桌面端与移动端编排多个 coding agent 的开源平台。官方发布了一个容器镜像，用于在服务器、虚拟机、NAS 或 homelab 机器上运行其 daemon，并且同一镜像内置了打包好的浏览器 Web UI——一个容器同时提供 daemon API 和自托管 UI。本文将完整讲解该镜像的工作原理、快速启动、Docker Compose 编排、Agent CLI 安装、数据卷、反向代理、安全加固、本地构建与常见问题排查，并结合仓库中的 Dockerfile、入口脚本与 daemon 配置源码，给出源码级佐证。

镜像工作原理

镜像源码位于docker/目录，核心构建定义是docker/base/Dockerfile。官方镜像的关键设计如下：

从源码工作区 tarball 构建@getpaseo/server与@getpaseo/cli：构建分两个阶段，第一阶段source-pack在node:22-bookworm-slim上执行npm ci并逐个npm pack出@getpaseo/highlight、@getpaseo/relay、@getpaseo/protocol、@getpaseo/client、@getpaseo/plugin、@getpaseo/server、@getpaseo/cli七个 workspace 包；第二阶段再全局安装这些 tarball，并校验supervisor-entrypoint.js的存在与语法。
以非 root 的paseo用户运行 daemon：镜像内创建 uid/gid 均为1000的paseo用户，入口脚本通过gosu从 root 降权到该用户执行。
监听容器内0.0.0.0:6767：由环境变量PASEO_LISTEN控制，Dockerfile 中默认值为0.0.0.0:6767，并EXPOSE 6767。
默认开启打包的 daemon Web UI：镜像设置PASEO_WEB_UI_ENABLED=true；静态 UI 文件无需 daemon 认证即可加载，API 与 WebSocket 请求在配置了PASEO_PASSWORD时仍受密码保护。
daemon 状态与 agent 凭据存放在/home/paseo：同时将CLAUDE_CONFIG_DIR=/home/paseo/.claude、CODEX_HOME=/home/paseo/.codex等 XDG 目录统一收敛到该主目录下。
基础镜像不预装任何 agent CLI：保持镜像小巧，也避免 Paseo 发版与第三方 agent 发版周期耦合。

容器启动后，直接打开其 HTTP 源，例如http://localhost:6767，即可加载 Web UI。UI 会收到同源连接提示并回连到该 daemon。

入口脚本的降权与目录准备

/usr/local/bin/paseo-docker-entrypoint（见 docker/base/rootfs/usr/local/bin/paseo-docker-entrypoint）承担了首次运行的准备工作：先用 root 权限ensure_dir确保$HOME、$PASEO_HOME、Claude/Codex 配置目录及各 XDG 目录存在；若目录属主是 root 则chown paseo:paseo移交所有权；随后若设置了PASEO_PASSWORD之外的任何命令参数，则以gosu paseo降权执行；否则以gosu paseo node <supervisor-entrypoint>启动 daemon。若未设置PASEO_PASSWORD，脚本会向 stderr 输出警告，提示 daemon 会接受任何可达客户端的未认证控制连接。

从源码看环境变量如何生效

packages/server/src/server/config-environment.ts列出了 daemon 从环境读取的全部PASEO_*键，其中与本部署场景直接相关的包括PASEO_LISTEN、PASEO_PASSWORD、PASEO_HOSTNAMES、PASEO_WEB_UI_ENABLED、PASEO_LOG_LEVEL、PASEO_LOG_FORMAT等。config-web-ui.test.ts验证了 Web UI 默认禁用、持久化配置可开启、PASEO_WEB_UI_ENABLED可覆盖持久化设置、CLI 参数优先级最高这一系列行为——镜像正是通过环境变量把 Web UI 置为开启。

宿主侧 CLI 如何连接容器

宿主侧 CLI 命令需要显式指定容器端点，例如paseo project ls --host 127.0.0.1:6767。不带端点选择器时，CLI 会寻找本机 home 的 supervisor。需要注意：容器内的环境变量属于部署层覆盖（deployment overrides），worker 重启后依然保留；而 supervisor 的完整替换则由你的容器管理器（如docker restart）负责。

快速启动

一条命令即可启动 daemon 与 Web UI：

docker run -d --name paseo \ -p 6767:6767 \ -e PASEO_PASSWORD=change-me \ -v "$PWD/paseo-home:/home/paseo" \ -v "$PWD:/workspace" \ ghcr.io/getpaseo/paseo:latest

然后打开：

http://localhost:6767

如果你设置了PASEO_PASSWORD，在 Web UI 或其它 Paseo 客户端中添加直连（direct daemon connection）时，需要输入同一个密码。示例中的change-me仅用于演示，任何可被网络访问的部署都应当换成强密码。

参数说明：

参数	说明
`-p 6767:6767`	将容器内`6767`端口映射到宿主，对应 daemon 的 HTTP 监听端口
`-e PASEO_PASSWORD=...`	设置 daemon 控制接口密码，保护 API 与 WebSocket
`-v "$PWD/paseo-home:/home/paseo"`	持久化 daemon 状态与 agent 凭据
`-v "$PWD:/workspace"`	挂载代码工作区，供 Paseo 与它启动的 agent 读写
`--name paseo`	容器命名，便于后续`docker exec`、`docker logs`引用

Docker Compose

仓库提供了现成的 Compose 模板 docker/docker-compose.example.yml，按以下步骤使用：

cp docker/docker-compose.example.yml docker-compose.yml $EDITOR docker-compose.yml docker compose up -d

最简示例：

services: paseo: image: ghcr.io/getpaseo/paseo:latest restart: unless-stopped ports: - "6767:6767" environment: PASEO_PASSWORD: "change-me" volumes: - ./paseo-home:/home/paseo - ./workspace:/workspace

模板中已将PASEO_HOSTNAMES以注释形式给出（paseo.example.com,.lan），用于补充你访问该容器所用的 DNS 名称——IP 与 localhost 默认已被允许。restart: unless-stopped保证容器在 daemon 崩溃或宿主重启后自动拉起。

安装 Agent CLI

基础镜像刻意不预装Claude Code、Codex、OpenCode、Copilot、Pi 等 agent CLI，以保证默认镜像体积小，且 Paseo 发版不与第三方 agent 发版节奏耦合。你需要为所用的 agents 创建子镜像：

FROM ghcr.io/getpaseo/paseo:latest USER root RUN npm install -g @openai/codex @anthropic-ai/claude-code opencode-ai

构建并切换使用：

docker build -f Dockerfile -t paseo-with-agents .

随后在 Compose 中使用image: paseo-with-agents替换官方镜像。

关键约束：子镜像用户必须保持 root。基础镜像入口只用 root 做首次运行的目录准备，随后会将 daemon 与它启动的 agents 一起降权到非 root 的paseo用户（uid/gid1000:1000）。仓库中的 docker/Dockerfile.agents.example 给出了完整可用的示例子镜像，构建命令为：

docker build -f docker/Dockerfile.agents.example -t paseo-with-agents .

在运行中的容器内登录 agent

也可以从宿主挂载凭据，或在容器内执行一次 agent 登录：

docker exec -it --user paseo paseo codex docker exec -it --user paseo paseo claude

--user paseo确保以镜像内同一非 root 用户身份登录，凭据落在/home/paseo下。agent 凭据与配置（如.codex、.claude）与 daemon 状态一同持久化在/home/paseo。

Provider 环境变量透传

诸如OPENAI_API_KEY、ANTHROPIC_API_KEY、OPENAI_BASE_URL、ANTHROPIC_BASE_URL等 provider 环境变量，可以通过docker run -e或compose.environment传入；Paseo 会把这些变量透传给启动的 agent 进程。CONFIG_CONTEXT_ENV_KEYS（见 config-environment.ts）即包含OPENAI_API_KEY、OPENAI_BASE_URL等键，作为 daemon 配置上下文环境的一部分保留。

数据卷

镜像约定以下两个挂载点：

挂载点	用途
`/home/paseo`	Paseo 状态（位于`.paseo`下）以及 agent 配置，如`.codex`、`.claude`
`/workspace`	Paseo 与所启动 agents 可读写的代码

镜像内建环境变量默认值（同样定义在 docker/base/Dockerfile 与入口脚本中）：

变量	默认值
`HOME`	`/home/paseo`
`PASEO_HOME`	`/home/paseo/.paseo`
`PASEO_LISTEN`	`0.0.0.0:6767`

其它与路径相关的镜像默认还包括CLAUDE_CONFIG_DIR=/home/paseo/.claude、CODEX_HOME=/home/paseo/.codex以及一组 XDG 目录（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME），全部收敛到/home/paseo之下，便于统一挂载与备份。

Linux 宿主的权限注意事项：如果直接 bind-mount 宿主目录，必须保证容器内用户可写。镜像内建paseo用户 uid/gid 为1000:1000。若宿主目录属主不是该 uid/gid，有两种处理方式：一是调整挂载目录的所有权，二是在docker run中使用--user或在 Compose 中使用user:以宿主 uid/gid 运行容器。

反向代理

当把 Paseo 放在反向代理后面时，需要将普通 HTTP 请求与 WebSocket 升级请求都转发到同一个 daemon 端口。

Caddy 示例：

paseo.example.com { reverse_proxy 127.0.0.1:6767 }

Nginx 示例（注意Upgrade/Connection头与X-Forwarded-Proto）：

server { listen 443 ssl; server_name paseo.example.com; location / { proxy_pass http://127.0.0.1:6767; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; } }

通过域名访问时的 Host 校验

daemon 默认只允许 IP 与localhost（含*.localhost）作为 Host 头。若通过 DNS 名称访问，需要设置PASEO_HOSTNAMES让 host-header 校验放行该名称：

environment: PASEO_HOSTNAMES: "paseo.example.com,.lan"

从源码看，config.ts将PASEO_HOSTNAMES（或兼容的PASEO_ALLOWED_HOSTS）解析后与持久化配置、CLI 参数合并为 hostnames 配置；hostnames.ts采用 Vite 风格的校验规则——localhost、*.localhost与所有 IP 地址默认放行，PASEO_HOSTNAMES中配置的名称在默认白名单之外追加。以.开头的条目（如.lan）代表该域及其子域。

安全

任何发布端口或可被网络访问的部署都必须设置PASEO_PASSWORD。入口脚本在未设置时会打印明确警告，说明 daemon 会接受任何可达客户端的未认证控制连接。
浏览器直连场景优先在反向代理处启用 HTTPS。
在不信任的网络或移动端访问、且不想直接暴露 daemon 端口时，可考虑官方 Paseo relay 方案（相关说明见 docker/README.md 与 SECURITY.md）。
容器是 agents 的隔离边界：agents 可以读写你挂载进/workspace的一切内容，以及你放入/home/paseo的全部凭据。不要向容器暴露超出预期的数据。
内置 Web UI 的静态文件在 daemon 源上是公开的；daemon API 与 WebSocket 在配置密码后仍受密码保护（/api/health等健康检查端点除外，镜像 HEALTHCHECK 使用http://127.0.0.1:6767/api/health探测）。
daemon 信任模型的完整说明参见 SECURITY.md。

本地构建

从源码树构建本地镜像：

docker build -f docker/base/Dockerfile -t paseo:local .

构建时校验源码树版本（断言与镜像版本一致）：

docker build \ --build-arg PASEO_VERSION=0.1.102 \ -t paseo:0.1.102 \ -f docker/base/Dockerfile \ .

PASEO_VERSION构建参数会在source-pack阶段用node -p "require('./package.json').version"与源码树 package.json 比对，不一致即构建失败。

发布工作流与手动发布

Docker 工作流在 Pull Request 与main分支上构建镜像，作为不发布的校验。
推送稳定vX.Y.Z标签时，发布ghcr.io/getpaseo/paseo:X.Y.Z与ghcr.io/getpaseo/paseo:latest。
Beta 标签只发布精确的预发布标签，例如ghcr.io/getpaseo/paseo:0.1.102-beta.1，不会更新latest。

如果只想原地替换 Docker 镜像、而无需重建桌面、APK 或 EAS 移动端发布产物，可以不推v*发布标签，改为手动触发 Docker 工作流：

gh workflow run docker.yml \ --ref main \ -f paseo_version=0.1.102-beta.1 \ -f publish=true

手动 Docker 发布必须显式指定paseo_version；工作流从检出的源码树构建，对于预发布版本只发布精确的预发布镜像标签。

发布镜像为多架构镜像，支持linux/amd64与linux/arm64（对 NAS 与 ARM homelab 用户友好）。

常见问题排查

Web UI 能加载但无法连接：若设置了PASEO_PASSWORD，需要在 Web UI 中添加直连并填入相同密码。
403 Host not allowed：将你实际使用的 DNS 名称加入PASEO_HOSTNAMES（IP 与localhost默认已放行）。
Provider not available：在子镜像中安装对应 agent CLI，或挂载一个二进制位于PATH中的运行时。
/workspace权限错误：让挂载目录对 uid/gid1000:1000可写，或以宿主 uid/gid 运行容器（--user/ Composeuser:）。
日志排查：查看docker logs paseo，或容器内/home/paseo/.paseo/daemon.log（镜像默认PASEO_LOG_FORMAT=json、PASEO_LOG_LEVEL=info，均可在启动时覆盖）。