177 lines
4.3 KiB
Markdown
177 lines
4.3 KiB
Markdown
# 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
|
||
```
|