Docker Compose 部署

Docker Compose 是启动 Open Connector 较为快捷的方式，适合本地开发和单机生产环境部署。项目没有发布预构建的 Docker 镜像 — 服务器镜像需从源码构建，使用 apps/server/Dockerfile，且构建上下文为 Monorepo 仓库根目录。

仓库根目录自带的 docker-compose.yml 仅包含基础设施（Postgres、MinIO 以及 grafana/otel-lgtm 后端），并不运行服务器本身。可用 pnpm infra:up 启动它（或用 pnpm db:start 仅启动 Postgres），服务器需单独运行。下方的 Compose 文件是一个自包含的变体，会从源码构建并运行服务器。

前置条件

Docker 20.10+
Docker Compose v2（通常随 Docker Desktop 一起安装）
一份 openconnector-dev/openconnector 仓库的克隆（作为构建上下文）
openssl（用于生成密钥）

完整的 docker-compose.yml

在仓库克隆的根目录中创建以下文件，命名为 docker-compose.selfhost.yml（build.context 必须是仓库根目录，Dockerfile 才能拷贝整个工作区）：

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: open_connector
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  server:
    # 从源码构建 — 没有预构建镜像。
    build:
      context: .
      dockerfile: apps/server/Dockerfile
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://postgres:${POSTGRES_PASSWORD:-postgres}@postgres:5432/open_connector
      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
      BETTER_AUTH_URL: ${BETTER_AUTH_URL:-http://localhost:3000}
      CORS_ORIGIN: ${CORS_ORIGIN:-http://localhost:3001}
      CONNECTOR_ENCRYPTION_KEY: ${CONNECTOR_ENCRYPTION_KEY}
      WEB_URL: ${WEB_URL:-http://localhost:3002}
      NODE_ENV: production
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:

配置环境变量

在 docker-compose.yml 所在目录中创建 .env 文件：

# 生成两个强随机密钥（macOS/Linux）
BETTER_AUTH_SECRET=$(openssl rand -base64 32)
CONNECTOR_ENCRYPTION_KEY=$(openssl rand -base64 32)
POSTGRES_PASSWORD=$(openssl rand -base64 16)

cat > .env << EOF
BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
CONNECTOR_ENCRYPTION_KEY=${CONNECTOR_ENCRYPTION_KEY}
POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
BETTER_AUTH_URL=http://localhost:3000
CORS_ORIGIN=http://localhost:3001
WEB_URL=http://localhost:3002
EOF

WEB_URL 为必填项（用于构建等待列表确认链接），请勿省略。

请将 .env 添加到 .gitignore 中，切勿将密钥提交到版本控制系统。

启动服务

# 构建服务器镜像并在后台启动所有服务
docker compose -f docker-compose.selfhost.yml up -d --build

# 查看启动日志（可选）
docker compose -f docker-compose.selfhost.yml logs -f server

服务启动后，从仓库根目录、设置好 DATABASE_URL 后初始化数据库 Schema：

DATABASE_URL='postgres://postgres:postgres@localhost:5432/open_connector' pnpm db:migrate

pnpm db:push 是开发用的直推变体（直接应用 Schema 差异，不生成迁移文件）。连接器目录行（GitHub、Telegram）会在服务器启动时自动写入（seedProviders），无需手动初始化连接器。

验证服务是否正常运行

# 检查健康状态（根路由即存活探针）
curl http://localhost:3000/

# 预期响应：
# OK

常用运维命令

# 查看运行状态
docker compose -f docker-compose.selfhost.yml ps

# 查看服务日志
docker compose -f docker-compose.selfhost.yml logs server
docker compose -f docker-compose.selfhost.yml logs postgres

# 停止服务（保留数据）
docker compose -f docker-compose.selfhost.yml stop

# 停止并移除容器（保留数据卷）
docker compose -f docker-compose.selfhost.yml down

# 停止并移除所有内容，包括数据库（危险操作！）
docker compose -f docker-compose.selfhost.yml down -v

# 拉取最新代码并重新构建镜像
git pull
docker compose -f docker-compose.selfhost.yml up -d --build

数据持久化

Postgres 数据存储在名为 postgres_data 的 Docker 卷中。这意味着：

执行 docker compose down 不会删除数据
执行 docker compose down -v 会删除所有数据（包括加密的 Token）
在迁移到新服务器时，需要同时迁移数据库卷和 CONNECTOR_ENCRYPTION_KEY

如果您更改 CONNECTOR_ENCRYPTION_KEY，所有存储的凭证将无法解密，所有用户都需要重新进行 OAuth 授权。此密钥请视同生产密钥妥善保管。

在反向代理后面运行（生产环境推荐）

对于生产环境，建议在 Open Connector 前面放置反向代理（如 Nginx 或 Caddy）来处理 TLS 终止和域名路由。

Caddy 示例配置（Caddyfile）：

connector.yourcompany.com {
  reverse_proxy localhost:3000
}

Caddy 会自动配置 Let's Encrypt TLS 证书。将 BETTER_AUTH_URL 更新为您的公网 HTTPS 域名，并将 CORS_ORIGIN 设置为您的前端应用域名。

升级到新版本

# 拉取最新代码并重新构建服务器镜像
git pull
docker compose -f docker-compose.selfhost.yml up -d --build server

# 如有新的数据库迁移，从仓库根目录执行迁移
DATABASE_URL='postgres://postgres:postgres@localhost:5432/open_connector' pnpm db:migrate

建议在执行升级前查看 CHANGELOG 以了解是否有 Breaking Change 或需要执行的迁移步骤。

On this page