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_ENABLEDtrue静态 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 overridesworker 重启后依然保留而 supervisor 的完整替换则由你的容器管理器如docker restart负责。快速启动一条命令即可启动 daemon 与 Web UIdocker run -d --name paseo \ -p 6767:6767 \ -e PASEO_PASSWORDchange-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/paseoPaseo 状态位于.paseo下以及 agent 配置如.codex、.claude/workspacePaseo 与所启动 agents 可读写的代码镜像内建环境变量默认值同样定义在 docker/base/Dockerfile 与入口脚本中变量默认值HOME/home/paseoPASEO_HOME/home/paseo/.paseoPASEO_LISTEN0.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-Protoserver { 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_VERSION0.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_version0.1.102-beta.1 \ -f publishtrue手动 Docker 发布必须显式指定paseo_version工作流从检出的源码树构建对于预发布版本只发布精确的预发布镜像标签。发布镜像为多架构镜像支持linux/amd64与linux/arm64对 NAS 与 ARM homelab 用户友好。常见问题排查Web UI 能加载但无法连接若设置了PASEO_PASSWORD需要在 Web UI 中添加直连并填入相同密码。403 Host not allowed将你实际使用的 DNS 名称加入PASEO_HOSTNAMESIP 与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_FORMATjson、PASEO_LOG_LEVELinfo均可在启动时覆盖。参考资源镜像构建定义docker/base/Dockerfile容器入口脚本docker/base/rootfs/usr/local/bin/paseo-docker-entrypointCompose 模板docker/docker-compose.example.ymlAgent 子镜像示例docker/Dockerfile.agents.example镜像目录说明docker/README.mddaemon 环境变量解析packages/server/src/server/config-environment.tsWeb UI 配置行为测试packages/server/src/server/config-web-ui.test.tsHost 校验实现packages/server/src/server/hostnames.tsdaemon 信任模型SECURITY.md【免费下载链接】paseoOrchestrate multiple coding agents from desktop and mobile项目地址: https://gitcode.com/gh_mirrors/pa/paseo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考