docs: add LFS COS storage migration guide with DNS bucket lookup fix

Documents how to migrate Gitea LFS from local disk to Tencent Cloud COS,
including the required MINIO_BUCKET_LOOKUP_TYPE=dns setting for COS compatibility.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/lfs-cos-storage.md

@@ -0,0 +1,179 @@
+# Gitea LFS 对接腾讯云 COS
+
+本文档适用于已通过本项目 Docker Compose 部署 Gitea，希望将 LFS 存储从本地磁盘迁移到腾讯云 COS 对象存储的场景。
+
+腾讯云轻量应用服务器（Lighthouse）可以正常使用，COS 通过 HTTPS 公网端点访问，无需额外网络配置。
+
+---
+
+## 一、腾讯云侧准备
+
+### 1.1 创建 COS Bucket
+
+进入 [COS 控制台](https://console.cloud.tencent.com/cos) → 存储桶列表 → 创建存储桶：
+
+| 选项 | 建议值 |
+|------|--------|
+| 地域 | 与服务器相同地域（降低延迟） |
+| 访问权限 | **私有读写** |
+| 版本控制 | 关闭（LFS 对象不需要） |
+
+创建后记录完整的 Bucket 名称，格式为 `<name>-<appid>`，例如 `gitea-lfs-1234567890`。
+
+### 1.2 创建 CAM 子账号并授权
+
+进入 [CAM 控制台](https://console.cloud.tencent.com/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 配置：
+
+```bash
+GITEA__lfs__START_SERVER=true
+GITEA__lfs__PATH=/data/git/lfs
+```
+
+替换为：
+
+```bash
+# 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 条目：
+
+```yaml
+- GITEA__lfs__START_SERVER=${GITEA__lfs__START_SERVER}
+- GITEA__lfs__PATH=${GITEA__lfs__PATH}
+```
+
+替换为：
+
+```yaml
+- 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 的模板，需同步更新（不填真实密钥）：
+
+```bash
+# 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](https://cloud.tencent.com/document/product/436/63143)：
+
+```bash
+# 安装 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 对象丢失。
+
+---
+
+## 四、重启并验证
+
+```bash
+# 重启 Gitea 服务（Compose 会自动检测 .env 变更并重建容器）
+docker compose up -d gitea
+
+# 查看启动日志，确认无报错
+docker compose logs -f gitea
+```
+
+验证 COS 是否生效：推送一个包含 LFS 文件的提交，然后到 COS 控制台的 `lfs/` 路径下确认对象是否出现。
+
+```bash
+# 本地测试推送
+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 实际所在地域一致。