Initial commit: 浼佷笟寰俊 AI 鏈哄櫒浜哄姪鐞?MVP

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-05 16:36:32 +08:00
commit 59275ed4dc
126 changed files with 9120 additions and 0 deletions
--- a/docs/github-config-guide.md
+++ b/docs/github-config-guide.md
@@ -0,0 +1,168 @@
+# 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)