使用 Docker Compose 部署

本页只使用公开的 GHCR 镜像启动最小本机环境：PostgreSQL、Redis、Legate Central 和 Console；Sidecar 通过 profile 可选启动。不需要访问任何源码或文档仓库。

仅限本地开发

示例使用 --admin-auth-mode=disabled，所有管理请求都获得平台管理员能力。端口必须只绑定 127.0.0.1，不要部署到服务器或共享开发机。共享环境请配置 OIDC。

前置条件

• Docker Engine 24+ 或 Docker Desktop；
• Docker Compose v2；
• 至少 4 GiB 可用内存。

准备文件

在同一个空目录下载 compose.yaml 和 legate.env.example，然后把 legate.env.example 重命名为 .env。也可以直接从下面的代码块创建这两个文件。

compose.yaml.env

name: legate-dev

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: legate
      POSTGRES_PASSWORD: ${LEGATE_DATABASE_PASSWORD:-legate-dev-only}
      POSTGRES_DB: legate
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U legate -d legate"]
      interval: 2s
      timeout: 3s
      retries: 30
    volumes:
      - postgres-data:/var/lib/postgresql/data

  redis:
    image: redis:8-alpine
    command: ["redis-server", "--appendonly", "yes"]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 2s
      timeout: 3s
      retries: 30
    volumes:
      - redis-data:/data

  central:
    image: ghcr.io/bit-fortress/legate:${LEGATE_VERSION:-edge}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    command:
      - --listen=:8080
      - --database-dsn=postgres://legate:${LEGATE_DATABASE_PASSWORD:-legate-dev-only}@postgres:5432/legate?sslmode=disable
      - --redis-addr=redis:6379
      - --redis-prefix=legate-dev
      - --admin-auth-mode=disabled
      - --instance-id=legate-dev-central
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/api/healthz"]
      interval: 3s
      timeout: 5s
      retries: 40
    ports:
      - "127.0.0.1:${LEGATE_GATEWAY_PORT:-8081}:8080"
    volumes:
      - central-telemetry-state:/var/lib/legate/telemetry

  console:
    image: ghcr.io/bit-fortress/legate-console:${LEGATE_CONSOLE_VERSION:-edge}
    depends_on:
      central:
        condition: service_healthy
    environment:
      API_UPSTREAM: http://central:8080
    ports:
      - "127.0.0.1:${LEGATE_CONSOLE_PORT:-8080}:80"

  sidecar:
    profiles: ["sidecar"]
    image: ghcr.io/bit-fortress/legate-sidecar:${LEGATE_VERSION:-edge}
    depends_on:
      central:
        condition: service_healthy
      redis:
        condition: service_healthy
    command:
      - --listen=:8081
      - --control-plane=http://central:8080
      - --central-gateway=http://central:8080
      - --telemetry-base-url=http://central:8080
      - --workspace=${LEGATE_SIDECAR_WORKSPACE:-default}
      - --token=${LEGATE_SIDECAR_TOKEN:-}
      - --instance-id=${LEGATE_SIDECAR_INSTANCE_ID:-local-sidecar-1}
      - --sync-interval=10s
      - --redis-addr=redis:6379
      - --redis-prefix=legate-dev
    ports:
      - "127.0.0.1:${LEGATE_SIDECAR_PORT:-8082}:8081"
    volumes:
      - sidecar-telemetry-state:/var/lib/legate-sidecar/telemetry

volumes:
  postgres-data:
  redis-data:
  central-telemetry-state:
  sidecar-telemetry-state:

# 仅供本机开发。不要把这些默认值用于共享或生产环境。
LEGATE_VERSION=edge
LEGATE_CONSOLE_VERSION=edge
LEGATE_DATABASE_PASSWORD=legate-dev-only
LEGATE_CONSOLE_PORT=8080
LEGATE_GATEWAY_PORT=8081
LEGATE_SIDECAR_PORT=8082

# 启动 Sidecar profile 前填写。Sidecar token 只在创建时显示一次。
LEGATE_SIDECAR_WORKSPACE=default
LEGATE_SIDECAR_TOKEN=
LEGATE_SIDECAR_INSTANCE_ID=local-sidecar-1

默认地址：

地址	用途
http://127.0.0.1:8080	Console
http://127.0.0.1:8081	Central 管理 API 与模型代理
http://127.0.0.1:8082	可选 Sidecar 模型代理

启动

docker compose pull
docker compose up -d

.env 默认使用公开的 edge 镜像，适合本机验证。需要复现或长期运行时，把 LEGATE_VERSION 和 LEGATE_CONSOLE_VERSION 固定为精确发布或提交标签；Central 与 Sidecar 必须使用同一个 LEGATE_VERSION。

检查容器与 Central health：

docker compose ps

curl -fsS http://127.0.0.1:8081/api/healthz

应返回 {"ok":true}。打开 http://127.0.0.1:8080，禁用认证模式会直接进入 Console。

第一次调用

按 Console 实际顺序：

1. 在“接入点”创建 Endpoint Group。
2. 在组内创建文本 Endpoint，选择类型、Base URL、api_key 与上游模型。
3. 在“模型组”创建文本组，选择入站协议并添加 tier 0 Endpoint Model 映射。
4. 在“API 密钥”创建 sk-leg-... 并绑定该模型组。

假设模型组为 chat-default：

curl http://127.0.0.1:8081/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <LEGATE_API_KEY>' \
  -d '{"model":"chat-default","messages":[{"role":"user","content":"Hello"}],"stream":false}'

调用方只使用 Authorization: Bearer。不要把 Endpoint API Key 或 Sidecar Token 放入业务请求。

启动 Sidecar

在 Console 创建 Sidecar Token，把 Workspace slug、一次性 Token 和稳定 instance ID 写入 .env：

LEGATE_SIDECAR_WORKSPACE=default
LEGATE_SIDECAR_TOKEN=<SIDECAR_TOKEN>
LEGATE_SIDECAR_INSTANCE_ID=local-sidecar-1

docker compose --profile sidecar pull sidecar
docker compose --profile sidecar up -d sidecar

curl http://127.0.0.1:8082/api/healthz 只检查进程。请同时在 Console “Sidecar → 实例”确认 last pull、snapshot revision 与 telemetry 状态。

日志与清理

docker compose logs -f

访问日志不会记录 prompt、请求/响应 body 或认证凭据。停止但保留数据：

docker compose --profile sidecar down

彻底删除开发数据：

docker compose --profile sidecar down --volumes --remove-orphans

--volumes 会永久删除 PostgreSQL、Redis 和 telemetry state。

常见问题

“没有可用接入点”时依次检查：模型组状态与入站 Contract、映射 kind、Endpoint 调度与状态、上游模型、Driver Binding、credential、breaker 和上游网络。

模型同步失败不影响手动添加模型；它通常表示上游没有兼容的 models API、Base URL 不正确或 credential 无权列出模型。

修改 PostgreSQL 初始化密码不会更新已有 volume。只在确认没有价值数据时删除 volume 重建。

共享环境前

至少完成：OIDC + HTTPS 同源入口、Secret Manager、持久化 PostgreSQL/Redis、Central 与 Sidecar telemetry state volume、受控网络、日志与备份，以及按实际流量校准文本流、replay 和 telemetry 预算。