Add main docs

README.md

@@ -0,0 +1,220 @@
+#Jenkins介绍与使用
+##什么是Jenkins
+Jenkins是一个可扩展的持续集成引擎，提高效率的软件。如版本发布，开发提交代码，Jenkins会自动运行编译脚本，编译成功后，再运行测试脚本，最后将新程序发布。简而言之Jenkins能把软件开发过程形成自动化 **工作流**，一键完成开发过程中一系列的工作。
+
+##如何配置Jenkins
+对于svi云平台来说，Jenkins仅仅做了3件事情：编译打包 -> FTP网元包-> 制作镜像部署应用。所以对于我们当前项目来说，仅仅只需配置此3个步骤即可完成Jenkins相关持续集成功能。
+
+###编译打包
+登录Jenkins，选择对应的项目（网元）。在Jenkins中编译打包时需要配置两个地方，首先获取代码再编译打包，操作步骤如下：
+
+  - 获取代码
+配置 –> 源码管理 –> Subversion。在“Subversion”选择中，填写“Repository URL”、“Credentials”、“Local module directory”等信息。其中账号必须是具备该网元的访问权限，具体的配置需要根据实际情况而定。如下图：
+  - 编译打包
+配置 – > 构建 – > Execute shell，在“Execute shell”选项“Command”中填写编译代码，代码由该网元开发者自行编写，包的格式请参照11，Jenkins配置如下图：
+
+###FTP网元包
+登录Jenkins，选择对应的项目（网元）。在Jenkins中FTP网元包仅需要配置一个地方，操作步骤如下：
+
+ -  FTP网元包
+配置 –> 构建 –> Send files over FTP。在“FTP Server”选项中，填写“Name”和“Transfers”。“Name”选择对应的FTP服务器。“Transfers” 又包含三个参数，“Source files”、“Remove prefix”、“Remote directory” 具体的配置需要根据实际情况而定。如下图。
+
+###制作镜像部署应用
+登录Jenkins，选择对应的项目（网元）。在Jenkins中编译打包时需要配置两个地方，首先制作镜像部署应用，操作步骤如下：
+
+-   制作镜像
+配置 –> 构建 –> Send files or execute commands over SSH。在“SSH Server”选项中，填写“Name”和“Transfers”。“Name”选择对应的build服务器。“Transfers” 又包含四个参数，“Source files”、“Remove prefix”、“Remote directory”、“Exec command”但是“除Exec command”填写“bash /opt/tools/build_images.sh aaa ${SVN_REVISION} powercloud”外。其它三项需要根据网元实际情况填写，一般情况下为空。脚本的参数请参照章节2.2.1build_images.sh填写。
+
+-   应用部署
+除Exec command”填写“bash /opt/tools/deploy_powercloud_latest.sh --module=aaa --env=powercloud --force”外，其它与制作镜像步骤基本相同，脚本的参数请参照章节2.2.2deploy_latest.sh填写。整体如下图：
+
+#build/FTP服务器介绍
+##什么是build/ftp服务器
+build服务器其实就是一台部署了镜像制作build_images.sh脚本与网元自动部署deploy_latest.sh脚本的服务器。build_images.sh脚本是根据网元编译打包之后的pkg包制作镜像，并将制作的镜像推送到对于的镜像仓库。deploy_latest.sh脚本是根据特定的参数将最新的镜像自动部署到云平台。
+FTP服务器其实就是存放Jenkins推送过来的网元包。保留的网元包可供后续版本的追踪与历史版本的保存，也是制作镜像的基础来源。简单的说就是版本存储与制作镜像。
+当前build/ftp服务器均为：192.168.100.19，脚本存放路径为：/opt/tools目录，ftp路径为：/data/ftp目录，后续可能会按照项目分不同的ftp目录。如下图：
+
+##脚本工具使用与介绍
+###build_images.sh
+脚本名：build_images.sh
+脚本存放路径：/opt/tools/build_images.sh
+脚本功能：根据网元包，制作镜像，并且将镜像推送到对应的镜像仓库。
+脚本接口参数：此脚本必须包含3个参数，均已空格隔开，且顺序不可错乱。
+
+-   第一个参数：aaa（网元名），
+-   第二个参数：${SVN_REVISION}（SVN版本号），
+-   第三个参数：powercloud（项目名称）。
+
+脚本日志输出：登录build/ftp服务器，在/tmp/portalms_web（portalms_web为网元的服务名）目录下可以查看所有完整日志包含错误日志。如下图：
+
+脚本下载地址：https://git.svicloud.com/svicloud/cloud-standard/raw/master/build/build_images.sh
+###deploy_latest.sh
+脚本名：脚本名：deploy_latest.sh
+脚本存放路径：/opt/tools/deploy_latest.sh
+脚本功能：通过接口参数，将网元部署到云平台对应的环境上。
+脚本接口参数：此脚本必须包含3个参数，均已空格隔开。
+
+-   第一个参数--module=aaa（网元名）。
+-   第二个参数--env=powercloud（云平台的环境名）。
+-   第三个参数--force（默认参数）。
+
+脚本日志输出：登录Jenkins，选择对应的项目，进入指定的构建ID，选择“控制台输出”，如下图：
+
+脚本下载地址：https://git.svicloud.com/svicloud/cloud-standard/raw/master/deploy/deploy_latest.sh
+
+#dockerfile规范与介绍
+##什么是dockerfile
+Dockerfile是由一系列命令和参数构成的脚本，由开发人员自己维护。简化了从头到尾的流程并极大的简化了部署工作。Dockerfile从FROM命令开始，紧接着跟随着各种方法、命令和参数。其产出为一个新的可以用于创建容器的镜像。对于我们来说其实就是符合一定格式的网元安装与启动过程的编排文件。 
+##dockerfile模板
+编写dockerfile的时候，只需要下载模板，根据网元的特性修改模板，如果有特殊需求请联系云平台工程师。模板如下图：
+
+###Dockerfile
+下载地址：https://git.svicloud.com/svicloud/cloud-standard/raw/a3c7e0a6d9ce77793531fabd9d69d26581ee0d4d/Dockerfile.tpl
+Dockerfile存放路径：网元根目录下存放Dockerfile文件，如下：
+
+###start.sh
+功能：网元前置检查、配置的更新、启动。
+下载地址：https://git.svicloud.com/svicloud/cloud-standard/raw/master/docker/start.sh
+存放路径：网元根目录docker目录下start.sh文件，如果网元根目录下无docker目录需要创建，如下图：
+
+#镜像仓库的介绍
+##什么是镜像仓库
+docker镜像集中起来存放的场所。仓库分为公开仓库（Public）和私有仓库（Private）两种形式。我们云平台的镜像仓库如下图：
+
+
+##镜像仓库项目规划
+对于云平台的镜像仓库来说，在镜像仓库的项目中需要将不同项目的镜像放到对应的项目中。比如聚能云，需要新建powercloud项目来存放聚能云的镜像。比如镜像地址：registry.sviyun.com/powercloud/ums/server:V01R01B01-817，其中registry.sviyun.com是镜像仓库的地址，powercloud是项目名称，ums是网元名，server服务名，V01R01B01-817是镜像版本号。
+#栈、服务的介绍
+##什么是栈/服务
+对于我们当前项目来说栈就是网元名，服务就是该网元包含的服务，比如cas_server，栈名是cas，服务名是server。再比如AAA: 栈名是aaa，服务名是aaa。
+##栈/服务如何规划
+一般栈/服务根据网元自身的特性来定，栈由至少1个服务组成，相同栈下名字不能重复。栈/服务名必须为小写且不允许有特殊字符。服务的数量取决于该网元的自身要求特性，由网元开发者确定，如下图：
+
+#域名、端口生成规则
+##域名端口的作用
+域名端口的作用用于各网元服务之间的通讯。如果网元的域名端口配置错误可能会导致服务连接异常。云平台所有服务之间的通讯禁止用IP通讯。且相同环境下所有的服务端口必须唯一。
+##域名端口如何规划与生成
+云平台的域名与端口其实比较简单，域名云平台会自动生成，端口需要项目立项时提前规划。云平台域名包含内部域名、外部域名。
+###内部域名
+内部域名，简单点说就是此域名只能在容器内部通讯。
+生成规则：由{服务名.栈名}组成
+实例：比如网元cas的server服务，栈为cas，服务为server，则域名为：server.cas
+###外部域名
+外部域名，可供外部任何接入Internet的主机访。
+生成规则：由{服务名.栈名.环境名.svi.pub}组成
+实例：比如网元cas的server服务，栈为cas，服务为server，当前环境为yuntest，则域名为：server.authcenter.yuntest.svi.pub，如下图：
+
+#git介绍与使用
+##什么是git
+是一个开源的分布式版本控制系统，可以有效、高速的处理从很小到非常大的项目版本管理。一个开放源码的版本控制软件。对于我们来说，git就是存放网元的编排文件。
+Git编排文件修改之后需要刷新应用商店，请参照11.1应用商店如何刷新刷新应用商店，且修改git之后栈必须删除重建，否则无法获取最新数据。
+##git模板
+网元的编排工具主要包含5个文件，其中最主要的就是docker-compose.yml
+和?rancher-compose.yml，此2文件主要是对网元在部署时进行编排梳理。其实简单点说是一个yml格式且符合一定特性规则的流程编排文件。整个工具的文件路径如下图：
+
+下面分别对每个文件进行介绍分析。
+网元aaa目录下必须包含：目录0、catalogIcon-aaa.svg、config.yml。目录0下必须包含docker-compose.yml和rancher-compose.yml文件，answer.txt文件是在需要添加动态变量时添加，添加动态变量请参照11.2。为非必要文件。
+Git服务器地址：https://git.svicloud.com/
+
+###Config.yml文件
+
+##catalogIcon-xxx.svg
+该文件必须为svg格式，组成方式为catalogIcon-网元名.svg，该文件为网元的logo文件，需要开发者根据网元的特性自己制作，如下图：
+
+###docker-compose.yml
+
+其中“- /opt/wisecloud/boss:/opt/wisecloud/boss”为数据持久化设置，具体的请参照9持久化数据介绍。
+###rancher-compose.yml
+
+#应用部署
+##手动部署
+登录云平台，应用商店 –> ?Powercloud(项目名称)，搜索指定网元，点击“查看详情”填写相关参数，点击启动，完成部署。
+
+
+##自动部署
+登录jenkins ，选择对应的项目PowerCloud_AAA_docker ，点击立即构建，完成部署，如下图：
+
+##升级部署
+手动部署与自动部署都只能部署该网元的最新版本，如果需要部署指定版本，就必须升级了。
+
+-   升级步骤
+登录云平台，选择需要升级的栈，点击栈名，选择对应的服务，点击“升级”按钮，在“选择镜像”选项中将latest替换成需要升级的版本。最后点击“升级”完成升级操作。
+
+
+升级成功如下图所示：
+
+#持久化数据介绍
+##什么叫持久化数据
+对于容器来说，可能会面临升级、故障、删除重建、重新部署等操作都将会重新拉取镜像，而此时相当于一个全新的服务，操作前的数据将全部丢失，这种情况下对于重要数据就需要数据持久化。说得直白点就是当容器再次部署，数据不会丢失，这就叫持久化数据，实现方法就是将容器中的数据保存到物理主机，防止丢失。
+但是做数据持久化之后容器将不允许漂移，所以是否需要做数据持久化需要慎重考虑。
+##如何做持久化数据
+docker数据持久化的方法有很多，结合我们当前的项目特性，我们只介绍一种简单的方式。如：需要将容器中的/opt/data目录中的数据永久保留在物理机的/opt/data。
+
+-   步骤
+需要在git上修改docker-compose.yml文件，增加映射规则，增加完成之后需要在云平台刷新应用商店，刷新应用商店参照11.1应用商店如何刷新，如果下图：
+
+注意：如果volumes:存在只需要添加一条 - /opt/data:/opt/data
+#标签
+##什么是标签
+对于云平台来说，标签就是在主机节点上做标记，让服务可以根据具体的标签特性运行在不同的主机上。如下图：
+
+##标签的使用
+标签的种类比较多，现在介绍一种当前项目中比较常见的标签用法，其它标签用法请联系云平台工程师。
+
+-   实例：比如现在需要将aaa服务固定在主机192.168.10.231上时。
+步骤1：选择对应的主机，点击“编辑”。在弹出的对话框中“标签”-> “添加标签”，标签的名字自由定义。如下图：
+步骤2：参照8.3升级部署服务升级步骤，调出升级对话框，“调度”-> “添加调度规则”，选择新加的标签test，点击升级。如果想永久生效需要将“io.rancher.scheduler.affinity:host_label: test=true”，更新到git服务器 aaa服务的“docker-compose.yml”文件中，最后刷新应用商店，方法参照11.1应用商店如何刷新。如下图。
+
+
+#网元包格式
+视维云平台为规范镜像的命名，对格式有一定的要求，网元名或者服务名必须大写，解压后网元程序运行目录名必选全小写所有的包必须符合该要求，否则镜像将无法使用。
+##栈与服务名相同
+很多网元栈服务名相同，这类网元一般是不包含后端web或者pc。
+包名：XXX_VxxRxxBxx_yyyymmdd_release-svn版本号-安装包md5值.tar.gz
+解压后安装目录命名规则：XXX_VxxRxxBxx_yyyymmdd_release
+程序运行目录命名规则：/opt/wisecloud/xxx 
+运行主程序名：xxx
+运行命令：start/stop/status/restart_xxx
+
+-   实例：AAA
+安装包：AAA_V01R04B03_20170919_release-13497-161f381182f15256c77e2ec3a622fdf5.tar.gz
+解压后安装目录名：AAA_V01R04B03_20170919_release
+程序运行目录名：/opt/wisecloud/aaa 
+运行主程序名：aaa
+运行命令：start/stop/status/restart_aaa
+如下图：
+
+##栈与服务名不相同
+很多网元栈服务名不相同，这类网元一般是包含后端web或者pc等其它服务。
+组成：XXX_[ SERVER | WEB | PC ]_VxxRxxBxx_yyyymmdd_release-svn版本号-安装包md5值.tar.gz
+解压后安装目录命名规则：XXX_ [ SERVER | WEB | PC ]_VxxRxxBxx_yyyymmdd_release
+程序运行目录命名规则：/opt/wisecloud/xxx/xxx_server/web/pc 
+运行主程序名：xxx_server/web/pc
+运行命令：start/stop/status/restart_xxx_server/web/pc
+例如：
+安装包：DCMP_SERVER_V01R04B05_20170925_release-13847-a17bfae091533eaa880bcf7ffb67c270.tar.gz
+解压后安装目录名：DCMP_SERVER_V01R04B05_20170925_release
+程序运行目录名：/opt/wisecloud/dcmp/dcmp_server 
+运行主程序名：dcmp_server
+运行命令：start/stop/status/restart_dcmp_server
+如下图：
+
+
+#FAQ
+##应用商店如何刷新
+-   操作步骤：
+登录云平台，应用商店，选择对应的项目，刷新即可，刷新时长根据栈的数据量而定，刷新完成之后“刷新”按钮图标将恢复原样，如下图：
+
+
+##如何添加动态变量
+动态变量一般指需要经常变更的参数，比如数据库IP，密码，数据库名，端口等。
+添加动态变量涉及到4个文件：业务的配置文件、docker-compose.yml?、rancher-compose.yml、answer.txt。
+实例：test网元中，test.conf文件中变量“DATABASE_USER”当前是固化在文件中，但是后续发现可能经常变动，现在需要将“DATABASE_USER”变量设置为动态变量，可以直接通过页面修改，避免每次修改配置文件还需要重新出镜像版本。
+
+-   操作步骤
+1.修改SVN test网元根目录下docker/conf/test.conf文件，如下图：
+2.修改git 上docker-compose.yml文件，如下图：
+3.修改git 上rancher-compose.yml文件，如下图：
+4.在git上添加answer.txt文件，如果文件存在只需要加新变量，如下图：
+5.提交SVN和git，参照11.1应用商店如何刷新刷新应用商店。
+6.参照8.1手动部署部署test网元，如下图：