diff --git a/.vitepress/config.js b/.vitepress/config.js index 4726e75985f4a3deb1a40bbdb346d04ca50a0865..7d5eb522d3ec46e6dcfa0e0a4351532856d373d9 100644 --- a/.vitepress/config.js +++ b/.vitepress/config.js @@ -41,8 +41,8 @@ module.exports = { children: [{ text: '触发器', children: [{ - text: '事件桥接器', - link: '/guide/event-bridge' + text: 'Webhook', + link: '/guide/webhook' }, { text: 'Cron', link: '/guide/cron', @@ -80,6 +80,9 @@ module.exports = { }, { text: "网关节点", link: "/guide/gateway" + }, { + text: "Shell节点", + link: "/guide/shell-node" }] }, // { @@ -89,6 +92,9 @@ module.exports = { { text: '自定义节点', link: '/guide/custom-node' + },{ + text: '一键还原项目', + link: '/guide/project-group' }, { text: '第三方库', link: '/guide/license-mixing' diff --git a/LICENSE b/LICENSE index e9fc50e468549212a9d3b48ad392cc900f795092..7bed5e1b421c8f3936c9acbbbd3114b565a83e9c 100644 --- a/LICENSE +++ b/LICENSE @@ -1,180 +1,128 @@ -木兰公共许可证, 第2版 -木兰公共许可证, 第2版 - -2021年5月 http://license.coscl.org.cn/MulanPubL-2.0 - -您对“贡献”的复制、使用、修改及分发受木兰公共许可证,第2版（以下简称“本许可证”）的如下条款的约束： - -0. 定义 - -“贡献” 是指由“贡献者”许可在“本许可证”下的受版权法保护的作品，包括最初“贡献者”许可在“本许可证”下的作品及后续“贡献者”许可在“本许可证”下的“衍生作品”。 - -“贡献者” 是指将受版权法保护的作品许可在“本许可证”下的自然人或“法人实体”。 - -“法人实体” 是指提交贡献的机构及其“关联实体”。 - -“关联实体” 是指，对“本许可证”下的行为方而言，控制、受控制或与其共同受控制的机构，此处的“控制”是指拥有受控方或共同受控方至少50%直接或间接的投票权、资金或其他有价证券。 - -“衍生作品” 是指基于“贡献”创作的作品，具体包括对全部或部分“贡献”进行修改、重写、翻译、注释、组合或与之链接（包括动态链接或静态链接）而形成的作品。仅与“贡献”进行进程间通信或系统调用的作品是独立作品，不属于“衍生作品”。 - -“对应源代码” 是指生成、安装和(对于可执行作品)运行目标代码所需的所有源文件和与之关联的接口定义文件，以及控制这些活动的脚本，但不包括编译环境、编译工具、云服务平台（如果有）。 - -“分发” 是指通过任何媒介向他人提供“贡献”或“衍生作品”的行为，以及利用“贡献”或“衍生作品”通过网络远程给用户提供服务的行为，例如：通过利用“贡献”或“衍生作品”搭建的云服务平台提供在线服务的行为。 - -1. 授予版权许可 - -每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的版权许可，您可以复制、使用、修改、“分发”其“贡献”或“衍生作品”，不论修改与否。 - -2. 授予专利许可 - -每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的（根据本条规定撤销的情形除外）专利许可，供您使用、制造、委托制造、销售、许诺销售、进口其“贡献”或以其他方式转移其“贡献”。前述专利许可仅限于“贡献者”现在或将来拥有或控制的其“贡献”中的专利权利要求，而不包括仅因您对“贡献”的修改而将必然会侵犯到的专利权利要求。如果您或您的“关联实体”直接或间接地，就“贡献”对任何人发起专利侵权诉讼（包括在诉讼中提出反诉请求或交叉请求）或发起其他专利维权行动，则“贡献者”根据“本许可证”授予您的专利许可自您发起专利诉讼或专利维权行动之日终止。 - -3. 无商标许可 - -“贡献者”在“本许可证”下不提供对其商品名称、商标、服务标识或产品名称的商标许可，但您为满足第4条规定的声明义务而必须使用的情形除外。 - -4. 分发限制 - -您可以将您接收到的“贡献”或您的“衍生作品”以源程序形式或可执行形式重新“分发”，但必须满足下列条件： - -（1）您必须向接收者提供“本许可证”的副本，并保留“贡献”中的版权、商标、专利及免责声明；并且， - -（2）如果您“分发”您接收到的“贡献”，您必须使用“本许可证”提供该“贡献”的源代码副本；如果您 “分发”您的“衍生作品”，您必须： - -（i）随“衍生作品”提供使用“本许可证”“分发”的您的“衍生作品”的“对应源代码”。如果您通过下载链接提供前述“对应源代码”，则您应将下载链接地址置于“衍生作品”或其随附文档中的明显位置，有效期自该“衍生作品”“分发”之日起不少于三年，并确保接收者可以获得“对应源代码”；或者， - -（ii）随“衍生作品”向接收者提供一个书面要约，表明您愿意提供根据“本许可证”“分发”的您“衍生作品”的“对应源代码”。该书面要约应置于“衍生作品”中的明显位置，并确保接收者根据书面要约可获取“对应源代码”的时间从您接到该请求之日起不得超过三个月，且有效期自该“衍生作品”“分发”之日起不少于三年。 - -5. 违约与终止 - -如果您违反“本许可证”，任何“贡献者”有权书面通知您终止其根据“本许可证”授予您的许可。该“贡献者”授予您的许可自您接到其终止通知之日起终止。仅在如下两种情形下，即使您收到“贡献者”的通知也并不终止其授予您的许可： - -（1）您在接到该终止通知之前已停止所有违反行为； - -（2）您是首次收到该“贡献者”根据“本许可证”发出的书面终止通知，并且您在收到该通知后30天内已停止所有违反行为。 - -只要您下游的接收者遵守“本许可证”的相关规定，即使您在“本许可证”下被授予的许可终止，不影响下游的接收者根据“本许可证”享有的权利。 - -6. 例外 - -如果您将“贡献”与采用GNU AFFERO GENERAL PUBLIC LICENSE Version 3（以下简称“AGPLv3”）或其后续版本的作品结合形成新的“衍生作品”，且根据“AGPLv3”或其后续版本的要求您有义务将新形成的“衍生作品”以“AGPLv3”或其后续版本进行许可的，您可以根据“AGPLv3”或其后续版本进行许可，只要您在“分发”该“衍生作品”的同时向接收者提供“本许可证”的副本，并保留“贡献”中的版权、商标、专利及免责声明。但任何“贡献者”不会因您选择“AGPLv3”或其后续版本而授予该“衍生作品”的接收者更多权利。 - -7. 免责声明与责任限制 - -“贡献”在提供时不带有任何明示或默示的担保。在任何情况下，“贡献者”或版权人不对任何人因使用“贡献”而引发的任何直接或间接损失承担任何责任，不论该等损失因何种原因导致或者基于何种法律理论,即使其曾被告知有该等损失的可能性。 - -8. 语言 - -“本许可证”以中英文双语表述，中英文版本具有同等法律效力。如果中英文版本存在任何不一致，以中文版为准。 - -条款结束 - -如何将木兰公共许可证，第2版，应用到您的软件 - -如果您希望将木兰公共许可证，第2版，应用到您的软件，为了方便接收者查阅，建议您完成如下三步： - -1， 请您补充如下声明中的空白，包括软件名、软件的首次发表年份以及您作为版权人的名字； - -2， 请您在软件包的一级目录下创建以“LICENSE”为名的文件，将整个许可证文本放入该文件中； - -3， 请将如下声明文本放入每个源文件的头部注释中。 - -Copyright (c) 2021 99cloud, Inc. -Jianmu is licensed under Mulan PubL v2. -You can use this software according to the terms and conditions of the Mulan PubL v2. -You may obtain a copy of Mulan PubL v2 at: - http://license.coscl.org.cn/MulanPubL-2.0 -THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, -EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, -MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. -See the Mulan PubL v2 for more details. -Mulan Public License，Version 2 -Mulan Public License，Version 2 (Mulan PubL v2) - -May 2021 http://license.coscl.org.cn/MulanPubL-2.0 - -Your reproduction, use, modification and Distribution of the Contribution shall be subject to Mulan Public License, Version 2 (this License) with following terms and conditions: - -0. Definition - -Contribution means the copyrightable work licensed by a particular Contributor under this License, including the work licensed by the initial Contributor under this License and its Derivative Work licensed by any subsequent Contributor under this License. - -Contributor means the Individual or Legal Entity who licenses its copyrightable work under this License. - -Legal Entity means the entity making a Contribution and all its Affiliates. - -Affiliates mmeans entities that control, are controlled by, or are under common control with the acting entity under this License, ‘control’ means direct or indirect ownership of at least fifty percent (50%) of the voting power, capital or other securities of controlled or commonly controlled entity. - -Derivative Work means works created based on Contribution, specifically including works formed by modifying, rewriting, translating, annotating, combining or linking to all or part of Contribution (including dynamic linking or static linking). Works which only communicate with Contribution through inter-process communication or system call, are independent works, rather than Derivative Work. - -Corresponding Source Code means all the source code needed to generate, install, and (for an executable work) run the object code including the interface definition files associated with source files for the work, and scripts to control those activities, excluding of compilation environment and compilation tools, cloud services platform (if any). - -Distribute (or Distribution) means the act of making the Contribution or Derivative Work available to others through any medium, and using the Contribution or Derivative Work to provide online services to users, such as the act of providing online services through a cloud service platform built using Contributions or Derivative Works. - -1. Grant of Copyright License - -Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable copyright license to reproduce, use, modify, or Distribute its Contribution or Derivative Work, with modification or not. - -2. Grant of Patent License - -Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable (except for revocation under this Section) patent license to use, make, have made, sell, offer for sale, import or otherwise transfer its Contribution, where such patent license is only limited to the patent claims owned or controlled by such Contributor now or in future which will be necessarily infringed by its Contribution alone, excluding of any patent claims solely be infringed by your modification. If you or your Affiliates directly or indirectly institute patent litigation (including a cross claim or counterclaim in a litigation) or other patent enforcement activities against any individual or entity by alleging that any Contribution infringes patents, then any patent license granted to you under this License for the Contribution shall terminate as of the date such litigation or activity is filed or taken. - -3. No Trademark License - -No trademark license is granted to use the trade names, trademarks, service marks, or product names of Contributor, except as required to fulfill notice requirements in Section 4. - -4. Distribution Restriction - -You may Distribute the Contribution you received or your Derivative Work, whether in source or executable forms, provided that you meet the following conditions: - -1) You must provide recipients with a copy of this License and retain copyright, trademark, patent and disclaimer statements in the Contribution; and, - -2) If you Distribute the Contribution you received, you must provide copies of the Contribution’s source code under this License; - -If you Distribute your Derivative Work, you have to: - -(i) accompanying the Derivative work, provide recipients with Corresponding Source Code of your Derivative Work under this License. If you provide the Corresponding Source Code through a download link, you should place such link address prominently in the Derivative Work or its accompanying documents, and be valid no less than three years from your Distribution of the particular Derivative Work, and ensure that the recipients can acquire the Corresponding Source Code through the link; or, - -(ii) accompanying the Derivative Work, provide recipients with a written offer indicating your willingness to provide the Corresponding Source Code of the Derivative Work licensed under this License. Such written offer shall be placed prominently in the Derivative Work or its accompanying documents. Without reasonable excuse, the recipient shall be able to acquire the Corresponding Source code of the Derivative work for no more than three months from your receipt of a valid request, and be valid no less than three years from your Distribution of the particular Derivative Work. - -5. Breach and Termination - -If you breach this License, any Contributor has the right to notify you in writing to terminate its license granted to you under this License. The license granted to you by such Contributor terminates upon your receipt of such notice of termination. Notwithstanding the foregoing, your license will not be terminated even if you receive a notice of termination from Contributor, provided that: - -1) you have cured all the breaches prior to receiving such notice of termination; or, - -2) it’s your first time to receive a notice of termination from such Contributor pursuant to this License, and you have cured all the breaches within 30 days of receipt of such notice. - -Termination of your license under this License shall not affect the downstream recipient's rights under this License, provided that the downstream recipient complies with this License. - -6. Exceptions - -If you combine Contribution or your Derivative Work with a work licensed under the GNU AFFERO GENERAL PUBLIC LICENSE Version 3 (hereinafter referred to as “AGPLv3”) or its subsequent versions, and according to the AGPLv3 or its subsequent versions, you have an obligation to make the combined work to be licensed under the corresponding license, you can license such combined work under the license, provided that when you Distribute the combined work, you also provide a copy of this License to the recipients, and retain copyright, trademarks, patents, and disclaimer statements in the Contribution. No Contributor will grant additional rights to the recipients of the combined work for your license under AGPLv3 or its subsequent versions. - -7. Disclaimer of Warranty and Limitation of liability - -CONTRIBUTION ARE PROVIDED WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL ANY CONTRIBUTOR OR COPYRIGHT HOLDER BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM YOUR USE OR INABILITY TO USE THE CONTRIBUTION, NO MATTER HOW IT’S CAUSED OR BASED ON WHICH LEGAL THEORY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -8. Language - -THIS LICENSE IS WRITTEN IN BOTH CHINESE AND ENGLISH, AND THE CHINESE VERSION AND ENGLISH VERSION SHALL HAVE THE SAME LEGAL EFFECT. IN THE CASE OF DIVERGENCE BETWEEN THE CHINESE AND ENGLISH VERSIONS, THE CHINESE VERSION SHALL PREVAIL. - -END OF THE TERMS AND CONDITIONS - -How to apply the Mulan Public License，Version 2 (Mulan PubL v2), to your software - -To apply the Mulan Public License，Version 2 to your work, for easy identification by recipients, you are suggested to complete following three steps: - -Fill in the blanks in following statement, including insert your software name, the year of the first publication of your software, and your name identified as the copyright owner; -Create a file named “LICENSE” which contains the whole context of this License in the first directory of your software package; -Attach the statement to the appropriate annotated syntax at the beginning of each source file. - -Copyright (c) 2021 99cloud, Inc. -Jianmu is licensed under Mulan PubL v2. -You can use this software according to the terms and conditions of the Mulan PubL v2. -You may obtain a copy of Mulan PubL v2 at: - http://license.coscl.org.cn/MulanPubL-2.0 -THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, -EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, -MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. -See the Mulan PubL v2 for more details. + 木兰宽松许可证, 第2版 + + 木兰宽松许可证， 第2版 + 2020年1月 http://license.coscl.org.cn/MulanPSL2 + + + 您对“软件”的复制、使用、修改及分发受木兰宽松许可证，第2版（“本许可证”）的如下条款的约束： + + 0. 定义 + + “软件”是指由“贡献”构成的许可在“本许可证”下的程序和相关文档的集合。 + + “贡献”是指由任一“贡献者”许可在“本许可证”下的受版权法保护的作品。 + + “贡献者”是指将受版权法保护的作品许可在“本许可证”下的自然人或“法人实体”。 + + “法人实体”是指提交贡献的机构及其“关联实体”。 + + “关联实体”是指，对“本许可证”下的行为方而言，控制、受控制或与其共同受控制的机构，此处的控制是指有受控方或共同受控方至少50%直接或间接的投票权、资金或其他有价证券。 + + 1. 授予版权许可 + + 每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的版权许可，您可以复制、使用、修改、分发其“贡献”，不论修改与否。 + + 2. 授予专利许可 + + 每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的（根据本条规定撤销除外）专利许可，供您制造、委托制造、使用、许诺销售、销售、进口其“贡献”或以其他方式转移其“贡献”。前述专利许可仅限于“贡献者”现在或将来拥有或控制的其“贡献”本身或其“贡献”与许可“贡献”时的“软件”结合而将必然会侵犯的专利权利要求，不包括对“贡献”的修改或包含“贡献”的其他结合。如果您或您的“关联实体”直接或间接地，就“软件”或其中的“贡献”对任何人发起专利侵权诉讼（包括反诉或交叉诉讼）或其他专利维权行动，指控其侵犯专利权，则“本许可证”授予您对“软件”的专利许可自您提起诉讼或发起维权行动之日终止。 + + 3. 无商标许可 + + “本许可证”不提供对“贡献者”的商品名称、商标、服务标志或产品名称的商标许可，但您为满足第4条规定的声明义务而必须使用除外。 + + 4. 分发限制 + + 您可以在任何媒介中将“软件”以源程序形式或可执行形式重新分发，不论修改与否，但您必须向接收者提供“本许可证”的副本，并保留“软件”中的版权、商标、专利及免责声明。 + + 5. 免责声明与责任限制 + + “软件”及其中的“贡献”在提供时不带任何明示或默示的担保。在任何情况下，“贡献者”或版权所有者不对任何人因使用“软件”或其中的“贡献”而引发的任何直接或间接损失承担责任，不论因何种原因导致或者基于何种法律理论，即使其曾被建议有此种损失的可能性。 + + 6. 语言 + “本许可证”以中英文双语表述，中英文版本具有同等法律效力。如果中英文版本存在任何冲突不一致，以中文版为准。 + + 条款结束 + + 如何将木兰宽松许可证，第2版，应用到您的软件 + + 如果您希望将木兰宽松许可证，第2版，应用到您的新软件，为了方便接收者查阅，建议您完成如下三步： + + 1， 请您补充如下声明中的空白，包括软件名、软件的首次发表年份以及您作为版权人的名字； + + 2， 请您在软件包的一级目录下创建以“LICENSE”为名的文件，将整个许可证文本放入该文件中； + + 3， 请将如下声明文本放入每个源文件的头部注释中。 + + Copyright (c) 2021 浙江九州云信息科技有限公司 + + jianmu is licensed under Mulan PSL v2. + You can use this software according to the terms and conditions of the Mulan PSL v2. + You may obtain a copy of Mulan PSL v2 at: + http://license.coscl.org.cn/MulanPSL2 + THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. + See the Mulan PSL v2 for more details. + + + Mulan Permissive Software License，Version 2 + + Mulan Permissive Software License，Version 2 (Mulan PSL v2) + January 2020 http://license.coscl.org.cn/MulanPSL2 + + Your reproduction, use, modification and distribution of the Software shall be subject to Mulan PSL v2 (this License) with the following terms and conditions: + + 0. Definition + + Software means the program and related documents which are licensed under this License and comprise all Contribution(s). + + Contribution means the copyrightable work licensed by a particular Contributor under this License. + + Contributor means the Individual or Legal Entity who licenses its copyrightable work under this License. + + Legal Entity means the entity making a Contribution and all its Affiliates. + + Affiliates means entities that control, are controlled by, or are under common control with the acting entity under this License, ‘control’ means direct or indirect ownership of at least fifty percent (50%) of the voting power, capital or other securities of controlled or commonly controlled entity. + + 1. Grant of Copyright License + + Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable copyright license to reproduce, use, modify, or distribute its Contribution, with modification or not. + + 2. Grant of Patent License + + Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable (except for revocation under this Section) patent license to make, have made, use, offer for sale, sell, import or otherwise transfer its Contribution, where such patent license is only limited to the patent claims owned or controlled by such Contributor now or in future which will be necessarily infringed by its Contribution alone, or by combination of the Contribution with the Software to which the Contribution was contributed. The patent license shall not apply to any modification of the Contribution, and any other combination which includes the Contribution. If you or your Affiliates directly or indirectly institute patent litigation (including a cross claim or counterclaim in a litigation) or other patent enforcement activities against any individual or entity by alleging that the Software or any Contribution in it infringes patents, then any patent license granted to you under this License for the Software shall terminate as of the date such litigation or activity is filed or taken. + + 3. No Trademark License + + No trademark license is granted to use the trade names, trademarks, service marks, or product names of Contributor, except as required to fulfill notice requirements in Section 4. + + 4. Distribution Restriction + + You may distribute the Software in any medium with or without modification, whether in source or executable forms, provided that you provide recipients with a copy of this License and retain copyright, patent, trademark and disclaimer statements in the Software. + + 5. Disclaimer of Warranty and Limitation of Liability + + THE SOFTWARE AND CONTRIBUTION IN IT ARE PROVIDED WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL ANY CONTRIBUTOR OR COPYRIGHT HOLDER BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM YOUR USE OR INABILITY TO USE THE SOFTWARE OR THE CONTRIBUTION IN IT, NO MATTER HOW IT’S CAUSED OR BASED ON WHICH LEGAL THEORY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + + 6. Language + + THIS LICENSE IS WRITTEN IN BOTH CHINESE AND ENGLISH, AND THE CHINESE VERSION AND ENGLISH VERSION SHALL HAVE THE SAME LEGAL EFFECT. IN THE CASE OF DIVERGENCE BETWEEN THE CHINESE AND ENGLISH VERSIONS, THE CHINESE VERSION SHALL PREVAIL. + + END OF THE TERMS AND CONDITIONS + + How to Apply the Mulan Permissive Software License，Version 2 (Mulan PSL v2) to Your Software + + To apply the Mulan PSL v2 to your work, for easy identification by recipients, you are suggested to complete following three steps: + + i Fill in the blanks in following statement, including insert your software name, the year of the first publication of your software, and your name identified as the copyright owner; + + ii Create a file named “LICENSE” which contains the whole context of this License in the first directory of your software package; + + iii Attach the statement to the appropriate annotated syntax at the beginning of each source file. + + + Copyright (c) 2021 浙江九州云信息科技有限公司 + jianmu is licensed under Mulan PSL v2. + You can use this software according to the terms and conditions of the Mulan PSL v2. + You may obtain a copy of Mulan PSL v2 at: + http://license.coscl.org.cn/MulanPSL2 + THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. + See the Mulan PSL v2 for more details. diff --git a/README.md b/README.md index 897c7e6379ff99f7300333ca02124bde966c72a5..50576179738ea26c1d27f462559b021085163343 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -# jianmu-docs +# 建木项目文档 #### 介绍 -jianmu-docs是建木团队开源的建木自动化集成平台相关的所有文档说明 +jianmu-docs是建木团队开源的建木自动化集成平台相关文档说明，通过该文档库维护官方文档更新，详情见：https://docs.jianmu.dev/guide/。 -#### 安装 +#### 文档安装 ``` bash # 安装依赖 @@ -16,5 +16,5 @@ npm run dev 或 yarn dev npm run build 或 yarn build ``` -#### 开源协议 -本项目基于Apache License 2.0协议。 +#### 文档开源协议 +本项目基于木兰宽松许可证, 第2版。 diff --git a/dsl/cicd.yml b/dsl/cicd.yml deleted file mode 100644 index e4a7cc7e20b56014c65d4b5293e8d5e295667c47..0000000000000000000000000000000000000000 --- a/dsl/cicd.yml +++ /dev/null @@ -1,28 +0,0 @@ -pipeline: - name: 建木文档CI/CD - ref: jianmu_docs_cicd - description: 建木文档CI/CD - git_clone: - type: git_clone:1.0.0 - param: - remote_url: https://gitee.com/jianmu-dev/jianmu-docs.git - ref: refs/heads/master - node_build: - type: nodejs_build:1.0.0-14.16.1 - param: - workspace: ${git_clone.git_path} - update_resoure: - type: scp_resouce:1.0.0 - param: - ssh_ip: 47.243.164.48 - ssh_private_key: ((private_key.alixg)) - remote_file: /etc/nginx/docs - local_file: ${git_clone.git_path}/.vitepress/dist - send_message: - type: qywx_notice:1.0.0 - param: - bot_webhook_url: ((charbot.webhook_url)) - mentioned_moblie_list: "[]" - text_content: "建木文档更新完成" - msgtype: "text" - mentioned_list: "[]" diff --git a/guide/centos-install.md b/guide/centos-install.md new file mode 100644 index 0000000000000000000000000000000000000000..996b216d91d2bf13c75bc2d43809e3a5419c9ea0 --- /dev/null +++ b/guide/centos-install.md @@ -0,0 +1,92 @@ +# CentOS 7.9安装注意事项 + +在CentOS 7.9安装过程需要替换自带的docker。 + +## 详细步骤 + +以root权限登陆系统，更新系统并安装docker。 + +更新操作系统,CentOS 7.9最新版本： +``` +yum -y update +``` + +移除CentOS默认的docker版本： +``` +yum remove docker \ + docker-client \ + docker-client-latest \ + docker-common \ + docker-latest \ + docker-latest-logrotate \ + docker-logrotate \ + docker-engine +``` + +配置docker官方yum仓库： +``` +yum install -y yum-utils +yum-config-manager \ + --add-repo \ + https://download.docker.com/linux/centos/docker-ce.repo +``` + +安装docker并启动： +``` +yum install docker-ce docker-ce-cli containerd.io +systemctl enable docker +systemctl restart docker +``` + +安装docker-compose： +``` +curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose +``` + +配置docker-compose权限： +``` +chmod +x /usr/local/bin/docker-compose +``` + +## 版本验证 + +验证环境可用性如下： + +``` +[root@localhost ~]# docker version +Client: Docker Engine - Community + Version: 20.10.11 + API version: 1.41 + Go version: go1.16.9 + Git commit: dea9396 + Built: Thu Nov 18 00:38:53 2021 + OS/Arch: linux/amd64 + Context: default + Experimental: true + +Server: Docker Engine - Community + Engine: + Version: 20.10.11 + API version: 1.41 (minimum version 1.12) + Go version: go1.16.9 + Git commit: 847da18 + Built: Thu Nov 18 00:37:17 2021 + OS/Arch: linux/amd64 + Experimental: false + containerd: + Version: 1.4.12 + GitCommit: 7b11cfaabd73bb80907dd23182b9347b4245eb5d + runc: + Version: 1.0.2 + GitCommit: v1.0.2-0-g52b36a2 + docker-init: + Version: 0.19.0 + GitCommit: de40ad0 + +[root@localhost ~]# docker-compose version +docker-compose version 1.29.2, build 5becea4c +docker-py version: 5.0.0 +CPython version: 3.7.10 +OpenSSL version: OpenSSL 1.1.0l 10 Sep 2019 + +``` \ No newline at end of file diff --git a/guide/cron.md b/guide/cron.md index 82808d78d84150a8c751e21f27dc6677d6ba0cf9..463f210f6fbe4357a9e3f4f77b8f6720a496a754 100644 --- a/guide/cron.md +++ b/guide/cron.md @@ -1,9 +1,15 @@ # Cron -可以使用Cron表达式来定义定时触发流程执行,例如: +可定义Cron表达式定时触发流程执行 + +**定义语法** ``` -cron: * 5/* * * * ? * +trigger: + type: cron + schedule: * 5/* * * * ? * ``` +* type: 此处固定填`cron`，必填 +* schedule: Cron表达式，必填 Cron表达式语法可以参考[这里](http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html) \ No newline at end of file diff --git a/guide/custom-node.md b/guide/custom-node.md index 3150ce7cee3031d85db56f20a4169c9540afcd7b..4a6b62f9618516afce28261707b6178a232738fd 100644 --- a/guide/custom-node.md +++ b/guide/custom-node.md @@ -39,83 +39,72 @@ 节点定义版本 dsl 说明： -| 关键字 | 说明 | -| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| ref | 归属人或归属组织的唯一标识/节点定义在归属内的唯一标识，必填，如：jianmu/hub_publish。若为官方节点定义，则可省略归属人或归属组织的唯一标识，如：hub_publish | -| version | 节点定义的版本，必填 | -| resultFile | 输出参数转换成 json 的文件路径，若定义了输出参数 outputParameters，则必填 | -| inputParameters | 输入参数列表 | -| inputParameters.ref | 参数唯一标识，会在容器内转译成'JIANMU\_'开头并大写的环境变量。如：hub_url 在容器内可通过 JIANMU_HUB_URL 环境变量调用，必填 | -| inputParameters.name | 参数名称，必填 | -| inputParameters.type | 参数类型，支持 STRING、SECRET、NUMBER、BOOL 等类型，必填。STRING/NUMBER/BOOL: 若参数类型为 STRING/NUMBER/BOOL，可直接填写值或引用其他变量(事件、全局、其他任务的输出等参数)。SECRET: 若参数类型为 SECRET，需要调用平台密钥，具体用法详见密钥管理章节 | -| inputParameters.value | 参数默认值，若执行该节点定义时，没有指定参数值，将会使用此默认值，必填 | -| inputParameters.description | 参数描述，选填 | -| outputParameters | 输出参数，需要在"resultFile"指定的文件路径内填写对应的 json 数据，key 为输出参数的唯一标识（ref）值，格式同输入参数 | -| spec | 镜像相关信息，节点定义类型为 docker 时，必填 | -| spec.image | 指定该节点定义使用的容器镜像，执行时，平台将会从 dockerhub 拉取指定镜像，必填 | -| spec.cmd | list 格式，指定容器运行时的 command 内容，选填 | -| spec.entrypoint | list 格式，指定容器运行时的 entrypoint 内容，选填 | - -节点定义示例: +| 关键字 | 说明 | +| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ref | 归属人或归属组织的唯一标识/节点定义在归属内的唯一标识，必填，如：jianmu/hub_publish。若为官方节点定义，则可省略归属人或归属组织的唯一标识，如：hub_publish | +| version | 节点定义的版本，必填 | +| resultFile | 输出参数转换成 json 的文件路径，若定义了输出参数 outputParameters，则必填 | +| inputParameters | 输入参数列表 | +| inputParameters.ref | 参数唯一标识，会在容器内转译成'JIANMU\_'开头并大写的环境变量。如：hub_url 在容器内可通过 JIANMU_HUB_URL 环境变量调用，必填 | +| inputParameters.name | 参数名称，必填 | +| inputParameters.type | 参数类型，支持 STRING、SECRET、NUMBER、BOOL 等类型，必填。STRING/NUMBER/BOOL: 若参数类型为 STRING/NUMBER/BOOL，可直接填写值或引用其他参数(事件、全局、其他任务的输出等参数)。SECRET: 若参数类型为 SECRET，需要调用平台密钥，具体用法详见密钥管理章节 | +| inputParameters.required | 参数是否必填，默认为 false。
required 为 false 或默认时，参数默认值 value 必填；required 为 true 时，不能有参数默认值 value | +| inputParameters.value | 参数默认值，若没有指定参数值，将会使用此默认值，若 required 为 false 或默认时，则必填 | +| inputParameters.description | 参数描述，选填 | +| outputParameters | 输出参数，需要定义 **required**，格式同输入参数；
需要在"resultFile"指定的文件路径内填写对应的 json 数据，key 为输出参数的唯一标识（ref）值，格式同输入参数 | +| spec | 镜像相关信息，节点定义类型为 docker 时，必填 | +| spec.image | 指定该节点定义使用的容器镜像，执行时，平台将会从 dockerhub 拉取指定镜像，必填 | +| spec.cmd | list 格式，指定容器运行时的 command 内容，选填 | +| spec.entrypoint | list 格式，指定容器运行时的 entrypoint 内容，选填 | + +节点定义版本示例: ``` -ref: git_clone +ref: redis_export version: 1.0.1 -resultFile: /usr/resultFile inputParameters: - - name: 用户名 - ref: netrc_username + - name: 主机地址 + ref: host type: SECRET - value: "" - description: git平台的账号 - - name: 密码 - ref: netrc_password + required: true + description: 主机地址 + - name: redis端口号 + ref: port + type: NUMBER + value: 6379 + description: redis端口号 + - name: redis密码 + ref: password type: SECRET - value: "" - description: git平台的密码 - - name: ssh私钥 - ref: ssh_key - type: SECRET - value: "" - description: 平台中设置的ssh公钥对应的私钥(id_rsa) - - name: git地址 - ref: remote_url - type: STRING - value: "" - description: 配置远程的git源,即从哪个url上clone项目,使用账号密码的方式的url"https://gitee.com/jianmu_dev/jianmu-ci-ui.git"或者使用ssh的方式的url"git@gitee.com:jianmu_dev/jianmu-ci-ui.git" - - name: git引擎 - ref: netrc_machine + value: ((xxx.xxx)) + description: redis密码 + - name: 数据库 + ref: database type: STRING - value: "" - description: gitee.com,github.com,gitlab.com等等 - - name: 标签或分支 - ref: ref + value: '' + description: 需要导出的数据库，默认为空，导出所有数据库 + - name: 模糊查询的key值 + ref: key type: STRING - value: refs/heads/master - description: 需要git的标签或者分支,如果是branch则格式为："/refs/heads/master",如果是tag则格式为："/refs/tags/1.0.0" + value: '' + description: 模糊查询的key值，默认为空，导出所有key outputParameters: - - ref: git_path - name: git clone目录 - type: STRING - value: "" - description: 会将clone完成后的项目存放的地址以绝对路径的方式返回 - - ref: git_branch - name: git分支 + - name: 导出的redis文件路径 + ref: redis_path type: STRING - value: "" - description: 如果选择git分支,则会将此分支名返回,如：master,git_tag参数和git_branch参数只会返回一个 - - ref: git_tag - name: git tags - type: STRING - value: "" - description: 如果选择某个标签,则会将此标签返回,如：1.0.0,git_tag参数和git_branch参数只会返回一个 + required: true + description: 导出的redis文件路径 +resultFile: /usr/result_file spec: - image: 'jianmudev/jianmu-runner-git-clone:1.0.1' + image: jianmudev/jianmu-runner-redis:1.0.0 + cmd: + - bash + - /usr/local/bin/export.sh ``` 相关链接： -1. 节点输出参数：[变量](vars.md) +1. 节点输出参数：[参数](vars.md) 2. 调用平台密钥：[密钥管理](secrets.md) 3. spec 的其他非必填参数：[spec 参数](https://gitee.com/jianmu-dev/jianmu-ci-server/blob/master/embedded-worker/src/main/java/dev/jianmu/embedded/worker/aggregate/spec/ContainerSpec.java) @@ -124,35 +113,35 @@ spec: 1.流程代码: ``` +name: 发布节点定义版本 redis_export +description: 这是一个创建节点定义版本的流程定义样例 + workflow: - name: 创建节点定义版本“hub-publish” - ref: publish_hub_publish_version - description: 这是一个创建节点定义版本的流程定义样例 start: type: start targets: - git_clone git_clone: - type: git_clone:1.0.0 + type: git_clone:1.0.1 sources: - start targets: - hub_publish param: ref: refs/heads/master - remote_url: https://gitee.com/jianmu-runners/jianmu-runner-node-definition-version-publisher.git + remote_url: https://gitee.com/jianmu-runners/jianmu-runner-redis.git netrc_machine: gitee.com netrc_username: ((gitee.username)) netrc_password: ((gitee.password)) hub_publish: - type: hub_publish:1.0.0 + type: hub_publish:1.0.1 sources: - git_clone targets: - end param: hub_url: https://api.jianmu.run - dsl_file_path: /xxx/xxx + dsl_file_path: ${git_clone.git_path}/dsl/export.yml hub_api_key: ((xxx.xxx)) end: type: end @@ -170,23 +159,23 @@ hub_api_key 获取步骤： 2.管道代码； ``` +name: 发布节点定义版本 redis_export +description: 这是一个创建节点定义版本的管道定义样例 + pipeline: - name: 发布节点定义版本“hub-publish” - ref: publish_hub_publish_version - description: 这是一个创建节点定义版本的管道定义样例 git_clone: - type: git_clone:1.0.0 + type: git_clone:1.0.1 param: - remote_url: https://gitee.com/jianmu-runners/jianmu-runner-node-definition-version-publisher.git + remote_url: https://gitee.com/jianmu-runners/jianmu-runner-redis.git ref: refs/heads/master netrc_machine: gitee.com netrc_username: ((gitee.username)) netrc_password: ((gitee.password)) hub_publish: - type: hub_publish:1.0.0 + type: hub_publish:1.0.1 param: hub_url: https://api.jianmu.run - dsl_file_path: /xxx/xxx + dsl_file_path: ${git_clone.git_path}/dsl/export.yml hub_api_key: ((xxx.xxx)) ``` diff --git a/guide/event-bridge.md b/guide/event-bridge.md deleted file mode 100644 index 025c0bee7361ab951d9412c979f3e587bd1786ea..0000000000000000000000000000000000000000 --- a/guide/event-bridge.md +++ /dev/null @@ -1,74 +0,0 @@ -# 事件桥接器 - -事件桥接器可以接收外部事件来触发项目的执行 - -### 核心概念 - -**来源** - -外部事件的来源，当前只支持Webhook类型的外部调用事件 - -登录后可以复制来源提供的Webhook链接给第三方调用 - -**目标** - -外部事件将要触发的目标，通过目标上设置的唯一标识来关联项目 - -*注意：此唯一标识必须全局唯一* - -**如何与项目关联** -``` -eb: your_target_ref -``` -在项目DSL中添加以上定义来关联目标 - -**转换器** - -在目标上可以配置多个转换器，转换器可以使用提取表达式从原始事件中提取事件变量，以供项目DSL中引用 - -当前根据提取的位置不同，提供三类转换器 - -* Body转换器：使用JsonPath语法来提取变量值 -* Header转换器：使用header的key来提前header的value -* Query转换器：使用QueryString中的key提取value - -### JsonPath示例 - -``` -{ "store": { - "book": [ - { "category": "reference", - "author": "Nigel Rees", - "title": "Sayings of the Century", - "price": 8.95 - }, - { "category": "fiction", - "author": "Evelyn Waugh", - "title": "Sword of Honour", - "price": 12.99 - }, - { "category": "fiction", - "author": "Herman Melville", - "title": "Moby Dick", - "isbn": "0-553-21311-3", - "price": 8.99 - }, - { "category": "fiction", - "author": "J. R. R. Tolkien", - "title": "The Lord of the Rings", - "isbn": "0-395-19395-8", - "price": 22.99 - } - ], - "bicycle": { - "color": "red", - "price": 19.95 - } - } -} -``` -表达式`$.store.book[0].title`的结果是`"Sayings of the Century"` - -表达式`$.store.book[2].price`的结果是`8.99` - -*更高阶的和具体语法规范可以参考[这里](https://goessner.net/articles/JsonPath/)* diff --git a/guide/expression.md b/guide/expression.md index 9af8ab76be66dc132c278844820297dab7e429fb..0fd248f6fe07c0b2d1bce19f0150a492f88ea2b3 100644 --- a/guide/expression.md +++ b/guide/expression.md @@ -29,7 +29,7 @@ ssh_cmd: echo 3 * 节点参数默认为字符串模版，如： ``` -# 全局变量: image_name = jianmu-runner-hub +# 全局参数: image_name = jianmu-runner-hub # node_build节点的输出参数: package_name = jianmu_runner_hub # node_build节点的输出参数: package_version = 1.0.0 pipeline: @@ -45,17 +45,17 @@ pipeline: ``` docker_file: Dockerfile ``` -2. 变量：`${xxx.xxx}` +2. 参数：`${xxx.xxx}` ``` -# 全局变量: image_name = jianmu-runner-hub +# 全局参数: image_name = jianmu-runner-hub image_name: ${global.image_name} ``` 等价于 ``` image_name: jianmu_runner_hub ``` -3. 变量 + 字符串：`${xxx.xxx}xxx${xxx.xxx}` +3. 参数 + 字符串：`${xxx.xxx}xxx${xxx.xxx}` ``` # node_build节点的输出参数: package_name = jianmu_runner_hub # node_build节点的输出参数: package_version = 1.0.0 diff --git a/guide/flow-dsl.md b/guide/flow-dsl.md index 8d3022154058851e32c07bc3e2a30b89b21749cf..eb3117e58402e76560769a5f36f79ba57e4ee844 100644 --- a/guide/flow-dsl.md +++ b/guide/flow-dsl.md @@ -7,10 +7,11 @@ CI/CD流程使用Yaml来定义 流程定义在workflow段落下： ``` +name: 流程名称 +description: 流程描述 + workflow: - name: 流程名称 - ref: 流程唯一标识 - description: 流程描述 + ``` ### 流程节点 @@ -88,4 +89,4 @@ workflow: netrc_password: ((gitee.password)) ``` -`输入参数`和`输出参数`也可以使用变量方式引用，详情参见[`变量章节`](vars.md) \ No newline at end of file +`输入参数`和`输出参数`也可以使用参数方式引用，详情参见[`参数章节`](vars.md) \ No newline at end of file diff --git a/guide/images/create_node_definition_version.png b/guide/images/create_node_definition_version.png index fd726ef6ae579df73057a3fedfc6d8d862961e4b..fad47f1da145448d75ce90d22f52c1850b300025 100644 Binary files a/guide/images/create_node_definition_version.png and b/guide/images/create_node_definition_version.png differ diff --git a/guide/images/view-webhook.png b/guide/images/view-webhook.png new file mode 100644 index 0000000000000000000000000000000000000000..42ec72a00ce10236cd7c3e0b1e2bb938ad1c4d9f Binary files /dev/null and b/guide/images/view-webhook.png differ diff --git a/guide/images/view_node_definition_version.png b/guide/images/view_node_definition_version.png index 2c3f2c266d62fef837fab1a64c1e0be193a15530..31592f6becb2434b705aa1114cf4e50359b79431 100644 Binary files a/guide/images/view_node_definition_version.png and b/guide/images/view_node_definition_version.png differ diff --git a/guide/images/wecom_bot_webhook.png b/guide/images/wecom_bot_webhook.png new file mode 100644 index 0000000000000000000000000000000000000000..4c731fe870bb464d5c77e7ccba7ea3c4faba765f Binary files /dev/null and b/guide/images/wecom_bot_webhook.png differ diff --git a/guide/images/wecom_space.png b/guide/images/wecom_space.png new file mode 100644 index 0000000000000000000000000000000000000000..25d552a3fdebc085664d4737e83a24846c71c78e Binary files /dev/null and b/guide/images/wecom_space.png differ diff --git a/guide/integration_with_vault.md b/guide/integration_with_vault.md new file mode 100644 index 0000000000000000000000000000000000000000..7048d0b0444f47b11b83d522cdbdf94431c77bfa --- /dev/null +++ b/guide/integration_with_vault.md @@ -0,0 +1,64 @@ +# 如何集成Vault来进行密钥管理 + +Vault支持的认证方式非常多，当前建木支持的有以下两种： + +* Token Auth Method +* TLS Certificates Auth Method + +部署Vault，请参考[这里](https://gitee.com/jianmu-dev/jianmu-deploy/blob/master/how_to_deploy_vault.md) + +## 前置准备 + +* Vault服务已正确部署 +* 如果使用TLS证书认证方式，则证书已生成 + +## 证书转换方式 + +将crt证书转换为P12证书,这里需要设置密码 + +``` +openssl pkcs12 -export -in vault.crt -inkey vault.key -out jianmu.p12 +``` + +再转换为Java所需的JKS证书，这里需要输入上面设置的密码 + +``` +keytool -importkeystore -keyalg EC -srckeystore jianmu.p12 -destkeystore jianmu.jks -srcstoretype pkcs12 +``` + +## 配置方式 + +不集成Vault的配置 + +``` +credential: + type: local +``` + +使用Token方式集成不使用HTTPS的Vault的配置 + +``` +credential: + type: vault + vault: + authentication: token + url: http://192.168.1.24:443 + token: s.QUiJwpVRpSshEYkS9Boewmbp + vault-engine-name: jianmu +``` + +使用Cert方式集成Vault的配置 + +``` +credential: + type: vault + vault: + authentication: cert + ssl: + key-store: file:jianmu.jks + key-store-password: 123456 + trust-store: file:jianmu.jks + trust-store-password: 123456 + url: https://192.168.1.24:443 + vault-engine-name: jianmu +``` diff --git a/guide/license-mixing.md b/guide/license-mixing.md index ef20bfd1a341c67fcc72e2c42edf0cd61e61a522..1b9c2017a5c36f9795352236b7b9383b5cb4b290 100644 --- a/guide/license-mixing.md +++ b/guide/license-mixing.md @@ -2,7 +2,7 @@ 建木用到了第三方库，可能是有自己授权，这篇文档介绍了建木和相关库的LICENSE问题。 -注意我们不是个律师，所以这不是法律建议，请找相关专业人士确认。 +注意我们不是律师，所以这不是法律建议，请找相关专业人士确认。 ## Spring boot diff --git a/guide/pipeline-dsl.md b/guide/pipeline-dsl.md index 2cb5da40078d3807ba56c97f01b123d48a92f0d9..c0def52d41c36b6ea6fe4a516e268c29d936cdc7 100644 --- a/guide/pipeline-dsl.md +++ b/guide/pipeline-dsl.md @@ -7,10 +7,11 @@ CI/CD管道使用Yaml来定义 管道定义在pipeline段落下： ``` +name: 管道名称 +description: 管道描述 + pipeline: - name: 管道名称 - ref: 管道唯一标识 - description: 管道描述 + ``` ### 管道节点 @@ -71,4 +72,4 @@ pipeline: hub_api_key: ((xxx.xxx)) ``` -`输入参数`和`输出参数`也可以使用变量方式引用，详情参见[`变量章节`](vars.md) \ No newline at end of file +`输入参数`和`输出参数`也可以使用参数方式引用，详情参见[`参数章节`](vars.md) \ No newline at end of file diff --git a/guide/project-group.md b/guide/project-group.md new file mode 100644 index 0000000000000000000000000000000000000000..bccfd8b61f571a0052b3f9ab7ff41fa4b5dcbff0 --- /dev/null +++ b/guide/project-group.md @@ -0,0 +1,70 @@ +# 一键还原项目 +一键还原 CI 中的项目 + +### 1. 项目组dsl文件 +**语法** +``` +groups: + - name: xxx + projects: + - xxx + - xxx + - name: xxx + projects: + - xxx + - xxx +``` +* name: 项目组的名称，尚未设置时为默认分组 +* projects: 需要导入的项目dsl文件，git仓库根目录的相对路径 + +**示例** +``` +groups: + - name: + projects: + # 批量导入 + - /batch_import.yml + # 建木api网关 + - /api-gw/cicd.yml + # 建木ci + - /ci/server_cicd.yml + - /ci/ui_cicd.yml + # 开发工具 + - /dev-tools/docker_image_builder.yml + # 建木hub + - /hub/server_cicd.yml + - /hub/ui_cicd.yml + # 官网 + - /official-site/cicd.yml + # ssl证书 + - /ssl/cert_cd.yml +``` + +### 2. 使用 +1.通过 [git clone](https://hub.jianmu.run/_/git_clone) 节点拉取项目组dsl文件、项目dsl文件所在的git仓库 + +2.通过 [同步项目组](https://hub.jianmu.run/_/sync_project_group) 节点，同步项目组dsl文件中定义的项目 + +**管道示例** +``` +name: 批量导入项目 + +pipeline: + git_clone: + type: git_clone:1.1.1 + param: + remote_url: https://gitee.com/jianmu-dev/jianmu-ci-dsl.git + ref: refs/heads/master + netrc_machine: gitee.com + netrc_username: ((gitee.username)) + netrc_password: ((gitee.password)) + sync_project_group: + type: sync_project_group:1.0.0 + param: + ci_url: https://ci.jianmu.run + ci_username: ((xxx.xxx)) + ci_password: ((xxx.xxx)) + git_path: ${git_clone.git_path} + group_file_path: /project_group.yml + deletable: false +``` \ No newline at end of file diff --git a/guide/quick-start.md b/guide/quick-start.md index 2b115e59faa7d0a40a17193fc317f27fd7b4ddb7..d8ed2f3110e7b5ff12bdd2b795a441cb2699d8ee 100644 --- a/guide/quick-start.md +++ b/guide/quick-start.md @@ -2,19 +2,20 @@ ### 系统要求 +推荐使用Ubuntu 21.04系统安装，如[CentOS 7可参考](https://docs.jianmu.dev/guide/centos-install.html)。 + Docker 19.30以上，[官方安装手册](https://docs.docker.com/get-started/#download-and-install-docker) Docker-Compose 1.29.2以上，[官方安装手册](https://docs.docker.com/compose/install/#install-compose) Kubernetes 1.18以上, [官方安装手册](https://kubernetes.io/docs/tasks/tools/) - -### docker部署 +### docker-compose部署 **下载`docker-compose.yml`** ``` -wget https://gitee.com/jianmu-dev/jianmu-deploy/raw/master/docker-compose.yml +wget https://gitee.com/jianmu-dev/jianmu-deploy/raw/2.0.0/docker-compose.yml ``` **启动** @@ -43,17 +44,31 @@ kubectl apply -f kubernetes.yaml 默认用户名密码为`admin/123456` -### 创建第一个项目 +### 创建第一个项目(来自建木的问候) -![create_porject](./images/create_project.png) +#### 前提条件说明 -点击git图标，URL输入`https://gitee.com/jianmu-dev/jianmu-docs.git` +* 有企业微信账号 +* 新建一个测试群 +* 测试群添加一个机器人，并获取机器人的webhook，形如：`https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=06de918a-fd35-45b7-b2e6-cff28371fd5d` -分支为默认的`master`无需修改 +#### 设置企业微信空间 -关闭下方的认证开关，点击下一步 +1. 创建企业微信用户空间，点击秘钥管理，填写命名空间和描述如下： +![create_space](./images/wecom_space.png) +2. 进入命名空间，创建秘钥，填写名称和值，参考如下 +![create_bot_webhook](./images/wecom_bot_webhook.png) -选择`hello_jianmu.yml`，点击保存 +#### 创建并执行第一个项目 + +1. 创建第一个hello项目 +![create_porject](./images/create_project.png) +2. 点击git图标，URL输入`https://gitee.com/jianmu-dev/jianmu-docs.git` +3. 填写分支为`2.0.0` +4. 关闭下方的认证开关，点击下一步 +5. 选择`hello_world.yml`，点击保存 -系统将会根据导入的yaml文件生成名为`hello_jianmu`的流程并在每小时的0/30分时触发执行。 +#### 实现效果 +1. 您可以点击项目立即触发执行，届时可以看到测试企业群的Bot就会给你第一个问候。 +2. 系统将会根据导入的yaml文件生成名为`hello_world`的流程并在每小时的0/30分时触发执行。 \ No newline at end of file diff --git a/guide/secrets.md b/guide/secrets.md index 259298377ba07b0f41f6640e63735df95f8f5468..1ee94f3b0742d775b2dfd079fef5021d99876335 100644 --- a/guide/secrets.md +++ b/guide/secrets.md @@ -52,3 +52,8 @@ ### 命名空间删除 点击命名空间标签右上角删除按钮，会弹出删除密钥提示框，点击确定后，即可删除对应命名空间，删除命名空间时，会同步删除其中所有的密钥。 + +### 第三方密钥库 +官方支持集成的密钥库如下： + +* [vault](integration_with_vault.md) \ No newline at end of file diff --git a/guide/shell-node.md b/guide/shell-node.md new file mode 100644 index 0000000000000000000000000000000000000000..049b00a740b7138ce4ecf4ffb158d0d9e2bcd2ff --- /dev/null +++ b/guide/shell-node.md @@ -0,0 +1,72 @@ +# Shell节点 +### 概念 + +可以在 DSL 中定义 Shell 节点，在指定镜像启动的容器中，执行多条 Shell 命令 + + +### 节点定义说明 +``` +image: 指定镜像，必填 +environment: 定义环境变量，会在容器内转译成大写的环境变量。如: aaa 在容器内可通过 AAA 环境变量调用，非必填 +script: 定义Shell命令，非必填，可使用上面定义的环境变量 +``` +在`environment`中可以使用表达式，引用全局参数、事件参数或上游节点的输出参数，详见[参数章节](vars.md) + +**注**：Shell节点没有输出参数 + +### 语法 + +**workflow示例** +``` +name: ShellNodeTest + +global: + param: + abc: abc + +workflow: + start: + targets: + - shell_node + type: start + shell_node: + sources: + - start + targets: + - end + image: ubuntu:18.04 + environment: + aaa: aaa${global.abc} + bBb: bbb666 + CCC: ccc666 + script: + - echo $AAA + - echo $BBB + - echo $CCC + end: + sources: + - shell_node + type: end +``` + +**pipeline示例** +``` +name: ShellNodeTest + +global: + param: + abc: abc + +pipeline: + shell_node: + image: ubuntu:18.04 + environment: + aaa: aaa${global.abc} + bBb: bbb666 + CCC: ccc666 + script: + - echo $AAA + - echo $BBB + - echo $CCC +``` + diff --git a/guide/vars.md b/guide/vars.md index e9eaf45307d998396d35989640356e2779f806d3..8aa548dee42d09003fb14f6311c99ae68e1bcb74 100644 --- a/guide/vars.md +++ b/guide/vars.md @@ -2,35 +2,104 @@ ### 全局参数 -可以在流程定义的`param`段落中定义全局参数，语法如下： +可以在流程定义的`param`段落中定义全局参数，参数类型`type`支持 STRING、NUMBER、BOOL。语法如下： ``` -param: - image_name: jianmudev/private +global: + param: + image_name: + type: STRING + value: jianmudev/private + num: + type: NUMBER + value: 10 + bool: + type: BOOL + value: true +``` +**注：出于安全性考虑，全局参数的`type`不支持 SECRET 类型** + +可以在参数名后面，直接定义参数值，**将默认为 STRING 类型** +``` +global: + param: + image_name: jianmudev/private ``` 然后可以在节点定义的输入参数中进行引用，语法如下： ``` - maven_jib_build: +maven_jib_build: type: maven_build:1.2.0-jdk11 param: image_name: ${global.image_name} ``` -### 事件参数 +### 触发器参数 + +如果当前流程已经定义了[Webhook](webhook.md)，那么当流程被事件触发时，可以使用如下语法来引用目标事件中的参数： + +`${trigger.gitlab_ref}` -如果当前流程已经与[事件桥接器](event-bridge.md)中的目标绑定，那么当流程被事件触发时，可以使用如下语法来引用目标事件中的参数： +完整例子： ``` -clone: +name: git_clone_test + +trigger: + type: webhook + param: + - name: gitlab_ref + type: STRING + exp: $.body.json.gitlab_ref + +pipeline: + clone: type: git_clone:1.0.0 param: remote_url: (`https://gitee.com/jianmu-dev/jianmu-ci-ui.git`) - ref: ${event.gitlab_ref} + ref: ${trigger.gitlab_ref} ``` ### 输出参数 可以在当前节点的输入参数中引用上游节点的输出参数的值： +#### 管道定义 +``` +name: 发布hub-server镜像 +description: 发布hub-server镜像 + +pipeline: + git_clone: + type: git_clone:1.0.0 + param: + remote_url: https://gitee.com/jianmu-hub/jianmu-hub-server.git + ref: refs/heads/master + netrc_machine: gitee.com + netrc_username: ((gitee.username)) + netrc_password: ((gitee.password)) + maven_jib_build: + type: maven_build:1.2.0-jdk11 + param: + workspace: ${pipeline.git_clone.git_path} ``` +如上所示，`maven_jib_build`节点可以使用`${pipeline.git_clone.git_path}`的语法 + +也可以简写成`${git_clone.git_path}` + +引用`git_clone`节点的输出参数`git_path`的值作为输入参数`workspace`的值 + +#### 流程定义 +``` +name: 发布hub-server镜像 +description: 发布hub-server镜像 + +workflow: + start: + targets: + - git_clone + type: start git_clone: + sources: + - start + targets: + - maven_jib_build type: git_clone:1.0.0 param: remote_url: https://gitee.com/jianmu-hub/jianmu-hub-server.git @@ -39,10 +108,18 @@ clone: netrc_username: ((gitee.username)) netrc_password: ((gitee.password)) maven_jib_build: + sources: + - git_clone + targets: + - end type: maven_build:1.2.0-jdk11 param: - workspace: ${git_clone.git_path} + workspace: ${workflow.git_clone.git_path} + end: + sources: + - maven_jib_build + type: end ``` -如上所示，`maven_jib_build`节点可以使用`${git_clone.git_path}`的语法 +如上所示，`maven_jib_build`节点可以使用`${workflow.git_clone.git_path}`的语法，也可以简写成`${git_clone.git_path}` 引用`git_clone`节点的输出参数`git_path`的值作为输入参数`workspace`的值 diff --git a/guide/webhook.md b/guide/webhook.md new file mode 100644 index 0000000000000000000000000000000000000000..08a09d94ab6873105bfea03e71fd2d1f4ee1c73d --- /dev/null +++ b/guide/webhook.md @@ -0,0 +1,131 @@ +# Webhook + +Webhook可以接收外部事件来触发项目执行 + +### 如何定义 + +**定义语法** +``` +trigger: + type: webhook + param: + - name: xxx + type: STRING + exp: $.xxx.xxx + auth: + token: ${trigger.xxx} + value: ((xxx.xxx)) + only: (${trigger.xxx} == "xxx") +``` +* type: 此处固定填`webhook`，必填 +* param: 触发器参数，非必填，*引用触发器参数参考[参数章节](vars.md)* + * name: 参数名称，必填 + * type: 参数类型，支持类型：STRING、NUMBER、BOOL、SECRET，必填 + * exp: 提取参数表达式，必填，*详见[提取规则](#触发器参数提取规则)* +* auth: 认证鉴权，非必填 + * token: Webhook请求携带的认证鉴权数据，如：请求头中的Authorization、Token等，`auth`存在时必填，支持[运算表达式](expression.md#运算表达式)和[字符串模版](expression.md#字符串模版) + * value: 用于校验`token`值，相同则验证成功，必须是密钥类型，`auth`存在时必填 +* only: 匹配规则，结果为 true 时触发流程，可以引用`全局参数`、`触发器参数`，非必填。*详见[运算表达式](expression.md)* + +**示例** +``` +trigger: + type: webhook + param: + - name: gitee_token + type: SECRET + exp: $.header.X-Gitee-Token + - name: pr_state + type: STRING + exp: $.body.json.pull_request.state + - name: pr_target_branch + type: STRING + exp: $.body.json.target_branch + auth: + token: ${trigger.gitee_token} + value: ((gitee.webhook_token)) + only: ((${trigger.pr_target_branch} == "wap" || ${trigger.pr_target_branch} == "web") && ${trigger.pr_state} == "merged") +``` +在项目DSL中添加以上定义，保存后会自动生成 Webhook链接 +![view-webhook.png](./images/view-webhook.png) + +### 触发器参数提取规则 + +可使用 [JsonPath](https://goessner.net/articles/JsonPath/) 从Webhook请求中提取触发器参数，以供项目DSL中引用 + +根据提取的位置不同，提取规则如下： + +* Header：$.header.xxx +* Query：$.query.xxx +* Body： + * JSON: $.body.json.xxx + * Form表单：$.body.form.xxx + * Text: $.body.text + +**Webhook请求参数示例** +``` +Webhook: +payload: { + "header": { + "content-length": "149", + "postman-token": "2ffe99d2-ff91-4546-a029-a9da8093c1ff", + "x-nginx-proxy": "true", + "connection": "close", + "content-type": "application/json", + "x-client-type": "jianmu", + "accept": "*/*" + }, + "query": { + "phone": "10086" + }, + "body": { + "json": { + "token": "yWi6XOJQ2VQ9BKSUnlK9jTiHY", + "user": [ + { + "name": "Jerry", + "age": 3 + }, + { + "name": "Tom", + "age": 5 + } + ] + } + } +} +``` + +**提取示例** +``` +trigger: + type: webhook + param: + - name: type + type: STRING + exp: $.header.x-client-type + - name: phone + type: STRING + exp: $.query.phone + - name: token + type: STRING + exp: $.body.json.token + - name: name + type: STRIING + exp: $.body.json.user[0].name + - name: age + type: NUMBER + exp: $.body.json.user[0].age + +``` +表达式`$.header.x-client-type`的结果是`"jianmu"` + +表达式`$.query.phone`的结果是`"10086"` + +表达式`$.body.json.token`的结果是`"yWi6XOJQ2VQ9BKSUnlK9jTiHY"` + +表达式`$.body.json.user[0].name`的结果是`"Jerry"` + +表达式`$.body.json.user[0].age`的结果是`3` + +*更高阶的用法和具体语法规范可以参考[这里](https://goessner.net/articles/JsonPath/)* diff --git a/hello-world.yml b/hello-world.yml new file mode 100644 index 0000000000000000000000000000000000000000..e52ef75d232f8863be0122955835a3d12c41b70b --- /dev/null +++ b/hello-world.yml @@ -0,0 +1,25 @@ +name: hello world +description: 建木快速入门，从hello world开始！ + +trigger: + type: cron + schedule: 0 0/30 * * * ? + +workflow: + start: + type: start + targets: + - sayhello + sayhello: + type: qywx_notice:1.2.1 + param: + bot_webhook_url: "((wecom.bot_webhook))" + text_content: "这是来自建木的第一个问候！" + sources: + - start + targets: + - end + end: + type: end + sources: + - sayhello \ No newline at end of file diff --git a/hello_jianmu.yml b/hello_jianmu.yml index f029d71ff6435cb85224ab5112ec1624ac39729a..64e46dbc7bbfd7d173326bb110c7c7eb342311eb 100644 --- a/hello_jianmu.yml +++ b/hello_jianmu.yml @@ -1,8 +1,11 @@ -cron: 0 0/30 * * * ? +name: hello jianmu +description: 快速开始构建建木，从hello jianmu开始 + +trigger: + type: cron + schedule: 0 0/30 * * * ? + pipeline: - name: hello jianmu - ref: hello_jianmu - description: 快速开始构建建木，从hello jianmu开始 ssh_cmd: type: ssh_cmd:1.0.0 param: