# Gitea Actions 工作流配置说明

本项目配置了两个 Gitea Actions 工作流，用于自动化构建、测试和部署。

## 工作流列表

### 1. ci.yml - 持续集成
**触发时机：**
- 推送代码到 `main` 或 `master` 分支
- 创建 Pull Request

**执行内容：**
- 自动检出代码
- 配置 Java 8 环境
- 使用 Gradle 构建项目
- 运行单元测试
- 上传构建产物（JAR 包）
- 上传测试报告

**查看结果：**
构建完成后，可以在 Gitea 仓库的 "Actions" 标签页查看运行结果和下载构建产物。

---

### 2. deploy.yml - 自动部署
**触发时机：**
- 推送代码到 `main` 或 `master` 分支
- 手动触发（在 Gitea Actions 页面点击 "Run workflow"）

**执行内容：**
- 构建项目
- 通过 SCP 将 JAR 包上传到服务器
- 通过 SSH 重启应用

**配置步骤：**

#### 第一步：在 Gitea 中配置 Secrets
进入仓库 → Settings → Secrets，添加以下密钥：

| 密钥名称 | 说明 | 示例 |
|---------|------|------|
| `SERVER_HOST` | 服务器 IP 地址 | `120.24.204.180` |
| `SERVER_PORT` | SSH 端口 | `22` |
| `SERVER_USER` | SSH 用户名 | `root` 或 `ubuntu` |
| `SERVER_SSH_KEY` | SSH 私钥内容 | 完整的私钥文件内容 |
| `DEPLOY_PATH` | 部署目录路径 | `/opt/corewing` |

#### 第二步：生成 SSH 密钥对（如果还没有）
```bash
# 在本地生成密钥对
ssh-keygen -t rsa -b 4096 -C "gitea-deploy" -f ~/.ssh/gitea_deploy

# 查看公钥
cat ~/.ssh/gitea_deploy.pub

# 查看私钥（复制到 Gitea Secrets 中）
cat ~/.ssh/gitea_deploy
```

#### 第三步：配置服务器
```bash
# 1. SSH 登录到服务器
ssh user@your-server

# 2. 创建部署目录
sudo mkdir -p /opt/corewing
sudo chown $USER:$USER /opt/corewing

# 3. 添加公钥到 authorized_keys
echo "your-public-key-content" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

# 4. 安装 Java（如果未安装）
sudo apt update
sudo apt install openjdk-8-jdk -y
java -version
```

#### 第四步：测试部署
推送代码到 main 分支，或在 Gitea Actions 页面手动触发 deploy 工作流。

---

## 启用 Gitea Actions

### Gitea 服务器端配置

如果你的 Gitea 实例还未启用 Actions，需要管理员配置：

1. **修改 Gitea 配置文件** (`app.ini`)：
```ini
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://gitea.com
```

2. **安装 Gitea Act Runner**：
```bash
# 下载 Act Runner
wget https://dl.gitea.com/act_runner/0.2.6/act_runner-0.2.6-linux-amd64
chmod +x act_runner-0.2.6-linux-amd64
mv act_runner-0.2.6-linux-amd64 /usr/local/bin/act_runner

# 注册 Runner
act_runner register --no-interactive --instance http://120.24.204.180:3000 --token YOUR_RUNNER_TOKEN

# 启动 Runner
act_runner daemon
```

3. **获取 Runner Token**：
   - 登录 Gitea 管理后台
   - 进入 Site Administration → Actions → Runners
   - 点击 "Create new Runner" 获取 Token

---

## 自定义工作流

### 修改触发条件
可以根据需要修改工作流的触发条件：

```yaml
on:
  push:
    branches: [ main, develop ]  # 监听多个分支
    tags:
      - 'v*'  # 监听标签
  schedule:
    - cron: '0 0 * * *'  # 定时执行（每天午夜）
```

### 添加环境变量
在工作流中使用环境变量：

```yaml
env:
  JAVA_VERSION: '8'
  SPRING_PROFILES_ACTIVE: 'prod'

steps:
  - name: 运行应用
    run: java -jar -Dspring.profiles.active=${{ env.SPRING_PROFILES_ACTIVE }} app.jar
```

### 添加通知
可以添加构建成功/失败通知：

```yaml
- name: 发送通知
  if: failure()
  run: |
    curl -X POST "https://your-notification-webhook" \
      -d "构建失败: ${{ github.repository }}"
```

---

## 常见问题

### 1. 工作流未触发？
- 检查 Gitea Actions 是否启用
- 检查 Act Runner 是否正常运行
- 确认触发条件是否匹配

### 2. 构建失败？
- 查看 Actions 日志获取详细错误信息
- 检查 Java 版本是否正确
- 确认依赖是否能正常下载

### 3. 部署失败？
- 检查 Secrets 配置是否正确
- 测试 SSH 连接是否正常
- 检查服务器目录权限

### 4. 如何查看日志？
- Gitea 仓库 → Actions 标签页
- 点击具体的工作流运行记录
- 展开各个步骤查看详细日志

---

## 最佳实践

1. **分支策略**：
   - `main` 分支自动部署到生产环境
   - `develop` 分支自动部署到测试环境
   - Pull Request 只执行构建和测试

2. **安全性**：
   - 不要在代码中硬编码密码和密钥
   - 使用 Secrets 管理敏感信息
   - 定期轮换 SSH 密钥

3. **性能优化**：
   - 启用 Gradle 缓存加快构建速度
   - 使用 `build -x test` 跳过测试快速构建
   - 合理设置产物保留时间

4. **监控**：
   - 定期检查工作流运行状态
   - 设置构建失败通知
   - 保存构建日志便于问题排查

---

## 更多资源

- [Gitea Actions 官方文档](https://docs.gitea.io/en-us/actions/)
- [GitHub Actions 语法参考](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions)（Gitea Actions 兼容 GitHub Actions 语法）
- [Act Runner 项目](https://gitea.com/gitea/act_runner)