271 lines
5.3 KiB
Markdown
271 lines
5.3 KiB
Markdown
# 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
|