Initial commit: 浼佷笟寰俊 AI 鏈哄櫒浜哄姪鐞?MVP
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
bujie9527
350
docs/github-setup-guide.md
Normal file
350
docs/github-setup-guide.md
Normal file
@@ -0,0 +1,350 @@
|
||||
# GitHub 项目设置与部署 Workflow 配置指南
|
||||
|
||||
## 一、创建 GitHub 仓库
|
||||
|
||||
### 1.1 在 GitHub 上创建新仓库
|
||||
|
||||
1. 登录 GitHub：https://github.com
|
||||
2. 点击右上角 **+** → **New repository**
|
||||
3. 填写仓库信息：
|
||||
- **Repository name**: `wecom-ai-assistant`（或你喜欢的名称）
|
||||
- **Description**: 企业微信 AI 机器人助理
|
||||
- **Visibility**: Private（推荐）或 Public
|
||||
- **不要**勾选 "Initialize this repository with a README"
|
||||
4. 点击 **Create repository**
|
||||
|
||||
### 1.2 推送本地代码到 GitHub
|
||||
|
||||
```powershell
|
||||
# 在项目根目录执行
|
||||
cd D:\企微AI助手
|
||||
|
||||
# 初始化 Git（如果还没有）
|
||||
git init
|
||||
|
||||
# 添加所有文件
|
||||
git add .
|
||||
|
||||
# 提交
|
||||
git commit -m "Initial commit: 企业微信 AI 助手 MVP"
|
||||
|
||||
# 添加远程仓库（替换 YOUR_USERNAME 为你的 GitHub 用户名）
|
||||
git remote add origin https://github.com/YOUR_USERNAME/wecom-ai-assistant.git
|
||||
|
||||
# 推送到 GitHub
|
||||
git branch -M main
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
**注意**：如果遇到认证问题，可能需要配置 GitHub Personal Access Token：
|
||||
- 访问：https://github.com/settings/tokens
|
||||
- 生成新 token（权限：`repo`, `write:packages`, `read:packages`）
|
||||
- 使用 token 作为密码推送
|
||||
|
||||
---
|
||||
|
||||
## 二、配置 GitHub Secrets
|
||||
|
||||
### 2.1 进入仓库设置
|
||||
|
||||
1. 在 GitHub 仓库页面，点击 **Settings**
|
||||
2. 左侧菜单选择 **Secrets and variables** → **Actions**
|
||||
3. 点击 **New repository secret**
|
||||
|
||||
### 2.2 添加必需的 Secrets
|
||||
|
||||
依次添加以下 Secrets：
|
||||
|
||||
| Secret 名称 | 说明 | 示例值 |
|
||||
|------------|------|--------|
|
||||
| `PROD_HOST` | 生产服务器 IP 或域名 | `123.45.67.89` |
|
||||
| `PROD_USER` | SSH 用户名 | `ubuntu` 或 `root` |
|
||||
| `PROD_SSH_KEY` | SSH 私钥（完整内容） | `-----BEGIN OPENSSH PRIVATE KEY-----...` |
|
||||
| `PROD_SSH_PORT` | SSH 端口（可选，默认 22） | `22` |
|
||||
| `PROD_DOMAIN` | 生产域名（用于健康检查） | `api.yourdomain.com` |
|
||||
| `PROD_APP_PATH` | 应用部署路径（可选） | `/opt/wecom-ai-assistant` |
|
||||
|
||||
### 2.3 生成 SSH 密钥对
|
||||
|
||||
在本地生成 SSH 密钥对（如果还没有）：
|
||||
|
||||
```powershell
|
||||
# 生成 SSH 密钥对
|
||||
ssh-keygen -t ed25519 -C "github-actions-deploy" -f $env:USERPROFILE\.ssh\github-actions-deploy
|
||||
|
||||
# 查看公钥（需要添加到服务器）
|
||||
cat $env:USERPROFILE\.ssh\github-actions-deploy.pub
|
||||
|
||||
# 查看私钥（需要添加到 GitHub Secrets）
|
||||
cat $env:USERPROFILE\.ssh\github-actions-deploy
|
||||
```
|
||||
|
||||
**重要**：
|
||||
- **公钥**（`.pub` 文件）需要添加到生产服务器的 `~/.ssh/authorized_keys`
|
||||
- **私钥**（无 `.pub` 后缀）需要添加到 GitHub Secrets 的 `PROD_SSH_KEY`
|
||||
|
||||
### 2.4 将公钥添加到生产服务器
|
||||
|
||||
```bash
|
||||
# 在本地执行（将公钥复制到服务器）
|
||||
type $env:USERPROFILE\.ssh\github-actions-deploy.pub | ssh user@your-server "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
|
||||
|
||||
# 或在服务器上手动添加
|
||||
# 1. SSH 登录服务器
|
||||
# 2. 编辑 ~/.ssh/authorized_keys
|
||||
# 3. 粘贴公钥内容
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、配置 GitHub Packages 权限
|
||||
|
||||
### 3.1 启用 GitHub Packages
|
||||
|
||||
GitHub Actions 默认使用 `GITHUB_TOKEN` 推送镜像到 GHCR，但需要确保仓库有写入权限：
|
||||
|
||||
1. 进入仓库 **Settings** → **Actions** → **General**
|
||||
2. 找到 **Workflow permissions**
|
||||
3. 选择 **Read and write permissions**
|
||||
4. 勾选 **Allow GitHub Actions to create and approve pull requests**（可选）
|
||||
5. 点击 **Save**
|
||||
|
||||
### 3.2 验证镜像推送权限
|
||||
|
||||
首次推送后，检查镜像是否成功推送到 GHCR：
|
||||
- 访问：`https://github.com/YOUR_USERNAME/wecom-ai-assistant/pkgs/container/wecom-ai-backend`
|
||||
|
||||
---
|
||||
|
||||
## 四、首次部署流程
|
||||
|
||||
### 4.1 在生产服务器上准备
|
||||
|
||||
```bash
|
||||
# 1. SSH 登录生产服务器
|
||||
ssh user@your-server
|
||||
|
||||
# 2. 安装 Docker 和 Docker Compose（如果还没有）
|
||||
# Ubuntu/Debian:
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y docker.io docker-compose-plugin
|
||||
|
||||
# CentOS/RHEL:
|
||||
sudo yum install -y docker docker-compose-plugin
|
||||
|
||||
# 3. 启动 Docker
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
|
||||
# 4. 将当前用户添加到 docker 组（避免每次使用 sudo）
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
|
||||
# 5. 创建项目目录
|
||||
sudo mkdir -p /opt/wecom-ai-assistant
|
||||
sudo chown $USER:$USER /opt/wecom-ai-assistant
|
||||
cd /opt/wecom-ai-assistant
|
||||
|
||||
# 6. 克隆项目
|
||||
git clone https://github.com/YOUR_USERNAME/wecom-ai-assistant.git .
|
||||
|
||||
# 7. 创建生产环境变量文件
|
||||
cp .env.prod.example .env.prod
|
||||
nano .env.prod # 填写实际的生产环境变量
|
||||
```
|
||||
|
||||
### 4.2 配置生产环境变量
|
||||
|
||||
编辑 `.env.prod`，填写以下必需变量：
|
||||
|
||||
```bash
|
||||
# WeCom Callback（必须）
|
||||
WECOM_CORP_ID=你的企业ID
|
||||
WECOM_AGENT_ID=你的应用AgentId
|
||||
WECOM_TOKEN=你的Token（必须与企微后台一致）
|
||||
WECOM_ENCODING_AES_KEY=你的43位密钥（必须与企微后台一致）
|
||||
|
||||
# 其他配置...
|
||||
```
|
||||
|
||||
### 4.3 配置 HTTPS（Let's Encrypt）
|
||||
|
||||
```bash
|
||||
# 1. 安装 Certbot
|
||||
sudo apt-get install -y certbot python3-certbot-nginx
|
||||
|
||||
# 2. 先启动 HTTP 服务（用于验证）
|
||||
export IMAGE_TAG=latest
|
||||
export GITHUB_REPOSITORY_OWNER=YOUR_USERNAME
|
||||
docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d backend nginx
|
||||
|
||||
# 3. 申请 SSL 证书
|
||||
export DOMAIN=your-domain.com
|
||||
export EMAIL=your-email@example.com
|
||||
sudo certbot certonly --nginx -d $DOMAIN --email $EMAIL --agree-tos --non-interactive
|
||||
|
||||
# 4. 更新 Nginx 配置（使用实际域名替换 nginx.conf 中的 _）
|
||||
# 编辑 deploy/docker/nginx.conf，将 server_name _ 改为 server_name your-domain.com
|
||||
# 将 SSL 证书路径改为实际路径
|
||||
|
||||
# 5. 重启 Nginx
|
||||
docker-compose -f docker-compose.prod.yml restart nginx
|
||||
```
|
||||
|
||||
### 4.4 触发首次部署
|
||||
|
||||
有两种方式：
|
||||
|
||||
#### 方式 A：通过 GitHub Actions（推荐）
|
||||
|
||||
1. 在 GitHub 仓库页面，点击 **Actions** 标签
|
||||
2. 选择 **Deploy to Production** workflow
|
||||
3. 点击 **Run workflow**
|
||||
4. 选择分支（`main`）和镜像标签（默认 `latest`）
|
||||
5. 点击 **Run workflow**
|
||||
|
||||
#### 方式 B：手动推送代码
|
||||
|
||||
```powershell
|
||||
# 在本地执行
|
||||
git add .
|
||||
git commit -m "Trigger deployment"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
推送后，GitHub Actions 会自动：
|
||||
1. 构建 backend 镜像
|
||||
2. 推送到 GHCR
|
||||
3. SSH 到生产服务器
|
||||
4. 拉取镜像并部署
|
||||
5. 执行健康检查
|
||||
|
||||
---
|
||||
|
||||
## 五、验证部署
|
||||
|
||||
### 5.1 查看 GitHub Actions 日志
|
||||
|
||||
1. 进入 GitHub 仓库 → **Actions**
|
||||
2. 点击最新的 workflow run
|
||||
3. 查看各步骤的执行日志
|
||||
|
||||
### 5.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
|
||||
|
||||
# 健康检查
|
||||
curl https://your-domain.com/api/health
|
||||
```
|
||||
|
||||
### 5.3 配置企业微信回调
|
||||
|
||||
1. 登录企业微信管理后台：https://work.weixin.qq.com
|
||||
2. 进入：应用管理 → 自建应用 → 选择你的应用
|
||||
3. 配置回调：
|
||||
- **接收消息服务器 URL**：`https://your-domain.com/api/wecom/callback`
|
||||
- **Token**：与 `.env.prod` 中的 `WECOM_TOKEN` **完全一致**
|
||||
- **EncodingAESKey**：与 `.env.prod` 中的 `WECOM_ENCODING_AES_KEY` **完全一致**
|
||||
- **消息加解密方式**：**安全模式**
|
||||
4. 点击 **保存**
|
||||
|
||||
---
|
||||
|
||||
## 六、后续更新部署
|
||||
|
||||
### 6.1 自动部署（推送到 main）
|
||||
|
||||
```powershell
|
||||
# 本地修改代码后
|
||||
git add .
|
||||
git commit -m "Update: 描述你的更改"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
推送后，GitHub Actions 会自动触发部署。
|
||||
|
||||
### 6.2 手动触发部署
|
||||
|
||||
1. 进入 GitHub 仓库 → **Actions**
|
||||
2. 选择 **Deploy to Production** workflow
|
||||
3. 点击 **Run workflow**
|
||||
4. 可选择指定镜像标签（用于回滚）
|
||||
|
||||
### 6.3 回滚到指定版本
|
||||
|
||||
```bash
|
||||
# 在 GitHub Actions 中手动触发，指定镜像标签
|
||||
# 例如：main-abc1234（commit SHA 的前缀）
|
||||
|
||||
# 或在服务器上手动回滚
|
||||
cd /opt/wecom-ai-assistant
|
||||
export IMAGE_TAG=main-abc1234
|
||||
docker-compose -f docker-compose.prod.yml --env-file .env.prod pull
|
||||
docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、故障排查
|
||||
|
||||
### 7.1 GitHub Actions 失败
|
||||
|
||||
**常见问题**：
|
||||
|
||||
1. **SSH 连接失败**：
|
||||
- 检查 `PROD_HOST`、`PROD_USER`、`PROD_SSH_KEY` 是否正确
|
||||
- 确认服务器防火墙允许 SSH 端口
|
||||
- 测试 SSH 连接：`ssh -i ~/.ssh/github-actions-deploy user@your-server`
|
||||
|
||||
2. **镜像推送失败**：
|
||||
- 检查 GitHub Packages 权限
|
||||
- 确认 `GITHUB_TOKEN` 有写入权限
|
||||
|
||||
3. **部署失败**：
|
||||
- 查看 GitHub Actions 日志中的错误信息
|
||||
- 检查服务器上的 Docker 和 docker-compose 是否正常
|
||||
|
||||
### 7.2 健康检查失败
|
||||
|
||||
```bash
|
||||
# 检查服务是否运行
|
||||
docker-compose -f docker-compose.prod.yml ps
|
||||
|
||||
# 检查后端日志
|
||||
docker-compose -f docker-compose.prod.yml logs backend
|
||||
|
||||
# 检查 Nginx 日志
|
||||
docker-compose -f docker-compose.prod.yml logs nginx
|
||||
|
||||
# 手动测试健康检查
|
||||
curl -v https://your-domain.com/api/health
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、安全检查清单
|
||||
|
||||
- [ ] GitHub 仓库设置为 Private（如果包含敏感信息）
|
||||
- [ ] 所有敏感信息存储在 `.env.prod`（不提交到 Git）
|
||||
- [ ] SSH 密钥使用强加密（ed25519）
|
||||
- [ ] 生产服务器防火墙配置正确（只开放必要端口）
|
||||
- [ ] SSL 证书配置正确（HTTPS）
|
||||
- [ ] 定期更新 Docker 镜像和依赖
|
||||
|
||||
---
|
||||
|
||||
## 九、参考文档
|
||||
|
||||
- [GitHub Actions 文档](https://docs.github.com/en/actions)
|
||||
- [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
|
||||
- [生产部署文档](./deploy.md)
|
||||
- [企业微信回调配置](./wecom.md)
|
||||
Reference in New Issue
Block a user