quick-start.md 9.13 KB

Edit Raw Blame History



快速开始


重要：关于此部分有疑惑，请在下面直接评论，或者到社区讨论
如果您已经熟悉并已经安装了 Node、Yarn，可以直接参照下面的命令，快速上手
如果您不熟悉，请阅读下面的详细教程


快速体验


以下三种方式，任选其中一种即可


一、一键脚本（推荐！）

git clone https://github.com/ly525/luban-h5 && cd luban-h5
# 安装依赖，构建前后端（安装依赖会耗时略长，请耐心等待）
./luban-h5.sh init

# 启动项目访问 http://localhost:1337 即可
./luban-h5.sh start

# ./luban-h5.sh stop


更多细节，请参照 鲁班H5-在线文档 的 快速开始 章节，进行配置即可
如果遇到接口 403 问题，请参照 快速开始 章节，搜索关键字：403 即可


二、本地安装了 Node、Yarn

git clone https://github.com/ly525/luban-h5
cd luban-h5 # 项目根目录

# 后端
cd back-end/h5-api && yarn && yarn dev

# 前端
# 新开一个终端，在项目根目录执行如下命令
cd front-end/h5 && yarn && yarn build:engine && yarn dev


按照提示，在浏览器中访问终端中提示的 URL 即可
更多细节，请参照 鲁班H5-在线文档 的 快速开始 章节，进行配置即可


三、熟悉 Docker（迭代中，不推荐使用，后期会推出docker image）


使用官方提供的 一键安装脚本，简化安装步骤，在本地通过使用 Docker+Ubuntu 镜像，即可快速安装+体验 鲁班H5

快速体验-完整文档，简而言之：


docker pull ubuntu
docker run -it -p 1234:80 -p 1235:1337  -v `pwd`:/app ubuntu
# 使用清华大学 Ubuntu 软件镜像
sed -i 's/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list
apt update && apt install -y wget git
wget -qO- https://raw.githubusercontent.com/ly525/luban-h5/dev/deploy/ubuntu-install.sh | bash

# 安装完成之后
# 1. visit ：http://localhost:1234/admin，自定义配置账号密码，登录即可
# 1.2 配置相关权限，文档参见：https://ly525.github.io/luban-h5/zh/getting-started/quick-start.html#%E5%90%8E%E7%AB%AF%E7%8E%AF%E5%A2%83%E6%90%AD%E5%BB%BA

# 2. 鲁班前端
# 2.1 宿主机访问 「鲁班前端」：localhost:1234, 即可看到鲁班的前端


常见问题


这部分一般是按照下面的教程运行之后，仍然可能会遇到的问题。比较适合粗心、文档只看了一半、比较着急的同学


接口 403 Forbidden，解决方案看这里：#_2-注意事项

弹框中的 预览页面显示空白，解决方案看这里：2. 构建预览所需的渲染引擎


视频教程

 
基础概念


首先你需要大概了解下 Node.js 的相关生态、Node.js 的安装
我们接下来会花几分钟介绍一下基础概念. 我们默认你知道 Linux 和 Git 的基本操作


Node.js、npm、nvm


Node.js 
服务器端的JavaScript 运行环境，你可以理解为和Python、Java等一样，它也是一门后端语言

npm(or yarn) Node.js 的包版本工具


类似于 Python 的pip，或 Centos 的yum，或 Ubuntu 的 apt-get
你在python 中安装requrest 库，通常是通过 pip install requests 来安装
在 Node.js 中，也是一样的，只是把 pip 换成 pip or yarn 即可： npm install requests  or yarn add requests 


nvm ：Node.js 版本工具


使用 nvm可以快速安装 Node 的某个版本，比如通过 node -v 查看你的Node 当前版本。
假如这个版本(假设当前版本为 v.8.0.0)不符合要求，你可以通过 nvm install v10.15.3 来安装 v10.15.3 


Node、Yarn、npm 安装


请参照 Strapi 的 预安装文档指导 ，安装 Node、npm 和 Yarn
因为 yarn 的仓库源在海外，所以，请配置国内镜像源，提高速度


yarn config get registry
# -> https://registry.yarnpkg.com

# 改成 taobao 的源：
yarn config set registry https://registry.npm.taobao.org
# -> yarn config v0.15.0
# -> success Set "registry" to "https://registry.npm.taobao.org".

# 看到 succes 表示安装完毕


技术栈(当前)


前端：Vue.js
后端：Strapi
存储：Sqlite


项目环境搭建


鲁班H5的后端接口，由 Strapi.js 驱动


后端环境搭建


如果遇到接口 403 问题，请看：#_2-注意事项


1. 快速上手


# 默认当前目录为 luban 项目的根目录
cd back-end/h5-api
# 使用 yarn 安装依赖，而非 npm
# 原因参见：https://github.com/ly525/luban-h5/issues/92
yarn install # 安装依赖

yarn dev
# 补充说明: 如果需要在 vscode 中进行debug ，请使用 npm run localdev

# #!en: default database is sqlite3(h5-api/.tmp/data.db)
# #!zh: 默认数据库是 sqlite3，位置在 h5-api/.tmp/data.db

# 访问 http://localhost:1337/admin
# visit http://localhost:1337/admin

请继续阅读，进行相关配置


2. 注意事项


如何打开下图所示的页面呢？对于node 后端框架， 大家知道比较多的可能是 阿里的 egg.js、express.js、koa.js，鲁班H5采用的是 strapi.js 作为其后端框架，答疑:为何采用Strapi.js作为后端?

我们在上一步cd back-end/h5/api && yarn && yarn dev之后，就可以打开 strapi.js 其自带的管理后台了（用来管理数据库Model、接口权限、注册用户、新增用户等），本地访问地址为：http://localhost:1337/admin

请将右上角语言改为：zh-Hans(简体中文)，如果你是第一次访问：http://localhost:1337/admin ，那么你需要按照页面的提示进行注册下（和你正常注册淘宝一样，输入邮箱、用户名、密码、确认密码即可），这个注册只是本地注册，没有其它影响。注册完成之后，就可以使用刚才注册的账号、密码登录了


本地开发，如果后端接口报错 403 Forbidden，请按照下图的操作，打开接口的访问权限接口：[Roles And Permission] -> [Public] - [Permissions]


上传封面图使用


前端环境搭建


1. 快速上手

# 默认当前位置目录为 luban-h5 项目的根目录
cd front-end/h5 && yarn && yarn build:engine && yarn dev

# 更多命令请参见 project/front-end/h5/package.json


2. 构建预览所需的渲染引擎


如果在「1. 快速上手」 已经执行了 yarn build:engine，这一步可以跳过
关于此部分有疑惑，请直接到社区评论即可


只需要在front-end/h5目录下，运行：yarn build:engine 即可
下面的内容感兴趣可以了解，感觉内容太多可以不看


2.1 基本原理

作品预览的基本原理参见 previewOne，关键代码如下：

previewOne: async (ctx) => {
  const work = await strapi.services.work.findOne(ctx.params);
  return ctx.render('engine', { work });
},


2.2 如何构建


在front-end/h5目录下，运行：yarn build:engine

构建完成之后，后端的h5-api/public里面会多一个文件夹 engine-assets

打开的预览窗口preview.vue, 里面的预览部分对应的其实是一个 iframe，可以看看对应的源码
这个预览其实依赖后端的模板引擎（比如 ejs、jade等）
参照这里luban-h5/front-end/h5/vue.config.js的engineOutputDir 变量（这个变量就是预览引擎构建完成，生成的文件所在的目录。默认是后端的 back-end/h5-api/public/engine-assets 目录）


欢迎大家到鲁班H5-社区 交流，在这里可以提问、反馈意见和建议，与作者直接互动