Merge pull request #30 from mlogclub/docs

完善使用文档
mlogclub · Nov 8, 2019 · 451612d · 451612d
2 parents 11bb495 + 84f5b9a
commit 451612d
Show file tree

Hide file tree

Showing 4 changed files with 143 additions and 54 deletions.
diff --git a/admin/src/apis/HttpClient.js b/admin/src/apis/HttpClient.js
@@ -2,11 +2,14 @@ import axios from 'axios';
 import qs from 'qs';
 import cookies from 'js-cookie'
 
+
+// 接口地址，请替换为你自己的
+const baseURL = 'https://mlog.club'
+
 class HttpClient {
   constructor() {
     this.http = axios.create({
-      // 请替换为你自己的接口地址
-      baseURL: 'https://mlog.club'
+      baseURL: baseURL
     });
     this.http.defaults.headers.common['X-Client'] = 'bbs-go-admin';
     this.http.defaults.headers.post['Content-Type'] = 'application/x-www-form-urlencoded';

diff --git a/docs/guide.md b/docs/guide.md
@@ -22,15 +22,15 @@ bbs-go 是一款基于Go语言开发的论坛系统，采用前后端分离技
 - 收藏功能
 - 站内消息
 
-## 演示
-
-[https://mlog.club](https://mlog.club)
-
-## 源码
+## 项目地址
 
 - Github：[https://github.com/mlogclub/bbs-go](https://github.com/mlogclub/bbs-go)
 - 码云：[https://gitee.com/mlog/bbs-go](https://gitee.com/mlog/bbs-go)
 
+## 演示
+
+[https://mlog.club](https://mlog.club)
+
 ## 技术栈
 
 - iris ([https://github.com/kataras/iris](https://github.com/kataras/iris)) Go语言 mvc 框架
@@ -42,56 +42,118 @@ bbs-go 是一款基于Go语言开发的论坛系统，采用前后端分离技
 - element-UI ([https://element.eleme.cn](https://element.eleme.cn)) 饿了么开源的基于 vue.js 的前端库
 - vditor ([https://github.com/b3log/vditor](https://github.com/b3log/vditor)) Markdown 编辑器
 
+## 获取源码
+
+`bbs-go`的源码托管在Github：[https://github.com/mlogclub/bbs-go](https://github.com/mlogclub/bbs-go)，通过以下命令将源代码克隆到本地：
+
+```bash
+git clone https://github.com/mlogclub/mlog.git
+```
+
 ## 项目结构
 
-bbs-go采用前后端分离技术，网站和后台均使用`http api`进行数据通信。所以bbs-go包含三个模块：server、site、admin。
+bbs-go采用前后端分离技术，网站和后台均使用`http api`进行数据通信。bbs-go包含三个模块：server、site、admin，三个模块的介绍如下：
 
 ### server模块
 
-server模块是基于Go语言搭建的，为bbs-go提供数据接口支撑的服务。
+`server`模块基于Go语言开发，他为整个项目提供接口数据支撑。`site`和`admin`模块的数据都是从该模块获取的。
 
 ### site模块
 
-site模块使用`nuxt.js`进行搭建，该模块是bbs-go的用户前端网页。nuxt.js相关知识可以去它的官网查看：[https://nuxtjs.org](https://nuxtjs.org)
+`site`模块使用`nuxt.js`进行搭建，该模块是bbs-go的用户前端网页。`nuxt.js`相关知识可以去它的官网查看：[https://nuxtjs.org](https://nuxtjs.org)
 
 ### admin模块
 
-admin模块是bbs-go的管理后台，他基于element-ui搭建，element-ui相关知识可以去它的官网查看：[https://element.eleme.cn](https://element.eleme.cn/)
+`admin`模块是`bbs-go`的管理后台，他基于`element-ui`搭建，`element-ui`相关知识可以去它的官网查看：[https://element.eleme.cn](https://element.eleme.cn/)
+
+## 配置详解
+
+### server模块配置
+
+`server`模块的示例配置文件为`server/bbs-go.example.yaml`，内容如下：
+
+```yaml
+Env: prod # 环境，线上环境：prod、测试环境：dev
+BaseUrl: https://mlog.club # 网站域名
+Port: '8082' # 端口
+LogFile: /data/logs/bbs-go.log # 日志文件
+ShowSql: false # 是否打印sql
+StaticPath: /data/www  # 根路径下的静态文件目录，可配置绝对路径
+
+# 数据库连接
+MySqlUrl: username:password@tcp(localhost:3306)/bbsgo_db?charset=utf8mb4&parseTime=True&loc=Local
+
+# github登录配置
+Github:
+  ClientID:
+  ClientSecret:
+
+# qq登录配置
+QQConnect:
+  AppId:
+  AppKey:
+
+# 阿里云oss配置
+AliyunOss:
+  Host: 请配置成你自己的
+  Bucket: 请配置成你自己的
+  Endpoint: 请配置成你自己的
+  AccessId: 请配置成你自己的
+  AccessSecret: 请配置成你自己的
+
+# 邮件服务器配置，用于邮件通知
+Smtp:
+  Addr: smtp.qq.com
+  Port: '25'
+  Username: 请配置成你自己的
+  Password: 请配置成你自己的
+
+# 百度ai配置，用于自动分析文章摘要、标签
+BaiduAi:
+  ApiKey:
+  SecretKey:
+```
 
-## 本地快速安装
+请复制该文件到：`server/bbs-go.yaml`，并根据配置文件中的注释将配置修改成你自己的。
 
-> 说明：适用于本地开发和体验，各端运行后需要保持前台窗口进程。
+### site模块配置
 
-### 安装依赖
+`site`模块是基于`nuxt.js`开发的，他的配置文件为：`site/nuxt.config.js`，我们主要关注一下两项配置即可：
 
-```shell
-# 第一步 clone 代码
-git clone https://github.com/mlogclub/mlog.git
+1. port：site模块启动端口，默认为3000
+2. proxy：`server`模块的连接地址，通过该地址可以请求`server`模块数据
 
-# 第二步 安装依赖
-cd mlog
-go mod tidy
-```
+### admin模块配置
 
-> 说明  :bbs-go 的依赖是使用go mod来进行管理的，go mod使用帮助看这里：[https://mlog.club/topic/9](https://mlog.club/topic/9)
+`admin`模块基于`vue`+`element-ui`开发，它是`bbs-go`的管理后台。 `server`模块为`admin`模块提供接口， `admin`模块提供UI界面，所以`admin`模块只需要配置`server`模块的接口地址即可，配置文件在：`admin/src/apis/HttpClient.js`，请将该文件中的`baseURL`配置为你自己的。
 
-### 配置文件
+## 快速启动
 
-在server目录中新建bbs-go.yaml配置文件（或者将bbs-go.example.yaml重命名)，配置内容请参考bbs-go.example.yaml中的说明。
+`bbs-go`总用有三个模块：server、site、admin，接下来我们一步步的启动这三个模块。
 
-> **注意：运行项目前先配置好数据库，否则程序无法运行。**
+### server模块启动
 
-### 启动服务
+#### 安装依赖
 
-在server目录中运行命令：
+server模块使用`go mod`管理依赖，如果你不清楚如何使用`go mod`，请先认真读一下下面两篇文章：
 
-```shell
-go run main.go
+- [go mod使用帮助](https://mlog.club/topic/617)
+- [配置go mod代理](https://mlog.club/topic/618)
+
+在项目的`server`目录下执行下面命令来下载`server`模块依赖：
+
+```bash
+go mod download
 ```
 
-### 数据初始化
+#### 初始化数据库
+
+新建数据库`bbsgo_db`(或者其他名字，你高兴就好)。并按照要求配置好你的数据库链接（请参见：[ server模块配置](#server模块配置)）。
+
+配置好数据库链接后，`bbs-go`在启动的时候会自动建表，所以我们无需手动建表，但是有些数据是需要提前初始化的，例如：管理员用户，基本配置，所以我们需要执行下面sql脚本进行数据初始化：
 
 ```sql
+```sql
 -- 初始化用户表
 CREATE TABLE IF NOT EXISTS `t_user` (
   `id` bigint(20) NOT NULL AUTO_INCREMENT,
@@ -135,37 +197,62 @@ insert into t_sys_config(`key`, `value`, `name`, `description`, `create_time`, `
     ('siteDescription', 'bbs-go，基于Go语言的开源社区系统', '站点描述', '站点描述', 1555419028975, 1555419028975),
     ('siteKeywords', 'bbs-go', '站点关键字', '站点关键字', 1555419028975, 1555419028975),
     ('siteNavs', '[{\"title\":\"首页\",\"url\":\"/\"},{\"title\":\"话题\",\"url\":\"/topics\"},{\"title\":\"文章\",\"url\":\"/articles\"}]', '站点导航', '站点导航', 1555419028975, 1555419028975);
+```
+```
+
+#### 配置server模块
+
+参见：[ server模块配置](#server模块配置)
+
+#### 启动server模块
+
+再配置好数据库链接并初始化数据库之后，在server模块目录下执行下面脚本启动server模块：
+
+```bash
+go run main.go
 ```
 
-### 启动网站前端
+### site模块启动
 
-在site目录中运行命令：
+第一步：进入site模块目录，执行下面命令安装依赖：
 
-```shell
+```bash
 npm install
+```
+
+第二步：打开`site/nuxt.config.js`进行相关配置，请参见：[site模块配置](#site模块配置)。
+
+第三步：执行下面命令启动site模块服务：
+
+```bash
 npm run dev
 ```
 
 正常启动后，打开 [http://127.0.0.1:8080](http://127.0.0.1:8080) 访问网站。
 
-### 启动管理后台
+### admin模块启动
+
+第一步：进入admin模块模块，执行下面命令安装依赖：
 
-```shell
+```bash
 npm install
-npm run serve
 ```
 
-正常启动后，打开 [http://127.0.0.1:8080](http://127.0.0.1:8080) 访问管理后台。
+第二步：配置接口链接地址，请参见：[admin模块配置](#admin模块配置)。
 
-## 生产环境编译部署
+第三步：执行下面命令启动admin模块服务：
 
-编译安装
+```bash
+npm run serve
+```
+
+正常启动后，打开 [http://127.0.0.1:8080](http://127.0.0.1:8080) 访问管理后台。
 
-> TODO
+## Docker启动
 
-Docker安装
+感谢 [athom](https://github.com/athom) ，Docker启动功能由 [athom](https://github.com/athom) 提供支持，详见：[https://github.com/mlogclub/bbs-go/pull/25](https://github.com/mlogclub/bbs-go/pull/25)
 
-> TODO
+使用Docker快速启动项目，首先参照[配置详解](#配置详解)，配置好你的项目，然后执行项目根目录下的：up.sh 启动服务。
 
 ## 问题反馈
 

diff --git a/server/bbs-go.example.yaml b/server/bbs-go.example.yaml
@@ -5,8 +5,8 @@ LogFile: /data/logs/bbs-go.log # 日志文件
 ShowSql: false # 是否打印sql
 StaticPath: /data/www  # 根路径下的静态文件目录，可配置绝对路径
 
-# 数据库配置
-MySqlUrl: username:password@tcp(localhost:3306)/bbsgo_db?charset=utf8mb4&parseTime=True&loc=Local  # 数据库链接
+# 数据库连接
+MySqlUrl: username:password@tcp(localhost:3306)/bbsgo_db?charset=utf8mb4&parseTime=True&loc=Local
 
 # github登录配置
 Github:
@@ -20,20 +20,20 @@ QQConnect:
 
 # 阿里云oss配置
 AliyunOss:
-  Host: https://file.mlog.club/
-  Bucket: bucket-name
-  Endpoint: oss-cn-hongkong-internal.aliyuncs.com
-  AccessId: accessId
-  AccessSecret: accessSecret
+  Host: 请配置成你自己的
+  Bucket: 请配置成你自己的
+  Endpoint: 请配置成你自己的
+  AccessId: 请配置成你自己的
+  AccessSecret: 请配置成你自己的
 
-# 邮件服务器配置
+# 邮件服务器配置，用于邮件通知
 Smtp:
   Addr: smtp.qq.com
   Port: '25'
-  Username: xxx
-  Password: xxx
+  Username: 请配置成你自己的
+  Password: 请配置成你自己的
 
-# 百度ai配置
+# 百度ai配置，用于自动分析文章摘要、标签
 BaiduAi:
   ApiKey:
   SecretKey:
diff --git a/site/nuxt.config.js b/site/nuxt.config.js
@@ -72,7 +72,6 @@ export default {
 
   proxy: {
     '/api/': 'http://localhost:8082'
-    // '/api/': 'https://mlog.club/'
   },
 
   // Doc: https://github.com/shakee93/vue-toasted