# 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)