mirror of https://github.com/RhenCloud/Cloud-Index.git synced 2025-12-06 23:36:10 +08:00

Files

2025-11-09 14:21:55 +08:00

11 KiB

Raw Blame History

title, createTime, permalink

title	createTime	permalink
GitHub	2025/11/09 00:26:55	/storage/github

GitHub 存储配置指南

使用 GitHub 仓库作为存储后端的详细配置。

概述

GitHub 存储是一个创新的免费存储方案，利用 GitHub 仓库来存储文件：

💚 完全免费（通过 GitHub）
📝 自动版本控制
🔐 私密仓库支持
🌍 全球访问
📦 便于备份和迁移

为什么选择 GitHub 存储？

优势

完全免费 - 无需付费，利用 GitHub 存储空间
自动版本控制 - 所有文件自动保存版本历史
内置权限管理 - 利用 GitHub 的访问权限系统
易于备份 - 通过 Git 可以轻松备份和迁移
开发者友好 - 与 Git 工作流完美集成

限制

仓库大小建议不超过 1GB
文件大小建议不超过 100MB
不适合大规模二进制文件存储

账户设置

1. 创建 GitHub 账户

如果还没有 GitHub 账户，访问 GitHub 创建一个免费账户。

2. 创建仓库

登录 GitHub
点击 "+" 图标 → "New repository"
输入仓库名称（例如 my-storage）
选择 "Private"（私密）或 "Public"（公开）
不要初始化 README
点击 "Create repository"

生成 Personal Access Token

1. 创建 Token

登录 GitHub
进入 Settings → Developer settings → Personal access tokens
点击 "Generate new token"（选择 "Tokens (classic)"）
输入 Token 名称（例如 cloud-index）
选择过期时间（推荐 "90 days" 或 "No expiration"）

2. 设置权限

选择以下权限：

✅ repo - 完整控制私有仓库（包括所有子权限）
✅ workflow - 更新 GitHub Action 工作流
❌ 其他权限保持未勾选

3. 生成并复制 Token

点击 "Generate token"
立即复制 Token（只显示一次）
保存到安全位置

⚠️ 重要: 不要分享你的 Token！

配置环境变量

编辑 .env 文件：

# 存储类型
STORAGE_TYPE=github

# GitHub 账户信息
GITHUB_REPO_OWNER=your-username
GITHUB_REPO_NAME=my-storage
GITHUB_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 可选：使用的分支
GITHUB_BRANCH=main

# 可选：GitHub Raw 内容代理（用于加速国内访问）
GITHUB_RAW_PROXY_URL=https://raw.ghproxy.com

# 可选：预签名 URL 过期时间（秒）
GITHUB_PRESIGN_EXPIRES=3600

配置说明：

GITHUB_REPO_OWNER: 你的 GitHub 用户名
GITHUB_REPO_NAME: 创建的仓库名称
GITHUB_ACCESS_TOKEN: 生成的 Personal Access Token
GITHUB_BRANCH: 默认 main（仓库主分支）
GITHUB_RAW_PROXY_URL: 可选，用于加速访问

国内加速代理配置

由于 GitHub 在国内访问速度较慢，推荐使用代理加速：

初始化仓库

首次使用时，需要初始化仓库（可选但推荐）：

# 克隆空仓库
git clone https://github.com/your-username/my-storage.git
cd my-storage

# 创建初始文件
echo "# 存储仓库" > README.md
git add README.md
git commit -m "Initial commit"
git push -u origin main

# 返回 Cloud Index 目录
cd ../cloud-index

测试连接

方式一：启动应用测试

python app.py

访问 http://localhost:5000，查看是否能正常显示文件列表。

方式二：使用 CLI 测试

# 测试 Token 是否有效
curl -H "Authorization: token ghp_xxx" \
  https://api.github.com/repos/your-username/my-storage

# 应该返回仓库信息

方式三：Python 测试

import requests

token = "ghp_xxx"
repo_owner = "your-username"
repo_name = "my-storage"

headers = {
    "Authorization": f"token {token}",
    "Accept": "application/vnd.github.v3+json"
}

url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/contents"
response = requests.get(url, headers=headers)

if response.status_code == 200:
    print("连接成功！")
    print("仓库文件：")
    for item in response.json():
        print(f"  - {item['name']} ({item['type']})")
else:
    print(f"连接失败！错误代码：{response.status_code}")

管理仓库

通过 Cloud Index 管理

应用提供完整的文件管理功能：

📁 浏览文件和文件夹
⬆️ 上传文件
🗑️ 删除文件
✏️ 重命名文件
📂 创建新文件夹

通过 GitHub Web 管理

访问你的仓库主页
点击 "Add file" → "Upload files"
选择要上传的文件
点击 "Commit changes"

通过 Git 命令行管理

# 克隆仓库
git clone https://github.com/your-username/my-storage.git
cd my-storage

# 添加文件
cp /path/to/file .

# 提交更改
git add .
git commit -m "Add new files"
git push

# 删除文件
git rm filename
git commit -m "Remove file"
git push

# 查看历史
git log

启用版本控制特性

查看文件历史

在 GitHub Web 上打开文件
点击 "History"
查看所有历史版本

恢复旧版本文件

# 查看文件历史
git log -- filename

# 恢复到特定版本
git checkout <commit-hash> -- filename

# 提交恢复
git commit -m "Restore filename to previous version"
git push

标记发布版本

# 创建标签
git tag -a v1.0 -m "Release version 1.0"
git push origin v1.0

# 查看所有标签
git tag -l

生成公开访问 URL

Raw 文件 URL

文件会自动通过 Raw GitHub URL 访问：

# 官方 URL（国外快）
https://raw.githubusercontent.com/your-username/my-storage/main/path/to/file

# 使用代理加速（国内快）
https://raw.ghproxy.com/https://raw.githubusercontent.com/your-username/my-storage/main/path/to/file

在应用中生成

在 Cloud Index 应用中：

点击文件
选择 "复制链接"
分享链接给他人

最佳实践

1. 安全性

✅ 使用 Personal Access Token 而非用户密码
✅ 定期轮换 Token
✅ 为 Token 设置过期时间
✅ 不要分享 Token
✅ 使用私密仓库存储敏感信息
✅ 不要在公开仓库存储个人数据

2. 性能优化

✅ 使用国内代理加速（如 ghproxy）
✅ 定期清理不需要的文件
✅ 合理组织文件结构
✅ 使用分支管理大型项目

3. 仓库管理

✅ 保持仓库大小 < 1GB
✅ 每个文件 < 100MB
✅ 定期清理历史版本
✅ 使用 .gitignore 排除不需要的文件

4. 备份

✅ 定期备份重要文件
✅ 使用 Git 本地备份
✅ 定期推送到其他服务（如 GitLab）

高级配置

使用 GitHub Actions 自动化

可以创建自动化工作流（可选）：

# .github/workflows/backup.yml
name: Daily Backup

on:
  schedule:
    - cron: '0 0 * * *'

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Backup
        run: |
          # 你的备份脚本
          echo "Backup completed"

使用分支隔离环境

为不同环境使用不同分支：

# 创建开发分支
git checkout -b develop
git push -u origin develop

# 创建生产分支
git checkout -b production
git push -u origin production

文件大小限制处理

如果遇到文件过大（> 100MB）：

使用 Git LFS

# 安装 Git LFS
git lfs install

# 追踪大文件
git lfs track "*.psd"
git add .gitattributes

# 提交文件
git add large-file.psd
git commit -m "Add large file"
git push

分割文件

# 分割大文件
split -b 50M large-file.zip large-file.zip.part_

# 上传分割后的文件
git add large-file.zip.part_*
git commit -m "Add split files"
git push

# 恢复时合并
cat large-file.zip.part_* > large-file.zip

常见问题

Q: 如何更新 Token？

生成新 Token
更新 .env 文件中的 GITHUB_ACCESS_TOKEN
重启应用

Q: Token 过期了怎么办？

进入 GitHub Settings
重新生成 Token
更新应用配置

Q: 可以在组织中使用吗？

A: 可以，配置仓库的所有者为组织名即可：

GITHUB_REPO_OWNER=my-organization

Q: 仓库大小有限制吗？

A: GitHub 建议仓库不超过 1GB。如果超过：

清理不需要的历史版本
使用 Git LFS
分割仓库

Q: 可以在多个应用中使用同一仓库吗？

A: 可以，但需要注意并发冲突。建议：

为每个环境创建不同的仓库
使用分支隔离
定期同步

故障排除

连接失败

检查：

Token 是否正确
仓库名称是否正确
用户名是否正确
网络连接是否正常
Token 是否过期

Token 无效

解决方案：

重新生成 Token
确保有 repo 权限
检查 Token 是否过期

文件无法访问

检查：

仓库是否存在
文件是否已提交
是否使用了正确的分支
代理 URL 是否正确

上传缓慢

优化方案：

配置国内代理
分割大文件
检查网络连接
考虑使用其他存储后端

与其他存储的对比

特性	GitHub	R2	S3
成本	免费	$0.36/百万请求	$2-3/GB
文件大小限制	100MB	无限	5TB
仓库大小限制	1GB	无限	无限
版本控制	✅	❌	⚠️
适合大文件	❌	✅	✅

成本示例

月均使用情况：

指标	数值	费用
存储	500MB	免费
请求	10K	免费
流量	1GB	免费
总计	-	完全免费 ✅

获取帮助

下一步

🚀 快速开始 - 开始使用应用
📖 存储后端对比 - 对比其他服务
💾 Cloudflare R2 配置 - R2 配置指南

11 KiB Raw Blame History Unescape Escape