# 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)