Vibe Kanban 自托管部署如何启用 Relay/Tunnel 并处理通配符域名与 TLS

Vibe Kanban 自托管部署如何启用 Relay/Tunnel 并处理通配符域名与 TLS【免费下载链接】vibe-kanbanGet 10X more out of Claude Code, Codex or any coding agent项目地址: https://gitcode.com/GitHub_Trending/vi/vibe-kanban在 Linux 服务器上用 Docker Compose 自托管 Vibe Kanban Cloud 时默认部署只包含主应用和 API。如果你需要在其他设备比如手机上通过云端访问本机运行的 Vibe Kanban 实例即 Remote Access / 隧道模式就必须额外启用 Relay/Tunnel运行relay-server服务、为relay.your-domain.com和*.relay.your-domain.com配置反向代理路由并为*.relay.your-domain.com配置通配符 TLS 证书。本文基于仓库内的自托管部署文档给出从基础部署到启用 Relay 的完整操作路径。部署前的准备条件按 自托管部署文档 的要求服务器需要满足Docker和Docker Compose v2.0最低2GB 内存建议 4GB10GB 磁盘空间一个指向服务器的域名一种认证方式GitHub 或 Google 的 OAuth 凭据或者用于单个自托管管理员的 bootstrap 本地认证凭据SSH 登录后安装 DockerUbuntu/Debian然后拉取仓库# Install Docker (Ubuntu/Debian) curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER # Log out and back in for group changes to take effect git clone https://github.com/BloopAI/vibe-kanban.git cd vibe-kanban注意如果要启用 Relay/TunnelVITE_RELAY_API_BASE_URL必须在构建remote-server之前就设置好它是构建参数而不是运行时参数这一点在本文第 3 步和第 4 步都会用到。第一步基础部署主应用 API在仓库根目录创建.env.remote# Required secrets VIBEKANBAN_REMOTE_JWT_SECRETyour_generated_jwt_secret ELECTRIC_ROLE_PASSWORDsecure_password_for_electric DB_PASSWORDsecure_database_password # Your domain DOMAINyour-domain.com # Relay API base URL (required if you enable relay/tunnel) VITE_RELAY_API_BASE_URLhttps://relay.your-domain.com # Authentication — configure at least one provider, or set bootstrap local auth credentials. GITHUB_OAUTH_CLIENT_IDyour_github_client_id GITHUB_OAUTH_CLIENT_SECRETyour_github_client_secret GOOGLE_OAUTH_CLIENT_ID GOOGLE_OAUTH_CLIENT_SECRET SELF_HOST_LOCAL_AUTH_EMAIL SELF_HOST_LOCAL_AUTH_PASSWORD其中VIBEKANBAN_REMOTE_JWT_SECRET用openssl rand -base64 48生成DOMAIN和VITE_RELAY_API_BASE_URL替换成你自己的域名。OAuth 回跳地址需要与域名一致GitHub 的 Authorization callback URL 为https://your-domain.com/v1/oauth/github/callbackGoogle 的 Authorized redirect URI 为https://your-domain.com/v1/oauth/google/callback。也可以在 OAuth 尚未配置好时先用SELF_HOST_LOCAL_AUTH_EMAIL/SELF_HOST_LOCAL_AUTH_PASSWORD引导单个本地管理员登录它只是一组共享凭据不是完整的多用户身份系统。在crates/remote目录创建生产用docker-compose.prod.yml文档给出的基础版本包含四个服务caddy80/443 端口负责自动 HTTPS、remote-dbPostgreSQL 16、electricElectricSQL实时同步、remote-server主应用监听 8081健康检查端点为http://127.0.0.1:8081/v1/health。完整内容见 部署文档关键结构如下services: caddy: image: caddy:2-alpine restart: unless-stopped ports: - 80:80 - 443:443 environment: DOMAIN: ${DOMAIN} volumes: - ./Caddyfile:/etc/caddy/Caddyfile - caddy_data:/data - caddy_config:/config depends_on: - remote-server remote-db: image: postgres:16-alpine command: [postgres, -c, wal_levellogical] restart: unless-stopped environment: POSTGRES_DB: remote POSTGRES_USER: remote POSTGRES_PASSWORD: ${DB_PASSWORD:-remote} volumes: - remote-db-data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U remote -d remote] interval: 5s timeout: 5s retries: 5 start_period: 5s remote-server: build: context: ../.. dockerfile: crates/remote/Dockerfile args: VITE_RELAY_API_BASE_URL: ${VITE_RELAY_API_BASE_URL:-} restart: unless-stopped depends_on: remote-db: condition: service_healthy environment: RUST_LOG: info,remoteinfo SERVER_DATABASE_URL: postgres://remote:${DB_PASSWORD:-remote}remote-db:5432/remote SERVER_LISTEN_ADDR: 0.0.0.0:8081 ELECTRIC_URL: http://electric:3000 SERVER_PUBLIC_BASE_URL: https://${DOMAIN} GITHUB_OAUTH_CLIENT_ID: ${GITHUB_OAUTH_CLIENT_ID:-} GITHUB_OAUTH_CLIENT_SECRET: ${GITHUB_OAUTH_CLIENT_SECRET:-} GOOGLE_OAUTH_CLIENT_ID: ${GOOGLE_OAUTH_CLIENT_ID:-} GOOGLE_OAUTH_CLIENT_SECRET: ${GOOGLE_OAUTH_CLIENT_SECRET:-} VIBEKANBAN_REMOTE_JWT_SECRET: ${VIBEKANBAN_REMOTE_JWT_SECRET} ELECTRIC_ROLE_PASSWORD: ${ELECTRIC_ROLE_PASSWORD} SELF_HOST_LOCAL_AUTH_EMAIL: ${SELF_HOST_LOCAL_AUTH_EMAIL:-} SELF_HOST_LOCAL_AUTH_PASSWORD: ${SELF_HOST_LOCAL_AUTH_PASSWORD:-} healthcheck: test: [CMD, wget, --spider, -q, http://127.0.0.1:8081/v1/health] interval: 5s timeout: 5s retries: 10 start_period: 10selectric服务的完整配置——包括DATABASE_URL、AUTH_MODE、ELECTRIC_MANUAL_TABLE_PUBLISHING等环境变量——请照抄部署文档本文不重复。在crates/remote目录创建基础Caddyfile为主域名做自动 HTTPS{$DOMAIN} { reverse_proxy remote-server:8081 }然后部署cd crates/remote # Build and start all services docker compose --env-file ../../.env.remote -f docker-compose.prod.yml up -d --build # View logs docker compose -f docker-compose.prod.yml logs -f首次构建需要 10-15 分钟后续构建有 Docker 缓存会更快。第二步验证基础部署浏览器打开https://your-domain.com应看到 Vibe Kanban Cloud 登录页用你配置的认证方式登录创建第一个组织和项目基础部署到这里为止只服务主 Cloud 应用/APIRelay/Tunnel 是可选能力需要下面这组附加配置。第三步启用 Relay/Tunnel 的四个条件部署文档明确列出了启用 Relay/Tunnel 的全部要求一个运行中的relay-server服务反向代理同时路由relay.your-domain.com和*.relay.your-domain.com*.relay.your-domain.com的通配符证书或边缘层等价的托管 TLS构建remote-server之前就把VITE_RELAY_API_BASE_URL设为你的公网 relay API 地址前两步的.env.remote里已经包含了第 4 项。如果之前没有设置现在补上后必须重新执行docker compose --env-file ../../.env.remote -f docker-compose.prod.yml up -d --build因为VITE_RELAY_API_BASE_URL是构建参数只改环境变量不重新构建不会生效。第四步在 Compose 中增加 relay-server在docker-compose.prod.yml的services下追加文档原文配置relay-server: build: context: ../.. dockerfile: crates/relay-tunnel/Dockerfile restart: unless-stopped depends_on: remote-db: condition: service_healthy environment: RUST_LOG: info SERVER_DATABASE_URL: postgres://remote:${DB_PASSWORD:-remote}remote-db:5432/remote RELAY_LISTEN_ADDR: 0.0.0.0:8082 VIBEKANBAN_REMOTE_JWT_SECRET: ${VIBEKANBAN_REMOTE_JWT_SECRET}注意relay-server的 Dockerfile 是crates/relay-tunnel/Dockerfile监听端口为 8082并复用同一个VIBEKANBAN_REMOTE_JWT_SECRET。第五步配置 Relay 反向代理路由反向代理必须把两个 host 都路由到relay-server:8082relay.your-domain.com-relay-server:8082*.relay.your-domain.com-relay-server:8082仓库里有一个可直接参考的本地示例 Caddyfile.example它展示了 host 级路由的写法relaymatcher 匹配relay.localhost与*.relay.localhost后转发到 relay 端口以及未匹配的 host 走主应用、其余返回 404 的结构生产环境可按同样的 matcher 思路扩展到真实域名。第六步处理通配符域名与 TLS这是 Relay 部署里最容易卡住的一步。标准 ACME HTTP challenge无法签发通配符证书因此*.relay.your-domain.com的 TLS 不能用默认 HTTP-01 方式自动申请。文档给出的两条路径使用基于 DNS 的 ACME challengeDNS-01或使用可以在边缘层终止通配符 TLS 证书的其他边缘服务商。主域名your-domain.com本身不受此限制Caddy 会从 Lets Encrypt 自动获取普通证书只有 relay 子域名的通配符证书需要上面的方式之一。如果你的边缘服务商直接签发了*.relay.your-domain.com的通配符证书则 Caddy 侧只需按第五步做路由TLS 由边缘层终止。验证 Relay 是否配置正确部署文档的验证方式与本地开发文档中的 Relay 健康检查一致——用 curl 直接请求 relay 域名的 health 端点文档示例# 期望返回 relay 健康 JSON例如文档示例 curl -sk https://relay.your-domain.com/health # {status:ok} # 主应用健康端点应返回 remote server 的健康 JSON curl -sk https://your-domain.com/v1/health判断依据是返回内容而不是状态码本身如果relay.your-domain.com/health返回的是 HTML 而不是 JSON说明反向代理把 relay 域名错误地路由到了主应用本地开发文档中记录的同类问题是 Caddy 把 relay host 路由到了 remote app 的 3000 端口而不是 relay 的 8082 端口这时应回到第五步检查 host 级路由是否覆盖了两条规则精确的relay.域名和*.relay.通配符域名。最后可用docker compose -f docker-compose.prod.yml ps确认所有服务状态docker compose -f docker-compose.prod.yml logs -f relay-server查看 relay 日志。常见部署问题与限制SSL 证书问题Caddy 自动从 Lets Encrypt 获取证书时确认域名 DNS 正确指向服务器、防火墙开放 80/443 端口、环境中的DOMAIN设置正确。数据库连接被拒服务可能先于数据库就绪启动先docker compose -f docker-compose.prod.yml logs remote-db查看再docker compose -f docker-compose.prod.yml restart remote-server。构建内存不足可用fallocatemkswap加 swap或换更大内存的服务器命令见 部署文档。限制方面需要注意relay 服务没有对外映射端口只能通过反向代理访问通配符 TLS 是 Relay 的前置条件而不是可选项没有可用的 DNS-01 或边缘通配符证书时*.relay.路由无法正常工作。后续更新升级到新版本时cd vibe-kanban git pull origin main cd crates/remote docker compose --env-file ../../.env.remote -f docker-compose.prod.yml up -d --build数据库备份可用pg_dump导出docker compose -f docker-compose.prod.yml exec remote-db pg_dump -U remote remote backup_$(date %Y%m%d).sql恢复时通过psql导入备份文件。【免费下载链接】vibe-kanbanGet 10X more out of Claude Code, Codex or any coding agent项目地址: https://gitcode.com/GitHub_Trending/vi/vibe-kanban创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考