生产环境部署

本指南介绍两条生产部署路径：使用全局 npm 包连接自有的 PostgreSQL 与 Redis 运行，以及使用仓库自带的安装脚本部署 AWS 栈。如果只是在单机上试用，请改用快速开始；如果要用容器部署，请参阅使用 Docker 部署。启动凭据、单点登录与安全升级等内容，请参阅运维自托管的 Chorus。

使用全局包连接外部 PostgreSQL

在运行 Web 应用的主机上全局安装 Chorus 命令：

npm install --global @chorus-aidlc/chorus

通过 DATABASE_URL 指向现有的 PostgreSQL 数据库，并提供必需的认证与密钥环境变量，然后启动：

DATABASE_URL='postgresql://chorus:password@db.internal:5432/chorus' \
NEXTAUTH_SECRET="${NEXTAUTH_SECRET:?Set a persistent random secret first}" \
SUPER_ADMIN_EMAIL='admin@example.com' \
SUPER_ADMIN_PASSWORD_HASH='$2b$10$...' \
chorus

启动时，Chorus 会自动应用所有待执行的数据库迁移（prisma migrate deploy），随后在 8637 端口提供 Web 应用。数据库必须已经存在且可访问；在这条路径上，Chorus 不会为你创建数据库。

Chorus 在生产运行中读取的环境变量：

环境变量	是否必需	说明
DATABASE_URL	是	PostgreSQL 连接串，格式为 postgresql://user:password@host:port/dbname。
NEXTAUTH_SECRET	多实例时必需	所有副本共享的签名密钥。单个 npm 实例可省略，chorus 默认生成并保存在 ~/.chorus-data/.secret。环境变量中的已知占位值会被忽略并触发警告；已保存的密钥若为空或为公开占位值，则停止启动。
SUPER_ADMIN_EMAIL	是	用于引导 /admin 超级管理员面板的邮箱。
SUPER_ADMIN_PASSWORD_HASH	是	超级管理员密码的 bcrypt 哈希值。
DEFAULT_USER	可选	可选的旧版 Default Auth 邮箱，需同时设置 DEFAULT_PASSWORD。按需创建用户和工作区，不会创建托管本地账号或授予本地工作区管理员角色。
DEFAULT_PASSWORD	可选	内置登录使用的密码。
REDIS_URL	可选	用于 SSE 和认证计数器的共享 Redis，多实例一致性需要它；也可使用 REDIS_HOST 和其他独立 Redis 变量。

这些启动凭据的工作方式、bcrypt 哈希的生成方法，以及如何关闭内置登录，请参阅运维自托管的 Chorus。

妥善处理密钥

NEXTAUTH_SECRET 与超级管理员凭据拥有完全访问权限。不要让它们进入命令历史或代码仓库，应通过进程管理器、systemd 单元或密钥管理服务提供，而不要在共享主机上直接内联输入。

运行多个实例

Chorus 通过 Redis 在多个实例之间传播实时更新（SSE 事件流）。请把 REDIS_URL 设为共享的 Redis，让每个实例都发布并接收相同的事件：

REDIS_URL='redis://default:password@redis.internal:6379'

Redis 通过独立连接提供跨实例 SSE 和共享认证计数器。非空 REDIS_URL 优先；否则 REDIS_HOST 使用 TLS（rediss），端口默认 6379、用户名默认 default，用户名在提供 REDIS_PASSWORD 时使用。非 TLS Redis 应显式使用 redis://。只有 URL 和 host 均未配置时，事件和限流才完全留在进程内。Redis 故障会启用每进程备用限流，不再共享额度，也不会阻止全部登录；意外的限流器错误可能放行。具体限制和恢复行为参见共享认证限流。

AUTH_TRUST_PROXY 默认关闭，仅 true 启用。AUTH_TRUST_PROXY_HOPS 默认 1，有效值为 1 到 16 的整数，从 X-Forwarded-For 右侧计数。只有代理链强制执行且不可绕过时才启用信任，HTTPS 本身不足以建立信任。内置 CDK 的 ALB 模式使用 true / 1，CloudFront 模式使用 false / 2，因为 VPC 流量仍可绕过 CloudFront 到达私有源站。

托管本地账号保存在数据库中，不通过 DEFAULT_USER / DEFAULT_PASSWORD 配置。向应用注入 SUPER_ADMIN_EMAIL 和 SUPER_ADMIN_PASSWORD_HASH，再从管理面板创建本地账号工作区并邀请首位工作区管理员。无需身份提供商或邮件服务。同一工作区的本地账号与 OIDC 互斥，已有工作区不可转换。持久化 NEXTAUTH_SECRET 并在所有副本间共享；共享访问使用 HTTPS 和 COOKIE_SECURE=true。设置账号以及如何只关闭旧版 Default Auth 参见运维指南。

所有实例还必须共享同一个安全的 NEXTAUTH_SECRET，这样无论请求落到哪个实例，Chorus 签发的会话都保持有效。

部署 AWS CDK 栈

Chorus 在 packages/chorus-cdk 下自带一个 AWS CDK 栈，并提供仓库根目录的 install.sh 以交互方式驱动它。该栈会搭建一套以 HTTPS 对外提供服务的完整部署，并附带托管的 PostgreSQL 与 Redis。

前置条件

install.sh 会检查 aws、node、pnpm 以及有效的 AWS 凭据。请先通过 aws configure 或 AWS_PROFILE 配置凭据。证书要求取决于下列模式。

选择部署模式

• alb（默认）：公网 ALB 使用 HTTPS 443 端口，必须提供部署区域内的 ACM 证书，自定义域名可选。
• cloudfront：CloudFront 提供公网 HTTPS，经 VPC origin 转发到私有 ALB 的 HTTP 80 端口。 默认的 *.cloudfront.net 域名无需自备证书。使用自定义域名时，必须同时提供域名和 us-east-1 的 ACM 证书。登录后的页面和 API 响应均禁用缓存。

在 ./install.sh 中选择模式，或向 CDK 传入 -c deployMode=cloudfront。 default_deploy.sh 会保留选择。非交互安装使用 CHORUS_INSTALL_NONINTERACTIVE=1、 DEPLOY_MODE=alb|cloudfront 及其他必需变量。两种模式都不会创建 DNS 记录；请将自定义域名指向 AlbDnsName 或 CloudFrontDomainName 栈输出，并更新 OIDC 回调地址。

切换现有部署的模式

模式切换会替换 ALB 并改变 DNS 名称。请部署新栈，迁移数据与 DNS，验证后再移除旧栈。 继续使用 alb 会保留现有拓扑。cloudfront 模式的 ALB 不可从公网访问，排障请使用 CloudFront 地址、ECS 日志或目标组健康状态，并确认部署区域支持 CloudFront VPC origin。

运行安装脚本

在仓库根目录执行：

./install.sh

安装脚本会依次询问部署配置：

提示	是否必需	说明
Deployment mode	否	alb（默认）或 cloudfront。
Stack name	否	默认为 Chorus。
ACM Certificate ARN	取决于模式	alb 必须使用部署区域的证书；cloudfront 仅在使用自定义域名时需要 us-east-1 的证书。
Custom domain	否	cloudfront 模式需同时提供 us-east-1 的证书，否则使用分配的 CloudFront 域名。
Super admin email	是	用于引导 /admin 超级管理员账号。
Super admin password	是	至少 8 个字符。在 synth 阶段用 bcrypt 哈希，明文不会写入模板。
NextAuth secret	否	留空时每次 synth 都会生成新值。提供同一个持久值，才能在重新部署后保留会话。

栈通过 Secrets Manager 共享 NEXTAUTH_SECRET，但 synth 时不会读回已保存的值。 每次部署请在安装器或 CDK 的 nextAuthSecret context 中复用同一值。若此前留空， 请在重新部署前保留 Secrets Manager 中的现有值，避免意外轮换。

收集完这些答案后，install.sh 会安装并构建 CDK 包，引导（bootstrap）CDK 环境，然后部署该栈。它还会把你的答案写入可重复执行的 default_deploy.sh，这样后续部署无需重新询问。

该栈会创建哪些组件

该栈会创建：

组件	是什么	关键配置
Application Load Balancer	alb 为公网 HTTPS:443；cloudfront 为私有 HTTP:80 源站。	转发到 ECS，空闲超时 60 分钟。
CloudFront	仅在 cloudfront 模式创建的公网 HTTPS 入口。	私有 VPC origin，禁用缓存，可选自定义域名。
ECS Fargate 服务	在私有子网中运行 Chorus 容器。	期望副本数 2，1024 CPU 单位／2048 MiB，部署断路器可自动回滚。
Aurora Serverless v2（PostgreSQL）	托管的 PostgreSQL 集群。	存储加密；凭据自动生成并存入 Secrets Manager；备份保留 1 天。
ElastiCache Serverless（Redis）	用于跨实例事件与共享认证计数器的托管 Redis。	使用 RBAC 用户；密码存入 Secrets Manager。
Secrets Manager	保存生成的数据库、Redis 凭据以及应用密钥。	在运行时注入到 ECS 任务中。

部署、更新与销毁

操作	命令
首次部署	./install.sh
重新部署或更新	./default_deploy.sh（或 pnpm cdk:deploy）
销毁	pnpm cdk:destroy

packages/chorus-cdk 是该栈的权威来源。当你需要精确的资源定义，或想调整容量、保留策略或网络时，请以那里的代码为准。