mirror of
https://github.com/ClovertaTheTrilobita/SanYeCao-blog.git
synced 2026-04-02 01:54:50 +00:00
Update Doc
This commit is contained in:
parent
10ba755a71
commit
470ccdc095
3 changed files with 186 additions and 35 deletions
85
README.md
85
README.md
|
|
@ -1,46 +1,59 @@
|
||||||
# Astro Starter Kit: Basics
|
# SanYeCao-Blog
|
||||||
|
|
||||||
```sh
|
<p align="center"><br>
|
||||||
npm create astro@latest -- --template basics
|
✨三叶草Blog✨<br>
|
||||||
|
🌊轻度/快速/美观🌊<br><br>
|
||||||
|
Built With<br>
|
||||||
|
<img alt="Static Badge" src="https://img.shields.io/badge/Astro-6.0-purple">
|
||||||
|
<img alt="Static Badge" src="https://img.shields.io/badge/Nodejs-24-green">
|
||||||
|
<img alt="Static Badge" src="https://img.shields.io/badge/Heart-♥️-pink">
|
||||||
|
<br>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
## 😋 特性
|
||||||
|
|
||||||
|
[screenshots]
|
||||||
|
|
||||||
|
- 使用纯静态页面，相应迅速，轻盈美观
|
||||||
|
- 操作简易，Github Action自动部署
|
||||||
|
- <del><i>Astro Is All You Need</i></del>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 🧳 使用
|
||||||
|
|
||||||
|
### 1. Fork 这个仓库
|
||||||
|
|
||||||
|
[screenshot]
|
||||||
|
|
||||||
|
并将其克隆到本地。
|
||||||
|
|
||||||
|
### 2. 运行/构建
|
||||||
|
|
||||||
|
> [!IMPORTANT]
|
||||||
|
>
|
||||||
|
> 在开始之前，请先<b>将根目录的`.env.example`重命名为`.env`并配置好环境变量</b>，否则功能会不完善
|
||||||
|
|
||||||
|
有关环境变量的说明详见：<b>[EnvVariables.md](docs/EnvVariables.md)</b>
|
||||||
|
|
||||||
|
- 本地调试
|
||||||
|
|
||||||
|
```shell
|
||||||
|
npm run dev
|
||||||
```
|
```
|
||||||
|
|
||||||
> 🧑🚀 **Seasoned astronaut?** Delete this file. Have fun!
|
- 本地构建
|
||||||
|
|
||||||
## 🚀 Project Structure
|
```shell
|
||||||
|
npm run build
|
||||||
Inside of your Astro project, you'll see the following folders and files:
|
|
||||||
|
|
||||||
```text
|
|
||||||
/
|
|
||||||
├── public/
|
|
||||||
│ └── favicon.svg
|
|
||||||
├── src
|
|
||||||
│ ├── assets
|
|
||||||
│ │ └── astro.svg
|
|
||||||
│ ├── components
|
|
||||||
│ │ └── Welcome.astro
|
|
||||||
│ ├── layouts
|
|
||||||
│ │ └── Layout.astro
|
|
||||||
│ └── pages
|
|
||||||
│ └── index.astro
|
|
||||||
└── package.json
|
|
||||||
```
|
```
|
||||||
|
|
||||||
To learn more about the folder structure of an Astro project, refer to [our guide on project structure](https://docs.astro.build/en/basics/project-structure/).
|
### 3. 部署
|
||||||
|
|
||||||
## 🧞 Commands
|
#### 使用Github Actions自动化部署
|
||||||
|
|
||||||
All commands are run from the root of the project, from a terminal:
|
详情参见：<b>[GithubActions.md](docs/GithubActions.md)</b>。
|
||||||
|
|
||||||
| Command | Action |
|
#### 手动部署
|
||||||
| :------------------------ | :----------------------------------------------- |
|
|
||||||
| `npm install` | Installs dependencies |
|
|
||||||
| `npm run dev` | Starts local dev server at `localhost:4321` |
|
|
||||||
| `npm run build` | Build your production site to `./dist/` |
|
|
||||||
| `npm run preview` | Preview your build locally, before deploying |
|
|
||||||
| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
|
|
||||||
| `npm run astro -- --help` | Get help using the Astro CLI |
|
|
||||||
|
|
||||||
## 👀 Want to learn more?
|
将生成的`dist/`目录上传至你的服务器，使用`NGINX`指向index.html。
|
||||||
|
|
||||||
Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).
|
|
||||||
|
|
|
||||||
44
docs/EnvVariables.md
Normal file
44
docs/EnvVariables.md
Normal file
|
|
@ -0,0 +1,44 @@
|
||||||
|
## 环境变量说明
|
||||||
|
|
||||||
|
在项目的`.env.example`中，列举了如下环境变量
|
||||||
|
|
||||||
|
| 变量名 | 内容 |
|
||||||
|
| --------------------- | ------------------------------------------------------------ |
|
||||||
|
| `GITHUB_TOKEN` | 填写你的 <b>[Personal access tokens](https://github.com/settings/personal-access-tokens)</b> |
|
||||||
|
| `GISCUS_REPO_OWNER` | 你的Github账号名，如`ClovertaTheTrilobita` |
|
||||||
|
| `GISCUS_REPO_NAME` | 你的代码仓库，如`SanYeCao-blog` |
|
||||||
|
| `GISCUS_CATEGORY_ID` | `GISCUS`的栏目ID,详见下方说明 |
|
||||||
|
| `GISCUS_DATA_REPO_ID` | `GISCUS`的仓库ID,详见下方说明 |
|
||||||
|
|
||||||
|
### 1. `GITHUB_TOKEN`
|
||||||
|
|
||||||
|
它可以大幅增加你的Github API访问限度，打开此链接：<b>[Personal access tokens](https://github.com/settings/personal-access-tokens)</b>
|
||||||
|
|
||||||
|
选择 <b>`Generate new token`</b>。
|
||||||
|
|
||||||
|
并将生成的Token复制到.env相应位置。
|
||||||
|
|
||||||
|
### 2. `GISCUS`
|
||||||
|
|
||||||
|
博客使用基于`GISCUS API`的评论区，它可以将github仓库的Discussion区域部分映射到网页中以作为评论区使用。
|
||||||
|
|
||||||
|
#### ①启用你仓库的Discussion
|
||||||
|
|
||||||
|
在仓库的<b>`Settings > General > Features`</b>中找到<b>`Discussions`</b>勾选以启用它。
|
||||||
|
|
||||||
|
之后进入<b>`Discussion`</b>页面，点击页面左边<b>`Categories`</b>旁边的铅笔按钮，随后点击<b>`New category`</b>，新建一个名为<b>`Comments`</b>的栏目。
|
||||||
|
|
||||||
|
#### ②安装Giscus的Github App
|
||||||
|
|
||||||
|
点击此链接：<b>[Github App - giscus](https://github.com/apps/giscus)</b>
|
||||||
|
|
||||||
|
将其安装到你Fork的博客代码仓库中。
|
||||||
|
|
||||||
|
随后进入：<b>[giscus.app](https://giscus.app)</b>
|
||||||
|
|
||||||
|
在<b>`Repository`</b>栏中填写你的仓库地址，并在<b>`Page ↔️ Discussions Mapping`</b>中选择<b>`Discussion title contains a specific term`</b>
|
||||||
|
|
||||||
|
在<b>`Discussion Category`</b>处选择我们刚刚新建的<b>`Comments`</b>。
|
||||||
|
|
||||||
|
最后在下面生成的代码中找到<b>`data-category-id`</b>和<b>`data-repo-id`</b>，将其填写到环境变量中。
|
||||||
|
|
||||||
94
docs/GithubActions.md
Normal file
94
docs/GithubActions.md
Normal file
|
|
@ -0,0 +1,94 @@
|
||||||
|
## Github Actions自动部署
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
>
|
||||||
|
> 此项目的Github Actions监听`src/blog`和`src/friends`两个目录的`git push`操作，两个目录有更新则触发构建流水线。
|
||||||
|
|
||||||
|
> [!IMPORTANT]
|
||||||
|
>
|
||||||
|
> 需要使用这个功能请自行Fork一份代码到自己的仓库，在你自己的仓库才能跑流水线。
|
||||||
|
|
||||||
|
### 一、设置SSH密钥
|
||||||
|
|
||||||
|
在仓库的<b>`Settings > Secrets and variables > Actions`</b>中，添加三个`Repository secrets`，分别为：
|
||||||
|
|
||||||
|
| 密钥名 | 用途 |
|
||||||
|
| -------------------- | ---------------------------- |
|
||||||
|
| `DEPLOY_KNOWN_HOSTS` | 用于让Gihub CI识别目标服务器 |
|
||||||
|
| `DEPLOY_SSH_KEY` | 用于登录目标服务器 |
|
||||||
|
| `ENV_FILE` | 私有环境变量 |
|
||||||
|
|
||||||
|
#### 1.`DEPLOY_KNOWN_HOSTS`
|
||||||
|
|
||||||
|
在终端执行命令
|
||||||
|
|
||||||
|
```shell
|
||||||
|
ssh-keyscan -H <你的服务器IP>
|
||||||
|
```
|
||||||
|
|
||||||
|
并将生成的所有内容放入该环境变量中
|
||||||
|
|
||||||
|
#### 2.`DEPLOY_SSH_KEY`
|
||||||
|
|
||||||
|
推荐在你本地新生成一把专门用于 GitHub 部署的 key
|
||||||
|
|
||||||
|
本地或服务器终端执行：
|
||||||
|
|
||||||
|
```
|
||||||
|
ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/github_actions_deploy
|
||||||
|
```
|
||||||
|
|
||||||
|
执行后会得到两个文件：
|
||||||
|
|
||||||
|
```
|
||||||
|
~/.ssh/github_actions_deploy
|
||||||
|
~/.ssh/github_actions_deploy.pub
|
||||||
|
```
|
||||||
|
|
||||||
|
> **`github_actions_deploy`** → 私钥，填到 `DEPLOY_SSH_KEY`
|
||||||
|
>
|
||||||
|
> **`github_actions_deploy.pub`** → 公钥，要加到服务器上
|
||||||
|
|
||||||
|
##### ① 设置Github私钥
|
||||||
|
|
||||||
|
查看私钥内容：
|
||||||
|
|
||||||
|
```
|
||||||
|
cat ~/.ssh/github_actions_deploy
|
||||||
|
```
|
||||||
|
|
||||||
|
把完整输出复制到变量值中。
|
||||||
|
|
||||||
|
##### ② 设置服务器公钥
|
||||||
|
|
||||||
|
随后，登录服务器终端，将`~/.ssh/github_actions_deploy.pub`中的内容添加到服务器的`~/.ssh/authorized_keys`，以实现Github CI访问服务器。
|
||||||
|
|
||||||
|
#### 3.`ENV_FILE`
|
||||||
|
|
||||||
|
这个变量用于生成构建所需的`.env`文件。
|
||||||
|
|
||||||
|
如果你已经设置好`.env`，它里面应该有如下内容
|
||||||
|
|
||||||
|
```env
|
||||||
|
GITHUB_TOKEN=
|
||||||
|
GISCUS_REPO_OWNER=
|
||||||
|
GISCUS_REPO_NAME=
|
||||||
|
GISCUS_CATEGORY_ID=
|
||||||
|
GISCUS_DATA_REPO_ID=
|
||||||
|
```
|
||||||
|
|
||||||
|
如果你还没配置好或不知道这些是干什么的，请详见：<b>[EnvVariables.md](EnvVariables.md)</b>
|
||||||
|
|
||||||
|
直接把`.env`中的所有内容复制到变量值中。
|
||||||
|
|
||||||
|
### 二、设置环境变量
|
||||||
|
|
||||||
|
同样，在<b>`Settings > Secrets and variables > Actions`</b>中，添加四个`Repository variables`，分别为：
|
||||||
|
|
||||||
|
| 密钥名 | 内容 |
|
||||||
|
| ------------- | -------------------------------------------------------- |
|
||||||
|
| `DEPLOY_HOST` | 服务器IP地址，如`192.168.1.1` |
|
||||||
|
| `DEPLOY_PATH` | 在服务器上的部署路径，如`/www/wwwroot/blog.cloverta.top` |
|
||||||
|
| `DEPLOY_PORT` | 服务器SSH端口，一般是`22` |
|
||||||
|
| `DEPLOY_USER` | 登录用户，例如`root` |
|
||||||
|
|
||||||
Loading…
Reference in a new issue