Add documentation and scripts
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
bujie9527
270
docs/git-clone-guide.md
Normal file
270
docs/git-clone-guide.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# Git 克隆和使用指南
|
||||
|
||||
## 项目信息
|
||||
|
||||
- **GitHub 仓库地址**：https://github.com/bujie9527/wecom-ai-assistant
|
||||
- **默认分支**：`main`
|
||||
- **项目类型**：Monorepo（backend + admin + deploy + docs）
|
||||
|
||||
## 克隆项目
|
||||
|
||||
### 方式一：HTTPS 克隆（推荐）
|
||||
|
||||
```bash
|
||||
# 克隆项目
|
||||
git clone https://github.com/bujie9527/wecom-ai-assistant.git
|
||||
|
||||
# 进入项目目录
|
||||
cd wecom-ai-assistant
|
||||
```
|
||||
|
||||
**如果需要认证**（推送代码时）：
|
||||
```bash
|
||||
# 使用 Personal Access Token 作为密码
|
||||
git clone https://github.com/bujie9527/wecom-ai-assistant.git
|
||||
# 用户名：bujie9527
|
||||
# 密码：你的 GitHub Personal Access Token
|
||||
```
|
||||
|
||||
### 方式二：SSH 克隆（需要配置 SSH 密钥）
|
||||
|
||||
```bash
|
||||
# 克隆项目
|
||||
git clone git@github.com:bujie9527/wecom-ai-assistant.git
|
||||
|
||||
# 进入项目目录
|
||||
cd wecom-ai-assistant
|
||||
```
|
||||
|
||||
**配置 SSH 密钥**：
|
||||
1. 生成 SSH 密钥：`ssh-keygen -t ed25519 -C "your_email@example.com"`
|
||||
2. 将公钥添加到 GitHub：https://github.com/settings/keys
|
||||
3. 测试连接：`ssh -T git@github.com`
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
wecom-ai-assistant/
|
||||
├── backend/ # Python FastAPI 后端
|
||||
├── admin/ # Next.js 管理后台
|
||||
├── deploy/ # 部署配置和脚本
|
||||
├── docs/ # 项目文档
|
||||
├── scripts/ # 自动化脚本
|
||||
├── docker-compose.yml # 本地开发配置
|
||||
└── README.md # 项目说明
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 克隆项目
|
||||
|
||||
```bash
|
||||
git clone https://github.com/bujie9527/wecom-ai-assistant.git
|
||||
cd wecom-ai-assistant
|
||||
```
|
||||
|
||||
### 2. 配置环境变量
|
||||
|
||||
```bash
|
||||
# 复制环境变量模板
|
||||
cp .env.example .env
|
||||
|
||||
# Windows PowerShell
|
||||
Copy-Item .env.example .env
|
||||
|
||||
# 编辑 .env 文件，填写必需配置
|
||||
```
|
||||
|
||||
### 3. 启动项目
|
||||
|
||||
```bash
|
||||
# 使用 Docker Compose 一键启动
|
||||
docker compose up -d
|
||||
|
||||
# 查看服务状态
|
||||
docker compose ps
|
||||
|
||||
# 查看日志
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
### 4. 访问服务
|
||||
|
||||
- **管理后台**：http://localhost
|
||||
- **后端 API**：http://localhost:8000/api/health
|
||||
- **PostgreSQL**：localhost:5432
|
||||
|
||||
## 常用 Git 操作
|
||||
|
||||
### 拉取最新代码
|
||||
|
||||
```bash
|
||||
# 拉取远程最新代码
|
||||
git pull origin main
|
||||
|
||||
# 或指定远程分支
|
||||
git pull origin main --rebase
|
||||
```
|
||||
|
||||
### 推送代码
|
||||
|
||||
```bash
|
||||
# 添加更改
|
||||
git add .
|
||||
|
||||
# 提交更改
|
||||
git commit -m "描述你的更改"
|
||||
|
||||
# 推送到远程
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### 查看分支
|
||||
|
||||
```bash
|
||||
# 查看所有分支
|
||||
git branch -a
|
||||
|
||||
# 查看远程分支
|
||||
git branch -r
|
||||
|
||||
# 切换分支
|
||||
git checkout branch-name
|
||||
```
|
||||
|
||||
### 查看提交历史
|
||||
|
||||
```bash
|
||||
# 查看提交历史
|
||||
git log --oneline
|
||||
|
||||
# 查看最近 10 条提交
|
||||
git log --oneline -10
|
||||
|
||||
# 查看图形化历史
|
||||
git log --graph --oneline --all
|
||||
```
|
||||
|
||||
## 分支管理
|
||||
|
||||
### 创建新分支
|
||||
|
||||
```bash
|
||||
# 从 main 分支创建新分支
|
||||
git checkout -b feature/new-feature
|
||||
|
||||
# 推送新分支到远程
|
||||
git push -u origin feature/new-feature
|
||||
```
|
||||
|
||||
### 合并分支
|
||||
|
||||
```bash
|
||||
# 切换到 main 分支
|
||||
git checkout main
|
||||
|
||||
# 拉取最新代码
|
||||
git pull origin main
|
||||
|
||||
# 合并功能分支
|
||||
git merge feature/new-feature
|
||||
|
||||
# 推送合并后的代码
|
||||
git push origin main
|
||||
```
|
||||
|
||||
## 推送代码到 GitHub
|
||||
|
||||
### 使用 HTTPS（需要 Token）
|
||||
|
||||
```bash
|
||||
# 方式一：在 URL 中嵌入 token（不推荐，但方便）
|
||||
git remote set-url origin https://bujie9527:YOUR_TOKEN@github.com/bujie9527/wecom-ai-assistant.git
|
||||
git push origin main
|
||||
|
||||
# 方式二：使用 Git Credential Manager（推荐）
|
||||
# Git 会提示输入用户名和密码
|
||||
# 用户名：bujie9527
|
||||
# 密码：你的 GitHub Personal Access Token
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### 使用 SSH（推荐，更安全）
|
||||
|
||||
```bash
|
||||
# 配置 SSH 密钥后
|
||||
git remote set-url origin git@github.com:bujie9527/wecom-ai-assistant.git
|
||||
git push origin main
|
||||
```
|
||||
|
||||
## 配置 Git 用户信息
|
||||
|
||||
```bash
|
||||
# 设置用户名
|
||||
git config user.name "bujie9527"
|
||||
|
||||
# 设置邮箱
|
||||
git config user.email "your_email@example.com"
|
||||
|
||||
# 查看配置
|
||||
git config --list
|
||||
```
|
||||
|
||||
## 忽略文件
|
||||
|
||||
项目已配置 `.gitignore`，以下文件不会被提交：
|
||||
|
||||
- `.env`、`.env.prod`（环境变量文件）
|
||||
- `.github-config`（GitHub 配置文件，包含敏感 token）
|
||||
- `node_modules/`（Node.js 依赖）
|
||||
- `__pycache__/`（Python 缓存）
|
||||
- `.next/`（Next.js 构建文件）
|
||||
- `logs/`（日志文件）
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 推送时提示认证失败
|
||||
|
||||
**问题**：`fatal: Authentication failed`
|
||||
|
||||
**解决方案**：
|
||||
1. 检查 GitHub Personal Access Token 是否有效
|
||||
2. 确认 token 权限包含 `repo`
|
||||
3. 更新远程 URL：`git remote set-url origin https://bujie9527:YOUR_TOKEN@github.com/bujie9527/wecom-ai-assistant.git`
|
||||
|
||||
### 拉取时提示冲突
|
||||
|
||||
**问题**：`error: Your local changes would be overwritten by merge`
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 保存本地更改
|
||||
git stash
|
||||
|
||||
# 拉取最新代码
|
||||
git pull origin main
|
||||
|
||||
# 恢复本地更改
|
||||
git stash pop
|
||||
```
|
||||
|
||||
### 无法连接到 GitHub
|
||||
|
||||
**问题**：`fatal: unable to access 'https://github.com/...'`
|
||||
|
||||
**解决方案**：
|
||||
1. 检查网络连接
|
||||
2. 检查防火墙设置
|
||||
3. 如果在中国大陆，可能需要配置代理或使用镜像
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [GitHub 快速开始指南](./github-quickstart.md)
|
||||
- [GitHub 配置文件指南](./github-config-guide.md)
|
||||
- [项目 README](../README.md)
|
||||
|
||||
## 获取帮助
|
||||
|
||||
- **Git 官方文档**：https://git-scm.com/doc
|
||||
- **GitHub 帮助**：https://docs.github.com
|
||||
- **项目 Issues**：https://github.com/bujie9527/wecom-ai-assistant/issues
|
||||
Reference in New Issue
Block a user