mirrors2/eiblog
1
0
Fork 0
mirror of https://github.com/eiblog/eiblog.git synced 2026-02-04 13:52:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: update docs

Browse Source
This commit is contained in:
deepzz0
2021-05-06 11:28:01 +08:00
parent 3527e11b04
commit 90e7082322
8 changed files with 404 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
docs/README.md
View File

@@ -1 +1,91 @@
Design and user documents (in addition to your godoc generated documentation).
# EiBlog [![Build Status](https://travis-ci.org/eiblog/eiblog.svg?branch=v1.3.0)](https://travis-ci.org/eiblog/eiblog) [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE.md) [![Versuib](https://img.shields.io/github/tag/eiblog/eiblog.svg)](https://github.com/eiblog/eiblog/releases)
> 博客项目结构参考模版：https://github.com/deepzz0/appdemo
用过其它博客系统，不喜欢，不够轻，不够快！这是我开发的第二款博客系统，也实在不想再在这件事情上过多纠结了。`EiBlog` 是一个比较稳定的博客系统，现已迭代至 `2.0` 版本，稳定性和维护你是不用担心的。
但它有着部署简单（上线复杂！）的特点，不推荐没有计算机知识的朋友搭建，欢迎咨询。该博客的个中优点（简洁、轻快，安全），等你体验。
### 快速体验
1、下载程序压缩包：到 [这里](https://github.com/eiblog/eiblog/releases) 下载 eiblog 相应系统压缩包，然后解压缩。
2、启动数据库服务：博客支持多种数据库后端，如MongoDB、MySQL、Postgres、SQLite等。
```
# 修改 conf/app.yml 数据库连接配置
# driver可选：mongodb、mysql、postgres、sqlite、sqlserver、clickhouse、redis等
# source为相应的连接地址
database:
driver: postgres
source: host=localhost port=5432 user=postgres dbname=eiblog sslmode=disable password=MTI3LjAuMC4x
```
3、启动 ES 搜索服务：博客使用 ElasticSearch 2.4.1 做为搜索引擎。
```
# 修改 conf/app.yml ElasticSearch连接配置
# 如果不启用搜索功能可以置空
eshost: http://localhost:9200
```
4、启动博客程序。
```
./backend
```
然后访问 `localhost:9000` 就可以了。
### 功能特性
本着博客本质用来分享知识的特点，`EiBlog` 不会有较强的定制功能（包括主题，CDN支持等），仅保持常用简单页面与功能：
```
首页、专题、归档、友链、关于、搜索
```
功能说明：
- [x] 博客归档，利用时间线帮助我们将归纳博文，内容少于一年按月归档，大于则按年归档。
- [x] 博客专题，有时候博文是同一系列，专题能够帮助我们很好归纳博文，对阅读者是非常友好的。
- [x] 标签系统，每篇博文都可以打上不同标签，使得在归档和专题不满足的情况下自定义归档，这块辅助搜索简直完美。
- [x] 搜索系统，依托ElasticSearch实现的站内搜索，速度与效率并存，再加上google opensearch，搜索只流畅。
- [x] 管理后台，内嵌全功能 `Typecho` 后台系统，全功能 `Markdown` 编辑器让你感觉什么是简洁清爽。
- [x] 谷歌统计，由于google api的速度问题，从而实现了后端API异步统计，使得博客页面加载飞速。
- [x] Disqus评论，国内评论系统不友好，因此选择disqus，又由于众所周知原因国内不能用，实现另类disqus评论方式。
- [x] 多存储后端，支持mongodb、mysql、postgres、sqlite等存储后端。
- [x] 七牛CDN，支持在 `Markdown` 编辑器直接上传附件，让你只考虑编辑内容，解放思想。
- [x] 自动备份，支持多存储后端的备份功能，备份数据保存到七牛CDN上。
当然，为了让整个系统加载速度更快，还做了更多优化措施：
* 文章评论数量（不重要）通过后端跑定时任务获取，所以有时评论数量是不对的，这样减少了 API 调用。
* 整站内容全部内存缓存，`mardown` 文档全部转换为 html 进行缓存，减少了转换过程。
* `.js`、`.css` 等静态文件浏览器本地存储，小图片 base64 内置到 css 中，二次访问不会产生网络带来的延迟，加速访问。通过版本控制更新。
* 最佳实践 nginx 配置，可以查看 `eiblog.conf`，开启压缩缩小传输量，服务器传输证书链、开启 `Session Resumption`、`Session Ticket`、`OCSP Stapling `等加速证书握手，再次提高速度。
### 博客页面
可以容易的看到 [httpsecurityreport](https://httpsecurityreport.com/?report=deepzz.com) 评分`96`，[ssllabs](https://www.ssllabs.com/ssltest/analyze.html?d=deepzz.com&latest) 评分`A+`，[myssl](https://myssl.com/deepzz.com) 评分`A+`，堪称完美。这些安全的相关配置会在后面的部署过程中接触到。
![show-home](https://st.deepzz.com/blog/img/show-home.png)
![show-home2](https://st.deepzz.com/blog/img/show-home2.png)
![show-admin](https://st.deepzz.com/blog/img/show-admin.png)
### 更多文档
* [安装部署](https://eiblog.github.io/eiblog/install)
* [写作须知](https://eiblog.github.io/eiblog/writing)
* [好玩功能](https://eiblog.github.io/eiblog/amusing)
* [如何备份](https://eiblog.github.io/eiblog/backup)
### 贡献成员
![graphs/contributors](https://opencollective.com/eiblog/contributors.svg?width=890&button=false)
### 授权许可
本项目采用 MIT 开源授权许可证，完整的授权说明已放置在 [LICENSE](https://github.com/eiblog/eiblog/blob/master/LICENSE) 文件中。

25
docs/amusing.md Normal file
View File

@@ -0,0 +1,25 @@
### Twitter Card
相信很多人不明白为什么会这样专注 twitter。首先 twitter 是一个社交网站，国际性的。其次我们可以使用它的Twitter Card 功能非常的酷。
当你配置好 Twitter 相关的参数后`conf/app.yml`：
```
# twitter地址: twitter.com/chenqijing2
twitter:
card: summary
site: chenqijing2
image: st.deepzz.com/static/img/avatar.jpg
address: twitter.com/chenqijing2
```
每当你发部一个推文，你如果带上你的网址，它会自动给你展示成卡片的形式
![twitter-pub](https://st.deepzz.com/blog/img/twitter-pub.png)
![twitter-pub2](https://st.deepzz.com/blog/img/twitter-pub2.png)
可以看到`，`之前是没有内容的，该内容是我们文章的描述。
### Google OpenSearch
在 Chrome 浏览器上，你可以在输入网站后按 TAB 键进入搜索模式，如：
![opensearch](/Users/edz/go/src/github.com/eiblog/eiblog/opensearch.gif)

2
docs/backup.md Normal file
View File

@@ -0,0 +1,2 @@
待完善。。。

142
docs/install.md Normal file
View File

@@ -0,0 +1,142 @@
这里只介绍通过 docker 进行安装部署的方式，二进制安装也可参考。
* [存储后端](#存储后端)
* [搜索引擎](#搜索引擎)
* [准备工作](#准备工作)
* [开始部署](#开始部署)
博主提供了下面将要用到的镜像，可到这里查看：[https://hub.docker.com/u/deepzz0](https://hub.docker.com/u/deepzz0)。由于所有配置均在 `app/conf.yml` 下，所以在通过 docker 部署时建议将配置映射出来方便调试。
### 存储后端
首先启动我们的存储后端，用来存储我们的博客数据。eiblog 目前支持多种存储后端：
```
# driver # source
mongodb mongodb://localhost:27017
postgres host=localhost port=5432 user=user dbname=eiblog sslmode=disable password=password
mysql user:password@tcp(127.0.0.1:3306)/eiblog?charset=utf8mb4&parseTime=True&loc=Local
sqlite /path/eiblog.db
sqlserver sqlserver://user:password@localhost:9930?database=eiblog
clickhouse tcp://localhost:9000?database=eiblog&username=user&password=password&read_timeout=10&write_timeout=20
```
选择自己最熟悉的方式作为存储后端，然后修改 `conf/app.yml` 下的数据库地址：
```
database:
driver: postgres
source: host=localhost port=5432 user=postgres dbname=eiblog sslmode=disable password=MTI3LjAuMC4x
```
### 搜索引擎
博客强依赖 ElasticSearch 搜索引擎，如果仅调试可以跳过不部署。但对外提供服务强烈建议部署上 ES，这样可以提高体验感。博主提供了一个已经配置好的 docker 镜像：`deepzz0/es`：
```
# 运行
$ docker run --name es \
-p 9200:9200 \
deepzz0/es:latest
```
修改 `conf/app.yml` 下的 `eshost` 配置：
```
# 如果不部署，请置空
eshost: http://localhost:9200
```
### 准备工作
整个博客部署的复杂点就在这里了，如果你真的想要一款不想再更换的博客，那么继续。
#### 提前准备
请提前准备好以下内容，方便后续工作：
* `一台服务器`，对外提供访问能力。
* `一个域名`，如果服务器在国内域名需要备案（免费域名不建议）。
* `SSL证书`，博客要求全站 HTTPS 访问 + 七牛 CDN。
* `Disqus评论`，作为博客评论系统，如果申请请自行 Google。简单说需要提供 `shortname` 和 `public key`。
* `Google Analystic`，数据统计分析工具。
* `Superfeedr`，加速 RSS 订阅。
* `Twitter账号`，希望你能有一个 twitter 账号。
要求很多吧。其实当初该博客系统只是为个人而设计的，是自己心中想要的那一款。博主些这篇文章不是想要多少人来用该博客，而是希望对那些追求至极的朋友说：你需要这款博客系统。
#### 文件准备
博主是一个有强迫症的人，一些文件的路径我使用了固定的路径，请大家见谅。假如你的 cdn 域名为 `st.example.com`，你需要确定这些文件已经在你的 cdn 中，它们路径分别是：
| 文件 | 地址 | 描述 |
| ------------------ | -------------------------------------------- | ------------------------------------------------------------ |
| favicon.ico | st.example.com/static/img/favicon.ico | cdn 名为 `static/img/favicon.ico`。你也可以在代理服务器自行配置，只要通过 example.com/favicon.ico 也是能够访问到。 |
| bg04.jpg | st.example.com/static/img/bg04.jpg | cdn 名为 `static/img/bg04.jpg`，首页左侧的大背景图，需要更名请到 website/st_blog.css 修改。 |
| avatar.png | st.example.com/static/img/avatar.png | cdn 名为 `static/img/avatar.png`，个人博客头像 |
| blank.gif | st.example.com/static/img/blank.gif | cdn 名为 `static/img/blank.gif`，空白图片，复制链接下载 https://st.deepzz.com/static/img/blank.gif。 |
| default_avatar.png | st.example.com/static/img/default_avatar.png | cdn 名为 `static/img/default_avatar.png`，disqus 默认头像图片，复制链接下载 https://st.deepzz.com/static/img/default_avatar.png |
> 注意：
>
> 1. cdn 提到的文件下载，请复制链接进行下载，因为博主使用了防盗链功能。
> 2. 每次修改 app.yml 文件（如：更换 cdn 域名或更新头像），如果你不知道是否应该提高 staticversion 一个版本，那么最好提高一个 +1。
> 3. 每次手动修改 website 内的以 `st_` 开头的文件，请将 `app.yml` 中的 staticversion 提高一个版本。
#### 配置说明
走到这里，我相信只走到 `80%` 的路程。放弃还来得及。这里会对 `eiblog/conf` 下的所有文件做说明，希望你做好准备。
```
├── app.yml # 整站配置
└── tpl # 相关模版
├── crossdomainTpl.xml
├── feedTpl.xml
├── opensearchTpl.xml
├── robotsTpl.xml
└── sitemapTpl.xml
```
具体的配置内容已经在 `app.yml` 中进行说明了。
如果用 nginx 作为代理服务器，博主提供了一份示例配置 `eiblog/eiblog.conf`，该配置涉及到 `ssl` 相关配置建议存放于 `/etc/nginx/ssl` 下。其中关于 `ssl_dhparam`、站点认证均提供了相关配置。
### 开始部署
下面是博主通过 `docker-compose` 一键部署的文件内容，仅供参考：
```
version: '3'
services:
mongodb:
image: mongo:3.2
volumes:
- ${PWD}/mgodb:/data/db
restart: always
elasticsearch:
image: deepzz0/es:2.4.1
environment:
- ES_JAVA_OPTS="-Xms512m -Xmx512m"
restart: always
eiblog:
iamge: deepzz0/eiblog:latest
volumes:
- ${PWD}/conf:/app/conf
extra_hosts:
- "disqus.com:23.235.33.134"
links:
- elasticsearch
- mongodb
ports:
- 9000:9000
restart: always
backup:
image: deepzz0/backup:latest
volumes:
- ${PWD}/conf:/app/conf
links:
- mongodb
restart: always
```
当启动成功之后，后续的代理配置请参考 `eiblog/eiblog.conf`。

75
docs/writing.md Normal file
View File

@@ -0,0 +1,75 @@
### 郑重提醒
**标题**、**slug**、**内容**。在你点击保存的时候一定确保三者不能为空，否则页面刷新内容就没了。所以，养成一个良好的写作习惯很重要。
当然，博客的自动保存功能也非常的好。在你不确定是否发布前，你可以将之保存到草稿，以便下次继续编辑。
### 文章标题
文章标题，这个可能要看个人习惯。我习惯从三级标题开始（###），依次往下四级标题，五级标题...。要注意的是一定不能跳级：
```
### 标题一
#### 标题1.1
#### 标题1.2
##### 标题1.2.1
##### 标题1.2.2
### 标题二
##### 标题2.1
##### 标题2.2
###### 标题2.2.1
###### 标题2.2.2
```
结果是：
![article-title](https://st.deepzz.com/blog/img/article-title.png)
### 文章描述
文章描述，主要是给`html->head->meta`中的 name 为 description 用的。现采用了一个临时的办法：在文章的第一行通过前缀识别（只看第一行）。
该前缀可到`conf/app.yml`设置，默认为`Desc:`，如：
![article-description](https://st.deepzz.com/blog/img/article-description.png)
### 图片懒加载
博客系统提供图片懒加载功能（浏览到某个位置，图片才会加载），以此来提高页面加载速度。我们可根据需要是否使用。当然由此带来的坏处就是rss不能够正确加载图片。后续看是否解决这个问题或朋友提PR。
首先看下图片的`markdown`标准写法：
```
![alt](img_addres)
```
如：
```
![sublime-dialog](https://st.deepzz.com/blog/img/dialog-box-without-all-contols.png)
```
![sublime-dialog](https://st.deepzz.com/blog/img/dialog-box-without-all-contols.png)
懒加载，需要为该图片指定大小（长高）：
```
![alt](img_addres =widthxheight)
```
x 为小写字母（x,y,z）中的 x。使页面未加载时也占了相应的位置大小，这样设计是为了让读者在浏览页面时不会感到抖动。
如：
```
![sublime-dialog](https://st.deepzz.com/blog/img/dialog-box-without-all-contols.png =640x301)
```
### 摘要截取
摘要截取主要是提供给首页显示，如：
![deepzz-home-page](https://st.deepzz.com/blog/img/deepzz-home-page.jpg)
红框中圈出来的就是截取出来的内容。在 `conf/app.yml` 的配置项有两个：
```
# 自动截取预览, 字符数
length: 400
# 截取预览标识
identifier: <!--more-->
```
当程序不能检查到 identifier 的标识符时，会采用长度的方式进行截取。