使用 Dokploy 部署

使用 Dockerfile 将 Vibecape Server 部署到 Dokploy，并配置 HTTPS、持久化和健康检查。

本教程只介绍一种生产部署方式：使用 Dockerfile 构建 Vibecape Server，由 Dokploy 管理容器生命周期、域名、HTTPS、日志和重启。

如果你希望由一个 Compose 文件同时声明构建、配置和持久化，请阅读使用 Dokploy Compose 部署。

Vibecape Server 使用 SQLite 数据库和本地 bare Git repositories。每个数据目录只能由一个 Server 实例使用，因此 Replica 必须保持为 1，并且必须持久化整个 /data 目录。

准备

部署前需要：

一个 Dokploy 实例；
一个可以指向 Dokploy 的域名，例如 spaces.example.com；
一个可用的 Downcity Federation URL、Bureau Token 和 City ID；
一个用于保存 Dockerfile 的 Git repository。

1. 创建 Dockerfile

在部署 repository 根目录创建 Dockerfile：

FROM node:22-bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends git curl ca-certificates \
    && npm install -g @vibecape/cli@latest \
    && rm -rf /var/lib/apt/lists/*

RUN mkdir -p /data && chown node:node /data

ENV VIBECAPE_REMOTE_HOST=0.0.0.0
ENV VIBECAPE_REMOTE_PORT=4178
ENV VIBECAPE_REMOTE_DATA=/data

USER node
VOLUME ["/data"]
EXPOSE 4178

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -fsS http://127.0.0.1:4178/v1/info || exit 1

CMD ["vibecape", "server", "start", "--foreground"]

容器中必须使用 server start --foreground。Vibecape 保持为前台主进程，由 Dokploy 负责停止、重启和收集日志。

生产部署应固定 CLI 版本。升级时修改 Dockerfile 中的版本号并重新构建，不要在容器每次启动时安装依赖。

2. 创建 Application

在 Dokploy 中创建 Application：

连接包含 Dockerfile 的 Git repository；
Build Type 选择 Dockerfile；
Container Port 设置为 4178；
Replica 保持为 1；
添加持久化 Volume，容器路径设置为 /data；
添加域名 spaces.example.com 并启用 HTTPS；
Health Check Path 设置为 /v1/info。

不要把 /data 配置为临时存储。容器重建后仍然需要使用同一个 Volume。

3. 配置环境变量

在 Application 的 Environment 中填写：

DOWNCITY_FEDERATION_URL=https://base.downcity.ai
DOWNCITY_BUREAU_TOKEN=replace-with-your-bureau-token
DOWNCITY_CITY_ID=vibecape

VIBECAPE_REMOTE_HOST=0.0.0.0
VIBECAPE_REMOTE_PORT=4178
VIBECAPE_REMOTE_URL=https://spaces.example.com
VIBECAPE_REMOTE_DATA=/data

其中：

VIBECAPE_REMOTE_HOST 必须是 0.0.0.0，否则 Dokploy 无法连接容器端口；
VIBECAPE_REMOTE_URL 必须是用户实际访问的 HTTPS 地址，不能使用 localhost、容器名或内部端口；
DOWNCITY_BUREAU_TOKEN 应作为敏感配置保存在 Dokploy 中，不要提交到 Git。

4. 部署并验证

触发部署，等待构建完成并通过健康检查。然后从外部验证：

curl https://spaces.example.com/v1/info

成功时会返回 Vibecape Server 信息。如果健康检查失败，先查看 Application Logs，并确认端口、环境变量和 Federation 网络连接。

5. 管理 Group

在 Dokploy 的 Application Terminal 中执行管理命令：

vibecape server group list
vibecape server group create \
  --name "Research Team" \
  --owner "federation-user-id"
vibecape server group request list <group-id>
vibecape server group request approve <group-id> <user-id> --role editor

容器中建议显式提供 --owner，避免依赖容器文件系统中的 CLI 登录账户。

数据、备份与升级

/data 同时包含：

server.db：Group、成员、Space 和权限；
repositories/：所有 Remote Space 的 Git 数据。

必须把整个 Volume 作为一个单元备份。只备份数据库或只备份 repositories 都可能产生不一致的数据。

升级步骤：

备份 /data Volume；
修改 Dockerfile 中 @vibecape/cli 的固定版本；
在 Dokploy 中重新部署；
保留并继续挂载原来的 /data Volume；
再次访问 /v1/info 并检查日志。

常见错误

Replica 大于 1：多个进程会同时操作同一份 SQLite 和 repositories；
没有持久化 /data：容器重建后 Group、Space 和 Git history 会丢失；
VIBECAPE_REMOTE_HOST 使用 127.0.0.1：Dokploy 无法连接容器端口；
VIBECAPE_REMOTE_URL 使用内部地址：其他用户无法访问 Group 和 Git URL；
域名代理限制请求体或缓冲 Git 请求：clone 或 push 可能中断；
容器无法访问 Federation：用户鉴权和 Space 操作会失败。

本页内容