164 lines
4.6 KiB
Markdown
164 lines
4.6 KiB
Markdown
# 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)
|