fenghuo/docs/ENVIRONMENT.md

环境变量配置指南

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

存储配置 (@repo/storage)

基础配置

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

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

本地存储配置

当 STORAGE_TYPE=local 时需要配置：

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

S3 存储配置

当 STORAGE_TYPE=s3 时需要配置：

# 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

配置示例

开发环境 - 本地存储

# .env.development
STORAGE_TYPE=local
UPLOAD_DIR=./uploads

生产环境 - AWS S3

# .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

MinIO 本地开发

# .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

# .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

# .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

其他配置

数据库配置

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

Redis 配置

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

应用配置

# 应用端口
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 端点验证存储配置：

# 验证存储配置
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

文件访问

统一下载接口

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

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

本地存储

当使用本地存储时：

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

S3 存储

当使用 S3 存储时：

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

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

文件 URL 生成

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) {
	// 本地存储会抛出错误
}