238 lines
4.7 KiB
Markdown
238 lines
4.7 KiB
Markdown
# 环境变量配置指南
|
||
|
||
本文档详细说明了项目中所有环境变量的配置方法和用途。
|
||
|
||
## 存储配置 (@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) {
|
||
// 本地存储会抛出错误
|
||
}
|
||
```
|