gitea/docs/lfs-cos-storage.md

Gitea LFS 对接腾讯云 COS

本文档适用于已通过本项目 Docker Compose 部署 Gitea，希望将 LFS 存储从本地磁盘迁移到腾讯云 COS 对象存储的场景。

腾讯云轻量应用服务器（Lighthouse）可以正常使用，COS 通过 HTTPS 公网端点访问，无需额外网络配置。

---

一、腾讯云侧准备

1.1 创建 COS Bucket

进入 COS 控制台 → 存储桶列表 → 创建存储桶：

选项	建议值
地域	与服务器相同地域（降低延迟）
访问权限	私有读写
版本控制	关闭（LFS 对象不需要）

创建后记录完整的 Bucket 名称，格式为 <name>-<appid>，例如 gitea-lfs-1234567890。

1.2 创建 CAM 子账号并授权

进入 CAM 控制台 → 用户管理 → 新建用户：

• 用户类型选编程访问（只需 API 密钥，无需登录控制台）
• 直接关联策略：搜索并勾选 QcloudCOSDataFullControl

如需最小权限，自定义策略只需包含： GetObject PutObject DeleteObject HeadObject ListBucket

创建完成后保存 SecretId 和 SecretKey，页面关闭后无法再次查看。

1.3 地域 ID 参考

地域	ID
广州	ap-guangzhou
上海	ap-shanghai
北京	ap-beijing
深圳	ap-shenzhen
成都	ap-chengdu
中国香港	ap-hongkong
新加坡	ap-singapore

---

二、修改项目配置

2.1 修改 .env

将原来的本地 LFS 配置：

GITEA__lfs__START_SERVER=true
GITEA__lfs__PATH=/data/git/lfs

替换为：

# Git LFS 配置 - 腾讯云 COS
GITEA__lfs__START_SERVER=true
GITEA__lfs__STORAGE_TYPE=minio
GITEA__lfs__MINIO_ENDPOINT=cos.ap-guangzhou.myqcloud.com   # 改为你的地域
GITEA__lfs__MINIO_ACCESS_KEY_ID=AKIDxxxxxxxxxx              # CAM SecretId
GITEA__lfs__MINIO_SECRET_ACCESS_KEY=xxxxxxxxxx              # CAM SecretKey
GITEA__lfs__MINIO_BUCKET=gitea-lfs-1234567890               # Bucket 完整名称
GITEA__lfs__MINIO_LOCATION=ap-guangzhou                     # 改为你的地域
GITEA__lfs__MINIO_USE_SSL=true
GITEA__lfs__MINIO_BASE_PATH=lfs/
GITEA__lfs__MINIO_BUCKET_LOOKUP_TYPE=dns

GITEA__lfs__PATH 仅在本地存储模式下生效，切换到 minio 后删除该行即可。

2.2 修改 docker-compose.yml

在 gitea 服务的 environment 下，将原来的 LFS 条目：

- GITEA__lfs__START_SERVER=${GITEA__lfs__START_SERVER}
- GITEA__lfs__PATH=${GITEA__lfs__PATH}

替换为：

- GITEA__lfs__START_SERVER=${GITEA__lfs__START_SERVER}
- GITEA__lfs__STORAGE_TYPE=${GITEA__lfs__STORAGE_TYPE}
- GITEA__lfs__MINIO_ENDPOINT=${GITEA__lfs__MINIO_ENDPOINT}
- GITEA__lfs__MINIO_ACCESS_KEY_ID=${GITEA__lfs__MINIO_ACCESS_KEY_ID}
- GITEA__lfs__MINIO_SECRET_ACCESS_KEY=${GITEA__lfs__MINIO_SECRET_ACCESS_KEY}
- GITEA__lfs__MINIO_BUCKET=${GITEA__lfs__MINIO_BUCKET}
- GITEA__lfs__MINIO_LOCATION=${GITEA__lfs__MINIO_LOCATION}
- GITEA__lfs__MINIO_USE_SSL=${GITEA__lfs__MINIO_USE_SSL}
- GITEA__lfs__MINIO_BASE_PATH=${GITEA__lfs__MINIO_BASE_PATH}
- GITEA__lfs__MINIO_BUCKET_LOOKUP_TYPE=${GITEA__lfs__MINIO_BUCKET_LOOKUP_TYPE}

2.3 同步更新 .env.example

.env.example 是提交到 git 的模板，需同步更新（不填真实密钥）：

# Git LFS 配置 - 腾讯云 COS
GITEA__lfs__START_SERVER=true
GITEA__lfs__STORAGE_TYPE=minio
GITEA__lfs__MINIO_ENDPOINT=cos.ap-guangzhou.myqcloud.com
GITEA__lfs__MINIO_ACCESS_KEY_ID=AKIDxxxxxxxxxx
GITEA__lfs__MINIO_SECRET_ACCESS_KEY=xxxxxxxxxx
GITEA__lfs__MINIO_BUCKET=your-bucket-name
GITEA__lfs__MINIO_LOCATION=ap-guangzhou
GITEA__lfs__MINIO_USE_SSL=true
GITEA__lfs__MINIO_BASE_PATH=lfs/
GITEA__lfs__MINIO_BUCKET_LOOKUP_TYPE=dns

---

三、迁移已有 LFS 数据（可选）

如果切换前本地 data/git/lfs/ 已有文件，需手动同步到 COS，否则历史 LFS 对象会返回 404。

使用腾讯云官方 CLI 工具 coscli：

# 安装 coscli（macOS 示例）
curl -o coscli https://github.com/tencentyun/coscli/releases/latest/download/coscli-darwin

chmod +x coscli

# 配置认证（交互式）
./coscli config init

# 上传本地 LFS 目录到 COS（同步模式，不重复上传）
./coscli sync ./data/git/lfs/ cos://gitea-lfs-1234567890/lfs/ --recursive

同步完成后再重启 Gitea，避免服务重启期间出现 LFS 对象丢失。

---

四、重启并验证

# 重启 Gitea 服务（Compose 会自动检测 .env 变更并重建容器）
docker compose up -d gitea

# 查看启动日志，确认无报错
docker compose logs -f gitea

验证 COS 是否生效：推送一个包含 LFS 文件的提交，然后到 COS 控制台的 lfs/ 路径下确认对象是否出现。

# 本地测试推送
git lfs track "*.bin"
git add .gitattributes largefile.bin
git commit -m "test: lfs upload to cos"
git push

---

五、常见问题

Q：Bucket 名称填什么格式？
填完整名称（含 AppId），例如 gitea-lfs-1234567890。不含 .cos.ap-xxx.myqcloud.com 后缀。

Q：轻量服务器能用 COS 内网端点吗？
轻量服务器使用独立的轻量网络，不在标准 VPC 内，默认无法访问 COS 内网端点。直接使用公网端点 cos.<region>.myqcloud.com 即可。若已通过云联网（CCN）打通网络，可将端点改为 cos-internal.<region>.myqcloud.com 以节省公网流量费用。

Q：推送 LFS 报 403 Forbidden？
检查 CAM 子账号的策略是否包含目标 Bucket 的操作权限，以及 SecretId / SecretKey 是否填写正确。

Q：推送 LFS 报 SignatureDoesNotMatch？
确认 MINIO_LOCATION 与 Bucket 实际所在地域一致。