存储配置
本地磁盘与 S3 兼容存储的接入方法，包含阿里云 OSS、腾讯云 COS、Cloudflare R2、MinIO。
Kite 支持多个存储配置同时存在，并通过「默认存储」标志决定新文件的落盘位置。管理员可在「系统设置 → 存储」中随时添加、切换或删除存储。
存储驱动
| Driver | 说明 | 典型场景 |
|---|---|---|
local | 本地文件系统 | 个人实例、内网、冷备份 |
s3 | AWS S3 v2 兼容协议 | 阿里云 OSS、腾讯云 COS、Cloudflare R2、MinIO |
本地存储
Kite 首次启动会自动创建一个本地存储，路径为 <dataDir>/uploads。通常无需手动配置。
若需手动新增，在后台填写：
| 字段 | 说明 |
|---|---|
| 名称 | 展示用名称，如「本机 SSD」 |
| Driver | local |
| Base Path | 文件存储根目录（绝对路径） |
| Base URL | 可选，CDN 或反向代理 URL 前缀 |
本地存储的文件通过 GET /uploads/* 直接由 Gin 提供静态服务。
S3 兼容存储
通用字段
| 字段 | 说明 |
|---|---|
| Endpoint | 服务端点域名 |
| Region | 区域，如 cn-hangzhou / auto |
| Bucket | 存储桶名称 |
| Access Key ID | 访问密钥 ID |
| Secret Access Key | 访问密钥 Secret |
| Base URL | 可选，CDN 域名（如 https://cdn.example.com） |
| Force Path Style | MinIO 需启用 |
阿里云 OSS
driver: s3
endpoint: oss-cn-hangzhou.aliyuncs.com
region: cn-hangzhou
bucket: my-kite-bucket
access_key_id: LTAI...
secret_access_key: ...
base_url: https://cdn.example.com # 可选：绑定 CDN 后填入
force_path_style: false
腾讯云 COS
driver: s3
endpoint: cos.ap-guangzhou.myqcloud.com
region: ap-guangzhou
bucket: my-kite-1300000000
access_key_id: AKID...
secret_access_key: ...
force_path_style: false
说明
腾讯云 COS 的 bucket 名称需包含 AppID 后缀（形如 name-1300000000）。
Cloudflare R2
driver: s3
endpoint: https://<account_id>.r2.cloudflarestorage.com
region: auto
bucket: my-kite-bucket
access_key_id: ...
secret_access_key: ...
base_url: https://files.your-domain.com # 绑定的 R2 自定义域名
force_path_style: false
建议
R2 的 Region 必须填 auto，并且建议在 R2 控制台绑定自定义域名后把它填入 Base URL，即可获得免费的全球 CDN 分发。
MinIO
driver: s3
endpoint: https://minio.your-domain.com
region: us-east-1
bucket: kite
access_key_id: minioadmin
secret_access_key: minioadmin
force_path_style: true # MinIO 必须启用
多存储与默认存储
- 任一时间至多一个存储被标记为「默认」。
- 新文件总是写入默认存储。
- 管理员切换默认存储不会迁移历史文件 —— 每条文件记录都保留自己的
storage_config_id，访问时走对应后端。 - 删除存储前务必确认没有文件引用它，否则这些文件将无法访问。
连通性测试
后台「存储 → 测试连接」按钮会触发一次 PUT → GET → DELETE 的完整往返，验证：
- 签名算法是否正确
- Bucket 是否存在且可写
- IAM/ACL 权限是否足够
测试对象使用特殊前缀 .kite-healthcheck/，执行完毕立即清除。
存储路径设计
无论本地还是 S3，Kite 都使用 path_pattern 生成 key。默认 {year}/{month}/{md5_8}/{uuid}.{ext} 示例：
2026/04/a1b2c3d4/01234567-89ab-cdef-0123-456789abcdef.jpg
这种结构让任意 bucket 在单月上传量达到百万级时仍有良好的前缀分布。