109 lines
3.2 KiB
Markdown
109 lines
3.2 KiB
Markdown
# yedir-ai 部署指南
|
||
|
||
本文档用于生产或准生产环境部署。所有真实密钥只应配置在运行环境中，不要提交到 Git。
|
||
|
||
## 运行环境
|
||
|
||
- Node.js 20
|
||
- pnpm 9.12.3
|
||
- Postgres
|
||
- 可选 Redis
|
||
- Vercel Blob 或 S3-compatible 对象存储
|
||
- 至少一个可用 AI Provider，或在后台设置中配置供应商
|
||
|
||
## 基础步骤
|
||
|
||
```bash
|
||
pnpm install --frozen-lockfile
|
||
pnpm db:migrate
|
||
pnpm build
|
||
pnpm start
|
||
```
|
||
|
||
`pnpm build` 只执行 Next.js 生产构建，不会隐式连接数据库。需要在单机部署脚本中把迁移和构建串起来时，可使用：
|
||
|
||
```bash
|
||
pnpm build:with-migrate
|
||
```
|
||
|
||
本地开发：
|
||
|
||
```bash
|
||
AUTH_TRUST_HOST=true PORT=3001 pnpm dev
|
||
```
|
||
|
||
## 环境变量分组
|
||
|
||
### Core / Auth
|
||
|
||
必须配置 `AUTH_SECRET` 和生产域名 `AUTH_URL`。只有在受信反向代理后部署，并确认 Host 头不会被用户伪造时，才允许设置 `AUTH_TRUST_HOST=true`。
|
||
|
||
Google、钉钉、邮箱验证等登录能力可以通过后台设置和环境变量组合启用。管理员初始化使用 `ADMIN_EMAIL` / `ADMIN_PASSWORD`，完成后建议移除或轮换。
|
||
|
||
### Database
|
||
|
||
主数据库使用 `POSTGRES_URL`。连接池默认值来自 `lib/db/index.ts`：
|
||
|
||
- `POSTGRES_MAX_CONNECTIONS=10`
|
||
- `POSTGRES_IDLE_TIMEOUT_SECONDS=20`
|
||
- `POSTGRES_CONNECT_TIMEOUT_SECONDS=5`
|
||
- `POSTGRES_MIGRATION_TIMEOUT_SECONDS=120`
|
||
|
||
生产环境可按数据库规格调整，但不建议无上限放大连接数。
|
||
|
||
### Object Storage
|
||
|
||
优先使用后台数据库中的存储配置；环境变量 S3 和 `BLOB_READ_WRITE_TOKEN` 作为 fallback。
|
||
|
||
S3 公网访问建议配置 `S3_PUBLIC_URL`，避免把内部 endpoint 暴露给前端或用户。
|
||
|
||
### AI Providers
|
||
|
||
大多数供应商都可以在后台设置中配置。环境变量适合作为 bootstrap 或 fallback，例如 `DASHSCOPE_API_KEY`、`FAL_KEY`、`TRIPO_API_KEY`、`KITTYCAD_API_TOKEN`。
|
||
|
||
不要在日志、README、issue 或截图中暴露真实 API Key、签名 URL、OAuth code、session、cookie。
|
||
|
||
### Logging
|
||
|
||
生产建议：
|
||
|
||
```env
|
||
LOG_LEVEL=info
|
||
LOG_INCLUDE_STACK=false
|
||
NEXT_PUBLIC_ENABLE_CLIENT_LOGS=false
|
||
```
|
||
|
||
日志会经过 `lib/observability` 脱敏。需要排查问题时，优先临时提高服务端 `LOG_LEVEL`，不要开启浏览器生产日志。
|
||
|
||
## 反向代理与安全
|
||
|
||
- 代理层应保留正确的 `X-Forwarded-*` 头。
|
||
- 只在可信代理后启用 `AUTH_TRUST_HOST=true`。
|
||
- 上传和生成接口可能处理大文件，代理需要配置足够的 body size 和超时时间。
|
||
- 对管理端、支付、生成任务回调和定时任务接口使用独立密钥或登录权限保护。
|
||
|
||
## 部署后烟测
|
||
|
||
如果可以从部署机或本地访问目标域名，推荐直接使用脚本：
|
||
|
||
```bash
|
||
SMOKE_BASE_URL=https://your-domain.com pnpm smoke:routes
|
||
```
|
||
|
||
也可以手动检查：
|
||
|
||
```bash
|
||
curl -I https://your-domain.com/
|
||
curl -I https://your-domain.com/classic
|
||
curl -I https://your-domain.com/chat/test-id
|
||
curl -I https://your-domain.com/settings
|
||
curl -I "https://your-domain.com/api/site-settings?scope=home"
|
||
```
|
||
|
||
预期：
|
||
|
||
- `/` 返回 200。
|
||
- `/classic` 和 `/chat/test-id` 重定向到 `/`。
|
||
- `/settings` 未登录重定向到登录页。
|
||
- 首页公开接口带有 `X-Cache` / `X-Fallback` / `Server-Timing` 等观测头。
|