news 2026/9/21 23:10:36

自托管 Paseo Hub：从 npx 一键启动到 PostgreSQL、Docker Compose 与 Fly 的生产化部署指南

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
自托管 Paseo Hub：从 npx 一键启动到 PostgreSQL、Docker Compose 与 Fly 的生产化部署指南

自托管 Paseo Hub：从 npx 一键启动到 PostgreSQL、Docker Compose 与 Fly 的生产化部署指南

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

Hub 是 Paseo 的连接中枢：它接收 GitHub、Slack、Discord 与手动请求，匹配触发器并派发 workflow，最终在已注册的 daemon 机器上启动 coding agent。本篇指南围绕public-docs/hub/self-hosting/index.md展开，完整覆盖自托管 Hub 的两种数据形态（嵌入式数据库与 PostgreSQL）、公网暴露要求、GitHub/Slack/Discord 应用配置、无人值守引导、Docker Compose + Caddy HTTPS 以及 Fly 部署，并结合当前仓库中 CLI 的 hub 命令实现（authority.ts、connect.ts、init.ts）给出源码级佐证。读完你可以独立把 Hub 从个人电脑上的临时实例升级为可长期运行的服务器部署。

Hub 自托管的两条路线

Paseo 提供托管版 Hub（hosted.md 提到入口为hub.paseo.sh，网页端在 hub.tsx 中同样指向该地址），而自托管则是把同一套服务跑在你自己控制的机器上。两种形态下，项目、配置、触发器、daemon 与活动记录采用完全相同的模型；区别在于：托管服务自带其 GitHub App、Slack app 与 Discord application，而自托管 Hub 使用的是你创建并完全掌控的应用凭据。

从部署形态看，自托管又分两级：

  • 嵌入式模式：无需任何外部数据库，一条npx命令即可启动，适合个人使用或单进程 Hub；
  • PostgreSQL 模式：适合需要持久化、多进程并发或已有数据库备份与运维体系的服务器部署。

最快路径：一条命令启动本地 Hub

最短的启动路径是直接运行：

npx @getpaseo/hub

然后打开 http://localhost:3000。首次启动的 Hub 会自动创建嵌入式数据库与认证密钥，并引导你完成两件事：创建 operator 账号，以及创建你想要接入的 GitHub、Slack 或 Discord 应用。

值得强调的是首次运行几乎零依赖：不需要数据库、Docker、环境变量或 API key（见 quickstart）。如果你想在本地不暴露公网的情况下先体验完整链路，可以按 quickstart 的指引连接 Slack Socket Mode 并运行第一个 workflow——Socket Mode 由 Hub 主动外连，不需要公共服务器。

前置条件：Paseo 已安装并运行（daemon 侧）、Node.js 可用、以及一个你能创建 Slack 应用的 workspace。

本地数据与嵌入式数据库

不设置DATABASE_URL时，Hub 使用嵌入式 PGlite 数据库，并把数据库与其生成的认证密钥存放在同一数据目录：

  • 默认目录为$XDG_DATA_HOME/paseo-hub；
  • 若XDG_DATA_HOME未设置为绝对路径，则回退到~/.local/share/paseo-hub（quickstart 中也是这样描述的）。

两者都跨重启保留。要显式指定其他位置，用PASEO_HUB_DATA_DIR覆盖：

PASEO_HUB_DATA_DIR=/path/to/paseo-hub-data npx @getpaseo/hub

嵌入式模式的约束需要牢记：

  • 一个数据目录只支持一个 Hub 进程，它面向个人或单进程场景；
  • 升级或迁移前务必整体备份该数据目录。目录里不仅有配置，还包含账号、应用凭据、配置修订历史、连接与执行历史（详见下文「升级」）。

公开地址与公网要求

Hub 默认监听http://localhost:3000。对以下场景这已经足够：

  • 打开 Hub 仪表盘；
  • daemon 通过paseo hub login反向接入；
  • Slack Socket Mode（出站连接）；
  • 由 Hub 主动外连的各类 provider。

需要公共 HTTPS 地址的场景则包括：

  • GitHub 事件触发器依赖 webhook 投递；不过仓库访问（repository access）不依赖 webhook，仍然可以工作；
  • Slack 的 Webhooks 传输方式需要公网 HTTPS；Socket Mode 不需要。

当 Hub 有了稳定的公网 origin 后，在启动前设置：

PASEO_HUB_APP_URL=https://hub.example.com npx @getpaseo/hub

注意：变更公网 origin 必须同步更新 provider 应用里的 callback 与 webhook 设置。Hub 的Apps页面会基于当前生效的 origin 自动生成所需的 URL，以此为准复制即可。

以 GitHub 为例，Hub 会使用这些 URL（详见 github-app.md）：

SettingHub URL
Homepage URL<PASEO_HUB_APP_URL>
Callback URL<PASEO_HUB_APP_URL>/api/integrations/github/callback
Setup URL<PASEO_HUB_APP_URL>/api/integrations/github/setup
Webhook URL<PASEO_HUB_APP_URL>/webhook

GitHub 侧需保持 SSL verification 开启。在本地 HTTP Hub 上，Apps 引导页可以配置仓库访问，但事件设置不可用；设置PASEO_HUB_APP_URL并以公网地址重新打开 Hub 后，才能补充 webhook 密钥与事件订阅。

Slack Webhooks 传输方式则要求（详见 slack-app.md）：

Provider settingHub URL
Redirect URL<PASEO_HUB_APP_URL>/api/integrations/slack/callback
Request URL<PASEO_HUB_APP_URL>/api/integrations/slack/events

切换 PostgreSQL

设置DATABASE_URL即可用 PostgreSQL 替代嵌入式数据库：

DATABASE_URL=postgres://paseo:password@localhost:5432/paseo_hub \ npx @getpaseo/hub

PostgreSQL 模式适合以下场景：

  • 需要持久化的服务器部署；
  • 需要运行多个 Hub 进程（嵌入式模式每数据目录只允许一个进程）；
  • 需要接入已有的数据库备份与运维体系。

迁移在启动时自动执行；迁移失败时 Hub 不会开始监听，避免带着不完整 schema 对外服务。

认证密钥同样存放在数据库中。只有当部署必须从平台密钥库注入该密钥时，才需要设置PASEO_HUB_AUTH_SECRET：

  • 设置该覆盖值期间，Hub 直接使用它，而不会替换数据库里已存的密钥；
  • 变更生效中的密钥会让所有仪表盘会话登出；
  • 已签发的执行凭据（execution credentials）不受影响，会一直有效到对应执行结束。

应用配置：GitHub、Slack 与 Discord

运营者可以在Apps页面配置 GitHub、Slack 与 Discord。Hub 会先验证凭据再存入数据库，并启动与「环境变量配置部署」完全相同的 provider runtime——也就是说，页面保存的应用和环境变量配置走的是同一套运行逻辑。

环境变量依旧可用，适合把密钥管理放在 Hub 之外的部署。一条规则贯穿始终：完整的环境配置优先于已保存的应用，此时仪表盘中会显示Managed by environment。

完整的传输与环境变量配置如下（来自原文档，逐一保留）：

# GitHub GITHUB_APP_SLUG= GITHUB_APP_ID= GITHUB_APP_CLIENT_ID= GITHUB_APP_CLIENT_SECRET= GITHUB_APP_PRIVATE_KEY= # or GITHUB_APP_PRIVATE_KEY_PATH GITHUB_WEBHOOK_SECRET= # Slack Socket Mode SLACK_TRANSPORT=socket SLACK_APP_ID= SLACK_APP_TOKEN= # Slack Webhooks instead of Socket Mode SLACK_TRANSPORT=webhook SLACK_APP_ID= SLACK_CLIENT_ID= SLACK_CLIENT_SECRET= SLACK_SIGNING_SECRET= # Discord DISCORD_CLIENT_ID= DISCORD_CLIENT_SECRET= DISCORD_BOT_TOKEN=

细节补充与子页面联动：

  • GitHub：GITHUB_APP_PRIVATE_KEY填 GitHub 下载的 PEM 文件内容；部署以挂载文件方式提供时改用GITHUB_APP_PRIVATE_KEY_PATH。完整的环境配置包含 webhook 密钥，因此期待一个公网 webhook origin。仓库访问与安装本身不需要 webhook，但 GitHub 事件触发器和配置同步需要（见 github-app.md）。
  • Slack：Socket Mode 与 Webhooks 两种传输产生相同的slack.mention触发器与线程回复。注意 Bot User OAuth Token 始终挂在每个已保存的 Slack workspace 连接上，不属于Socket Mode 的环境配置项；Socket Mode 环境只需要SLACK_APP_ID与SLACK_APP_TOKEN（见 slack-app.md）。
  • Discord：DISCORD_CLIENT_ID即General Information中显示的 Application ID。配置 Discord 应用时务必在Bot → Privileged Gateway Intents开启Message Content Intent，否则 bot 收到的是空消息，任何触发器都无法匹配；Server Members Intent 不需要。一个 Discord 应用与 gateway 连接可服务连接到此 Hub 的所有组织与服务器（见 discord-app.md）。

从环境引导（无人值守部署）

对全新数据库，默认走浏览器引导。无人值守部署则可以通过环境变量直接创建第一个 operator：

PASEO_BOOTSTRAP_ORGANIZATION=My organization PASEO_BOOTSTRAP_OWNER_EMAIL=me@example.com PASEO_BOOTSTRAP_OWNER_PASSWORD=replace-with-a-temporary-password

约束与后续动作：

  • 密码至少 12 个字符；
  • 首次登录后请在仪表盘里更换该密码，然后移除PASEO_BOOTSTRAP_OWNER_PASSWORD；
  • Hub 会保留账号与组织本身，不会因移除变量而删除。

Fly 部署等场景可直接在部署前设置这组变量，跳过浏览器引导。

Docker Compose 部署

Hub 仓库以一套 Compose 栈同时提供 Hub 与 PostgreSQL（注意：这是 Hub 自身仓库的部署栈；本仓库的 docker 目录 提供的是 Paseo daemon 镜像与 docker-compose.example.yml，两者分别部署，daemon 侧示例监听6767端口并持久化paseo-home与workspace卷）。

部署步骤：

git clone <hub-repository> cd hub cp .env.example .env docker compose up -d

打开 http://localhost:3000 完成浏览器引导。若要公网部署，请在启动栈之前于.env中设置PASEO_HUB_APP_URL以及任何反向代理相关设置。

该栈的要点：

  • Hub 发布在宿主机3000端口；
  • PostgreSQL 数据存放在命名卷（named volume）中；
  • Hub 镜像为ghcr.io/getpaseo/hub:latest。

用 Caddy 终结 HTTPS

Compose 默认以明文 HTTP 在 3000 端口提供服务。可以在同一主机上运行 Caddy 来终结 TLS，配置如下：

hub.example.com { reverse_proxy 127.0.0.1:3000 }

将hub.example.com解析到该主机，并开放 80 与 443 端口，Caddy 会自动获取并续期证书（这是 Caddy 的自动 HTTPS 行为）。

随后在.env中设置：

PASEO_HUB_APP_URL=https://hub.example.com PASEO_HUB_TRUSTED_CLIENT_IP_HEADER=x-forwarded-for

其中PASEO_HUB_TRUSTED_CLIENT_IP_HEADER让 Hub 信任反向代理写入的X-Forwarded-For头，从而正确识别客户端 IP。

若希望 3000 端口完全不暴露在公网接口上，把compose.yml中 hub 服务的端口映射改为仅绑定回环地址：

"127.0.0.1:3000:3000"

Fly 部署

克隆 Hub 仓库后，创建你自己命名空间下的应用与数据库：

git clone <hub-repository> cd hub fly apps create your-hub fly postgres create --name your-hub-db fly postgres attach your-hub-db -a your-hub

部署 Dockerfile 并赋予 Hub 公网 origin：

fly deploy -a your-hub \ -e PASEO_HUB_APP_URL=https://your-hub.fly.dev

打开该地址完成浏览器引导；也可以在部署前设置上文「从环境引导」中的 bootstrap 变量，实现全自动初始化。

Fly 部署有一个必须遵守的运维要求：保持一台机器持续运行。Hub 进程内持有 Slack Socket Mode 与 Discord gateway 的长连接，并把事件派发给 daemon；机器停机期间到达的事件会被错过（Hub 不做事件排队，详见后文）。

升级

升级流程为：拉取新镜像（或新源码）并重新部署。需要留意两点：

  • 迁移是仅前向（forward-only）的，不支持回滚 schema；
  • 升级前先备份嵌入式数据目录或 PostgreSQL 数据库——其中包含账号、应用凭据、配置修订、连接与执行历史。

结合 activity.md 的说明可以再补一层认知：Hub 不会排队事件，daemon 离线时派发失败会以daemon_not_connected记录在项目 Activity 中，不会稍后自动重试；升级或维护窗口要安排在事件低谷期。

部署后的 daemon 接入与验证

自托管 Hub 的价值在于把事件派发到你自己的机器上跑 agent。接入 daemon 的命令：

paseo hub login https://hub.example.com

在交互终端中，登录完成后会询问是否连接 daemon、是否允许 Hub 自动化在该 daemon 上运行 agent（执行权限默认拒绝）。paseo hub connect则用于单独注册 daemon：它使用当前登录换取一次性 enrollment token，daemon 再凭该 token 换取自己的关系凭据——你的 CLI 登录不会被保存为 daemon 权限（见 daemons.md）。

关于 origin 与凭据的解析优先级，源码给出了确切实现（authority.ts）：

  • origin：显式--hub→PASEO_HUB_URL→ 已存储的活动登录 → 默认https://hub.paseo.sh；
  • 凭据：显式--api-key→PASEO_HUB_API_KEY→ 与精确 origin 匹配的存储登录。

runHubConnect（connect.ts）先经resolveHubOrigin/resolveHubCredential解析目标，再调用issueEnrollmentToken换取一次性 token，最后由 daemon 侧connectHub建立关系。这一调用链印证了「enrollment token 是一次性、CLI 登录不落地为 daemon 权限」的设计。

部署完成后，推荐按以下路径验证闭环是否真正打通：

  1. 事件是否到达 Hub：项目Activity列出已路由的触发器运行；Connections → Known unrouted events记录被接受但未匹配任何触发器的 provider 事件，原因分为no_project_route、no_trigger_for_source、trigger_filters_rejected、configuration_unavailable四类（见 activity.md）。
  2. 触发器是否匹配：外部来源事件强制要求非空from_users白名单；GitHub 用登录名，Slack/Discord 用用户 ID 而非显示名。
  3. daemon 是否在线：离线 daemon 会以daemon_not_connected失败，事件不会被排队。

安全边界速览

自托管意味着你同时承担了安全配置职责。几条与部署强相关的要点（完整版见 security.md）：

  • 连接 daemon 不等于授权执行：hub.execute权限需要显式授予，它允许 Hub 在该 daemon 上创建与续跑 agent、查看状态与 timeline、配置模型与 provider 权限模式；授予时注意 provider 模式可能绕过审批提示；
  • 从from_users白名单起步：把 GitHub 钉在repo、Slack 钉在workspace与channels、Discord 钉在guild与channels；保护承载.paseo配置包的仓库，因为它能选择连接、daemon、工作目录、完整命名 agent 与输出能力；
  • 密钥轮换的全局影响：如前面「PostgreSQL」一节所述，变更PASEO_HUB_AUTH_SECRET会让所有仪表盘会话登出，但已签发的执行凭据运行到结束为止。

小结

自托管 Paseo Hub 的决策路径可以概括为：先用npx @getpaseo/hub在本机跑通嵌入式模式，用paseo hub login接入 daemon 并部署首个触发器；当需要持久化、多进程或公网事件入口时，切换 PostgreSQL 并设置PASEO_HUB_APP_URL；需要长期对外服务时，选择 Docker Compose + Caddy（注意PASEO_HUB_TRUSTED_CLIENT_IP_HEADER）或 Fly 部署，并始终在升级前完成数据备份。Hub 的事件派发不做排队，保持 Hub 进程持续运行是自托管形态的基本运维前提。

进一步阅读：quickstart、How Hub works、Daemons in Hub、Hub security。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/21 22:53:43

QQ空间备份 3 步搞定：用 GetQzonehistory 完整导出历史说说

QQ空间备份 3 步搞定&#xff1a;用 GetQzonehistory 完整导出历史说说 【免费下载链接】GetQzonehistory 获取QQ空间发布的历史说说 项目地址: https://gitcode.com/GitHub_Trending/ge/GetQzonehistory GetQzonehistory 是一个开源工具&#xff0c;用来备份QQ空间说说…

作者头像 李华
网站建设 2026/9/21 22:32:19

把QQ空间十年说说完整搬回本地：免费GetQzonehistory一键备份指南

把QQ空间十年说说完整搬回本地&#xff1a;免费GetQzonehistory一键备份指南 【免费下载链接】GetQzonehistory 获取QQ空间发布的历史说说 项目地址: https://gitcode.com/GitHub_Trending/ge/GetQzonehistory 翻到去年那条动态&#xff0c;配图全灰&#xff0c;只剩一行…

作者头像 李华
网站建设 2026/9/21 22:31:35

django基于数据挖掘的股票预测系统的设计与实现机器学习实战机器学习入门

1.1研究背景与意义随着互联网技术的迅猛发展&#xff0c;金融行业也迎来了前所未有的变革。股票市场作为金融市场的重要组成部分&#xff0c;其波动性和不确定性给投资者带来了巨大的挑战。传统的股票交易方式受限于地域、时间以及信息不对称等问题&#xff0c;导致投资者难以做…

作者头像 李华
网站建设 2026/9/21 22:29:42

Spring配置管理实战：从XML到注解与安全优化

1. Spring配置文件基础认知在Java企业级开发领域&#xff0c;Spring框架的配置文件如同乐高积木的拼装说明书。我见过不少团队在微服务改造过程中&#xff0c;因为对配置管理理解不透彻&#xff0c;导致服务间调用出现各种诡异问题。配置文件本质上是一种"约定大于配置&qu…

作者头像 李华
网站建设 2026/9/21 22:29:40

OpenClaw分布式计算框架架构升级深度解析

1. 项目概述OpenClaw作为开源社区中备受关注的分布式计算框架&#xff0c;在沉寂9天后终于迎来了里程碑式的架构升级。这次更新绝非简单的功能迭代&#xff0c;而是从底层设计理念到核心组件实现的全方位重构。作为一名长期跟踪分布式系统演进的开发者&#xff0c;我在第一时间…

作者头像 李华