fenghuo/docs/ENVIRONMENT.md

# 环境变量配置指南

本文档详细说明了项目中所有环境变量的配置方法和用途。

## 存储配置 (@repo/storage)

### 基础配置

```bash
# 存储类型选择
STORAGE_TYPE=local  # 可选值: local | s3

# 上传文件过期时间（毫秒），0表示不过期
UPLOAD_EXPIRATION_MS=0
```

### 本地存储配置

当 `STORAGE_TYPE=local` 时需要配置：

```bash
# 本地存储目录路径
UPLOAD_DIR=./uploads
```

### S3 存储配置

当 `STORAGE_TYPE=s3` 时需要配置：

```bash
# S3 存储桶名称 (必需)
S3_BUCKET=my-app-uploads

# S3 区域 (必需)
S3_REGION=us-east-1

# S3 访问密钥 ID (必需)
S3_ACCESS_KEY_ID=your-access-key-id

# S3 访问密钥 (必需)
S3_SECRET_ACCESS_KEY=your-secret-access-key

# 自定义 S3 端点 (可选，用于 MinIO、阿里云 OSS 等)
S3_ENDPOINT=

# 是否强制使用路径样式 (可选)
S3_FORCE_PATH_STYLE=false

# 分片上传大小，单位字节 (可选，默认 8MB)
S3_PART_SIZE=8388608

# 最大并发上传数 (可选)
S3_MAX_CONCURRENT_UPLOADS=60
```

## 配置示例

### 开发环境 - 本地存储

```bash
# .env.development
STORAGE_TYPE=local
UPLOAD_DIR=./uploads
UPLOAD_EXPIRATION_MS=86400000  # 24小时过期
```

### 生产环境 - AWS S3

```bash
# .env.production
STORAGE_TYPE=s3
S3_BUCKET=prod-app-uploads
S3_REGION=us-west-2
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
UPLOAD_EXPIRATION_MS=604800000  # 7天过期
```

### MinIO 本地开发

```bash
# .env.local
STORAGE_TYPE=s3
S3_BUCKET=uploads
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_ENDPOINT=http://localhost:9000
S3_FORCE_PATH_STYLE=true
```

### 阿里云 OSS

```bash
# .env.aliyun
STORAGE_TYPE=s3
S3_BUCKET=my-oss-bucket
S3_REGION=oss-cn-hangzhou
S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-access-key-secret
S3_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
S3_FORCE_PATH_STYLE=false
```

### 腾讯云 COS

```bash
# .env.tencent
STORAGE_TYPE=s3
S3_BUCKET=my-cos-bucket-1234567890
S3_REGION=ap-beijing
S3_ACCESS_KEY_ID=your-secret-id
S3_SECRET_ACCESS_KEY=your-secret-key
S3_ENDPOINT=https://cos.ap-beijing.myqcloud.com
S3_FORCE_PATH_STYLE=false
```

## 其他配置

### 数据库配置

```bash
# PostgreSQL 数据库连接字符串
DATABASE_URL="postgresql://username:password@localhost:5432/database"
```

### Redis 配置

```bash
# Redis 连接字符串
REDIS_URL="redis://localhost:6379"
```

### 应用配置

```bash
# 应用端口
PORT=3000

# 应用环境
NODE_ENV=development

# CORS 允许的源
CORS_ORIGIN=http://localhost:3001
```

## 安全注意事项

1. **敏感信息保护**:

   - 永远不要将包含敏感信息的 `.env` 文件提交到版本控制系统
   - 使用 `.env.example` 文件作为模板

2. **生产环境**:

   - 使用环境变量管理服务（如 AWS Secrets Manager、Azure Key Vault）
   - 定期轮换访问密钥

3. **权限控制**:
   - S3 存储桶应配置适当的访问策略
   - 使用最小权限原则

## 验证配置

可以使用以下 API 端点验证存储配置：

```bash
# 验证存储配置
curl -X POST http://localhost:3000/api/storage/storage/validate \
  -H "Content-Type: application/json" \
  -d '{
    "type": "s3",
    "s3": {
      "bucket": "my-bucket",
      "region": "us-east-1",
      "accessKeyId": "your-key",
      "secretAccessKey": "your-secret"
    }
  }'

# 获取当前存储信息
curl http://localhost:3000/api/storage/storage/info
```

## 文件访问

### 统一下载接口

无论使用哪种存储类型，都通过统一的下载接口访问文件：

```bash
# 统一下载接口（推荐）
GET http://localhost:3000/download/2024/01/01/abc123/example.jpg
```

### 本地存储

当使用本地存储时：

- 下载接口会直接读取本地文件并返回
- 支持内联显示（图片、PDF等）和下载

### S3 存储

当使用 S3 存储时：

- 下载接口会重定向到 S3 URL
- 也可以直接访问 S3 URL（如果存储桶是公开的）

```bash
# 直接访问 S3 URL
GET https://bucket.s3.region.amazonaws.com/2024/01/01/abc123/example.jpg
```

### 文件 URL 生成

```typescript
import { StorageUtils } from '@repo/storage';

const storageUtils = StorageUtils.getInstance();

// 生成下载 URL（推荐方式）
const fileUrl = storageUtils.generateFileUrl('file-id');
// 结果: http://localhost:3000/download/file-id

// 生成完整的公开访问 URL
const publicUrl = storageUtils.generateFileUrl('file-id', 'https://yourdomain.com');
// 结果: https://yourdomain.com/download/file-id

// 生成 S3 直接访问 URL（仅 S3 存储）
try {
	const directUrl = storageUtils.generateDirectUrl('file-id');
	// 结果: https://bucket.s3.region.amazonaws.com/file-id
} catch (error) {
	// 本地存储会抛出错误
}
```