Initial commit: 浼佷笟寰俊 AI 鏈哄櫒浜哄姪鐞?MVP
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
bujie9527
235
docs/github-quickstart.md
Normal file
235
docs/github-quickstart.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# GitHub Actions 快速开始指南
|
||||
|
||||
## 5 分钟快速部署
|
||||
|
||||
### 步骤 1：创建 GitHub 仓库（2 分钟）
|
||||
|
||||
1. 访问 https://github.com/new
|
||||
2. 填写仓库名称：`wecom-ai-assistant`
|
||||
3. 选择 **Private**（推荐）
|
||||
4. 点击 **Create repository**
|
||||
|
||||
### 步骤 2：推送代码到 GitHub（1 分钟）
|
||||
|
||||
在项目根目录执行：
|
||||
|
||||
```powershell
|
||||
# 初始化 Git（如果还没有）
|
||||
git init
|
||||
|
||||
# 添加所有文件
|
||||
git add .
|
||||
|
||||
# 提交
|
||||
git commit -m "Initial commit: 企业微信 AI 助手"
|
||||
|
||||
# 添加远程仓库（替换 YOUR_USERNAME）
|
||||
git remote add origin https://github.com/YOUR_USERNAME/wecom-ai-assistant.git
|
||||
|
||||
# 推送到 GitHub
|
||||
git branch -M main
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
**如果遇到认证问题**：
|
||||
- 访问 https://github.com/settings/tokens
|
||||
- 生成新 token（权限：`repo`, `write:packages`）
|
||||
- 使用 token 作为密码推送
|
||||
|
||||
### 步骤 3：配置 GitHub Secrets（2 分钟）
|
||||
|
||||
1. 进入仓库 → **Settings** → **Secrets and variables** → **Actions**
|
||||
2. 点击 **New repository secret**，依次添加：
|
||||
|
||||
#### 必需 Secrets
|
||||
|
||||
| Secret 名称 | 说明 | 如何获取 |
|
||||
|------------|------|---------|
|
||||
| `PROD_HOST` | 服务器 IP | 你的云服务器公网 IP |
|
||||
| `PROD_USER` | SSH 用户名 | 通常是 `root` 或 `ubuntu` |
|
||||
| `PROD_SSH_KEY` | SSH 私钥 | 见下方"生成 SSH 密钥" |
|
||||
| `PROD_DOMAIN` | 生产域名 | 例如：`api.yourdomain.com` |
|
||||
|
||||
#### 可选 Secrets
|
||||
|
||||
| Secret 名称 | 说明 | 默认值 |
|
||||
|------------|------|--------|
|
||||
| `PROD_SSH_PORT` | SSH 端口 | `22` |
|
||||
| `PROD_APP_PATH` | 应用路径 | `/opt/wecom-ai-assistant` |
|
||||
| `GHCR_TOKEN` | GitHub Packages Token | 使用默认 `GITHUB_TOKEN` |
|
||||
|
||||
#### 生成 SSH 密钥
|
||||
|
||||
```powershell
|
||||
# 在本地生成 SSH 密钥对
|
||||
ssh-keygen -t ed25519 -C "github-actions" -f $env:USERPROFILE\.ssh\github-actions
|
||||
|
||||
# 查看私钥（复制到 GitHub Secrets 的 PROD_SSH_KEY）
|
||||
cat $env:USERPROFILE\.ssh\github-actions
|
||||
|
||||
# 查看公钥（需要添加到服务器）
|
||||
cat $env:USERPROFILE\.ssh\github-actions.pub
|
||||
```
|
||||
|
||||
**将公钥添加到服务器**：
|
||||
|
||||
```bash
|
||||
# SSH 登录服务器
|
||||
ssh user@your-server
|
||||
|
||||
# 添加公钥到 authorized_keys
|
||||
mkdir -p ~/.ssh
|
||||
echo "你的公钥内容" >> ~/.ssh/authorized_keys
|
||||
chmod 600 ~/.ssh/authorized_keys
|
||||
chmod 700 ~/.ssh
|
||||
```
|
||||
|
||||
### 步骤 4：配置仓库权限（30 秒）
|
||||
|
||||
1. 进入仓库 → **Settings** → **Actions** → **General**
|
||||
2. 找到 **Workflow permissions**
|
||||
3. 选择 **Read and write permissions**
|
||||
4. 点击 **Save**
|
||||
|
||||
### 步骤 5：在生产服务器上准备（5 分钟）
|
||||
|
||||
```bash
|
||||
# 1. SSH 登录服务器
|
||||
ssh user@your-server
|
||||
|
||||
# 2. 安装 Docker（Ubuntu/Debian）
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y docker.io docker-compose-plugin
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
|
||||
# 3. 创建项目目录
|
||||
sudo mkdir -p /opt/wecom-ai-assistant
|
||||
sudo chown $USER:$USER /opt/wecom-ai-assistant
|
||||
cd /opt/wecom-ai-assistant
|
||||
|
||||
# 4. 克隆项目
|
||||
git clone https://github.com/YOUR_USERNAME/wecom-ai-assistant.git .
|
||||
|
||||
# 5. 创建生产环境变量文件
|
||||
cp .env.prod.example .env.prod
|
||||
nano .env.prod # 填写实际配置
|
||||
```
|
||||
|
||||
**必需的环境变量**（`.env.prod`）：
|
||||
|
||||
```bash
|
||||
# WeCom 回调配置（必须）
|
||||
WECOM_CORP_ID=你的企业ID
|
||||
WECOM_AGENT_ID=你的应用AgentId
|
||||
WECOM_TOKEN=你的Token（43位随机字符串）
|
||||
WECOM_ENCODING_AES_KEY=你的43位密钥
|
||||
|
||||
# 其他配置...
|
||||
```
|
||||
|
||||
### 步骤 6：触发首次部署（1 分钟）
|
||||
|
||||
#### 方式 A：推送代码自动触发
|
||||
|
||||
```powershell
|
||||
# 在本地执行
|
||||
git add .
|
||||
git commit -m "Trigger deployment"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
#### 方式 B：手动触发
|
||||
|
||||
1. 进入 GitHub 仓库 → **Actions**
|
||||
2. 选择 **Deploy to Production** workflow
|
||||
3. 点击 **Run workflow**
|
||||
4. 选择分支 `main`，点击 **Run workflow**
|
||||
|
||||
### 步骤 7：验证部署（1 分钟）
|
||||
|
||||
1. **查看 GitHub Actions 日志**：
|
||||
- 进入 **Actions** → 点击最新的 workflow run
|
||||
- 查看各步骤执行情况
|
||||
|
||||
2. **验证服务状态**：
|
||||
```bash
|
||||
# SSH 到服务器
|
||||
ssh user@your-server
|
||||
cd /opt/wecom-ai-assistant
|
||||
|
||||
# 查看服务状态
|
||||
docker compose -f docker-compose.prod.yml ps
|
||||
|
||||
# 查看日志
|
||||
docker compose -f docker-compose.prod.yml logs -f backend
|
||||
```
|
||||
|
||||
3. **健康检查**：
|
||||
```bash
|
||||
curl https://your-domain.com/api/health
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 后续更新部署
|
||||
|
||||
### 自动部署（推送到 main）
|
||||
|
||||
```powershell
|
||||
git add .
|
||||
git commit -m "Update: 描述你的更改"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
推送后，GitHub Actions 会自动：
|
||||
1. 构建 backend 镜像
|
||||
2. 推送到 GHCR
|
||||
3. SSH 到服务器部署
|
||||
4. 执行健康检查
|
||||
|
||||
### 手动触发部署
|
||||
|
||||
1. 进入 **Actions** → **Deploy to Production**
|
||||
2. 点击 **Run workflow**
|
||||
3. 可选择指定镜像标签（用于回滚）
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: SSH 连接失败？
|
||||
|
||||
**A**: 检查以下项：
|
||||
- `PROD_HOST`、`PROD_USER`、`PROD_SSH_KEY` 是否正确
|
||||
- 服务器防火墙是否开放 SSH 端口
|
||||
- SSH 公钥是否已添加到服务器的 `~/.ssh/authorized_keys`
|
||||
|
||||
### Q: 镜像推送失败？
|
||||
|
||||
**A**:
|
||||
- 确认仓库权限已设置为 "Read and write"
|
||||
- 检查 GitHub Packages 是否启用
|
||||
|
||||
### Q: 部署后服务无法访问？
|
||||
|
||||
**A**:
|
||||
- 检查 `.env.prod` 配置是否正确
|
||||
- 查看服务日志：`docker compose -f docker-compose.prod.yml logs backend`
|
||||
- 确认域名 DNS 已正确解析到服务器 IP
|
||||
|
||||
### Q: 如何回滚到之前的版本？
|
||||
|
||||
**A**:
|
||||
1. 在 GitHub Actions 中手动触发
|
||||
2. 指定镜像标签（例如：`main-abc1234`，commit SHA 的前缀）
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
- 配置 HTTPS：参见 `docs/deploy.md` 中的 Let's Encrypt 部分
|
||||
- 配置企业微信回调：参见 `docs/wecom.md`
|
||||
- 详细部署文档：参见 `docs/github-setup-guide.md`
|
||||
Reference in New Issue
Block a user