Add GitHub Secrets setup guide and scripts
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
bujie9527
176
GITHUB_SETUP_COMPLETE.md
Normal file
176
GITHUB_SETUP_COMPLETE.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# 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
|
||||
```
|
||||
163
docs/github-secrets-setup.md
Normal file
163
docs/github-secrets-setup.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# GitHub Secrets 配置指南
|
||||
|
||||
## 概述
|
||||
|
||||
GitHub Secrets 用于存储敏感信息（如服务器 IP、SSH 密钥等），供 GitHub Actions 自动部署使用。
|
||||
|
||||
## 配置步骤
|
||||
|
||||
### 步骤 1：进入 Secrets 配置页面
|
||||
|
||||
1. 访问你的仓库：https://github.com/bujie9527/wecom-ai-assistant
|
||||
2. 点击 **Settings**（设置）
|
||||
3. 左侧菜单选择 **Secrets and variables** → **Actions**
|
||||
4. 点击 **New repository secret**
|
||||
|
||||
### 步骤 2：添加必需的 Secrets
|
||||
|
||||
依次添加以下 Secrets：
|
||||
|
||||
#### 1. PROD_HOST（生产服务器 IP）
|
||||
|
||||
- **Name**: `PROD_HOST`
|
||||
- **Secret**: 你的云服务器公网 IP（例如：`123.45.67.89`）
|
||||
- **说明**: 用于 SSH 连接到生产服务器
|
||||
|
||||
#### 2. PROD_USER（SSH 用户名）
|
||||
|
||||
- **Name**: `PROD_USER`
|
||||
- **Secret**: SSH 用户名（通常是 `root` 或 `ubuntu`）
|
||||
- **说明**: 用于 SSH 登录的用户名
|
||||
|
||||
#### 3. PROD_SSH_KEY（SSH 私钥）
|
||||
|
||||
- **Name**: `PROD_SSH_KEY`
|
||||
- **Secret**: SSH 私钥的完整内容（包括 `-----BEGIN OPENSSH PRIVATE KEY-----` 和 `-----END OPENSSH PRIVATE KEY-----`）
|
||||
- **说明**: 用于 GitHub Actions 通过 SSH 连接到服务器
|
||||
|
||||
**如何获取 SSH 私钥**：
|
||||
```powershell
|
||||
# 如果已有 SSH 密钥
|
||||
cat $env:USERPROFILE\.ssh\id_rsa
|
||||
# 或
|
||||
cat $env:USERPROFILE\.ssh\id_ed25519
|
||||
|
||||
# 如果没有，生成新的 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，将**公钥**（`.pub` 文件）添加到生产服务器的 `~/.ssh/authorized_keys`
|
||||
|
||||
#### 4. PROD_DOMAIN（生产域名）
|
||||
|
||||
- **Name**: `PROD_DOMAIN`
|
||||
- **Secret**: 你的生产域名（例如：`api.yourdomain.com`）
|
||||
- **说明**: 用于健康检查和部署验证
|
||||
|
||||
#### 5. PROD_SSH_PORT（可选）
|
||||
|
||||
- **Name**: `PROD_SSH_PORT`
|
||||
- **Secret**: SSH 端口（默认：`22`）
|
||||
- **说明**: 如果使用非标准 SSH 端口，需要配置
|
||||
|
||||
#### 6. PROD_APP_PATH（可选）
|
||||
|
||||
- **Name**: `PROD_APP_PATH`
|
||||
- **Secret**: 应用部署路径（默认：`/opt/wecom-ai-assistant`）
|
||||
- **说明**: 如果部署路径不同，需要配置
|
||||
|
||||
### 步骤 3：配置 Workflow 权限
|
||||
|
||||
1. 在 **Settings** → **Actions** → **General**
|
||||
2. 找到 **Workflow permissions**
|
||||
3. 选择 **Read and write permissions**
|
||||
4. 点击 **Save**
|
||||
|
||||
## 验证配置
|
||||
|
||||
### 检查 Secrets 是否已添加
|
||||
|
||||
1. 进入：https://github.com/bujie9527/wecom-ai-assistant/settings/secrets/actions
|
||||
2. 确认以下 Secrets 已添加：
|
||||
- ✅ PROD_HOST
|
||||
- ✅ PROD_USER
|
||||
- ✅ PROD_SSH_KEY
|
||||
- ✅ PROD_DOMAIN
|
||||
- （可选）PROD_SSH_PORT
|
||||
- （可选）PROD_APP_PATH
|
||||
|
||||
### 测试 GitHub Actions
|
||||
|
||||
1. 推送代码到 `main` 分支
|
||||
2. 进入：https://github.com/bujie9527/wecom-ai-assistant/actions
|
||||
3. 查看 workflow 是否自动运行
|
||||
|
||||
## 生成 SSH 密钥对（如果还没有）
|
||||
|
||||
### 在本地生成
|
||||
|
||||
```powershell
|
||||
# 生成 SSH 密钥对
|
||||
ssh-keygen -t ed25519 -C "github-actions-deploy" -f $env:USERPROFILE\.ssh\github-actions-deploy
|
||||
|
||||
# 查看私钥（添加到 GitHub Secrets）
|
||||
cat $env:USERPROFILE\.ssh\github-actions-deploy
|
||||
|
||||
# 查看公钥（添加到服务器）
|
||||
cat $env:USERPROFILE\.ssh\github-actions-deploy.pub
|
||||
```
|
||||
|
||||
### 将公钥添加到生产服务器
|
||||
|
||||
```bash
|
||||
# SSH 登录服务器
|
||||
ssh user@your-server
|
||||
|
||||
# 添加公钥到 authorized_keys
|
||||
mkdir -p ~/.ssh
|
||||
echo "你的公钥内容" >> ~/.ssh/authorized_keys
|
||||
chmod 600 ~/.ssh/authorized_keys
|
||||
chmod 700 ~/.ssh
|
||||
|
||||
# 测试 SSH 连接（从本地）
|
||||
ssh -i ~/.ssh/github-actions-deploy user@your-server
|
||||
```
|
||||
|
||||
## 安全建议
|
||||
|
||||
1. **SSH 密钥安全**：
|
||||
- 私钥只存储在 GitHub Secrets 中
|
||||
- 公钥添加到服务器的 `authorized_keys`
|
||||
- 不要将私钥提交到 Git
|
||||
|
||||
2. **定期轮换**：
|
||||
- 定期更新 SSH 密钥和 Token
|
||||
- 如果密钥泄露，立即撤销并重新生成
|
||||
|
||||
3. **最小权限原则**：
|
||||
- 只授予必要的权限
|
||||
- 使用专用的部署用户（而不是 root）
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 问题：GitHub Actions 部署失败
|
||||
|
||||
**检查项**：
|
||||
1. Secrets 是否正确配置
|
||||
2. SSH 密钥是否正确添加到服务器
|
||||
3. 服务器防火墙是否开放 SSH 端口
|
||||
4. 服务器上是否安装了 Docker 和 docker-compose
|
||||
|
||||
### 问题：SSH 连接失败
|
||||
|
||||
**解决方案**：
|
||||
1. 测试 SSH 连接：`ssh -i ~/.ssh/github-actions-deploy user@your-server`
|
||||
2. 检查服务器日志：`tail -f /var/log/auth.log`
|
||||
3. 确认公钥格式正确（一行，无换行）
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [GitHub Actions 文档](https://docs.github.com/en/actions)
|
||||
- [GitHub Secrets 文档](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
|
||||
- [项目部署文档](./deploy.md)
|
||||
126
scripts/setup-github-secrets.ps1
Normal file
126
scripts/setup-github-secrets.ps1
Normal file
@@ -0,0 +1,126 @@
|
||||
# GitHub Secrets 配置辅助脚本
|
||||
# 用途：帮助生成 SSH 密钥并准备配置 GitHub Secrets
|
||||
|
||||
Write-Host "=== GitHub Secrets 配置辅助工具 ===" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
|
||||
# 检查是否已有 SSH 密钥
|
||||
$sshKeyPath = "$env:USERPROFILE\.ssh\github-actions-deploy"
|
||||
$sshKeyPubPath = "$sshKeyPath.pub"
|
||||
|
||||
Write-Host "检查 SSH 密钥..." -ForegroundColor Yellow
|
||||
|
||||
if (Test-Path $sshKeyPath) {
|
||||
Write-Host "✓ 找到现有 SSH 密钥: $sshKeyPath" -ForegroundColor Green
|
||||
$regenerate = Read-Host "是否重新生成? (y/n)"
|
||||
if ($regenerate -eq "y" -or $regenerate -eq "Y") {
|
||||
Remove-Item $sshKeyPath -Force -ErrorAction SilentlyContinue
|
||||
Remove-Item $sshKeyPubPath -Force -ErrorAction SilentlyContinue
|
||||
} else {
|
||||
$useExisting = $true
|
||||
}
|
||||
}
|
||||
|
||||
if (-not $useExisting) {
|
||||
Write-Host ""
|
||||
Write-Host "生成新的 SSH 密钥对..." -ForegroundColor Yellow
|
||||
ssh-keygen -t ed25519 -C "github-actions-deploy" -f $sshKeyPath -N '""'
|
||||
Write-Host "✓ SSH 密钥已生成" -ForegroundColor Green
|
||||
}
|
||||
|
||||
# 显示密钥信息
|
||||
Write-Host ""
|
||||
Write-Host "=== SSH 密钥信息 ===" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
|
||||
Write-Host "1. 私钥（需要添加到 GitHub Secrets 的 PROD_SSH_KEY）:" -ForegroundColor Yellow
|
||||
Write-Host "---" -ForegroundColor Gray
|
||||
Get-Content $sshKeyPath
|
||||
Write-Host "---" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
|
||||
Write-Host "2. 公钥（需要添加到生产服务器的 ~/.ssh/authorized_keys）:" -ForegroundColor Yellow
|
||||
Write-Host "---" -ForegroundColor Gray
|
||||
Get-Content $sshKeyPubPath
|
||||
Write-Host "---" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
|
||||
# 保存到文件
|
||||
$privKeyFile = "github-actions-deploy.key"
|
||||
$pubKeyFile = "github-actions-deploy.pub"
|
||||
Copy-Item $sshKeyPath $privKeyFile -Force
|
||||
Copy-Item $sshKeyPubPath $pubKeyFile -Force
|
||||
|
||||
Write-Host "✓ 密钥已保存到项目根目录:" -ForegroundColor Green
|
||||
Write-Host " - $privKeyFile (私钥)" -ForegroundColor Gray
|
||||
Write-Host " - $pubKeyFile (公钥)" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
Write-Host "⚠ 注意: 请妥善保管私钥文件，不要提交到 Git！" -ForegroundColor Red
|
||||
Write-Host ""
|
||||
|
||||
# 生成配置清单
|
||||
Write-Host "=== GitHub Secrets 配置清单 ===" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
|
||||
$secretsGuide = @"
|
||||
请访问以下页面配置 GitHub Secrets:
|
||||
https://github.com/bujie9527/wecom-ai-assistant/settings/secrets/actions
|
||||
|
||||
需要添加的 Secrets:
|
||||
|
||||
1. PROD_HOST
|
||||
值: [你的服务器 IP]
|
||||
说明: 生产服务器公网 IP
|
||||
|
||||
2. PROD_USER
|
||||
值: [SSH 用户名，通常是 root 或 ubuntu]
|
||||
说明: SSH 登录用户名
|
||||
|
||||
3. PROD_SSH_KEY
|
||||
值: [上面的私钥内容，完整复制]
|
||||
说明: SSH 私钥，用于 GitHub Actions 连接服务器
|
||||
|
||||
4. PROD_DOMAIN
|
||||
值: [你的生产域名，例如: api.yourdomain.com]
|
||||
说明: 用于健康检查和部署验证
|
||||
|
||||
5. PROD_SSH_PORT (可选)
|
||||
值: 22
|
||||
说明: SSH 端口，默认 22
|
||||
|
||||
6. PROD_APP_PATH (可选)
|
||||
值: /opt/wecom-ai-assistant
|
||||
说明: 应用部署路径
|
||||
|
||||
配置步骤:
|
||||
1. 点击 "New repository secret"
|
||||
2. 输入 Name 和 Secret 值
|
||||
3. 点击 "Add secret"
|
||||
4. 重复以上步骤添加所有 Secrets
|
||||
|
||||
配置 Workflow 权限:
|
||||
1. 进入: Settings → Actions → General
|
||||
2. 找到 "Workflow permissions"
|
||||
3. 选择 "Read and write permissions"
|
||||
4. 点击 "Save"
|
||||
"@
|
||||
|
||||
$secretsGuide | Out-File "GITHUB_SECRETS_SETUP.md" -Encoding UTF8
|
||||
Write-Host $secretsGuide
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "=== 下一步操作 ===" -ForegroundColor Cyan
|
||||
Write-Host ""
|
||||
Write-Host "1. 将公钥添加到生产服务器:" -ForegroundColor Yellow
|
||||
Write-Host " ssh user@your-server" -ForegroundColor Gray
|
||||
Write-Host " mkdir -p ~/.ssh" -ForegroundColor Gray
|
||||
Write-Host " echo '$(Get-Content $pubKeyFile)' >> ~/.ssh/authorized_keys" -ForegroundColor Gray
|
||||
Write-Host " chmod 600 ~/.ssh/authorized_keys" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
Write-Host "2. 配置 GitHub Secrets:" -ForegroundColor Yellow
|
||||
Write-Host " 查看文件: GITHUB_SECRETS_SETUP.md" -ForegroundColor Gray
|
||||
Write-Host " 或访问: https://github.com/bujie9527/wecom-ai-assistant/settings/secrets/actions" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
Write-Host "3. 测试 SSH 连接:" -ForegroundColor Yellow
|
||||
Write-Host " ssh -i $privKeyFile user@your-server" -ForegroundColor Gray
|
||||
Write-Host ""
|
||||
Reference in New Issue
Block a user