From 459f99e8049e020ae138f29cdcd22356cd0f828f Mon Sep 17 00:00:00 2001
From: "ethan.chen" <ethan.chen@sangoai.cn>
Date: Wed, 7 Jan 2026 14:06:12 +0800
Subject: [PATCH] feat: Add Gitea Actions workflows and setup documentation for
 deployment

---
 .gitea/workflows/README.md         |  18 +++
 .gitea/workflows/deploy-simple.yml |  62 ++++++++
 .gitea/workflows/deploy.yml        |  41 +++++
 .gitignore                         |   3 +
 GITEA_ACTIONS_SETUP.md             | 237 +++++++++++++++++++++++++++++
 5 files changed, 361 insertions(+)
 create mode 100644 .gitea/workflows/README.md
 create mode 100644 .gitea/workflows/deploy-simple.yml
 create mode 100644 .gitea/workflows/deploy.yml
 create mode 100644 GITEA_ACTIONS_SETUP.md

diff --git a/.gitea/workflows/README.md b/.gitea/workflows/README.md
new file mode 100644
index 0000000..61622ed
--- /dev/null
+++ b/.gitea/workflows/README.md
@@ -0,0 +1,18 @@
+# Gitea Actions 工作流
+
+本目录包含 Gitea Actions 工作流配置文件。
+
+## 文件说明
+
+- `deploy.yml` - 基础部署工作流
+- `deploy-simple.yml` - 简化版部署工作流（推荐使用）
+
+## 使用说明
+
+1. 确保已安装并运行 Act Runner
+2. 在 Gitea 仓库中配置 Secrets
+3. 更新工作流中的项目路径
+4. 推送代码或手动触发工作流
+
+详细配置请参考 `GITEA_ACTIONS_SETUP.md`
+
diff --git a/.gitea/workflows/deploy-simple.yml b/.gitea/workflows/deploy-simple.yml
new file mode 100644
index 0000000..3c2d6fd
--- /dev/null
+++ b/.gitea/workflows/deploy-simple.yml
@@ -0,0 +1,62 @@
+name: Deploy to Server (Simple)
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      
+      - name: Deploy to server via SSH
+        env:
+          SSH_KEY: ${{ secrets.SERVER_SSH_KEY }}
+          SSH_USER: ${{ secrets.SERVER_USERNAME }}
+          SSH_HOST: ${{ secrets.SERVER_HOST }}
+        run: |
+          # Setup SSH
+          mkdir -p ~/.ssh
+          echo "$SSH_KEY" > ~/.ssh/deploy_key
+          chmod 600 ~/.ssh/deploy_key
+          
+          # Add host to known_hosts (optional, for security)
+          ssh-keyscan -H "$SSH_HOST" >> ~/.ssh/known_hosts 2>/dev/null || true
+          
+          # Deploy
+          ssh -i ~/.ssh/deploy_key \
+            -o StrictHostKeyChecking=no \
+            -o UserKnownHostsFile=~/.ssh/known_hosts \
+            "$SSH_USER@$SSH_HOST" << 'ENDSSH'
+            set -e
+            echo "Starting deployment..."
+            
+            # Navigate to project directory (update this path)
+            cd /opt/cloud-mcp || {
+              echo "Error: Project directory not found"
+              exit 1
+            }
+            
+            # Pull latest code
+            echo "Pulling latest code..."
+            git fetch origin
+            git checkout main || git checkout master
+            git pull origin main || git pull origin master
+            
+            # Run deployment script
+            echo "Running deployment script..."
+            chmod +x deploy-gitea.sh
+            ./deploy-gitea.sh
+            
+            echo "Deployment completed!"
+          ENDSSH
+          
+          # Cleanup
+          rm -f ~/.ssh/deploy_key
+
diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml
new file mode 100644
index 0000000..c3a6c16
--- /dev/null
+++ b/.gitea/workflows/deploy.yml
@@ -0,0 +1,41 @@
+name: Deploy to Server
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      
+      - name: Setup SSH
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{ secrets.SERVER_SSH_KEY }}" > ~/.ssh/deploy_key
+          chmod 600 ~/.ssh/deploy_key
+          ssh-keyscan -H ${{ secrets.SERVER_HOST }} >> ~/.ssh/known_hosts 2>/dev/null || true
+      
+      - name: Deploy to server
+        run: |
+          ssh -i ~/.ssh/deploy_key \
+            -o StrictHostKeyChecking=no \
+            -o UserKnownHostsFile=~/.ssh/known_hosts \
+            ${{ secrets.SERVER_USERNAME }}@${{ secrets.SERVER_HOST }} << 'ENDSSH'
+            set -e
+            cd /opt/cloud-mcp || cd /path/to/cloud-mcp
+            git pull origin main || git pull origin master
+            ./deploy-gitea.sh
+          ENDSSH
+      
+      - name: Cleanup
+        if: always()
+        run: |
+          rm -f ~/.ssh/deploy_key
+
diff --git a/.gitignore b/.gitignore
index 6c673e3..f45bad2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,6 @@ data/
 deploy.log
 *.log
 
+# Gitea Actions
+.gitea/workflows/*.yml.bak
+
diff --git a/GITEA_ACTIONS_SETUP.md b/GITEA_ACTIONS_SETUP.md
new file mode 100644
index 0000000..9607cd6
--- /dev/null
+++ b/GITEA_ACTIONS_SETUP.md
@@ -0,0 +1,237 @@
+# Gitea Actions 部署配置指南
+
+## 前置要求
+
+### 1. 确保 Gitea Actions 已启用
+
+在 Gitea 管理员设置中：
+- 进入 **Site Administration** → **Actions**
+- 确保 **Actions** 功能已启用
+- 检查 `app.ini` 配置：
+
+```ini
+[actions]
+ENABLED = true
+```
+
+### 2. 安装并运行 Act Runner
+
+Act Runner 是 Gitea Actions 的执行器，需要在服务器上运行。
+
+#### 下载 Act Runner
+
+```bash
+# 在服务器上执行
+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
+
+```bash
+# 在服务器上执行
+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
+
+```bash
+# 作为服务运行（推荐）
+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
+```
+
+或者直接运行：
+
+```bash
+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 密钥对**（如果还没有）：
+
+```bash
+# 在本地或服务器上
+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`，更新项目路径：
+
+```yaml
+cd /opt/cloud-mcp  # 改为你的实际项目路径
+```
+
+## 工作流文件说明
+
+项目包含两个工作流文件：
+
+### deploy.yml
+- 使用 SSH 密钥文件方式
+- 包含清理步骤
+
+### deploy-simple.yml（推荐）
+- 使用环境变量方式
+- 更详细的日志输出
+- 更好的错误处理
+
+## 测试部署
+
+### 1. 手动触发
+
+在 Gitea 仓库中：
+- 进入 **Actions** 标签页
+- 选择 **Deploy to Server** 工作流
+- 点击 **Run workflow**
+
+### 2. 推送代码触发
+
+```bash
+git add .
+git commit -m "Test deployment"
+git push origin main
+```
+
+### 3. 查看日志
+
+在 Gitea 仓库的 **Actions** 页面查看工作流执行日志。
+
+## 故障排查
+
+### 工作流一直显示"等待中"
+
+1. **检查 Runner 是否运行**：
+   ```bash
+   sudo systemctl status gitea-act-runner
+   # 或
+   ps aux | grep act_runner
+   ```
+
+2. **检查 Runner 标签匹配**：
+   - 工作流中 `runs-on: ubuntu-latest`
+   - Runner 注册时需要包含 `ubuntu-latest` 标签
+
+3. **查看 Runner 日志**：
+   ```bash
+   sudo journalctl -u gitea-act-runner -f
+   ```
+
+### SSH 连接失败
+
+1. **测试 SSH 连接**：
+   ```bash
+   ssh -i ~/.ssh/deploy_key user@server
+   ```
+
+2. **检查 SSH 密钥格式**：
+   - 确保私钥包含完整的 `-----BEGIN` 和 `-----END` 行
+   - 确保没有多余的空格或换行
+
+3. **检查服务器防火墙**：
+   ```bash
+   # 确保 SSH 端口开放
+   sudo ufw allow 22
+   ```
+
+### 部署脚本执行失败
+
+1. **检查脚本权限**：
+   ```bash
+   chmod +x /opt/cloud-mcp/deploy-gitea.sh
+   ```
+
+2. **检查项目路径**：
+   - 确保工作流中的路径与实际路径一致
+
+3. **查看服务器日志**：
+   ```bash
+   tail -f /opt/cloud-mcp/deploy.log
+   ```
+
+## 安全建议
+
+1. **使用专用部署用户**：
+   ```bash
+   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
+
+## 验证部署
+
+部署成功后，检查：
+
+```bash
+# 在服务器上
+docker ps | grep cloud-mcp
+docker logs cloud-mcp
+```
+
+## 下一步
+
+- 配置自动部署触发条件
+- 添加部署通知（邮件、Slack 等）
+- 设置部署回滚机制
+