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