cloud-mcp/GITEA_ACTIONS_SETUP.md

Gitea Actions 部署配置指南

前置要求

1. 确保 Gitea Actions 已启用

在 Gitea 管理员设置中：

• 进入 Site Administration → Actions
• 确保 Actions 功能已启用
• 检查 app.ini 配置：

[actions]
ENABLED = true

2. 安装并运行 Act Runner

Act Runner 是 Gitea Actions 的执行器，需要在服务器上运行。

下载 Act Runner

# 在服务器上执行
cd /tmp
wget https://gitea.com/gitea/act_runner/releases/download/v0.2.6/act_runner-linux-amd64
chmod +x act_runner-linux-amd64
sudo mv act_runner-linux-amd64 /usr/local/bin/act_runner

注册 Runner

# 在服务器上执行
act_runner register \
  --instance <your-gitea-url> \
  --token <runner-token> \
  --name my-runner \
  --labels ubuntu-latest:docker://node:20-bullseye

获取 Runner Token：

1. 进入 Gitea：Site Administration → Actions → Runners
2. 点击 New Runner
3. 复制显示的 Token

运行 Runner

# 作为服务运行（推荐）
sudo tee /etc/systemd/system/gitea-act-runner.service > /dev/null <<EOF
[Unit]
Description=Gitea Act Runner
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/cloud-mcp
ExecStart=/usr/local/bin/act_runner daemon
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable gitea-act-runner
sudo systemctl start gitea-act-runner
sudo systemctl status gitea-act-runner

或者直接运行：

act_runner daemon

3. 配置 GitHub Secrets（在 Gitea 中）

在 Gitea 仓库中设置 Secrets：

1. 进入仓库：Settings → Secrets → Actions
2. 添加以下 Secrets：

SERVER_HOST=你的服务器IP或域名
SERVER_USERNAME=部署用户名（如 root 或 deployer）
SERVER_SSH_KEY=你的SSH私钥（完整内容，包括 -----BEGIN 和 -----END）

生成 SSH 密钥对（如果还没有）：

# 在本地或服务器上
ssh-keygen -t ed25519 -C "gitea-actions-deploy" -f ~/.ssh/gitea_deploy

# 将公钥添加到服务器的 authorized_keys
ssh-copy-id -i ~/.ssh/gitea_deploy.pub user@your-server

# 复制私钥内容作为 SERVER_SSH_KEY secret
cat ~/.ssh/gitea_deploy

4. 更新部署脚本路径

编辑 .gitea/workflows/deploy.yml 或 deploy-simple.yml，更新项目路径：

cd /opt/cloud-mcp  # 改为你的实际项目路径

工作流文件说明

项目包含两个工作流文件：

deploy.yml

• 使用 SSH 密钥文件方式
• 包含清理步骤

deploy-simple.yml（推荐）

• 使用环境变量方式
• 更详细的日志输出
• 更好的错误处理

测试部署

1. 手动触发

在 Gitea 仓库中：

• 进入 Actions 标签页
• 选择 Deploy to Server 工作流
• 点击 Run workflow

2. 推送代码触发

git add .
git commit -m "Test deployment"
git push origin main

3. 查看日志

在 Gitea 仓库的 Actions 页面查看工作流执行日志。

故障排查

工作流一直显示"等待中"

1. 检查 Runner 是否运行：

   sudo systemctl status gitea-act-runner
   # 或
   ps aux | grep act_runner
   

2. 检查 Runner 标签匹配：

   • 工作流中 runs-on: ubuntu-latest
   • Runner 注册时需要包含 ubuntu-latest 标签

3. 查看 Runner 日志：

   sudo journalctl -u gitea-act-runner -f
   

SSH 连接失败

1. 测试 SSH 连接：

   ssh -i ~/.ssh/deploy_key user@server
   

2. 检查 SSH 密钥格式：

   • 确保私钥包含完整的 -----BEGIN 和 -----END 行
   • 确保没有多余的空格或换行

3. 检查服务器防火墙：

   # 确保 SSH 端口开放
   sudo ufw allow 22
   

部署脚本执行失败

1. 检查脚本权限：

   chmod +x /opt/cloud-mcp/deploy-gitea.sh
   

2. 检查项目路径：

   • 确保工作流中的路径与实际路径一致

3. 查看服务器日志：

   tail -f /opt/cloud-mcp/deploy.log
   

安全建议

1. 使用专用部署用户：

   sudo adduser deployer
   sudo usermod -aG docker deployer
   

2. 限制 SSH 密钥权限：

   • 使用 command= 限制 SSH 密钥只能执行特定命令
   • 在 ~/.ssh/authorized_keys 中：

   command="/opt/cloud-mcp/deploy-gitea.sh" ssh-ed25519 AAAAC3...
   

3. 使用 SSH 密钥而非密码：

   • 禁用密码登录
   • 只使用密钥认证

4. 定期轮换密钥：

   • 定期更新 SSH 密钥
   • 更新 Gitea Secrets

验证部署

部署成功后，检查：

# 在服务器上
docker ps | grep cloud-mcp
docker logs cloud-mcp

下一步

• 配置自动部署触发条件
• 添加部署通知（邮件、Slack 等）
• 设置部署回滚机制