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 内存（建议 4GB），10GB 磁盘空间
一个指向服务器的域名
一种认证方式：GitHub 或 Google 的 OAuth 凭据，或者用于单个自托管管理员的 bootstrap 本地认证凭据

SSH 登录后安装 Docker（Ubuntu/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/Tunnel，VITE_RELAY_API_BASE_URL必须在构建remote-server之前就设置好，它是构建参数而不是运行时参数，这一点在本文第 3 步和第 4 步都会用到。

第一步：基础部署（主应用 + API）

在仓库根目录创建.env.remote：

# Required secrets VIBEKANBAN_REMOTE_JWT_SECRET=<your_generated_jwt_secret> ELECTRIC_ROLE_PASSWORD=<secure_password_for_electric> DB_PASSWORD=<secure_database_password> # Your domain DOMAIN=your-domain.com # Relay API base URL (required if you enable relay/tunnel) VITE_RELAY_API_BASE_URL=https://relay.your-domain.com # Authentication — configure at least one provider, or set bootstrap local auth credentials. GITHUB_OAUTH_CLIENT_ID=your_github_client_id GITHUB_OAUTH_CLIENT_SECRET=your_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/callback，Google 的 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，文档给出的基础版本包含四个服务：caddy（80/443 端口，负责自动 HTTPS）、remote-db（PostgreSQL 16）、electric（ElectricSQL，实时同步）、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_level=logical"] 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,remote=info 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: 10s

（electric服务的完整配置——包括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 应用/API；Relay/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:8082：

relay.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 challenge（DNS-01）；
或使用可以在边缘层终止通配符 TLS 证书的其他边缘服务商。

主域名your-domain.com本身不受此限制，Caddy 会从 Let's 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 自动从 Let's 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。
构建内存不足：可用fallocate+mkswap加 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），仅供参考