# 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 等）
- 设置部署回滚机制