GITHUB-TOKEN-GUIDE.md

GitHub Token 权限设置完整指南

第一步：访问 GitHub Token 设置页面

1. 登录 GitHub
2. 点击右上角头像 -> Settings
3. 左侧菜单选择 "Developer settings"
4. 选择 "Personal access tokens" -> "Tokens (classic)"
5. 点击 "Generate new token" -> "Generate new token (classic)"

第二步：配置 Token 基本信息

Token 名称和过期时间

Token Name: VvvebJs-WebEditor (建议使用描述性名称)
Expiration: 
  - 推荐：90 days (3个月)
  - 安全考虑：30 days (1个月)
  - 便利性：No expiration (永不过期，但不推荐)

Note 字段示例

VvvebJs Website Editor - Full repo access for saving pages
Created: 2024-01-XX
Purpose: File management for visual website builder

第三步：权限选择（重要！）

必需权限 ✅

✅ repo (Full control of private repositories)
   ├── ✅ repo:status (Access commit status)
   ├── ✅ repo_deployment (Access deployment status)
   ├── ✅ public_repo (Access public repositories)
   └── ✅ repo:invite (Access repository invitations)

可选但推荐的权限

✅ workflow (Update GitHub Action workflows)
✅ write:packages (Upload packages to GitHub Package Registry)
✅ read:packages (Download packages from GitHub Package Registry)

不需要的权限 ❌

❌ admin:repo_hook (不需要 webhook 管理)
❌ admin:org (不需要组织管理)
❌ admin:public_key (不需要公钥管理)
❌ admin:org_hook (不需要组织 webhook)
❌ gist (不需要 Gist 权限)
❌ notifications (不需要通知权限)
❌ user (不需要用户信息权限)
❌ delete_repo (不需要删除仓库权限)

权限详细说明

repo 权限包含的子权限：

权限名称	说明	VvvebJs 是否需要
repo:status	读取仓库提交状态	✅ 需要
repo_deployment	读取部署状态	✅ 需要
public_repo	访问公开仓库	✅ 需要
repo:invite	管理仓库邀请	✅ 需要
security_events	读取安全事件	❌ 不需要

为什么需要完整的 repo 权限？

1. 读取文件 - 检查文件是否存在，获取文件 SHA
2. 创建文件 - 保存新的网页文件
3. 更新文件 - 修改现有网页内容
4. 分支操作 - 检查分支是否存在
5. 提交操作 - 创建提交记录

第四步：Token 安全最佳实践

1. Token 存储安全

# ✅ 正确方式：环境变量
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

# ❌ 错误方式：硬编码在文件中
$token = "ghp_xxxxxxxxxxxxxxxxxxxx";  // 不要这样做！

2. Token 权限最小化

# 只为特定仓库创建 Token
# 而不是给所有仓库权限

3. 定期轮换 Token

建议周期：
- 生产环境：30-90 天
- 开发环境：90-180 天
- 测试环境：可以更长

第五步：验证 Token 权限

使用 curl 测试

# 测试 Token 基本权限
curl -H "Authorization: token YOUR_TOKEN" \
     -H "User-Agent: VvvebJs/1.0" \
     https://api.github.com/user

# 测试仓库访问权限
curl -H "Authorization: token YOUR_TOKEN" \
     -H "User-Agent: VvvebJs/1.0" \
     https://api.github.com/repos/YOUR_USERNAME/YOUR_REPO

# 测试文件创建权限
curl -X PUT \
     -H "Authorization: token YOUR_TOKEN" \
     -H "User-Agent: VvvebJs/1.0" \
     -H "Content-Type: application/json" \
     -d '{"message":"test","content":"VGVzdCBmaWxl"}' \
     https://api.github.com/repos/YOUR_USERNAME/YOUR_REPO/contents/test.txt

第六步：在 VvvebJs 中配置

Hugging Face Space 环境变量

# 在 Settings -> Variables and secrets 中添加：
GITHUB_TOKEN=ghp_your_40_character_token_here
GITHUB_OWNER=your_github_username
GITHUB_REPO=your_repository_name
GITHUB_BRANCH=main
GITHUB_PATH=pages/
STORAGE_TYPE=github

本地开发环境

# .env 文件
GITHUB_TOKEN=ghp_your_40_character_token_here
GITHUB_OWNER=your_github_username
GITHUB_REPO=your_repository_name

常见权限问题排查

问题 1: 403 Forbidden

原因：Token 权限不足
解决：确保勾选了 repo 权限

问题 2: 401 Unauthorized

原因：Token 无效或过期
解决：重新生成 Token

问题 3: 404 Not Found

原因：仓库不存在或 Token 无访问权限
解决：检查仓库名称和权限设置

问题 4: 422 Unprocessable Entity

原因：请求格式错误或文件内容问题
解决：检查 API 请求格式和文件编码

Token 权限检查清单

在配置完成后，请确认：

• Token 有 repo 完整权限
• Token 未过期
• 目标仓库存在且可访问
• 环境变量配置正确
• 可以通过 API 访问仓库
• 可以创建和修改文件
• User-Agent 头部已设置

安全提醒

1. 永远不要在代码中硬编码 Token
2. 定期检查 Token 使用情况
3. 及时删除不使用的 Token
4. 使用最小权限原则
5. 在 GitHub Settings -> Personal access tokens 中监控 Token 活动

相关链接

• GitHub Token 设置页面
• GitHub API 文档
• Token 权限说明