From 90e708232257526a5855a483d0cbdf2bcf4ccb65 Mon Sep 17 00:00:00 2001 From: deepzz0 Date: Thu, 6 May 2021 11:28:01 +0800 Subject: [PATCH] chore: update docs --- README.md | 69 +++++++++++----------- conf/app.yml | 4 +- docker-compose.yml | 31 ++++++++++ docs/README.md | 92 ++++++++++++++++++++++++++++- docs/amusing.md | 25 ++++++++ docs/backup.md | 2 + docs/install.md | 142 +++++++++++++++++++++++++++++++++++++++++++++ docs/writing.md | 75 ++++++++++++++++++++++++ 8 files changed, 404 insertions(+), 36 deletions(-) create mode 100644 docker-compose.yml create mode 100644 docs/amusing.md create mode 100644 docs/backup.md create mode 100644 docs/install.md create mode 100644 docs/writing.md diff --git a/README.md b/README.md index dd48b84..56de673 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,37 @@ 但它有着部署简单（上线复杂！）的特点，不推荐没有计算机知识的朋友搭建，欢迎咨询。该博客的个中优点（简洁、轻快，安全），等你体验。 +### 快速体验 + +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支持等），仅保持常用简单页面与功能： @@ -38,45 +69,17 @@ 可以容易的看到 [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) -![eiblog-mem](https://st.deepzz.com/blog/img/eiblog-mem.png) +### 更多文档 -> 注：图片1，图片2是博客界面，图片3是后台界面，图片4是内存占用。 - -### 快速体验 - -1、下载程序压缩包：到 [这里](https://github.com/eiblog/eiblog/releases) 下载，解压缩。 - -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 做为搜索引擎： - -``` -# 修改 conf/app.yml ElasticSearch连接配置 -# 如果不启用搜索功能可以置空 -eshost: http://localhost:9200 -``` - -4、启动博客程序： - -``` -./backend -``` +* [安装部署](https://eiblog.github.io/eiblog/install) +* [写作须知](https://eiblog.github.io/eiblog/writing) +* [好玩功能](https://eiblog.github.io/eiblog/amusing) +* [如何备份](https://eiblog.github.io/eiblog/backup) ### 贡献成员 diff --git a/conf/app.yml b/conf/app.yml index 9939672..a4ba39a 100644 --- a/conf/app.yml +++ b/conf/app.yml @@ -27,7 +27,7 @@ eiblogapp: shortname: xxxxxx publickey: wdSgxRm9rdGAlLKFcFdToBe3GT4SibmV7Y8EjJQ0r4GWXeKtxpopMAeIeoI2dTEg accesstoken: 50023908f39f4607957e909b495326af - google: + google: # 谷歌分析 url: https://www.google-analytics.com/collect tid: UA-xxxxxx-1 v: "1" @@ -42,7 +42,7 @@ eiblogapp: site: deepzz02 image: st.deepzz.com/static/img/avatar.jpg address: twitter.com/deepzz02 - feedrpc: + feedrpc: # rss ping feedrurl: https://deepzz.superfeedr.com/ pingrpc: - http://ping.baidu.com/ping/RPC2 diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..b551a6c --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,31 @@ +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 diff --git a/docs/README.md b/docs/README.md index be8e536..56de673 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) 文件中。 + diff --git a/docs/amusing.md b/docs/amusing.md new file mode 100644 index 0000000..71bc6fc --- /dev/null +++ b/docs/amusing.md @@ -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) \ No newline at end of file diff --git a/docs/backup.md b/docs/backup.md new file mode 100644 index 0000000..347052b --- /dev/null +++ b/docs/backup.md @@ -0,0 +1,2 @@ +待完善。。。 + diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..2e48d10 --- /dev/null +++ b/docs/install.md @@ -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`。 \ No newline at end of file diff --git a/docs/writing.md b/docs/writing.md new file mode 100644 index 0000000..2da7b53 --- /dev/null +++ b/docs/writing.md @@ -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: +``` +当程序不能检查到 identifier 的标识符时，会采用长度的方式进行截取。 +