根据分析 `docker-compose.yml`、`.env.example` 和代码中使用的环境变量，以下是完整的环境变量清单：

---

## Docker Compose 部署环境变量

### 必需变量（必须配置）

| 变量名 | 说明 | 示例值 | 生成方式 |
|--------|------|--------|----------|
| `POSTGRES_PASSWORD` | PostgreSQL 数据库密码 | `BJ4hbYQTLsz97zzJUGg8RFiq` | `openssl rand -base64 24` |
| `JWT_SECRET` | JWT 签名密钥（≥32字符，至少 3 类字符） | `A1!b7e9c4d0...` | `printf 'A1!%s\n' "$(openssl rand -hex 48)" \| cut -c1-64` |
| `ENCRYPTION_KEY` | 敏感数据加密密钥（≥32字符，需稳定保存） | `XpPc3tcVSmy4/...` | `openssl rand -base64 32` |

---

### 可选变量（有默认值）

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `POSTGRES_USER` | 数据库用户名 | `incudal` |
| `POSTGRES_DB` | 数据库名称 | `incudal` |
| `REDIS_PASSWORD` | Redis 密码 | 空（无密码） |
| `APP_PORT` | 外部暴露端口 | `3000` |
| `ADMIN_PASSWORD` | 首次初始化管理员密码 | `admin123` |
| `LOG_LEVEL` | 日志级别 | `info` |
| `DISABLE_REQUEST_LOG` | 禁用请求日志 | `true` |
| `COOKIE_SECRET` | Cookie 签名密钥 | 空 |
| `FRONTEND_URL` | 前端 URL（CORS 白名单 + 页面跳转） | 空 |
| `PAYMENT_CALLBACK_BASE_URL` | 支付回调使用的后端公网 URL | 空（默认回退到 `FRONTEND_URL`） |
| `PAYMENT_CALLBACK_IP_WHITELIST` | 支付回调来源 IP 白名单（逗号分隔，留空时 Heleket 默认收紧到官方 IP） | 空 |
| `PAYMENT_CALLBACK_SKIP_IP_WHITELIST` | 跳过支付回调 IP 白名单校验（仅开发调试） | `false` |
| `ALERT_WEBHOOK_URL` | 系统告警 Webhook URL | 空 |
| `DB_POOL_MAX` | PostgreSQL 连接池最大连接数 | `20` |
| `DB_POOL_MIN` | PostgreSQL 连接池最小连接数 | `5` |
| `DB_CONNECTION_TIMEOUT` | 获取数据库连接超时（毫秒） | `5000` |
| `DB_IDLE_TIMEOUT` | 数据库空闲连接超时（毫秒） | `30000` |
| `DB_STATEMENT_TIMEOUT` | PostgreSQL 语句超时（毫秒） | `30000` |
| `DB_QUERY_TIMEOUT` | PostgreSQL 查询超时（毫秒） | `30000` |
| `TRAFFIC_CONCURRENCY_PER_HOST` | 每宿主机流量采集并发数 | `10` |
| `TRAFFIC_HOST_CONCURRENCY` | 同时处理宿主机数量 | `3` |
| `DB_WORKER_BACKOFF_MS` | worker 遇到数据库异常后的退避时间（毫秒） | `15000` |

---

### 最小 .env 配置示例

可以直接自动生成或补齐缺失项：

```bash
bash scripts/init-env.sh
```

脚本只补齐缺失或空值的变量，不覆盖已有非空配置。

```bash
# ============ 必需配置 ============
# 数据库密码 - 使用 openssl rand -base64 24 生成
POSTGRES_PASSWORD=your_strong_password_here

# JWT 密钥 - 使用下面命令生成：
# printf 'A1!%s\n' "$(openssl rand -hex 48)" | cut -c1-64
JWT_SECRET=your_mixed_64_char_secret_here

# 敏感数据加密密钥 - 使用 openssl rand -base64 32 生成
# 注意：上线后必须稳定保存，不能随意更换
ENCRYPTION_KEY=your_base64_32_byte_encryption_key_here

# ============ 建议配置 ============
# 管理员初始密码（首次启动后建议立即修改）
ADMIN_PASSWORD=your_admin_password

# Redis 密码（可选但推荐）
REDIS_PASSWORD=your_redis_password
```

---

### 完整 .env 配置示例（生产环境推荐）

```bash
# ============ 数据库配置 ============
POSTGRES_USER=incudal
POSTGRES_PASSWORD=BJ4hbYQTLsz97zzJUGg8RFiq
POSTGRES_DB=incudal

# ============ Redis 配置 ============
REDIS_PASSWORD=redis_password_here

# ============ 安全配置（必须修改！）============
# JWT 密钥 - 生成方式:
# printf 'A1!%s\n' "$(openssl rand -hex 48)" | cut -c1-64
JWT_SECRET=A1!b7e9c4d0f2a8e6b9d1c3f5a7b8d0e2c4f6a9b1d3e5c7a8f0b2d4e6c8

# Cookie 签名密钥（可选，增强安全性）
COOKIE_SECRET=another_random_string_here

# 敏感数据加密密钥（2FA 等）- 生成方式: openssl rand -base64 32
ENCRYPTION_KEY=XpPc3tcVSmy4/pxpLL40jVfMDJyayR+bE1ibamEWlys=

# ============ 应用配置 ============
APP_PORT=3000
ADMIN_PASSWORD=QpXEZrBkDosvu7TFMcAJjbv7
LOG_LEVEL=info
DISABLE_REQUEST_LOG=true

# ============ CORS 配置 + 页面跳转（必配！）============
FRONTEND_URL=https://your-domain.com

# ============ 支付回调（前后端分域时必配）============
# 第三方支付平台回调到后端时使用的公网地址
# 例如前端为 https://panel.example.com，后端为 https://api.example.com
# 则这里应配置为 https://api.example.com
PAYMENT_CALLBACK_BASE_URL=https://api.your-domain.com

# 支付回调来源 IP 白名单（逗号分隔）
# 留空时 Heleket 默认仅允许官方文档中的 webhook IP：31.133.220.8
# PAYMENT_CALLBACK_IP_WHITELIST=31.133.220.8

# 仅开发调试时可临时跳过支付回调 IP 白名单校验
# PAYMENT_CALLBACK_SKIP_IP_WHITELIST=false

# ============ 监控告警（可选）============
# 系统异常时发送 Webhook 告警
# ALERT_WEBHOOK_URL=https://your-webhook-url

# ============ 数据库稳定性调优（可选）============
DB_POOL_MAX=30
DB_POOL_MIN=2
DB_CONNECTION_TIMEOUT=10000
DB_IDLE_TIMEOUT=15000
DB_STATEMENT_TIMEOUT=30000
DB_QUERY_TIMEOUT=30000
TRAFFIC_CONCURRENCY_PER_HOST=10
TRAFFIC_HOST_CONCURRENCY=3
DB_WORKER_BACKOFF_MS=15000
```

---

### 部署命令

```bash
# 1. 创建 .env 文件
cp .env.example .env

# 2. 编辑 .env，配置上述变量
nano .env

# 3. 启动服务
docker-compose up -d

# 4. 查看日志
docker-compose logs -f app
```

---

### 变量来源说明

```
┌─────────────────────────────────────────────────────────────────┐
│                    环境变量流向图                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  .env 文件                                                      │
│     │                                                           │
│     ├─── POSTGRES_* ──────► db 容器 (PostgreSQL)               │
│     │                                                           │
│     ├─── REDIS_PASSWORD ──► redis 容器                          │
│     │                                                           │
│     └─── 其他变量 ────────► app 容器 (Incudal)                  │
│              │                                                  │
│              ├── DATABASE_URL (自动组装)                        │
│              ├── REDIS_URL (自动组装)                           │
│              ├── JWT_SECRET                                     │
│              ├── ENCRYPTION_KEY                                 │
│              ├── ADMIN_PASSWORD                                 │
│              └── LOG_LEVEL 等                                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

**重点**：`DATABASE_URL` 和 `REDIS_URL` 由 docker-compose.yml 自动组装，无需在 .env 中配置。