Gitea Actions 自动化构建与部署指南

本文档描述 EBAOZU V4 项目的 Gitea CI/CD 配置方案。

1. 架构概览

┌─────────────────────────────────────────────────────────────────┐
│                        Gitea Actions                            │
│                                                                 │
│  push develop ──► 智能检测变更 ──► ┌─ 仅PHP ──► 拉代码+重启     │
│                                   ├─ 含admin ─► 构建admin+部署  │
│                                   └─ 含store ─► 构建store+部署  │
│                                                                 │
│  手动触发 ──► 选择模块+环境 ──► 构建+部署到指定服务器            │
└─────────────────────────────────────────────────────────────────┘

服务器环境

环境	标识	说明	分支
测试环境	`test`	开发测试用	`develop`
正式环境	`prod`	生产环境	`master`
客户A	`client_a`	客户A独立部署	`master` 或指定分支
客户B	`client_b`	客户B独立部署	`master` 或指定分支

2. 前置准备

2.1 Gitea Runner 配置

项目使用 self-hosted runner（即部署服务器本身），需要在 Gitea 后台注册：

bash

# 在部署服务器上安装 act_runner
# 下载地址: https://gitea.com/gitea/act_runner/releases

# 注册到 Gitea
./act_runner register \
  --instance http://your-gitea-host:3000 \
  --token <从Gitea后台 管理 > Actions > Runners 获取>

# 启动 runner
./act_runner daemon --config config.yaml

2.2 配置 Secrets

在 Gitea 仓库 设置 > 仓库设置 > Actions > Secrets 中添加：

通用 Secrets

Secret 名称	说明	示例
`SSH_PRIVATE_KEY`	SSH 私钥（用于远程部署）	`-----BEGIN OPENSSH PRIVATE KEY-----...`

测试环境 Secrets

Secret 名称	说明	示例
`TEST_HOST`	测试服务器 IP/域名	`192.168.1.100`
`TEST_USER`	SSH 用户名	`www`
`TEST_PATH`	项目根目录	`/www/wwwroot/ebaozu_v4`

正式环境 Secrets

Secret 名称	说明	示例
`PROD_HOST`	正式服务器 IP/域名	`prod.example.com`
`PROD_USER`	SSH 用户名	`www`
`PROD_PATH`	项目根目录	`/www/wwwroot/ebaozu_v4`

客户环境 Secrets（按需添加）

Secret 名称	说明
`CLIENT_A_HOST`	客户A服务器
`CLIENT_A_USER`	客户A SSH 用户
`CLIENT_A_PATH`	客户A项目路径
`CLIENT_B_HOST`	客户B服务器
`CLIENT_B_USER`	客户B SSH 用户
`CLIENT_B_PATH`	客户B项目路径

2.3 SSH 免密配置

确保 Gitea Runner 所在机器能通过 SSH 免密登录到所有目标服务器：

bash

# 生成密钥对（如果还没有）
ssh-keygen -t ed25519 -C "gitea-runner"

# 将公钥复制到各目标服务器
ssh-copy-id www@TEST_HOST
ssh-copy-id www@PROD_HOST
ssh-copy-id www@CLIENT_A_HOST
ssh-copy-id www@CLIENT_B_HOST

3. 工作流文件说明

工作流文件位于 .gitea/workflows/ 目录：

.gitea/workflows/
├── deploy.yml    # 主部署流程（智能检测 + 多环境）
└── test.yml      # 单元测试（PR 时触发）

4. deploy.yml 详解

4.1 触发方式

自动触发（push 到 develop）

yaml

on:
  push:
    branches: [develop]

push 到 develop 时自动触发
自动部署到测试环境
智能检测变更文件，决定是否需要构建前端

手动触发（workflow_dispatch）

yaml

on:
  workflow_dispatch:
    inputs:
      build_modules:
        description: '构建模块'
        type: choice
        options: [auto, none, admin, store, all]
        default: 'auto'
      deploy_target:
        description: '部署目标'
        type: choice
        options: [test, prod, client_a, client_b]
        default: 'test'
      git_ref:
        description: 'Git 分支/标签（留空用默认）'
        default: ''

手动触发时可选择：

构建模块：auto（智能判断）、none（只拉代码）、admin、store、all
部署目标：test、prod、client_a、client_b
Git 分支：留空则 test=develop，prod=master

4.2 智能变更检测

核心逻辑：通过 git diff 检测上次部署以来哪些文件发生了变化。

bash

# 检测 view/admin 目录是否有变更
git diff --name-only HEAD~1 | grep -q "^view/admin/"

# 检测 view/store 目录是否有变更
git diff --name-only HEAD~1 | grep -q "^view/store/"

判定规则：

变更内容	行为
仅 PHP 文件变更	只拉代码，不构建前端
`view/admin/` 下文件变更	构建 admin + 部署
`view/store/` 下文件变更	构建 store + 部署
两者都变更	都构建 + 部署

4.3 部署流程

1. 智能检测变更文件
      │
      ├─ 需要构建 admin? ──► npm ci + npm run build
      │
      ├─ 需要构建 store? ──► npm ci + npm run build
      │
      └─ SSH 到目标服务器
            │
            ├─ git fetch + reset（更新后端代码）
            │
            ├─ rsync admin 构建产物（如有）
            │
            ├─ rsync store 构建产物（如有）
            │
            └─ Swoole 重启

5. 构建产物说明

5.1 Admin 前端（view/admin）

项目	值
构建命令	`npm run build`
输出目录	`view/admin/dist/`
静态资源	`dist/static_admin/` → `public/static_admin/`
页面文件	`dist/view_admin/` → `public/view_admin/`
入口 HTML	`dist/system.html` → `public/system.html`

5.2 Store 前端（view/store）

项目	值
构建命令	`npm run build`
输出目录	`view/store/dist/`
静态资源	`dist/static_store/` → `public/static_store/`
页面文件	`dist/view_store/` → `public/view_store/`
入口 HTML	`dist/store.html` → `public/store.html`

6. 常用操作

6.1 部署到测试环境（自动）

直接 push 到 develop 分支即可，workflow 会自动：

检测变更文件
按需构建前端
部署到测试环境

6.2 部署到正式环境（手动）

进入 Gitea 仓库页面
点击 Actions 选项卡
选择 精细化构建与部署 工作流
点击 Run workflow
选择参数：
- 构建模块：auto 或 all
- 部署目标：prod
- Git 分支：master（留空默认）
点击 Run workflow 确认

6.3 部署到客户环境

同上，部署目标选择 client_a 或 client_b。

6.4 只拉代码不构建

手动触发时，构建模块选择 none。

6.5 强制重新构建前端

手动触发时，构建模块选择 all。

7. 扩展：添加新客户环境

7.1 添加 Secrets

在 Gitea 后台添加新客户的 Secrets：

CLIENT_X_HOST
CLIENT_X_USER
CLIENT_X_PATH

7.2 更新 deploy.yml

在 deploy_target 的 options 中添加新选项：

yaml

deploy_target:
  type: choice
  options: [test, prod, client_a, client_b, client_x]  # 添加 client_x

8. 故障排查

8.1 构建失败

bash

# 查看 Gitea Actions 日志
# 进入仓库 > Actions > 点击失败的运行 > 查看具体步骤

8.2 SSH 连接失败

bash

# 测试 SSH 连接
ssh -i ~/.ssh/id_rsa www@TEST_HOST "echo ok"

# 检查 known_hosts
ssh-keyscan -H TEST_HOST >> ~/.ssh/known_hosts

8.3 前端构建失败

bash

# 清除 node_modules 重试
cd view/admin && rm -rf node_modules && npm ci
cd view/store && rm -rf node_modules && npm ci

8.4 部署后页面空白

检查 Nginx 配置，确保：

try_files 指向正确的入口文件（system.html / store.html）
publicPath 与部署路径一致

9. 最佳实践

develop 分支：日常开发，push 自动部署到测试环境
master 分支：生产代码，手动触发部署到正式环境
feature 分支：开发完成后合并到 develop
hotfix 分支：紧急修复，从 master 拉出，修复后合并回 master 并部署

Git 工作流

feature/xxx ──► develop (自动部署测试)
                │
                ▼
              master (手动部署生产)
                │
                ▼
           client_a (手动部署客户)

10. 文件清单

文件	说明
`.gitea/workflows/deploy.yml`	主部署工作流
`.gitea/workflows/test.yml`	单元测试工作流
`docs-wiki/cicd/gitea-cicd-guide.md`	本文档
`docs-wiki/cicd/cicd-check.sh`	环境检查脚本

11. 快速检查

运行环境检查脚本，确认 CI/CD 所需依赖是否就绪：

bash

bash docs-wiki/cicd/cicd-check.sh

附录：deploy.yml 工作流图

                    ┌─────────────────┐
                    │  detect-changes │
                    │  (智能检测变更)  │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
              ▼              ▼              ▼
     ┌────────────┐  ┌────────────┐  ┌────────────┐
     │build-admin │  │build-store │  │  (跳过)    │
     │ (按需构建) │  │ (按需构建) │  │            │
     └──────┬─────┘  └──────┬─────┘  └──────┬─────┘
            │               │               │
            └───────────────┼───────────────┘
                            │
                            ▼
                    ┌───────────────┐
                    │    deploy     │
                    │  (SSH 部署)   │
                    └───────────────┘

Gitea Actions 自动化构建与部署指南 ​

1. 架构概览 ​

服务器环境 ​

2. 前置准备 ​

2.1 Gitea Runner 配置 ​

2.2 配置 Secrets ​

通用 Secrets ​

测试环境 Secrets ​

正式环境 Secrets ​

客户环境 Secrets（按需添加） ​

2.3 SSH 免密配置 ​

3. 工作流文件说明 ​

4. deploy.yml 详解 ​

4.1 触发方式 ​

自动触发（push 到 develop） ​

手动触发（workflow_dispatch） ​

4.2 智能变更检测 ​

4.3 部署流程 ​

5. 构建产物说明 ​

5.1 Admin 前端（view/admin） ​

5.2 Store 前端（view/store） ​

6. 常用操作 ​

6.1 部署到测试环境（自动） ​

6.2 部署到正式环境（手动） ​

6.3 部署到客户环境 ​

6.4 只拉代码不构建 ​

6.5 强制重新构建前端 ​

7. 扩展：添加新客户环境 ​

7.1 添加 Secrets ​

7.2 更新 deploy.yml ​

8. 故障排查 ​

8.1 构建失败 ​

8.2 SSH 连接失败 ​

8.3 前端构建失败 ​

8.4 部署后页面空白 ​

9. 最佳实践 ​

Git 工作流 ​

10. 文件清单 ​

11. 快速检查 ​

附录：deploy.yml 工作流图 ​

Gitea Actions 自动化构建与部署指南

1. 架构概览

服务器环境

2. 前置准备

2.1 Gitea Runner 配置

2.2 配置 Secrets

通用 Secrets

测试环境 Secrets

正式环境 Secrets

客户环境 Secrets（按需添加）

2.3 SSH 免密配置

3. 工作流文件说明

4. deploy.yml 详解

4.1 触发方式

自动触发（push 到 develop）

手动触发（workflow_dispatch）

4.2 智能变更检测

4.3 部署流程

5. 构建产物说明

5.1 Admin 前端（view/admin）

5.2 Store 前端（view/store）

6. 常用操作

6.1 部署到测试环境（自动）

6.2 部署到正式环境（手动）

6.3 部署到客户环境

6.4 只拉代码不构建

6.5 强制重新构建前端

7. 扩展：添加新客户环境

7.1 添加 Secrets

7.2 更新 deploy.yml

8. 故障排查

8.1 构建失败

8.2 SSH 连接失败

8.3 前端构建失败

8.4 部署后页面空白

9. 最佳实践

Git 工作流

10. 文件清单

11. 快速检查

附录：deploy.yml 工作流图