使用 Docker 部署

Chorus 提供了官方 Docker 镜像 chorusaidlc/chorus-app。本指南展示两种 Compose 形态： 独立（内置数据库）与生产（外部 PostgreSQL + Redis），一个对接现有数据库的 docker run 示例、完整的环境变量参考，以及容器启动时的行为。

先拉取镜像：

docker pull chorusaidlc/chorus-app:latest

关于如何在独立与生产两种形态之间做选择，请参见部署概览。

独立（内置数据库）

无需外部数据库。镜像内置了 PGlite（嵌入式 PostgreSQL），并会自动启动 一切。数据保存在 Docker 卷中，可在容器重启后持久保留。

创建 docker-compose.local.yml：

# Standalone Chorus — embedded PGlite, no external PostgreSQL or Redis
services:
  app:
    image: chorusaidlc/chorus-app:latest
    ports:
      - "8637:8637"
    environment:
      # No DATABASE_URL — entrypoint auto-starts embedded PGlite
      - REDIS_URL=
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET:-chorus-local-secret}
      - COOKIE_SECURE=false
      - DEFAULT_USER=${DEFAULT_USER:-admin@example.com}
      - DEFAULT_PASSWORD=${DEFAULT_PASSWORD:-changeme}
    volumes:
      - chorus-local-data:/app/data

volumes:
  chorus-local-data:

然后运行：

docker compose -f docker-compose.local.yml up -d

打开 http://localhost:8637，使用 admin@example.com / changeme 登录（或通过 DEFAULT_USER / DEFAULT_PASSWORD 环境变量覆盖）。

在独立模式下，容器会：

• 在内部端口（5433）上启动 PGlite，不对外暴露。
• 将数据存放在 chorus-local-data Docker 卷中，因此可在重启后持久保留。
• 禁用 Redis（回退到内存 EventBus，仅支持单实例）。
• 在启动时自动执行 Prisma 迁移。

生产（外部 PostgreSQL + Redis）

面向生产环境，尤其是多副本部署时，请将应用对接到外部 PostgreSQL 与 Redis。创建 docker-compose.yml：

services:
  app:
    image: chorusaidlc/chorus-app:latest
    ports:
      - "8637:8637"
    environment:
      - DATABASE_URL=postgresql://chorus:chorus@db:5432/chorus
      - REDIS_URL=redis://default:chorus-redis@redis:6379
      - NEXTAUTH_SECRET=change-me-to-a-random-secret
      - DEFAULT_USER=admin@example.com
      - DEFAULT_PASSWORD=your-password
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass chorus-redis
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "chorus-redis", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: chorus
      POSTGRES_PASSWORD: chorus
      POSTGRES_DB: chorus
    volumes:
      - chorus-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U chorus -d chorus"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  chorus-data:
  redis-data:

然后运行：

docker compose up -d

打开 http://localhost:8637，使用你在 DEFAULT_USER / DEFAULT_PASSWORD 中设置的凭据 登录。

HTTPS 与安全 Cookie

上面的 Compose 文件设置了 COOKIE_SECURE=false，以支持纯 HTTP 部署（例如内网测试）。只应 在可信内网中使用 COOKIE_SECURE=false，此时 Cookie 会通过未加密的 HTTP 发送。当你在生产 环境以 HTTPS 部署时，请设置 COOKIE_SECURE=true 以启用安全 Cookie。

对接现有 PostgreSQL 运行

如果你已经有 PostgreSQL 和 Redis 在运行，可直接启动容器：

docker run -d \
  -p 8637:8637 \
  -e DATABASE_URL=postgresql://user:pass@your-db-host:5432/chorus \
  -e REDIS_URL=redis://default:password@your-redis-host:6379 \
  -e NEXTAUTH_SECRET=change-me-to-a-random-secret \
  -e COOKIE_SECURE=false \
  -e DEFAULT_USER=admin@example.com \
  -e DEFAULT_PASSWORD=your-password \
  chorusaidlc/chorus-app:latest

环境变量

必需

| 变量 | 说明 | | --- | --- | | DATABASE_URL | PostgreSQL 连接字符串。格式：postgresql://user:password@host:port/dbname。也可以改为设置单独的 DB_* 变量（见下文）。若省略，入口脚本会自动启动一个嵌入式 PGlite 实例。 | | NEXTAUTH_SECRET | 用于签发 JWT 会话令牌的密钥。请使用随机字符串（例如 openssl rand -base64 32）。 |

数据库（DATABASE_URL 的替代方案）

若未设置 DATABASE_URL，入口脚本会用以下单独变量拼装它：

| 变量 | 说明 | | --- | --- | | DB_HOST | PostgreSQL 主机 | | DB_PORT | PostgreSQL 端口（默认：5432） | | DB_USERNAME | PostgreSQL 用户名 | | DB_PASSWORD | PostgreSQL 密码 | | DB_NAME | 数据库名 |

Redis

| 变量 | 说明 | | --- | --- | | REDIS_URL | 完整的 Redis 连接字符串。格式：redis://username:password@host:port。优先级高于以下单独变量。 | | REDIS_HOST | Redis 主机（在未设置 REDIS_URL 时使用） | | REDIS_PORT | Redis 端口（默认：6379） | | REDIS_USERNAME | Redis 用户名（默认：default） | | REDIS_PASSWORD | Redis 密码 |

身份认证

| 变量 | 说明 | | --- | --- | | DEFAULT_USER | 内置登录的邮箱地址（绕过 OIDC）。首次登录时自动创建该用户及公司。 | | DEFAULT_PASSWORD | 默认用户的密码（明文，运行时通过 bcrypt 比对）。 | | NEXTAUTH_URL | 应用对外的基础 URL（默认：http://localhost:8637）。在反向代理后运行时请设置此项。 | | COOKIE_SECURE | 设为 "false" 可为纯 HTTP 部署禁用安全 Cookie（docker-compose 中默认为 "false"）。以 HTTPS 部署到生产环境时设为 "true"。 |

日志

| 变量 | 默认值 | 说明 | | --- | --- | --- | | LOG_LEVEL | info（生产）/ debug（开发） | 服务端最低日志级别。可选：trace、debug、info、warn、error、fatal、silent。设为 info 可抑制 Prisma 查询日志。 | | NEXT_PUBLIC_LOG_LEVEL | warn（生产）/ debug（开发） | 浏览器端最低日志级别。可选：debug、info、warn、error。 |

生产 Docker 镜像始终将 JSON 输出到 stdout（可直接对接 CloudWatch / ELK）。彩色美化输出仅在 本地开发时可用。

超级管理员

| 变量 | 说明 | | --- | --- | | SUPER_ADMIN_EMAIL | 超级管理员账号的邮箱（可访问 /admin 面板）。 | | SUPER_ADMIN_PASSWORD_HASH | 超级管理员密码的 bcrypt 哈希。生成方式：node -e "console.log(require('bcryptjs').hashSync('your-password', 10))" |

启动行为

容器的入口脚本每次启动都会执行相同的流程：

1. 若未设置 DATABASE_URL 且未提供任何 DB_* 变量，入口脚本会在内部端口（5433）上启动 一个嵌入式 PGlite 实例。当已配置外部数据库时，不会启动 PGlite。
2. 执行 prisma migrate deploy，应用任何待处理的数据库迁移。
3. 若数据库尚未就绪，每 10 秒重试一次（最多 30 次，约五分钟）。
4. 迁移成功后，Next.js 服务在 8637 端口启动。

迁移自动执行

你无需自行执行迁移。在启动时应用待处理的迁移是入口脚本的一部分，因此升级就是用新版镜像对接 同一个数据库并启动它。由于新镜像可能在首次启动时迁移你的数据库结构，请在升级前备份数据库或 数据卷，参见运维。

镜像细节

• 基础镜像： node:22-alpine
• 内部端口： 8637
• 架构： linux/amd64、linux/arm64

后续步骤

• 生产部署：从全局 npm 包运行，以及完整的 AWS CDK 演练。
• 运维：首次登录引导、部署侧身份认证，以及升级前的 备份。