docs: update local development and deployment

ly525
1 parent 4090dcd0
Showing 3 changed files with 382 additions and 48 deletions
docs/zh/getting-started/deployment.md
docs/zh/getting-started/features.md
docs/zh/getting-started/quick-start.md
 # Deployment/部署
-## Heroku
-已经部署完毕，待完善
-
 ## 阿里云/腾讯云/Digital Ocean
-TODO
+#### 云服务器(centos)
+首先需要安装一些基础的软件包，请自行安装（具体参照其官网文档）
+
+-  node
+-  npm
+-  nginx
+-  yarn
+-  pm2
+
+以下脚本仅供参考
+
+```bash
+# install yarn
+curl --silent --location https://dl.yarnpkg.com/rpm/yarn.repo | sudo tee /etc/yum.repos.d/yarn.repo
+sudo yum install yarn -y
+
+# install nginx
+sudo yum install nginx -y
+# install pm2
+npm install pm2 -g
+# pm2 examples
+# pm2 start server.js
+# pm2 stop server
+# pm2 restart server
+# pm2 stop all
+
+```
+
+nginx 配置文件 demo
+
+```nginx
+server {
+  listen 443;
+  server_name your_domain;
+
+  client_body_buffer_size 20M;
+  client_max_body_size 20M;
+  proxy_buffer_size 20M;
+  proxy_buffers 32 20M;
+  proxy_busy_buffers_size 20M;
+
+  ssl on;
+  ssl_certificate cert/luban-api.pem;
+  ssl_certificate_key cert/luban-api.key;
+  ssl_session_timeout 5s;
+  ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
+  ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
+  ssl_prefer_server_ciphers on;
+
+  gzip on;
+  gzip_min_length 1k;
+  gzip_buffers 4 16k;
+  gzip_disable "MSIE [1-6]\.";
+  gzip_comp_level 3;
+  gzip_types image/png application/json text/plain application/x-javascript text/css application/xml text/javascript application/javascript;
+
+  # TODO 这边的 psd-files、engine-assets、third-libs 开发的时候，可以走 proxy_pass
+  # 生产环境的时候，最好走另外的 location，直接让 nginx 访问静态文件
+  location ~ ^/(upload|content-manager|users-permissions|works|admin|psd-files|workforms|third-libs|engine-assets) {
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_pass http://localhost:1337;
+  }
+  location / {
+
+    root /home/centos/codebase/luban/luban-h5-dist/front-end/;
+    #try_files $uri $uri/ /index.html;
+  }
+
+}
+```
+
+#### 本地执行：
+请先提前调研：flightplan
+在项目根目录作如下操作：
+
+```bash
+yarn add flightplan // 部署脚本，官方链接
+npm run deploy:esc // 云服务器 (Elastic Compute Service, 简称 ECS)
+```
+
+本地部署脚本
+
+```javascript
+var os = require('os');
+var plan = require('flightplan');
+
+// configuration
+local_dist_dir = './'; // root path for luban-h5
+remote_project_dir = '~/codebase/luban/luban-h5'; // root path for luban-h5 on server
+remote_project_api_dir = '~/codebase/luban/luban-h5/back-end/h5-api'; // api root path for luban-h5 on server
+
+// production server config
+plan.target('production', {
+  host: 'your host ip', // your server ip
+  username: 'centos', // your server username
+  // 更新为绝对路径
+  privateKey: `${os.homedir}/.ssh/id_rsa` // your privateKey to rsync files
+});
+
+/**
+ * 1. setup folders
+ * 2. sync files
+ * 3. install dependencies
+ * 4. (re)start api service
+ * 5. soft link nginx conf
+ *
+ * 1. 创建同步文件件
+ * 2. 同步本地在 git 中的文件（你也可以在服务器端git clone）
+ * 3. 在 h5-api 目录安装依赖
+ * 4. 使用pm2 重启服务
+ * 5. 给 nginx 文件做一个软件链接
+ *
+ */
+
+// init remove server path
+// 在第一步的时候，需要打开这一项：初始化服务器，现在还不完整，需要补充
+// plan.remote(remote => {
+//   // remove.exec(`mkdir -p ${remote_project_dir}`)
+//   remove.sudo(`yum install nginx -y`)
+//   remote.with(`mkdir -p ${remote_project_dir}`, () => {
+//     // remote.log('Install dependencies');
+//     // remote.exec('yarn');
+//     remote.exec('pwd');
+//   });
+// });
+
+
+// run commands on localhost
+plan.local(local => {
+  // local.log('=> Run build');
+  // local.exec('npm run build');
+  // local.log('=> Build finish');
+
+  local.log('=> Copy files to remote hosts');
+  // TODO reference: https://github.com/pstadler/flightplan/issues/142
+  local.with(`cd ${local_dist_dir}`, () => {
+    // const filesToCopy = local.exec('find . -type f', { silent: true })
+    const filesToCopy = local.git('ls-files', {silent: true}) // get list of files under version control
+
+    local.transfer(filesToCopy, remote_project_dir);
+    local.log('=> Copy finish');
+
+  });
+});
+
+// run commands on the target's remote hosts
+plan.remote(remote => {
+  remote.with(`cd ${remote_project_api_dir}`, () => {
+    remote.log('Install dependencies');
+    remote.exec('yarn');
+    remote.exec('pm2 restart server')
+  });
+});
+
+
+```
+
+
+
+#### 中间可能遇到的一些问题：
+
+1. `Cannot parse privateKey: Unsupported key format` 
+解决方案请参照：[Cannot parse privateKey: Unsupported key format](https://stackoverflow.com/questions/53400628/cannot-parse-privatekey-unsupported-key-format)
+
 ## Docker 部署
-TODO
+
+> 以下方案来自：[https://github.com/yi-ge/luban-h5#docker-%E9%83%A8%E7%BD%B2](https://github.com/yi-ge/luban-h5#docker-%E9%83%A8%E7%BD%B2)，非常非常感谢。
+> 但仅供参考，此方案不是鲁班的官方的解决方案
+>
+> 鲁班决定暂时不按照这种方案来做，可以先使用上面部署脚本来发布到服务器上，进行部署。
+> 鲁班后期考虑出一个简单版本docker image的部署方案，直接拉镜像，在服务器端就能直接跑起来。
+>
+
+请确保您的`80`端口和`443`端口均打开，如果已经配置了其它项目，请进行手工调整。
+
+1. 修改`yourdomain.tld`为您的前端域名并解析到服务器。
+1. 修改`api.yourdomain.tld`为您的后端域名并解析到服务器。
+1. 依次执行以下命令。
+
+```bash
+# Clone luban-h5
+git clone https://github.com/ly525/luban-h5.git
+cd luban-h5
+
+# Install require package
+docker run --rm -v `pwd`:/root -w /root/back-end/h5-api node:12.8.1 bash -c "yarn && NODE_ENV=production yarn build"
+
+docker run --rm -v `pwd`:/root -w /root/front-end/h5 \
+    --env "PUBLIC_PATH=/" \
+    --env "PROD_API_ORIGIN=api.yourdomain.tld" \
+    node:12.8.1 bash -c "yarn && NODE_ENV=production yarn build && node build/engine.webpack.js"
+
+# Start back-end
+docker run --detach \
+    --name nginx-proxy \
+    --publish 80:80 \
+    --publish 443:443 \
+    --volume /etc/nginx/certs \
+    --volume /etc/nginx/vhost.d \
+    --volume /usr/share/nginx/html \
+    --volume /var/run/docker.sock:/tmp/docker.sock:ro \
+    jwilder/nginx-proxy
+
+docker run --detach \
+    --name nginx-proxy-letsencrypt \
+    --volumes-from nginx-proxy \
+    --volume /var/run/docker.sock:/var/run/docker.sock:ro \
+    jrcs/letsencrypt-nginx-proxy-companion
+
+docker run -itd -m 512m \
+    --restart=always \
+    --name luban-h5-front \
+    -v `pwd`/front-end/h5/dist:/usr/share/nginx/html \
+    --env "NODE_ENV=production" \
+    --env "VIRTUAL_HOST=yourdomain.tld" \
+    --env "LETSENCRYPT_HOST=yourdomain.tld" \
+    --env "PROD_API_ORIGIN=api.yourdomain.tld" \
+    nginx
+
+# Start font-end
+docker run -itd -m 1024m \
+    --name luban-h5-api \
+    --restart=always \
+    -v `pwd`:/root -w /root/back-end/h5-api \
+    -p 1337:1337 \
+    --env "NODE_ENV=production" \
+    --env "VIRTUAL_PORT=1337" \
+    --env "VIRTUAL_HOST=api.yourdomain.tld" \
+    --env "LETSENCRYPT_HOST=api.yourdomain.tld" \
+   --restart=always node:12.8.1 \
+   yarn start
+```
+
+稍等片刻，访问`https://你的域名`，部署完成。
+
+关于Nginx、SSL的配置，可以参考：[https://github.com/JrCs/docker-letsencrypt-nginx-proxy-companion](https://github.com/JrCs/docker-letsencrypt-nginx-proxy-companion)
+
+
+
+---
+
+docker 自我学习，请忽略
+
+```bash
+docker --rm
+	相当于：
+	1. docker run hello-world(hello-world为image-name)
+	2. docker rm hello-world-container-id(通过 docker ps -a 查看)
+
+	在Docker容器退出时，默认容器内部的文件系统仍然被保留，以方便调试并保留用户数据。
+	但是，对于foreground容器，由于其只是在开发调试过程中短期运行，其用户数据并无保留的必要，因而可以在容器启动时设置--rm选项，这样在容器退出时就能够自动清理容器内部的文件系统。示例如下：
+	docker run --rm bba-208等价于docker run --rm=true bba-208。
+	显然，--rm选项不能与-d同时使用，即只能自动清理foreground容器，不能自动清理detached容器
+	注意，--rm选项也会清理容器的匿名data volumes。
+	所以，执行docker run命令带--rm命令选项，等价于在容器退出后，执行docker rm -v。
+
+
+Docker命令详解（run篇）
+	命令格式：docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
+	Usage: Run a command in a new container
+	中文意思为：通过run命令创建一个新的容器（container）
+
+	常用选项说明
+	-d, --detach=false， 指定容器运行于前台还是后台，默认为false
+	-i, --interactive=false， 打开STDIN，用于控制台交互
+	-t, --tty=false， 分配tty设备，该可以支持终端登录，默认为false
+	-u, --user=""， 指定容器的用户
+	-a, --attach=[]， 登录容器（必须是以docker run -d启动的容器）
+	-w, --workdir=""， 指定容器的工作目录
+	-c, --cpu-shares=0， 设置容器CPU权重，在CPU共享场景使用
+	-e, --env=[]， 指定环境变量，容器中可以使用该环境变量
+	-m, --memory=""， 指定容器的内存上限
+	-P, --publish-all=false， 指定容器暴露的端口
+	-p, --publish=[]， 指定容器暴露的端口
+	-h, --hostname=""， 指定容器的主机名
+	-v, --volume=[]， 给容器挂载存储卷，挂载到容器的某个目录
+	--volumes-from=[]， 给容器挂载其他容器上的卷，挂载到容器的某个目录
+	--cap-add=[]， 添加权限，权限清单详见：http://linux.die.net/man/7/capabilities
+	--cap-drop=[]， 删除权限，权限清单详见：http://linux.die.net/man/7/capabilities
+	--cidfile=""， 运行容器后，在指定文件中写入容器PID值，一种典型的监控系统用法
+	--cpuset=""， 设置容器可以使用哪些CPU，此参数可以用来容器独占CPU
+	--device=[]， 添加主机设备给容器，相当于设备直通
+	--dns=[]， 指定容器的dns服务器
+	--dns-search=[]， 指定容器的dns搜索域名，写入到容器的/etc/resolv.conf文件
+	--entrypoint=""， 覆盖image的入口点
+	--env-file=[]， 指定环境变量文件，文件格式为每行一个环境变量
+	--expose=[]， 指定容器暴露的端口，即修改镜像的暴露端口
+	--link=[]， 指定容器间的关联，使用其他容器的IP、env等信息
+	--lxc-conf=[]， 指定容器的配置文件，只有在指定--exec-driver=lxc时使用
+	--name=""， 指定容器名字，后续可以通过名字进行容器管理，links特性需要使用名字
+	--net="bridge"， 容器网络设置:
+	bridge 使用docker daemon指定的网桥
+	host //容器使用主机的网络
+	container:NAME_or_ID >//使用其他容器的网路，共享IP和PORT等网络资源
+	none 容器使用自己的网络（类似--net=bridge），但是不进行配置
+	--privileged=false， 指定容器是否为特权容器，特权容器拥有所有的capabilities
+	--restart="no"， 指定容器停止后的重启策略:
+	no：容器退出时不重启
+	on-failure：容器故障退出（返回值非零）时重启
+	always：容器退出时总是重启
+	--rm=false， 指定容器停止后自动删除容器(不支持以docker run -d启动的容器)
+	--sig-proxy=true， 设置由代理接受并处理信号，但是SIGCHLD、SIGSTOP和SIGKILL不能被代理
+	示例
+	运行一个在后台执行的容器，同时，还能用控制台管理：docker run -i -t -d ubuntu:latest
+	运行一个带命令在后台不断执行的容器，不直接展示容器内部信息：docker run -d ubuntu:latest ping www.docker.com
+	运行一个在后台不断执行的容器，同时带有命令，程序被终止后还能重启继续跑，还能用控制台管理，docker run -d --restart=always ubuntu:latest ping www.docker.com
+	为容器指定一个名字，docker run -d --name=ubuntu_server ubuntu:latest
+	容器暴露80端口，并指定宿主机80端口与其通信(: 之前是宿主机端口，之后是容器需暴露的端口)，docker run -d --name=ubuntu_server -p 80:80 ubuntu:latest
+	指定容器内目录与宿主机目录共享(: 之前是宿主机文件夹，之后是容器需共享的文件夹)，docker run -d --name=ubuntu_server -v /etc/www:/var/www ubuntu:latest
+```
+
+
+## Heroku
+> 因为 Strapi + postgresql  在 Heroku 上还有一些坑，需要官方解决，这个方案暂时pending
 ---
 # Features
 ### 编辑器
-
-  - [x] 参考线
-  - [x] 吸附线、组件对齐
-  - [x] 拖拽改变组件形状
-  - [x] 元素: 复制（画布）
-  - [x] 元素: 删除（画布）
-  - [x] 元素: 编辑（画布）
-  - [x] 页面：新增
-  - [x] 页面：复制
-  - [x] 页面：删除
-  - [x] 快速预览
-  - [x] 撤销、重做
+- [x] 参考线
+- [x] 吸附线、组件对齐
+- [x] 拖拽改变组件形状
+- [x] 元素: 复制（画布）
+- [x] 元素: 删除（画布）
+- [x] 元素: 编辑（画布）
+- [x] 页面：新增
+- [x] 页面：复制
+- [x] 页面：删除
+- [x] 快速预览
+- [x] 撤销、重做
 ### 组件系统
-  - [x] 文字
-  - [x] 普通按钮
-  - [x] 表单按钮
-  - [x] 表单输入框
-  - [x] 普通图片
-  - [ ] 背景图
-  - [ ] 视频（Iframe形式）
-
-### 增强功能
-  - [ ] 上传 PSD，一键转换为 H5(已经调研，可以实现)
-  - [ ] 图片库
-  - [ ] 第三方无版权图片搜索
-  - [ ] 自定义脚本(已经调研，可以实现)
+#### 基础组件
+
+- [x] 普通文字
+- [x] 普通按钮
+- [x] 普通图片
+- [ ] 背景图
+- [ ] 视频（Iframe形式）
+
+#### 表单组件
+
+- [x] 表单按钮
+- [x] 表单输入框
+- [x] 表单单选框
+- [x] 表单多选框
+
+
+### 增强功能[已开放]
+
+- [x] 模板列表
+- [x] 基于模板制作H5
+- [x] 保存作品为模板
+- [ ] 图片库
+- [ ] 第三方无版权图片搜索
+- [ ] SSO 登录、第三方登录
+
+
+### 增强功能[暂未开放]
+> 已经调研，可以实现，高级功能，暂未开放
+
+- [x] 上传 PSD，一键转换为 H5
+- [x] 自定义脚本
+
 ### 后端 API
-  - [x] 创建、保存、更新作品
-  - [x] 表单数据收集
-  - [x] 表单数据展示
-  - [x] 在线预览
-  - [x] 二维码预览
+
+- [x] 创建、保存、更新作品
+- [x] 表单数据收集
+- [x] 表单数据展示
+- [x] 在线预览
+- [x] 二维码预览
 ---
 # 快速开始
-# 概述
 ## 基础概念
 > 首先你需要大概了解下 Node.js 的相关生态、Node.js 的安装
 我们接下来会花一分钟介绍一下基础概念. 我们默认你知道 Linux 和 Git 的基本操作
@@ -19,7 +18,7 @@
 > 1. 假如这个版本(假设当前版本为 v.8.0.0)不符合要求，你可以通过 `nvm install v10.15.3` 来安装 `v10.15.3` 
-### Node、Yarn、npm 安装 
+### Node、Yarn、npm 安装
 1. 请参照 [Strapi 的 预安装文档指导](https://strapi.io/documentation/3.0.0-beta.x/getting-started/install-requirements.html#installation-requirements) ，安装 Node、npm 和 Yarn
 1. 因为 yarn 的仓库源在海外，所以，请配置国内镜像源，提高速度
@@ -27,7 +26,7 @@
 ```bash
 yarn config get registry
-# -> https://registry.yarnpkg.com 
+# -> https://registry.yarnpkg.com
 # 改成 taobao 的源：
 yarn config set registry https://registry.npm.taobao.org
@@ -38,14 +37,15 @@ yarn config set registry https://registry.npm.taobao.org
 ```
 ## 技术栈(当前)
-前端：Vue.js
-后端：Strapi
-存储：Sqlite
+- 前端：Vue.js
+- 后端：Strapi
+- 存储：Sqlite
 # 项目环境搭建
 1. 鲁班H5的后端接口，由 [Strapi](https://github.com/strapi/strapi/) 强力驱动
-1. 后端部分文档会尽量和 `[github-后端部分文档说明(project/back-end/h5-api/README.md)](https://github.com/ly525/luban-h5/blob/dev/back-end/h5-api/README.md)`保持同步
+1. 后端部分文档会尽量和 `[github-后端部分文档说明(project/back-end/h5-api/README.md)](https://github.com/ly525/luban-h5/blob/dev/back-end/h5-api/README.md)`保持同步
+
 ## 后端环境搭建
 ### 1. 快速上手
@@ -56,7 +56,7 @@ yarn install # 安装依赖
 yarn add psd # 安装psd 依赖
 # 安装 ejs 渲染引擎，主要用来预览作品
-yarn add strapi-hook-ejs 
+yarn add strapi-hook-ejs
 # 需要在 h5-api/hook.json中添加如下配置：
 # strapi-hook-ejs 更多细节参见：https://github.com/strapi/strapi/tree/master/packages/strapi-hook-ejs#configuration
@@ -96,7 +96,7 @@ h5-api/hook.json 配置如下：
 ### 2. 注意事项
-1. 本地开发，如果后端接口报错 403 Forbidden，请按照下图的操作，打开接口的访问权限接口：`[Roles And Permission] -> [Public] - [Permissions]`  
+1. 本地开发，如果后端接口报错 403 Forbidden，请按照下图的操作，打开接口的访问权限接口：`[Roles And Permission] -> [Public] - [Permissions]`
 ![](https://cdn.nlark.com/yuque/0/2019/png/358499/1567438464273-e0892ee2-5dca-45ec-a528-8090d80b23bd.png#align=left&display=inline&height=1016&originHeight=1016&originWidth=1906&size=0&status=done&width=1906)
@@ -112,7 +112,7 @@ error TypeError: ctx.render is not a function
 ```
 ## 前端环境搭建
-这部分会尽量和  `[project/front-end/h5/README.md](https://github.com/ly525/luban-h5/blob/dev/front-end/h5/README.md)` 保持同步
+这部分会尽量和  `[project/front-end/h5/README.md](https://github.com/ly525/luban-h5/blob/dev/front-end/h5/README.md)` 保持同步
 ### 1. 快速上手
@@ -124,16 +124,21 @@ yarn # install dependencies
 yarn serve # develop
 # 更多命令
-请参见 project/front-end/h5/package.json 
+请参见 project/front-end/h5/package.json
 ```
 ### 2. 构建预览所需的渲染引擎
-> 参见 [https://www.yuque.com/liuyan-ew1qk/luban-h5-docs/gmk13a#962e6e56](https://www.yuque.com/liuyan-ew1qk/luban-h5-docs/gmk13a#962e6e56)
+1. 在 front-end/h5 目录下，运行：`node build/engine.webpack.js` (这个是用来生成预览引擎的东西)
+2. 构建完成之后,看下 后端的 `h5-api/public` 里面会多一个文件夹 `engine-assets`
+3. 打开的预览窗口（preview.vue）,里面的预览部分对应的其实是一个 iframe，可以看看对应的源码
+  也就是说，这个预览其实依赖后端的渲染引擎 比如 ejs 或者 jade 这种模板引擎，所以 `build/engine.webpack.js` 的 `output dir` 是在`back-end/h5-api/public`中的
 ### 3. 前端组件说明
 1. `lbp-`
-
 全称为 `lu-ban-plugin:``鲁班H5的插件`，位置：`front-end/h5/src/components/plugins`
+---
+
+<Vssue issueId="6" />
 \ No newline at end of file