MBE 文档中心

🔐 GitHub Secrets 配置指南

📋 概述

本文档详细说明如何配置 GitHub Secrets，用于 CI/CD 自动化部署。所有敏感信息（如SSH密钥、API Token等）都应存储在 GitHub Secrets 中，而不是代码仓库中。

🎯 配置步骤

1. 访问 GitHub Secrets 设置

  1. 打开您的 GitHub 仓库
  2. 点击 Settings（设置）
  3. 在左侧菜单中找到 Secrets and variables → Actions
  4. 点击 New repository secret（新建仓库密钥）

📝 需要配置的 Secrets

🔹 开发环境配置

DEV_HOST

  • 名称: DEV_HOST
  • 描述: 开发环境服务器地址
  • 示例: dev-server.example.com 或 192.168.1.100
  • 获取方式: 您的开发服务器IP或域名

DEV_USER

  • 名称: DEV_USER
  • 描述: 开发环境SSH用户名
  • 示例: deploy 或 ubuntu 或 root
  • 获取方式: 服务器上的SSH用户名

DEV_SSH_KEY

  • 名称: DEV_SSH_KEY
  • 描述: 开发环境SSH私钥
  • 获取方式: 见下方"生成SSH密钥"部分

DEV_PATH

  • 名称: DEV_PATH
  • 描述: 开发环境部署目录
  • 示例: /opt/mbe-dev 或 /home/deploy/mbe-dev
  • 获取方式: 服务器上用于部署的目录路径

🔹 测试环境配置

STAGING_HOST

  • 名称: STAGING_HOST
  • 描述: 测试环境服务器地址
  • 示例: staging-server.example.com
  • 获取方式: 您的测试服务器IP或域名

STAGING_USER

  • 名称: STAGING_USER
  • 描述: 测试环境SSH用户名
  • 示例: deploy
  • 获取方式: 服务器上的SSH用户名

STAGING_SSH_KEY

  • 名称: STAGING_SSH_KEY
  • 描述: 测试环境SSH私钥
  • 获取方式: 见下方"生成SSH密钥"部分

STAGING_PATH

  • 名称: STAGING_PATH
  • 描述: 测试环境部署目录
  • 示例: /opt/mbe-staging
  • 获取方式: 服务器上用于部署的目录路径

🔹 生产环境配置（国内）

CN_HOST

  • 名称: CN_HOST
  • 描述: 国内生产环境服务器地址
  • 示例: cn-server.example.com 或 123.456.789.0
  • 获取方式: 国内服务器的IP或域名

CN_USER

  • 名称: CN_USER
  • 描述: 国内生产环境SSH用户名
  • 示例: deploy
  • 获取方式: 服务器上的SSH用户名

CN_SSH_KEY

  • 名称: CN_SSH_KEY
  • 描述: 国内生产环境SSH私钥
  • 获取方式: 见下方"生成SSH密钥"部分

CN_PATH

  • 名称: CN_PATH
  • 描述: 国内生产环境部署目录
  • 示例: /opt/mbe-prod-cn
  • 获取方式: 服务器上用于部署的目录路径

🔹 生产环境配置（国外）

GLOBAL_HOST

  • 名称: GLOBAL_HOST
  • 描述: 国外生产环境服务器地址
  • 示例: global-server.example.com 或 54.123.45.67
  • 获取方式: 国外服务器的IP或域名

GLOBAL_USER

  • 名称: GLOBAL_USER
  • 描述: 国外生产环境SSH用户名
  • 示例: deploy
  • 获取方式: 服务器上的SSH用户名

GLOBAL_SSH_KEY

  • 名称: GLOBAL_SSH_KEY
  • 描述: 国外生产环境SSH私钥
  • 获取方式: 见下方"生成SSH密钥"部分

GLOBAL_PATH

  • 名称: GLOBAL_PATH
  • 描述: 国外生产环境部署目录
  • 示例: /opt/mbe-prod-global
  • 获取方式: 服务器上用于部署的目录路径

🔹 Cloudflare 配置

CLOUDFLARE_API_TOKEN

  • 名称: CLOUDFLARE_API_TOKEN
  • 描述: Cloudflare API Token（用于管理CDN和DNS）
  • 获取方式: 见下方"获取Cloudflare Token"部分

CLOUDFLARE_ZONE_ID

  • 名称: CLOUDFLARE_ZONE_ID
  • 描述: Cloudflare Zone ID（域名区域ID）
  • 获取方式: 见下方"获取Cloudflare Zone ID"部分

CLOUDFLARE_TUNNEL_TOKEN_DEV

  • 名称: CLOUDFLARE_TUNNEL_TOKEN_DEV
  • 描述: 开发环境 Cloudflare Tunnel Token
  • 获取方式: 见下方"获取Cloudflare Tunnel Token"部分

CLOUDFLARE_TUNNEL_TOKEN_STAGING

  • 名称: CLOUDFLARE_TUNNEL_TOKEN_STAGING
  • 描述: 测试环境 Cloudflare Tunnel Token
  • 获取方式: 见下方"获取Cloudflare Tunnel Token"部分

CLOUDFLARE_TUNNEL_TOKEN_PROD

  • 名称: CLOUDFLARE_TUNNEL_TOKEN_PROD
  • 描述: 生产环境 Cloudflare Tunnel Token
  • 获取方式: 见下方"获取Cloudflare Tunnel Token"部分

🔹 通知配置（可选）

SLACK_WEBHOOK

  • 名称: SLACK_WEBHOOK
  • 描述: Slack Webhook URL（用于发送部署通知）
  • 获取方式: 见下方"配置Slack通知"部分
  • 可选: 是

DISCORD_WEBHOOK

  • 名称: DISCORD_WEBHOOK
  • 描述: Discord Webhook URL（用于发送部署通知）
  • 获取方式: 见下方"配置Discord通知"部分
  • 可选: 是

🔑 详细配置说明

1. 生成SSH密钥

Windows (PowerShell)

# 1. 生成SSH密钥对
ssh-keygen -t ed25519 -C "github-actions-deploy" -f $env:USERPROFILE\.ssh\deploy_key

# 2. 查看私钥（复制到 GitHub Secrets）
Get-Content $env:USERPROFILE\.ssh\deploy_key

# 3. 查看公钥（添加到服务器）
Get-Content $env:USERPROFILE\.ssh\deploy_key.pub

Linux/macOS

# 1. 生成SSH密钥对
ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/deploy_key

# 2. 查看私钥（复制到 GitHub Secrets）
cat ~/.ssh/deploy_key

# 3. 查看公钥（添加到服务器）
cat ~/.ssh/deploy_key.pub

将公钥添加到服务器

# 方法1: 使用 ssh-copy-id
ssh-copy-id -i ~/.ssh/deploy_key.pub deploy@your-server.com

# 方法2: 手动添加
# 1. 复制公钥内容
cat ~/.ssh/deploy_key.pub

# 2. SSH登录到服务器
ssh deploy@your-server.com

# 3. 添加到 authorized_keys
mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo "你的公钥内容" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

测试SSH连接

# 测试连接
ssh -i ~/.ssh/deploy_key deploy@your-server.com

# 如果成功，说明配置正确

2. 获取Cloudflare API Token

  1. 登录 Cloudflare Dashboard

  2. 创建API Token

    • 点击右上角用户图标 → My Profile
    • 选择 API Tokens 标签
    • 点击 Create Token
    • 选择 Edit zone DNS 模板，或自定义权限：
      • Zone → DNS → Edit
      • Zone → Zone Settings → Read
      • Account → Cloudflare Tunnel → Edit
    • 选择要授权的域名（Zone）
    • 点击 Continue to summary
    • 点击 Create Token
    • 复制Token（只显示一次，请妥善保存）

  3. 添加到GitHub Secrets

    • 名称：CLOUDFLARE_API_TOKEN
    • 值：刚才复制的Token

3. 获取Cloudflare Zone ID

  1. 访问 Cloudflare Dashboard

  2. 找到Zone ID

    • 在右侧边栏找到 Zone ID
    • 点击复制

  3. 添加到GitHub Secrets

    • 名称：CLOUDFLARE_ZONE_ID
    • 值：复制的Zone ID

4. 获取Cloudflare Tunnel Token

开发环境Token

  1. 访问 Cloudflare Zero Trust Dashboard

  2. 创建或选择Tunnel

    • 进入 Networks → Tunnels
    • 如果已有 mises-engine-dev Tunnel，点击它
    • 如果没有，点击 Create a tunnel → 选择 Cloudflared → 输入名称 mises-engine-dev

  3. 获取Token

    • 点击 Tunnel 名称进入详情页
    • 点击 Configure
    • 在 Install Connector 部分找到 Token
    • 点击 Copy 复制Token

  4. 添加到GitHub Secrets

    • 名称：CLOUDFLARE_TUNNEL_TOKEN_DEV
    • 值：复制的Token

测试环境Token

重复上述步骤，创建或选择 mbe-staging Tunnel，获取Token后添加到：

  • 名称：CLOUDFLARE_TUNNEL_TOKEN_STAGING

生产环境Token

重复上述步骤，创建或选择 mbe-prod Tunnel，获取Token后添加到：

  • 名称：CLOUDFLARE_TUNNEL_TOKEN_PROD

5. 配置Slack通知（可选）

  1. 创建Slack App

  2. 启用Incoming Webhooks

    • 在左侧菜单选择 Incoming Webhooks
    • 开启 Activate Incoming Webhooks
    • 点击 Add New Webhook to Workspace
    • 选择要发送通知的频道
    • 点击 Allow

  3. 复制Webhook URL

    • 复制生成的Webhook URL

  4. 添加到GitHub Secrets

    • 名称：SLACK_WEBHOOK
    • 值：复制的Webhook URL

6. 配置Discord通知（可选）

  1. 创建Discord Webhook

    • 在Discord服务器中，选择要接收通知的频道
    • 点击频道设置 → Integrations → Webhooks
    • 点击 New Webhook
    • 输入名称，选择频道
    • 点击 Copy Webhook URL

  2. 添加到GitHub Secrets

    • 名称：DISCORD_WEBHOOK
    • 值：复制的Webhook URL

✅ 配置检查清单

使用以下清单确保所有Secrets都已配置：

开发环境

  • DEV_HOST
  • DEV_USER
  • DEV_SSH_KEY
  • DEV_PATH
  • CLOUDFLARE_TUNNEL_TOKEN_DEV

测试环境

  • STAGING_HOST
  • STAGING_USER
  • STAGING_SSH_KEY
  • STAGING_PATH
  • CLOUDFLARE_TUNNEL_TOKEN_STAGING

生产环境（国内）

  • CN_HOST
  • CN_USER
  • CN_SSH_KEY
  • CN_PATH

生产环境（国外）

  • GLOBAL_HOST
  • GLOBAL_USER
  • GLOBAL_SSH_KEY
  • GLOBAL_PATH

Cloudflare

  • CLOUDFLARE_API_TOKEN
  • CLOUDFLARE_ZONE_ID
  • CLOUDFLARE_TUNNEL_TOKEN_DEV
  • CLOUDFLARE_TUNNEL_TOKEN_STAGING
  • CLOUDFLARE_TUNNEL_TOKEN_PROD

通知（可选）

  • SLACK_WEBHOOK
  • DISCORD_WEBHOOK

🧪 验证配置

1. 测试SSH连接

# 测试开发环境
ssh -i ~/.ssh/deploy_key $DEV_USER@$DEV_HOST

# 测试生产环境（国内）
ssh -i ~/.ssh/deploy_key $CN_USER@$CN_HOST

# 测试生产环境（国外）
ssh -i ~/.ssh/deploy_key $GLOBAL_USER@$GLOBAL_HOST

2. 测试Cloudflare API

# 测试API Token
curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

# 应该返回成功响应

3. 测试GitHub Actions

  1. 访问 GitHub Actions 页面
  2. 手动触发 Complete CI/CD Pipeline 工作流
  3. 查看日志，确认可以访问Secrets

🔒 安全建议

  1. 使用不同的SSH密钥

    • 为每个环境使用不同的SSH密钥
    • 不要在生产环境使用开发环境的密钥

  2. 定期轮换Token

    • 定期更新Cloudflare API Token
    • 定期更新SSH密钥

  3. 限制权限

    • SSH密钥只授予必要的权限
    • Cloudflare Token只授予必要的权限

  4. 不要提交Secrets到代码仓库

    • 所有Secrets都应存储在GitHub Secrets中
    • 不要将Secrets写入代码或配置文件

  5. 使用环境保护规则

    • 为生产环境设置审批流程
    • 限制谁可以访问生产环境Secrets

📚 相关文档

🆘 常见问题

Q: SSH连接失败怎么办？

A: 检查以下几点：

  1. SSH密钥是否正确添加到服务器
  2. 服务器防火墙是否允许SSH连接
  3. SSH用户名是否正确
  4. 服务器地址是否正确

Q: Cloudflare Token无效怎么办？

A: 检查以下几点：

  1. Token是否已过期
  2. Token权限是否足够
  3. Zone ID是否正确
  4. Token格式是否正确（没有多余空格）

Q: 如何更新Secret？

A:

  1. 访问 GitHub Secrets 设置页面
  2. 找到要更新的Secret
  3. 点击 Update
  4. 输入新值
  5. 点击 Update secret

Q: 可以删除Secret吗？

A: 可以，但请确保：

  1. 没有工作流正在使用该Secret
  2. 删除后相关功能将无法工作
  3. 删除操作不可恢复

最后更新: 2026-02-08