# GitHub 配置完成指南

## ✅ 当前状态

- ✅ Git 仓库已配置
- ✅ 代码已推送到 GitHub
- ✅ SSH 密钥已生成
- ⏳ 需要配置 GitHub Secrets
- ⏳ 需要添加 workflow 文件

## 📋 配置步骤

### 步骤 1：创建包含 workflow 权限的新 Token

1. **访问 Token 创建页面**：
   https://github.com/settings/tokens/new

2. **填写信息**：
   - Token 名称：`wecom-ai-assistant-full`
   - 过期时间：90 天（或 No expiration）

3. **选择权限**（必须包含）：
   - ✅ **repo**（完整仓库访问）
   - ✅ **workflow**（工作流权限）← **必需**
   - ✅ **write:packages**（推送 Docker 镜像）
   - ✅ **read:packages**（拉取镜像）

4. **生成并复制 Token**：
   - 点击 **Generate token**
   - **立即复制 token**（只显示一次）

5. **更新本地配置**：
   ```powershell
   # 使用新 token 更新配置
   .\scripts\update-github-token.ps1 -NewToken "你的新token"
   ```

### 步骤 2：配置 GitHub Secrets

1. **访问 Secrets 页面**：
   https://github.com/bujie9527/wecom-ai-assistant/settings/secrets/actions

2. **添加以下 Secrets**：

   #### PROD_HOST
   - Name: `PROD_HOST`
   - Value: 你的服务器 IP（例如：`123.45.67.89`）

   #### PROD_USER
   - Name: `PROD_USER`
   - Value: SSH 用户名（通常是 `root` 或 `ubuntu`）

   #### PROD_SSH_KEY
   - Name: `PROD_SSH_KEY`
   - Value: 私钥完整内容（查看 `github-actions-deploy.key` 文件）

   #### PROD_DOMAIN
   - Name: `PROD_DOMAIN`
   - Value: 你的生产域名（例如：`api.yourdomain.com`）

   #### PROD_SSH_PORT（可选）
   - Name: `PROD_SSH_PORT`
   - Value: `22`（默认）

   #### PROD_APP_PATH（可选）
   - Name: `PROD_APP_PATH`
   - Value: `/opt/wecom-ai-assistant`（默认）

3. **配置 Workflow 权限**：
   - 进入：Settings → Actions → General
   - 找到 **Workflow permissions**
   - 选择 **Read and write permissions**
   - 点击 **Save**

### 步骤 3：将 SSH 公钥添加到生产服务器

```bash
# SSH 登录服务器
ssh user@your-server

# 添加公钥
mkdir -p ~/.ssh
echo "你的公钥内容" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
chmod 700 ~/.ssh

# 测试连接（从本地）
ssh -i github-actions-deploy.key user@your-server
```

**公钥内容**：查看 `github-actions-deploy.pub` 文件

### 步骤 4：添加 Workflow 文件并推送

```powershell
# 添加 workflow 文件
git add .github/workflows/

# 提交
git commit -m "Add GitHub Actions workflows"

# 推送（使用新 token）
git push origin main
```

## 🔍 验证配置

### 1. 检查 Secrets

访问：https://github.com/bujie9527/wecom-ai-assistant/settings/secrets/actions

确认以下 Secrets 已添加：
- ✅ PROD_HOST
- ✅ PROD_USER
- ✅ PROD_SSH_KEY
- ✅ PROD_DOMAIN

### 2. 测试 GitHub Actions

1. 推送代码到 `main` 分支
2. 访问：https://github.com/bujie9527/wecom-ai-assistant/actions
3. 查看 workflow 是否自动运行

### 3. 验证 SSH 连接

```powershell
# 从本地测试 SSH 连接
ssh -i github-actions-deploy.key user@your-server
```

## 📚 相关文档

- [GitHub Secrets 配置指南](./docs/github-secrets-setup.md)
- [GitHub Token 权限指南](./docs/github-token-permissions.md)
- [GitHub 快速开始](./docs/github-quickstart.md)

## 🆘 故障排查

### 问题：推送 workflow 文件时提示权限不足

**解决方案**：
1. 确认新 Token 包含 `workflow` 权限
2. 使用 `.\scripts\update-github-token.ps1` 更新 token
3. 重新推送

### 问题：GitHub Actions 部署失败

**检查项**：
1. Secrets 是否正确配置
2. SSH 密钥是否正确添加到服务器
3. 服务器防火墙是否开放 SSH 端口
4. 服务器上是否安装了 Docker 和 docker-compose

## ✨ 完成后的效果

配置完成后，每次推送代码到 `main` 分支时：

1. ✅ GitHub Actions 自动构建 backend 镜像
2. ✅ 推送到 GHCR（GitHub Container Registry）
3. ✅ SSH 到生产服务器自动部署
4. ✅ 执行健康检查验证部署结果

## 📝 快速命令参考

```powershell
# 更新 Token
.\scripts\update-github-token.ps1 -NewToken "你的新token"

# 生成 SSH 密钥
.\scripts\setup-github-secrets.ps1

# 添加并推送 workflow
git add .github/workflows/
git commit -m "Add GitHub Actions workflows"
git push origin main
```