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

## 使用全局包连接外部 PostgreSQL

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

```sh
npm install --global @chorus-aidlc/chorus
```

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

```sh
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 在生产运行中读取的环境变量：

<div class="table-scroll" role="region" aria-label="生产环境变量" tabindex="0">

| 环境变量 | 是否必需 | 说明 |
| --- | --- | --- |
| `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_PASSWORD` | 可选 | 内置登录使用的密码。 |
| `REDIS_URL` | 可选 | Redis 连接串。运行多个实例时必需（见下文）。 |

</div>

这些启动凭据的工作方式、bcrypt 哈希的生成方法，以及如何关闭内置登录，请参阅[运维自托管的 Chorus](/zh/guides/deploy-operations/)。

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

## 运行多个实例

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

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

**跨实例的事件传播必须依赖 Redis。** 未设置 `REDIS_URL` 时，Chorus 会退回到进程内的内存事件总线，其作用范围仅限单个进程，在一个实例上产生的更新不会到达其他实例。单实例部署可以不配置 Redis，依靠这种内存回退运行；但只要部署多于一个实例，就必须配置共享 Redis。

所有实例还必须共享同一个安全的 `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 回调地址。

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

### 运行安装脚本

在仓库根目录执行：

```sh
./install.sh
```

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

<div class="table-scroll" role="region" aria-label="install.sh 交互提示" tabindex="0">

| 提示 | 是否必需 | 说明 |
| --- | --- | --- |
| 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 都会生成新值。提供同一个持久值，才能在重新部署后保留会话。 |

</div>

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

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

### 该栈会创建哪些组件

该栈会创建：

<div class="table-scroll" role="region" aria-label="CDK 栈组件" tabindex="0">

| 组件 | 是什么 | 关键配置 |
| --- | --- | --- |
| 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 任务中。 |

</div>

### 部署、更新与销毁

<div class="table-scroll" role="region" aria-label="部署命令" tabindex="0">

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

</div>

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