diff --git a/README.md b/README.md index 414a13a..2bed447 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,59 @@ -# Astro Starter Kit: Basics +# SanYeCao-Blog -```sh -npm create astro@latest -- --template basics -``` +


+ ✨三叶草Blog✨
+ 🌊轻度/快速/美观🌊

+ Built With
+ Static Badge + Static Badge + Static Badge +
+

-> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun! +## 😋 特性 -## 🚀 Project Structure +[screenshots] -Inside of your Astro project, you'll see the following folders and files: +- 使用纯静态页面，相应迅速，轻盈美观 +- 操作简易，Github Action自动部署 +- Astro Is All You Need -```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/). -## 🧞 Commands +## 🧳 使用 -All commands are run from the root of the project, from a terminal: +### 1. Fork 这个仓库 -| 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 | +[screenshot] -## 👀 Want to learn more? +并将其克隆到本地。 -Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat). +### 2. 运行/构建 + +> [!IMPORTANT] +> +> 在开始之前，请先将根目录的`.env.example`重命名为`.env`并配置好环境变量，否则功能会不完善 + +有关环境变量的说明详见：[EnvVariables.md](docs/EnvVariables.md) + +- 本地调试 + + ```shell + npm run dev + ``` + +- 本地构建 + + ```shell + npm run build + ``` + +### 3. 部署 + +#### 使用Github Actions自动化部署 + +详情参见：[GithubActions.md](docs/GithubActions.md)。 + +#### 手动部署 + +将生成的`dist/`目录上传至你的服务器，使用`NGINX`指向index.html。 diff --git a/docs/EnvVariables.md b/docs/EnvVariables.md new file mode 100644 index 0000000..32cc253 --- /dev/null +++ b/docs/EnvVariables.md @@ -0,0 +1,44 @@ +## 环境变量说明 + +在项目的`.env.example`中，列举了如下环境变量 + +| 变量名 | 内容 | +| --------------------- | ------------------------------------------------------------ | +| `GITHUB_TOKEN` | 填写你的 [Personal access tokens](https://github.com/settings/personal-access-tokens) | +| `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访问限度，打开此链接：[Personal access tokens](https://github.com/settings/personal-access-tokens) + +选择 `Generate new token`。 + +并将生成的Token复制到.env相应位置。 + +### 2. `GISCUS` + +博客使用基于`GISCUS API`的评论区，它可以将github仓库的Discussion区域部分映射到网页中以作为评论区使用。 + +#### ①启用你仓库的Discussion + +在仓库的`Settings > General > Features`中找到`Discussions`勾选以启用它。 + +之后进入`Discussion`页面，点击页面左边`Categories`旁边的铅笔按钮，随后点击`New category`，新建一个名为`Comments`的栏目。 + +#### ②安装Giscus的Github App + +点击此链接：[Github App - giscus](https://github.com/apps/giscus) + +将其安装到你Fork的博客代码仓库中。 + +随后进入：[giscus.app](https://giscus.app) + +在`Repository`栏中填写你的仓库地址，并在`Page ↔️ Discussions Mapping`中选择`Discussion title contains a specific term` + +在`Discussion Category`处选择我们刚刚新建的`Comments`。 + +最后在下面生成的代码中找到`data-category-id`和`data-repo-id`，将其填写到环境变量中。 + diff --git a/docs/GithubActions.md b/docs/GithubActions.md new file mode 100644 index 0000000..4703038 --- /dev/null +++ b/docs/GithubActions.md @@ -0,0 +1,94 @@ +## Github Actions自动部署 + +> [!NOTE] +> +> 此项目的Github Actions监听`src/blog`和`src/friends`两个目录的`git push`操作，两个目录有更新则触发构建流水线。 + +> [!IMPORTANT] +> +> 需要使用这个功能请自行Fork一份代码到自己的仓库，在你自己的仓库才能跑流水线。 + +### 一、设置SSH密钥 + +在仓库的`Settings > Secrets and variables > Actions`中，添加三个`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= +``` + +如果你还没配置好或不知道这些是干什么的，请详见：[EnvVariables.md](EnvVariables.md) + +直接把`.env`中的所有内容复制到变量值中。 + +### 二、设置环境变量 + +同样，在`Settings > Secrets and variables > Actions`中，添加四个`Repository variables`，分别为： + +| 密钥名 | 内容 | +| ------------- | -------------------------------------------------------- | +| `DEPLOY_HOST` | 服务器IP地址，如`192.168.1.1` | +| `DEPLOY_PATH` | 在服务器上的部署路径，如`/www/wwwroot/blog.cloverta.top` | +| `DEPLOY_PORT` | 服务器SSH端口，一般是`22` | +| `DEPLOY_USER` | 登录用户，例如`root` | +