wecom-ai-assistant/GITHUB_SETUP_COMPLETE.md

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. 更新本地配置：

   # 使用新 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 公钥添加到生产服务器

# 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 文件并推送

# 添加 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 连接

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

📚 相关文档

• GitHub Secrets 配置指南
• GitHub Token 权限指南
• GitHub 快速开始

🆘 故障排查

问题：推送 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. ✅ 执行健康检查验证部署结果

📝 快速命令参考

# 更新 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