图片上传配置

在DirEasy中，对于图片上传(头像、项目图片、项目logo)，我们默认使用uploadthing作为存储服务提供商。对于小型项目它是免费的(每月2G)。

Uploadthing 配置

如果你想继续使用uploadthing作为存储提供商，集成非常简单。

创建账户并获取API密钥

在uploadthing上创建账户并获取你的API密钥。

获取你的终端域名

在仪表板上传一张图片，然后找到该图片，点击更多按钮，复制文件URL，格式为：https://******.ufs.sh/f/******，将******.ufs.sh替换为下一步中NEXT_PUBLIC_UPLOADTHING_URL的值

更新环境变量

在你的.env文件中设置环境变量：

.env

NEXT_PUBLIC_UPLOADTHING_URL=你的uploadthing_url(不带协议头)
UPLOADTHING_TOKEN=你的uploadthing_token

如果你对AWS S3有所了解，那么你有更低成本的选项，S3或Cloudflare R2是不错的选择。

Cloudflare R2 配置 [可选]

设置Cloudflare R2实现快速、经济高效的文件上传

为什么选择Cloudflare R2?

🚀 全球性能：利用Cloudflare的边缘网络实现全球快速上传
💰 经济高效：比S3便宜10倍且无出口费用
🔗 S3兼容：可与现有S3工具和库一起使用
🌍 内置CDN：通过Cloudflare网络自动分发内容

1. 创建R2存储桶

前往Cloudflare仪表板
在侧边栏点击**"R2对象存储"**
点击**"创建存储桶"**
选择一个唯一的存储桶名称(如my-app-uploads)
选择首选位置(自动选择以获得最佳全球性能)
点击**"创建存储桶"**

2. 配置公共访问(可选)

进入你的存储桶设置
点击**"设置"**标签页
在**"公共访问"下，点击"允许访问"**

3. 自定义域名设置

在你的自定义域名中添加一个CNAME记录，如： upload.yourdomain.com

4. 生成API令牌

前往**"管理R2 API令牌"**
点击**"创建API令牌"**
设置权限：
- Object:Read ✅
- Object:Write ✅
- Bucket:Read ✅
选择**"指定存储桶"**并选择你的存储桶
点击**"创建API令牌"**
保存你的访问密钥ID和秘密访问密钥

5. 配置CORS(如果使用自定义域名)

完整CORS指南：有关详细的CORS配置、测试和故障排除，请参阅CORS & ACL配置指南。

在你的R2存储桶设置中，添加以下CORS策略：

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedOrigins": ["http://localhost:3000", "https://yourdomain.com"],
    "ExposeHeaders": ["ETag", "Content-Length"]
  }
]

6. 设置环境变量

添加到你的.env文件：

.env

# Cloudflare R2配置
NEXT_PUBLIC_ENABLE_UPLOADTHING=false
CLOUDFLARE_ACCOUNT_ID=你的cloudflare账户id
R2_ACCESS_KEY_ID=你的r2访问密钥id
R2_SECRET_ACCESS_KEY=你的r2秘密访问密钥
R2_BUCKET=你的r2存储桶名称
 
# 可选：公共文件的自定义域名
CLOUDFLARE_R2_PUBLIC_URL=https://uploads.yourdomain.com

🔒 安全最佳实践

使用限定范围的API令牌 - 只授予特定存储桶的权限
启用自定义域名 - 比r2.dev子域名更安全
设置WAF规则 - 通过Cloudflare仪表板防止滥用
监控使用情况 - 为意外使用设置账单提醒

🆘 常见问题

CORS错误？ → 检查你的域名是否在AllowedOrigins中并验证自定义域名设置。有关详细的CORS配置，请参阅CORS & ACL配置指南。
访问被拒绝？ → 验证API令牌是否有Object:Read和Object:Write权限
上传速度慢？ → 确保你使用了带有账户ID的正确终端URL
自定义域名不工作？ → 验证CNAME记录和存储桶公共访问设置

💰 成本比较

提供商	存储成本	出口费用	请求成本
Cloudflare R2	$0.015/GB	免费 🎉	$0.36/百万次
AWS S3	$0.023/GB	$0.09/GB	$0.40/百万次
节省	节省35%	节省100%	节省10%

AWS S3 配置 [可选]

在5分钟内设置AWS S3用于生产环境文件上传

完成本指南后，你将拥有：

✅ 一个为网页上传配置的安全S3存储桶
✅ 具有最小必要权限的IAM用户
✅ 为你的域名配置的CORS
✅ 准备用于生产的环境变量
✅ 启用的成本优化设置

创建AWS账户和S3存储桶

如果你没有AWS账户，免费注册 - 你可以获得12个月5GB的免费S3存储。

打开S3控制台：前往S3控制台
创建存储桶：点击"创建存储桶"
配置基本设置：

存储桶命名：使用唯一、描述性名称。存储桶名称在所有AWS账户中是全局的且之后不能更改。

阻止公共访问：保持所有"阻止公共访问"设置启用(这是安全的 - 我们将使用预签名URL)
启用版本控制：推荐用于数据保护
创建存储桶：点击"创建存储桶"

为网页访问配置CORS

完整CORS指南：有关详细的CORS配置、测试和故障排除，请参阅CORS & ACL配置指南。

你的网页应用需要权限才能直接上传文件到S3。

打开你的存储桶：点击你新创建的存储桶
前往权限标签页：点击"权限"
编辑CORS配置：滚动到"跨源资源共享(CORS)"并点击"编辑"
添加CORS规则：

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
    "AllowedOrigins": [
      "http://localhost:3000",
      "https://yourdomain.com"
    ],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3000
  }
]

保存更改：点击"保存更改"

安全注意：只添加你信任的来源。生产环境中绝不要使用通配符(*) - 它们允许任何网站上传到你的存储桶。

创建具有最小权限的IAM用户

为你的应用创建一个专用用户，只赋予它需要的权限。

打开IAM控制台：前往IAM控制台
创建用户：
- 点击"用户" → "创建用户"
- 用户名: your-app-s3-user
- 只选择"编程访问"
创建自定义策略：
- 点击"直接附加策略"
- 点击"创建策略"
- 使用JSON编辑器并粘贴：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::your-app-uploads-prod/*"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": "arn:aws:s3:::your-app-uploads-prod"
    }
  ]
}

命名策略：YourApp-S3-Upload-Policy
附加到用户：返回用户创建并附加你的新策略
创建用户：完成用户创建

替换存储桶名称：确保在策略JSON中将your-app-uploads-prod替换为你的实际存储桶名称。

获取访问密钥

你的应用需要这些凭证来生成预签名URL。

选择你的用户：在IAM用户中，点击你新创建的用户
安全凭证标签页：点击"安全凭证"
创建访问密钥：
- 点击"创建访问密钥"
- 选择"在AWS外部运行的应用程序"
- 点击"下一步"
复制凭证：
- 访问密钥ID：复制这个值
- 秘密访问密钥：复制这个值(你只能看到它一次!)

安全警告：切勿将这些密钥提交到版本控制系统或公开分享。使用环境变量或安全的密钥管理服务。

配置环境变量

将你的AWS凭证添加到.env文件。

开发环境生产环境

.env

# .env
NEXT_PUBLIC_ENABLE_UPLOADTHING=false
AWS_ACCESS_KEY_ID=你的访问密钥id
AWS_SECRET_ACCESS_KEY=你的秘密访问密钥
AWS_REGION=你的区域
AWS_S3_BUCKET=your-app-uploads-prod

💰 成本优化

使用这些优化技巧保持你的AWS账单低廉：

存储类别

# 标准：$0.023每GB/月 - 用于频繁访问的文件
# 标准-IA：$0.0125每GB/月 - 用于不频繁访问的文件
# Glacier：$0.004每GB/月 - 用于归档(检索需要数小时)

设置自动转换以节省资金：

前往你的存储桶 → 管理 → 生命周期规则
创建规则：
- 30天后转换到Standard-IA
- 90天后转换到Glacier
- 1天后删除未完成的分段上传

请求优化

使用CloudFront：全局缓存文件以减少S3请求
批量操作：尽可能将多个操作分组
监控使用情况：为意外成本设置账单提醒

🔒 安全最佳实践

访问控制

// 示例：用户特定的上传路径
{
  "prefix": "users/${user.id}/*",
  "maxFileSize": "10MB",
      "types": ["image/jpeg", "image/png"]
}

监控

启用CloudTrail：跟踪所有S3 API调用
设置提醒：监控异常访问模式
定期审计：每季度审查IAM权限

备份策略

# 关键数据的跨区域复制
源存储桶: us-east-1
副本存储桶: us-west-2
复制: 实时

图片上传配置

目录