feat: migrate and organize documentation and blog posts
refactor(blog): restructure blog post layouts and metadata docs: add markdown migration guide and project rules update style(global.css): update typography theme variables chore: move temp_docs to appropriate blog post locations
This commit is contained in:
joyzhao
350
temp_docs/01-03.md
Normal file
350
temp_docs/01-03.md
Normal file
@@ -0,0 +1,350 @@
|
||||
---
|
||||
authors: [joyZhao]
|
||||
title: 利用Gitea actions创建项目部署的自动化流程
|
||||
tags: [gitea, actions, CI/CD, 自动化部署]
|
||||
---
|
||||
|
||||
本文以部署一个前端项目为示例，将手把手教你如何利用Gitea actions创建项目部署的自动化流程，对于不想使用Jenkins的小伙伴来说，Gitea actions是一个不错的`CI/CD`解决方案。
|
||||
|
||||
<!-- truncate -->
|
||||
|
||||
## 前言
|
||||
在我们开发完一个项目后，需要将项目部署到服务器上，以便于用户可以访问。但是，每次部署都需要手动操作，这会浪费我们的时间和精力。因此，我们可以利用Gitea actions创建一个自动化流程，以便于我们快速部署项目。
|
||||
|
||||
## 什么是Gitea actions
|
||||
Gitea actions是Gitea的一个功能，它允许我们创建自动化流程，以便于我们快速部署项目。Gitea actions可以执行各种任务，例如构建、测试、部署等。Gitea actions可以使用各种编程语言和工具，例如Python、Java、Docker等。并且Gitea actions在配置上尽量与GitHub actions的配置兼容，因此，如果你已经熟悉了GitHub actions，那么你也可以轻松地使用Gitea actions。
|
||||
详见官方文档：[Gitea actions](https://docs.gitea.com/zh-cn/usage/actions/overview)
|
||||
|
||||
## 准备工作
|
||||
在我们开始创建此流程前，首先你需要准备以下资料：
|
||||
1. 一台服务器,最好拥有root权限（会安装一些工具）
|
||||
2. 一个已部署的Gitea仓库,版本至少需要>=`v1.19`，官方强烈建议使用`v1.20`或更高版本
|
||||
3. docker环境（非必须, 用在部署runner的主机上）
|
||||
|
||||
> ps: 作者这里服务器准备的是：一台打包服务器 + 一台部署（目标）服务器， 你可以只用一台服务器，但注意环境的隔离
|
||||
|
||||
请在进行后续步骤前，确保已完成所有的准备工作，具体的安装配置，请参考官方文档，这里我不会再赘述。[安装](https://docs.gitea.com/zh-cn/category/installation)
|
||||
|
||||
如果你使用**1panel面板**，可直接在应用商店中一键完成安装，作者就就是使用此方式。
|
||||
|
||||
>注意：在版本 < `v1.21.0`之前的版本，需要在配置文件中，开启`actions`功能，具体请参考官方文档[配置](https://docs.gitea.com/zh-cn/usage/actions/quickstart),之后的版本则是默认开启。
|
||||
|
||||
本教程使用的Gitea版本为`v1.22.6` !
|
||||
|
||||
|
||||
## 配置Runner
|
||||
在Gitea actions中，运行Job，都是通过Runner来执行的，因此，我们需要先配置Runner，以便于我们后续的部署流程。有两种安装方式，可直接安装到主机上，也可以通过docker容器中，这里作者将通过docker安装，为避免过多的资源消耗，可以将其安装到一个单独的主机中（ps：对于国内用户，可以选择一台香港服务器，这样运行job的速度会更快😄）, 作者选择的主机就是一台香港的VPS
|
||||
|
||||
### 下载act_Runner
|
||||
|
||||
首先我们需要下载此工具，用来注册或者生成配置[下载地址](https://gitea.com/gitea/act_runner/releases)，请在此页面中选择与你的系统对应的版本进行下载，下载完成后，上传到服务器中，这里我是上传到了服务器中的`/gitea_runner2`目录下。也可以使用`curl`等工具直接下载, 可直接使用以下命令，但注意名称和下载地址，我的系统是`Debain12 x86_64`,因此下载的是`act_runner-0.2.11-linux-amd64`。
|
||||
|
||||
```bash
|
||||
curl -o act_runner2 https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-linux-amd64
|
||||
```
|
||||
完成后，设置下执行权限
|
||||
```bash
|
||||
chmod +x act_runner2 # 注意文件名,请根据实际情况修改
|
||||
|
||||
./act_runner --version # 看到版本信息就代表成功了
|
||||
```
|
||||
### 生成配置
|
||||
```
|
||||
./act_runner2 generate-config > config.yaml
|
||||
```
|
||||
一般情况下默认的配置就够了，如果你有其他的需求请自行修改`config.yaml`。
|
||||
|
||||
**由于作者选用docker安装的方式，所以如果你选用直接在主机安装的方式，可以跳过后续的安装步骤，参考官方文档进行安装[直接安装](https://docs.gitea.com/zh-cn/usage/actions/quickstart)**
|
||||
|
||||
### 注册runner
|
||||
|
||||
这里我选择通过`docker-compose.yml`配置的方式进行注册
|
||||
|
||||
**注意： 将配置中的参数结合你自己的情况修改，以下配置仅供参考！！！**
|
||||
|
||||
```yaml
|
||||
version: "3.8"
|
||||
services:
|
||||
runner:
|
||||
image: gitea/act_runner:latest
|
||||
environment:
|
||||
CONFIG_FILE: /config.yaml
|
||||
GITEA_INSTANCE_URL: "<your_gitea.com>"
|
||||
GITEA_RUNNER_REGISTRATION_TOKEN: "<your_registration_token_here>"
|
||||
GITEA_RUNNER_NAME: "act_vps_runner2"
|
||||
GITEA_RUNNER_LABELS: "act_vps_runner2"
|
||||
volumes:
|
||||
- /gitea_runner2/config.yaml:/config.yaml
|
||||
- /gitea_runner2/runner_data/data:/data
|
||||
- /gitea_runner2/runner_data/cache:/root/.cache
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
### 配置说明
|
||||
|
||||
**GITEA_RUNNER_REGISTRATION_TOKEN** 此参数为注册令牌，需要从你的gitea中进行获取，一共有三个级别，我这里直接选用组织级别的，在组织设置页中进行获取，如下图所示：
|
||||
|
||||
|
||||
其他的实例配置页面及说明请参考官方文档，有详细的说明
|
||||
|
||||
**如果您无法看到设置页面，请确保您具有正确的权限并且已启用 Actions, 检查Gitea版本 !!!**
|
||||
|
||||
### 运行并生成runner
|
||||
|
||||
由于作者使用1panel面板，因此直接在容器选项中编排即可，如果你没有使用此类的可视化工具，就需要手动执行``docker-compose up -d``
|
||||
|
||||
成功后，可查看容器的运行以及日志，日志中会显示注册成功的信息，如下图所示：
|
||||
|
||||
|
||||
|
||||
|
||||
然后我们回到你获取runner令牌的页面，进行刷新就能看到你的runner了，如下图所示：
|
||||
|
||||
图中的名称是根据你注册配置时的名称
|
||||
|
||||
> 至此，我们的runner部署就算完成了，接下来可以去在项目中使用了。
|
||||
|
||||
## 使用actions
|
||||
|
||||
gitea actions的使用方式与github actions类似，如果你不熟悉这类配置，可以先去了解下**github actions**,
|
||||
作者将使用一个`vitepress`项目作为示例
|
||||
|
||||
### 创建配置文件
|
||||
1. 在项目根目录下创建`.gitea/workflows`目录
|
||||
2. 在其目录中创建`deploy.yaml`配置文件
|
||||
3. 我们先写个测试配置，用于测试环境变量，如下所示：
|
||||
```yaml
|
||||
name: Deploy Test
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Print Environment Variables
|
||||
run: env
|
||||
|
||||
- name: Print Current Directory
|
||||
run: pwd
|
||||
|
||||
- name: List Files in Working Directory
|
||||
run: ls -la
|
||||
```
|
||||
然后提交代码到仓库，我们应该就可以在仓库的actions中看到执行任务了，如下图所示:
|
||||
|
||||
|
||||
> **ps：如果你没有看到actions执行，甚至没看到actions这个选项，可能需要你在仓库、组织或管理页面中开启actions选项**
|
||||
### 配置打包
|
||||
我们修改`deploy.yaml`配置文件，添加打包步骤, 我这里使用的是pnpm，请根据自己的实际情况调整一些配置，这里不过多展开
|
||||
|
||||
````yaml
|
||||
name: Deploy docs for project
|
||||
run-name: ${{ gitea.actor }} is building out Gitea Actions 🚀
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
strategy:
|
||||
matrix:
|
||||
node-version: [18.x]
|
||||
steps:
|
||||
# TODO 临时解决 https://github.com/go-gitea/gitea/issues/32481, 等待gitea发布1.23.0进行修复
|
||||
- name: Install git
|
||||
run: |
|
||||
if ! command -v git &> /dev/null; then
|
||||
apt-get update && apt-get install -y git
|
||||
else
|
||||
echo "git is already installed"
|
||||
fi
|
||||
|
||||
- name: Checkout repository code
|
||||
uses: https://gitea.com/actions/checkout@v4
|
||||
with:
|
||||
ref: 'main'
|
||||
|
||||
- name: Use Node.js ${{ matrix.node-version }}
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ matrix.node-version }}
|
||||
|
||||
# Skip pnpm cache to reduce overhead
|
||||
- name: Install pnpm
|
||||
run: |
|
||||
if ! command -v pnpm &> /dev/null; then
|
||||
npm install -g pnpm@9
|
||||
else
|
||||
echo "pnpm is already installed"
|
||||
fi
|
||||
|
||||
- name: Check Node.js and pnpm versions
|
||||
run: |
|
||||
echo "pnpm version ===>" && pnpm -v
|
||||
echo "node version ===>" && node -v
|
||||
|
||||
# Simplify node_modules handling without caching
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
if [ ! -d "node_modules" ] || [ "$(find package.json -newer node_modules)" ]; then
|
||||
echo "Dependencies are outdated or missing, installing..."
|
||||
pnpm install
|
||||
else
|
||||
echo "Dependencies are up-to-date, skipping installation."
|
||||
fi
|
||||
|
||||
- name: Build docs
|
||||
run: pnpm run docs:build
|
||||
````
|
||||
|
||||
> **特意说明：安装git是为了修复目前gitea actions中无法通过`actions/checkout`检出代码的问题，此问题预计会在`v1.23.0`中修复，目前我们只能这样处理, 但据作者的观察发现好像与使用的镜像版本也有关系，如果是`ubuntu-latest`好像就不用安装，请以实际情况为准**
|
||||
|
||||
如果一切顺利，那么你应该可以看到工作流中完成了打包任务，如图所示
|
||||
|
||||
|
||||
### 部署项目
|
||||
|
||||
部署代码的原理，实际上是通过`ssh`的方式连接到目标服务器并执行部署脚本，因此我们需要先配置好SSH，然后使用`actions` [easingthemes/ssh-deploy](https://github.com/easingthemes/ssh-deploy) 连接到目标服务器并推送代码即可
|
||||
|
||||
#### 配置SSH
|
||||
这一步骤实际上是为服务器配置一个用户并支持`SSH`登录，也就是免密登录，因此我们在**目标服务器**依次使用以下命令，作者使用的`Debian 12`，请根据实际情况调整命令！
|
||||
|
||||
##### 创建用户(建议创建一个操作部署目录的用户，不要使用root用户！！！)
|
||||
```bash
|
||||
sudo adduser deployuser # 请根据自己实际情况修改用户名
|
||||
```
|
||||
创建成功后，可以查看是否存在`/home/deployuser`目录，不存在则可能需要手动创建
|
||||
|
||||
##### 创建密钥对
|
||||
我们需要先将用户切换到`deployuser`用户下，然后执行以下命令
|
||||
```bash
|
||||
# 1. 创建公私钥
|
||||
ssh-keygen -t rsa -b 4096 -C ""
|
||||
# 将公钥内容添加到 authorized_keys 文件
|
||||
echo ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
|
||||
# 设置正确的权限
|
||||
chmod 600 ~/.ssh/authorized_keys
|
||||
chmod 700 ~/.ssh
|
||||
```
|
||||
##### 赋予特定目录的读写权限（可跳过）
|
||||
这里需要`root`权限的用户操作
|
||||
```bash
|
||||
# 1. 创建目录
|
||||
mkdir -p /var/www/html/project
|
||||
# 2. 修改目录权限
|
||||
sudo chown deployuser:deployuser /var/www/project
|
||||
sudo chmod 700 /var/www/project
|
||||
```
|
||||
由于作者这里使用了`1panel`进行管理网站所以目录就是自动生成的目录，与此有所出入，但流程步骤一致，请根据自己实际情况修改
|
||||
|
||||
#### 在gitea中配置密钥信息
|
||||
|
||||
1. 在你的gitea的个人、组织或管理的actions页面中，点击`密钥`，将我们刚刚在服务器中生成的私钥复制到`密钥`中，然后点击`添加密钥`即可
|
||||
2. 因为后续我们需要用到服务器IP、用户名，这里也建议配置到密钥或变量中，方便后续使用。
|
||||
|
||||
作者这里，将私钥、服务器IP、用户名配置到了密钥中，如图所示
|
||||
|
||||
|
||||
到这里我们就完成了部署项目所需要的配置了，接下来我们就可以开始部署流程了。
|
||||
|
||||
> ps：由于`easingthemes/ssh-deploy`需要使用`rsync`执行脚本命令，所以在镜像容器中或者目标服务器都需要依赖此工具，如果不存在，就需要提前安装好，特别是**目标服务器**, 一般需要用root用户或者有安装权限的用户操作
|
||||
|
||||
### 项目部署
|
||||
|
||||
我们在`deploy.yml`中，添加以下代码,注意格式！！！
|
||||
|
||||
````yaml
|
||||
- name: ssh deploy
|
||||
uses: easingthemes/ssh-deploy@v5.1.0
|
||||
with:
|
||||
SSH_PRIVATE_KEY: ${{ secrets.SH_SSH_PRIVATE_KEY }}
|
||||
REMOTE_HOST: ${{ secrets.SH_REMOTE_HOST }}
|
||||
REMOTE_USER: ${{ secrets.SH_REMOTE_USER }}
|
||||
SOURCE: "/.vitepress/dist/"
|
||||
TARGET: "/1Panel/1panel/apps/openresty/openresty/www/sites/demo.zhaoguiyang.cn/index/dist" # 请根据实际情况修改为你的部署目录
|
||||
EXCLUDE: "/node_modules/"
|
||||
````
|
||||
如果一切顺利的话，你就会看到actions执行成功，并且在你的部署目录下，有一个dist目录存在了，如下图所示：
|
||||
|
||||
|
||||
|
||||
接下来，你就只需要使用`nginx`之类的工具指向此目录，就可以访问了。
|
||||
|
||||
> ps: 如果你在上面这个步骤出现了错误，请仔细查看错误日志，根据作者的经验来说，大概率是出现在ssh密钥和权限处理的这两个问题上，如果你使用的不是`ubuntu-latest`,那你可能还需根据报错信息，安装一些必须的工具，如:`git`、`rsync`等
|
||||
|
||||
|
||||
### 完整配置
|
||||
|
||||
````yaml
|
||||
name: Deploy docs for project
|
||||
run-name: ${{ gitea.actor }} is building out Gitea Actions 🚀
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
strategy:
|
||||
matrix:
|
||||
node-version: [18.x]
|
||||
steps:
|
||||
- name: Checkout repository code
|
||||
uses: https://gitea.com/actions/checkout@v4
|
||||
with:
|
||||
ref: 'main'
|
||||
|
||||
- name: Use Node.js ${{ matrix.node-version }}
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ matrix.node-version }}
|
||||
|
||||
# Skip pnpm cache to reduce overhead
|
||||
- name: Install pnpm
|
||||
run: |
|
||||
if ! command -v pnpm &> /dev/null; then
|
||||
npm install -g pnpm@9
|
||||
else
|
||||
echo "pnpm is already installed"
|
||||
fi
|
||||
|
||||
- name: Check Node.js and pnpm versions
|
||||
run: |
|
||||
echo "pnpm version ===>" && pnpm -v
|
||||
echo "node version ===>" && node -v
|
||||
|
||||
# Simplify node_modules handling without caching
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
if [ ! -d "node_modules" ] || [ "$(find package.json -newer node_modules)" ]; then
|
||||
echo "Dependencies are outdated or missing, installing..."
|
||||
pnpm install
|
||||
else
|
||||
echo "Dependencies are up-to-date, skipping installation."
|
||||
fi
|
||||
|
||||
- name: Build docs
|
||||
run: pnpm run docs:build
|
||||
|
||||
- name: ssh deploy
|
||||
uses: easingthemes/ssh-deploy@v5.1.0
|
||||
with:
|
||||
SSH_PRIVATE_KEY: ${{ secrets.SH_SSH_PRIVATE_KEY }}
|
||||
REMOTE_HOST: ${{ secrets.SH_REMOTE_HOST }}
|
||||
REMOTE_USER: ${{ secrets.SH_REMOTE_USER }}
|
||||
SOURCE: "/.vitepress/dist/"
|
||||
TARGET: "/1Panel/1panel/apps/openresty/openresty/www/sites/demo.zhaoguiyang.cn/index/dist" # 请根据实际情况修改为你的部署目录
|
||||
EXCLUDE: "/node_modules/"
|
||||
|
||||
````
|
||||
|
||||
|
||||
到这里，本文就结束了，如有错误，请多多谅解,希望给有需要的小伙伴带来一些思路和帮助
|
||||
|
||||
Reference in New Issue
Block a user