wecom-ai-assistant/docs/github-setup-guide.md

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

# 在项目根目录执行
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 密钥对（如果还没有）：

# 生成 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 将公钥添加到生产服务器

# 在本地执行（将公钥复制到服务器）
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 在生产服务器上准备

# 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，填写以下必需变量：

# WeCom Callback（必须）
WECOM_CORP_ID=你的企业ID
WECOM_AGENT_ID=你的应用AgentId
WECOM_TOKEN=你的Token（必须与企微后台一致）
WECOM_ENCODING_AES_KEY=你的43位密钥（必须与企微后台一致）

# 其他配置...

4.3 配置 HTTPS（Let's Encrypt）

# 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：手动推送代码

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

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

# 本地修改代码后
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 回滚到指定版本

# 在 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 健康检查失败

# 检查服务是否运行
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 文档
• GitHub Container Registry
• 生产部署文档
• 企业微信回调配置