chore: clean up and migrate temp docs to proper locations

- Remove outdated temporary documentation files - Migrate relevant content to appropriate locations in docs structure - Update gitea actions deployment guide with proper images and content
2025-06-19 20:42:28 +08:00
parent f8173fd706
commit 10e7a24da8
7 changed files with 253 additions and 933 deletions
--- a/src/pages/zh/blog/posts/gitea-actions-deployment-automation.md
+++ b/src/pages/zh/blog/posts/gitea-actions-deployment-automation.md
@@ -10,9 +10,10 @@ category: "DevOps"
 categoryId: "devops"
 readTime: "10 min read"
 ---
-
 本文以部署一个前端项目为示例，将手把手教你如何利用Gitea actions创建项目部署的自动化流程，对于不想使用Jenkins的小伙伴来说，Gitea actions是一个不错的`CI/CD`解决方案。

+<!-- truncate -->
+
 ## 前言
 在我们开发完一个项目后，需要将项目部署到服务器上，以便于用户可以访问。但是，每次部署都需要手动操作，这会浪费我们的时间和精力。因此，我们可以利用Gitea actions创建一个自动化流程，以便于我们快速部署项目。

@@ -87,7 +88,7 @@ services:
 ### 配置说明

 **GITEA_RUNNER_REGISTRATION_TOKEN** 此参数为注册令牌，需要从你的gitea中进行获取，一共有三个级别，我这里直接选用组织级别的，在组织设置页中进行获取，如下图所示：
-![image](https://images.unsplash.com/photo-1633356122102-3fe601e05bd2?q=80&w=1470&auto=format&fit=crop)
+![image](https://pic1.imgdb.cn/item/6779f8dfd0e0a243d4ef14ab.png)

 其他的实例配置页面及说明请参考官方文档，有详细的说明

@@ -99,6 +100,254 @@ services:

 成功后，可查看容器的运行以及日志，日志中会显示注册成功的信息，如下图所示：

-![image](https://images.unsplash.com/photo-1607706189992-eae578626c86?q=80&w=1470&auto=format&fit=crop)
+![image](https://pic1.imgdb.cn/item/677893b5d0e0a243d4eeccca.png)
+![image](https://pic1.imgdb.cn/item/677893bad0e0a243d4eecccb.png)
+
+然后我们回到你获取runner令牌的页面，进行刷新就能看到你的runner了，如下图所示：
+![image](https://pic1.imgdb.cn/item/6779f844d0e0a243d4ef1478.png)
+图中的名称是根据你注册配置时的名称
+
+> 至此，我们的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中看到执行任务了，如下图所示:
+![image](https://pic1.imgdb.cn/item/6779f972d0e0a243d4ef14da.png)
+
+> **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`好像就不用安装，请以实际情况为准**
+
+如果一切顺利，那么你应该可以看到工作流中完成了打包任务，如图所示
+![image](https://pic1.imgdb.cn/item/677bcf9bd0e0a243d4f00c7a.png)
+
+### 部署项目
+
+部署代码的原理，实际上是通过`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、用户名配置到了密钥中，如图所示
+![image](https://pic1.imgdb.cn/item/677bd9c0d0e0a243d4f011f2.png)
+
+到这里我们就完成了部署项目所需要的配置了，接下来我们就可以开始部署流程了。
+
+> 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目录存在了，如下图所示：
+![image](https://pic1.imgdb.cn/item/677bdd23d0e0a243d4f014a3.png)
+![image](https://pic1.imgdb.cn/item/677bdd1bd0e0a243d4f014a1.png)
+
+接下来，你就只需要使用`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/"
+
+````

-然后我们回到你获取runner令牌的页面，进行刷新就能看到你的runner了。