169 lines
4.4 KiB
Markdown
169 lines
4.4 KiB
Markdown
# GitHub 配置文件使用指南
|
||
|
||
## 概述
|
||
|
||
项目已包含 GitHub 配置文件（`.github-config`），用于自动化 GitHub 操作。配置文件包含你的 GitHub 用户名、token 和仓库信息。
|
||
|
||
## 配置文件说明
|
||
|
||
### 文件位置
|
||
|
||
- **`.github-config`**：实际配置文件（包含敏感信息，**不提交到 Git**）
|
||
- **`.github-config.example`**：配置模板（可提交到 Git）
|
||
|
||
### 配置项说明
|
||
|
||
```bash
|
||
# GitHub 用户名/组织
|
||
GITHUB_USERNAME=bujie9527
|
||
|
||
# GitHub Personal Access Token
|
||
# ⚠️ 警告：此 token 具有仓库访问权限，请妥善保管！
|
||
GITHUB_TOKEN=your_token_here
|
||
|
||
# GitHub 仓库名称
|
||
GITHUB_REPO_NAME=wecom-ai-assistant
|
||
|
||
# GitHub 仓库完整 URL
|
||
GITHUB_REPO_URL=https://github.com/bujie9527/wecom-ai-assistant.git
|
||
|
||
# 默认分支
|
||
GITHUB_DEFAULT_BRANCH=main
|
||
|
||
# Container Registry 配置
|
||
GHCR_REGISTRY=ghcr.io
|
||
GHCR_IMAGE_PREFIX=bujie9527
|
||
|
||
# 镜像名称
|
||
BACKEND_IMAGE_NAME=wecom-ai-backend
|
||
ADMIN_IMAGE_NAME=wecom-ai-admin
|
||
```
|
||
|
||
## 快速使用
|
||
|
||
### 1. 初始化 GitHub 仓库
|
||
|
||
```powershell
|
||
# 使用配置文件自动设置 Git 远程仓库
|
||
.\scripts\setup-github-from-config.ps1
|
||
```
|
||
|
||
此脚本会：
|
||
- 检查并初始化 Git 仓库
|
||
- 配置 Git 用户信息（如果需要）
|
||
- 设置远程仓库地址
|
||
- 配置 Git 凭据（使用 token）
|
||
- 创建初始提交（如果还没有）
|
||
|
||
### 2. 推送代码到 GitHub
|
||
|
||
```powershell
|
||
# 快速推送（使用默认提交信息）
|
||
.\scripts\push-to-github.ps1
|
||
|
||
# 自定义提交信息
|
||
.\scripts\push-to-github.ps1 -CommitMessage "Fix: 修复登录问题"
|
||
|
||
# 强制推送（危险操作）
|
||
.\scripts\push-to-github.ps1 -Force
|
||
```
|
||
|
||
### 3. 手动操作
|
||
|
||
如果不想使用脚本，也可以手动操作：
|
||
|
||
```powershell
|
||
# 添加远程仓库
|
||
git remote add origin https://github.com/bujie9527/wecom-ai-assistant.git
|
||
|
||
# 使用 token 推送（将 token 嵌入 URL）
|
||
git remote set-url origin https://bujie9527:YOUR_TOKEN@github.com/bujie9527/wecom-ai-assistant.git
|
||
|
||
# 推送代码
|
||
git push -u origin main
|
||
```
|
||
|
||
## 安全注意事项
|
||
|
||
### ⚠️ 重要安全提示
|
||
|
||
1. **`.github-config` 文件已添加到 `.gitignore`**，不会被提交到 Git
|
||
2. **Token 安全**：
|
||
- 不要将 token 分享给他人
|
||
- 不要在公开场合展示 token
|
||
- 如果 token 泄露，立即在 GitHub 上撤销并重新生成
|
||
3. **Token 权限**：
|
||
- 当前 token 需要以下权限：
|
||
- `repo`：访问和修改仓库
|
||
- `write:packages`：推送 Docker 镜像到 GHCR
|
||
- `read:packages`：从 GHCR 拉取镜像
|
||
|
||
### 撤销和重新生成 Token
|
||
|
||
如果 token 泄露或需要更新：
|
||
|
||
1. 访问：https://github.com/settings/tokens
|
||
2. 找到对应的 token，点击 **Revoke**（撤销）
|
||
3. 点击 **Generate new token**（生成新 token）
|
||
4. 选择权限：`repo`, `write:packages`, `read:packages`
|
||
5. 复制新 token 并更新 `.github-config` 文件
|
||
|
||
## 配置文件的使用场景
|
||
|
||
### 1. 本地开发
|
||
|
||
配置文件主要用于：
|
||
- 自动配置 Git 远程仓库
|
||
- 快速推送代码
|
||
- 本地脚本自动化操作
|
||
|
||
### 2. GitHub Actions
|
||
|
||
GitHub Actions workflow 使用 GitHub Secrets，而不是配置文件：
|
||
- 配置文件中的 token 用于**本地推送**
|
||
- GitHub Actions 使用 `GITHUB_TOKEN`（自动提供）或 `GHCR_TOKEN`（在 Secrets 中配置）
|
||
|
||
### 3. 生产部署
|
||
|
||
生产服务器上：
|
||
- 使用 SSH 密钥（不是 token）进行部署
|
||
- 通过 GitHub Actions 自动部署
|
||
- 不需要在生产服务器上配置 token
|
||
|
||
## 常见问题
|
||
|
||
### Q: 配置文件在哪里？
|
||
|
||
**A**: 配置文件位于项目根目录：
|
||
- `.github-config`：实际配置文件（本地使用，不提交）
|
||
- `.github-config.example`：模板文件（可提交）
|
||
|
||
### Q: 如何更新配置？
|
||
|
||
**A**: 直接编辑 `.github-config` 文件，修改对应的值即可。
|
||
|
||
### Q: Token 在哪里获取？
|
||
|
||
**A**:
|
||
1. 访问：https://github.com/settings/tokens
|
||
2. 点击 **Generate new token (classic)**
|
||
3. 选择权限：`repo`, `write:packages`, `read:packages`
|
||
4. 复制 token 并更新配置文件
|
||
|
||
### Q: 推送时提示认证失败？
|
||
|
||
**A**:
|
||
1. 检查 token 是否正确
|
||
2. 确认 token 权限包含 `repo`
|
||
3. 尝试重新运行 `.\scripts\setup-github-from-config.ps1`
|
||
|
||
### Q: 配置文件可以提交到 Git 吗？
|
||
|
||
**A**: **不可以**。`.github-config` 包含敏感 token，已添加到 `.gitignore`。只有 `.github-config.example`（模板）可以提交。
|
||
|
||
## 相关文档
|
||
|
||
- [GitHub 快速开始指南](./github-quickstart.md)
|
||
- [GitHub 完整设置指南](./github-setup-guide.md)
|
||
- [生产部署文档](./deploy.md)
|