wecom-ai-assistant/docs/github-quickstart.md

GitHub Actions 快速开始指南

5 分钟快速部署

步骤 1：创建 GitHub 仓库（2 分钟）

1. 访问 https://github.com/new
2. 填写仓库名称：wecom-ai-assistant
3. 选择 Private（推荐）
4. 点击 Create repository

步骤 2：推送代码到 GitHub（1 分钟）

在项目根目录执行：

# 初始化 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 密钥

# 在本地生成 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

将公钥添加到服务器：

# 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 分钟）

# 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）：

# WeCom 回调配置（必须）
WECOM_CORP_ID=你的企业ID
WECOM_AGENT_ID=你的应用AgentId
WECOM_TOKEN=你的Token（43位随机字符串）
WECOM_ENCODING_AES_KEY=你的43位密钥

# 其他配置...

步骤 6：触发首次部署（1 分钟）

方式 A：推送代码自动触发

# 在本地执行
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. 验证服务状态：

   # 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. 健康检查：

   curl https://your-domain.com/api/health
   

---

后续更新部署

自动部署（推送到 main）

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