From b90c5d1e4379da021a64d7165e8fb7d421092b15 Mon Sep 17 00:00:00 2001 From: fit2cloud-fengyi Date: Thu, 8 Mar 2018 12:00:14 +0800 Subject: [PATCH] =?UTF-8?q?=E8=8B=B1=E6=96=87=E6=A0=BC=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/admin_instruction.rst | 14 ++--- docs/admin_system_settings.rst | 6 +-- docs/api_style_guide.rst | 53 +++++++++---------- docs/contributor.rst | 8 +-- docs/introduce.rst | 6 +-- docs/project_structure.rst | 28 +++++----- docs/python_style_guide.rst | 80 ++++++++++++++--------------- docs/quickstart.rst | 6 +-- docs/step_by_step.rst | 93 ++++++++++++++++------------------ docs/upgrade.rst | 8 +-- 10 files changed, 145 insertions(+), 157 deletions(-) diff --git a/docs/admin_instruction.rst b/docs/admin_instruction.rst index 3e513b92d..77719f5b1 100644 --- a/docs/admin_instruction.rst +++ b/docs/admin_instruction.rst @@ -9,15 +9,15 @@ ================= Jumpserver -``````````` -现指Jumpserver管理后台，是核心组件(Core), 使用 Django Class Based View 风格开发，支持Restful API。 +````````````` +现指 Jumpserver 管理后台，是核心组件（Core）, 使用 Django Class Based View 风格开发，支持 Restful API。 `Github `_ Coco ```````` -实现了SSH Server 和 Web Terminal Server的组件，提供ssh和websocket接口, 使用 Paramiko 和 Flask 开发。 +实现了 SSH Server 和 Web Terminal Server 的组件，提供 SSH 和 WebSocket 接口, 使用 Paramiko 和 Flask 开发。 `Github `__ @@ -25,19 +25,19 @@ Coco Luna ```````` -现在是Web Terminal前端，计划前端页面都由该项目提供，Jumpserver只提供API，不再负责后台渲染html等。 +现在是 Web Terminal 前端，计划前端页面都由该项目提供，Jumpserver 只提供 API，不再负责后台渲染html等。 `Github `__ Guacamole ``````````` -Apache 跳板机项目，Jumpserver使用其组件实现RDP功能，Jumpserver并没有修改其代码而是添加了额外的插件，支持Jumpserver调用 +Apache 跳板机项目，Jumpserver 使用其组件实现 RDP 功能，Jumpserver 并没有修改其代码而是添加了额外的插件，支持 Jumpserver 调用。 -Jumpserver-python-sdk +Jumpserver-Python-SDK ``````````````````````` -Jumpserver API Python SDK，Coco目前使用该SDK与Jumpserver API交互 +Jumpserver API Python SDK，Coco 目前使用该 SDK 与 Jumpserver API 交互。 `Github `__ diff --git a/docs/admin_system_settings.rst b/docs/admin_system_settings.rst index eca804a62..e6d6f4590 100644 --- a/docs/admin_system_settings.rst +++ b/docs/admin_system_settings.rst @@ -17,21 +17,21 @@ 基本设置 ````````` -点击页面上边的“基本设置“ TAB ，进入基本设置页面，编辑当前站点 URL、用户想到 URL、Email 主题前缀等信息，点击“提交”按钮，基本设置完成。 +点击页面上边的"基本设置" TAB ，进入基本设置页面，编辑当前站点 URL、用户想到 URL、Email 主题前缀等信息，点击“提交”按钮，基本设置完成。 .. _email_settings: 邮件设置 ````````` -点击页面上边的“邮件设置” TAB ，进入邮件设置页面，编辑 SMTP 主机、SMTP 端口、SMTP 账号、SMTP 密码和使用 SSL 或者 TSL 等信息，点击“测试连接”按钮，测试是否正确设置，点击“提交”按钮，邮件设置完成。 +点击页面上边的"邮件设置" TAB ，进入邮件设置页面，编辑 SMTP 主机、SMTP 端口、SMTP 账号、SMTP 密码和使用 SSL 或者 TSL 等信息，点击“测试连接”按钮，测试是否正确设置，点击“提交”按钮，邮件设置完成。 .. _ladp_settings: LDAP 设置 ```````````` -点击页面上边的“ LDAP 设置” TAB ，进入 LDAP 设置页面，编辑 LDAP 地址、DN、用户 OU、用户过滤器、LDAP 属性映射和是否使用 SSL、是否启用 LDAP 认证等信息，点击“测试连接”按钮，测试是否正确设置，点击“提交”按钮，完成 LDAP 设置。 +点击页面上边的" LDAP 设置" TAB ，进入 LDAP 设置页面，编辑 LDAP 地址、DN、用户 OU、用户过滤器、LDAP 属性映射和是否使用 SSL、是否启用 LDAP 认证等信息，点击“测试连接”按钮，测试是否正确设置，点击“提交”按钮，完成 LDAP 设置。 .. _terminal_settings: diff --git a/docs/api_style_guide.rst b/docs/api_style_guide.rst index 438a6d94a..ee0103afb 100644 --- a/docs/api_style_guide.rst +++ b/docs/api_style_guide.rst @@ -1,21 +1,21 @@ REST API规范约定 ---------------- -这里仅考虑REST API的基本情况。参考 +这里仅考虑 REST API 的基本情况。参考 `RESTful API 设计指南`_ -`github api文档`_ +`Github API 文档`_ 协议 ~~~~ -API与用户的通信协议，总是使用HTTPs协议。 +API 与用户的通信协议，总是使用 HTTPS 协议。 域名 ~~~~ -这版api相对简单, 没有前后端分离, 没有独立app, 所以放在主域名下 +这版 API 相对简单, 没有前后端分离, 没有独立 APP, 所以放在主域名下 :: @@ -24,8 +24,7 @@ API与用户的通信协议，总是使用HTTPs协议。 版本 ~~~~ -将API的版本号放入URL中, 由于一个项目多个app所以Jumpserver使用以下风格, -将版本号放到app后面 +将 API 的版本号放入 URL 中，由于一个项目多个 APP 所以 Jumpserver 使用以下风格，将版本号放到 APP 后面 :: @@ -36,9 +35,9 @@ API与用户的通信协议，总是使用HTTPs协议。 路径 ~~~~ -路径又称“终点”（endpoint），表示API的具体网址。 -在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的“集合”（collection），所以API中的名词也应该使用复数。 -举例来说 cmdb中的assets列表, idc列表 +路径又称“终点”（endpoint），表示 API 的具体网址。 +在 RESTful 架构中，每个网址代表一种资源（Resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的“集合”（Collection），所以 API 中的名词也应该使用复数。 +举例来说 Cmdb 中的 Assets 列表, IDC 列表。 :: @@ -48,18 +47,14 @@ API与用户的通信协议，总是使用HTTPs协议。 https://example.com/api/assets/v1.0/assets/1 [GET, PUT, DELETE] https://example.com/api/assets/v1.0/idcs [GET, POST] -一般性的增删查改(CRUD)API，完全使用HTTP -method加上url提供的语义，url中的可变部分（比如上面提到的） -一般用来传递该API操作的核心实体对象的唯一ID，如果有更多的参数需要提供，GET方法请使用url -parameter -(例如：“?client_id=xxxxx&app_id=xxxxxx”)，PUT/POST/DELETE方法请使用请求体传递参数。 +一般性的增删查改（CRUD）API，完全使用 HTTP Method 加上 URL 提供的语义，URL 中的可变部分（比如上面提到的），一般用来传递该API操作的核心实体对象的唯一 ID，如果有更多的参数需要提供，GET 方法请使用 URL Parameter（例如：“?client_id=xxxxx&app_id=xxxxxx”)，PUT/POST/DELETE 方法请使用请求体传递参数。 HTTP Method ~~~~~~~~~~~ -对于资源的具体操作类型，由HTTP动词表示。 +对于资源的具体操作类型，由 HTTP 动词表示。 -常用的HTTP动词有下面五个（括号里是对应的SQL命令）。 +常用的HTTP动词有下面五个（括号里是对应的 SQL 命令）。 - GET（SELECT）：从服务器取出资源（一项或多项）。 - POST（CREATE）：在服务器新建一个资源。 @@ -68,7 +63,7 @@ HTTP Method - DELETE（DELETE）：从服务器删除资源。 .. _RESTful API 设计指南: http://www.ruanyifeng.com/blog/2014/05/restful_api.html -.. _github api文档: https://developer.github.com/v3/ +.. _Github API 文档: https://developer.github.com/v3/ 过滤信息 @@ -90,8 +85,7 @@ HTTP Method 服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。 -- 200 OK - - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。 +- 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。 - 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。 - 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务） - 204 NO CONTENT - [DELETE]：用户删除数据成功。 @@ -113,7 +107,7 @@ HTTP Method 错误处理 ~~~~~~~~ -如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。 +如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将 error 作为键名，出错信息作为键值即可。 :: @@ -140,8 +134,8 @@ Hypermedia API ~~~~~~~~~~~~~~ RESTful -API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。 -比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。 +API 最好做到 Hypermedia，即返回结果中提供链接，连向其他 API 方法，使得用户不查文档，也知道下一步应该做什么。 +比如，当用户向 api.example.com 的根目录发出请求，会得到这样一个文档。 :: @@ -152,15 +146,18 @@ API最好做到Hypermedia，即返回结果中提供链接，连向其他API方 "type": "application/vnd.yourformat+json" }} -上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。 +上面代码表示，文档中有一个 Link 属性，用户读取这个属性就知道下一步该调用什么 API 了。 -rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址）， +- rel 表示这个 API 与当前网址的关系（Collection 关系，并给出该 Collection 的网址） +- href 表示 API 的路径 +- title 表示 API 的标题 +- type 表示返回类型 -href表示API的路径，title表示API的标题，type表示返回类型。 Hypermedia -API的设计被称为HATEOAS。 Github的API就是这种设计. +Hypermedia API 的设计被称为 HATEOAS。 Github API 就是这种设计. 其它 ~~~~ -（1）API的身份认证应该使用OAuth 2.0框架。 -（2）服务器返回的数据格式，应该尽量使用JSON \ No newline at end of file +（1）API 的身份认证应该使用 OAuth 2.0 框架。 + +（2）服务器返回的数据格式，应该尽量使用 JSON。 \ No newline at end of file diff --git a/docs/contributor.rst b/docs/contributor.rst index 4c351291f..579d105f6 100644 --- a/docs/contributor.rst +++ b/docs/contributor.rst @@ -1,16 +1,16 @@ 贡献者 ============= -感谢一下朋友为Jumpserver做出的贡献，世界因你们而不同，排名不分先后 +感谢以下朋友为 Jumpserver 做出的贡献，世界因你们而不同，排名不分先后 - **小彧 <李磊>** Django 资深开发者，为用户模块贡献了很多代码 - **sofia <周小侠>** 资深前端工程师, 前端代码贡献者 - **liuz <刘正> 全栈工程师** 编写了 Web Terminal 大部分代码 -- **jiaxiangkong <陈尚委>** Jumpserver测试运营 +- **jiaxiangkong <陈尚委>** Jumpserver 测试运营 - **halcyon <王墉>** DevOps 资深开发者, 0.3.2 核心开发者之一 -- **yumaojun03 <喻茂峻>** DevOps 资深开发者，擅长Python, Go以及 PaaS 平台开发 -- **kelianchun <柯连春>** DevOps 资产开发者，fix了很多bug +- **yumaojun03 <喻茂峻>** DevOps 资深开发者，擅长 Python、Go 以及 PaaS 平台开发 +- **kelianchun <柯连春>** DevOps 资产开发者，修复了很多 Bugs - **q4speed <莫鹍>** 架构师，贡献了 0.5.0 Windows 远程桌面登录大部分代码 - **ZhangFengyi <张峰毅>** 贡献了 0.5.0 新版文档 - **Aaron3S <沈晨阳>** 贡献了 0.5.0 新版文档 diff --git a/docs/introduce.rst b/docs/introduce.rst index eff6f16ca..910f21052 100644 --- a/docs/introduce.rst +++ b/docs/introduce.rst @@ -3,10 +3,10 @@ 欢迎来到 Jumpserver 文档。 -Jumpserver是全球首款完全开源的堡垒机，使用GNU GPL v2.0开源协议，是符合 4A 的专业运维审计系统。 +Jumpserver 是全球首款完全开源的堡垒机，使用 GNU GPL v2.0 开源协议，是符合 4A 的专业运维审计系统。 -Jumpserver使用Python / Django 进行开发，遵循 Web 2.0 规范，配备了业界领先的 Web Terminal 解决方案，交互界面美观、用户体验好。 +Jumpserver 使用 Python / Django 进行开发，遵循 Web 2.0 规范，配备了业界领先的 Web Terminal 解决方案，交互界面美观、用户体验好。 -Jumpserver采纳分布式架构，支持多机房跨区域部署，中心节点提供 API，各机房部署登录节点，可横向扩展、无并发访问限制。 +Jumpserver 采纳分布式架构，支持多机房跨区域部署，中心节点提供 API，各机房部署登录节点，可横向扩展、无并发访问限制。 改变世界，从一点点开始。 \ No newline at end of file diff --git a/docs/project_structure.rst b/docs/project_structure.rst index 151cda143..d809733a9 100644 --- a/docs/project_structure.rst +++ b/docs/project_structure.rst @@ -7,34 +7,34 @@ . ├── config-example.py // 配置文件样例 - ├── docs // 所有doc文件放到该目录 + ├── docs // 所有 DOC 文件放到该目录 │ └── README.md ├── LICENSE ├── README.md ├── install // 安装说明 ├── logs // 日志目录 - ├── apps // 管理后台目录，也是各app所在目录 - │ └── assets // app目录 + ├── apps // 管理后台目录，也是各 APP 所在目录 + │ └── assets // APP 目录 │ │ ├── admin.py - │ │ ├── apps.py // 新版本django app设置文件 - │ │ ├── api.py // api文件 - │ │ ├── __init__.py // 对外暴露的接口，放到该文件中，方便别的app引用 - │ │ ├── migrations // models Migrations版本控制目录 + │ │ ├── apps.py // 新版本 Django APP 设置文件 + │ │ ├── api.py // API 文件 + │ │ ├── __init__.py // 对外暴露的接口，放到该文件中，方便别的 APP 引用 + │ │ ├── migrations // Models Migrations 版本控制目录 │ │ │ └── __init__.py │ │ ├── models.py // 数据模型目录 - │ │ ├── static // app下静态资源目录,如果需要 + │ │ ├── static // APP 下静态资源目录,如果需要 │ │ │ └── assets // 多一层目录，防止资源重名 │ │ │ └── some_image.png - │ │ ├── templates // app下模板目录 + │ │ ├── templates // APP 下模板目录 │ │ │ └── assets // 多一层目录，防止资源重名 │ │ │ └── asset_list.html │ │ ├── templatetags // 模板标签目录 │ │ ├── tests.py // 测试用例文件 - │ │ ├── urls.py // urlconf文件 - │ │ ├── utils.py // 将views和api可复用的代码放在这里, api和views只是请求和返回不同 - │ │ └── views.py // views文件 + │ │ ├── urls.py // Urlconf 文件 + │ │ ├── utils.py // 将 Views 和 API 可复用的代码放在这里, API 和 Views 只是请求和返回不同 + │ │ └── views.py // Views 文件 │ ├── common - │ │ ├── templatetags // 通用template tag + │ │ ├── templatetags // 通用 Template Tag │ │ ├── utils.py // 通用的函数方法 │ │ └── views.py │ ├── fixtures // 初始化数据目录 @@ -43,7 +43,7 @@ │ ├── jumpserver // 项目设置目录 │ │ ├── __init__.py │ │ ├── settings.py // 项目设置文件 - │ │ ├── urls.py // 项目入口urlconf + │ │ ├── urls.py // 项目入口 Urlconf │ │ └── wsgi.py │ ├── manage.py │ ├── static // 项目静态资源目录 diff --git a/docs/python_style_guide.rst b/docs/python_style_guide.rst index 976e627ed..d182a8dd2 100644 --- a/docs/python_style_guide.rst +++ b/docs/python_style_guide.rst @@ -2,55 +2,54 @@ Jumpserver 项目规范（Draft） ============================ 语言框架 --------- +---------- 1. Python 3.6.1 (当前最新) 2. Django 1.11 (当前最新) 3. Flask 0.12 Luna (当前最新) 4. Paramiko 2.12 Coco (当前最新) -Django规范 ----------- +Django 规范 +-------------- -1. 尽量使用Class Base View编程，更少代码 -2. 使用Django Form -3. 每个url独立命名，不要硬编码，同理static也是 +1. 尽量使用 Class Base View 编程，更少代码 +2. 使用 Django Form +3. 每个 URL 独立命名，不要硬编码，同理 Static 也是 4. 数据库表名手动指定，不要使用默认 5. 代码优雅简洁 6. 注释明确优美 7. 测试案例尽可能完整 -8. 尽可能利用Django造好的轮子 +8. 尽可能利用 Django 造好的轮子 代码风格 --------- +----------- -Python方面大致的风格，我们采用pocoo的\ `Style +Python 方面大致的风格，我们采用 pocoo 的\ `Style Guidance`_\ ，但是有些细节部分会尽量放开 参考国内翻译 基本的代码布局 ~~~~~~~~~~~~~~ 缩进 -^^^^ +^^^^^^^^ -1. Python严格采用4个空格的缩进，任何python代码都都必须遵守此规定。 -2. web部分代码(HTML, CSS,JavaScript)，Node.js采用2空格缩进，同样不使用tab。 - 之所以与Python不同，是因为js中有大量回调式的写法，2空格可以显著降低视觉上的负担。 +1. Python 严格采用4个空格的缩进，任何 Python 代码都都必须遵守此规定。 +2. Web 部分代码（HTML、CSS、JavaScript），Node.js 采用2空格缩进，同样不使用 TAB。 + 之所以与 Python 不同，是因为 JS 中有大量回调式的写法，2空格可以显著降低视觉上的负担。 最大行长度 -^^^^^^^^^^ +^^^^^^^^^^^^^ -按PEP8规范，Python一般限制最大79个字符, -但是Django的命名,url等通常比较长, -而且21世纪都是宽屏了,所以我们限制最大120字符 +按 PEP8 规范，Python 一般限制最大79个字符， +但是 Django 的命名，URL 等通常比较长, +而且21世纪都是宽屏了，所以我们限制最大120字符 -**补充说明：HTML代码不受此规范约束。** +**补充说明：HTML 代码不受此规范约束。** 长语句缩进 -^^^^^^^^^^ +^^^^^^^^^^^^ -编写长语句时，可以使用换行符（）换行。在这种情况下，下一行应该与上一行的最后 -一个“.”句点或“=”对齐，或者是缩进4个空格符 +编写长语句时，可以使用换行符"\"换行。在这种情况下，下一行应该与上一行的最后一个“.”句点或“=”对齐，或者是缩进4个空格符。 :: @@ -81,7 +80,7 @@ Guidance`_\ ，但是有些细节部分会尽量放开 参考国内翻译 空行 -^^^^ +^^^^^^ 顶层函数与类之间空两行，此外都只空一行。不要在代码中使用太多的空行来区分不同的逻辑模块。 @@ -124,48 +123,45 @@ Guidance`_\ ，但是有些细节部分会尽量放开 参考国内翻译 ^^^^ 1. 任意类型之间的比较，使用“==”和“!=”。 -2. 与单例（singletons）进行比较时，使用is和is not。 +2. 与单例（singletons）进行比较时，使用 is 和 is not。 3. 永远不要与True或False进行比较（例如，不要这样写：foo == False，而应该这样写：not foo）。 否定成员关系检查 ^^^^^^^^^^^^^^^^ -使用foo not in bar，而不是not foo in bar。 +使用 foo not in bar，而不是 not foo in bar。 命名约定 ~~~~~~~~ -1. 类名称：采用骆驼拼写法（CamelCase），首字母缩略词保持大写不变（HTTPWriter，而不是HttpWriter）。 +1. 类名称：采用骆驼拼写法（CamelCase），首字母缩略词保持大写不变（HTTPWriter，而不是 HttpWriter）。 2. 变量名：小写_以及_下划线（lowercase_with_underscores）。 3. 方法与函数名：小写_以及_下划线（lowercase_with_underscores）。 4. 常量：大写_以及_下划线（UPPERCASE_WITH_UNDERSCORES）。 5. 预编译的正则表达式：name_re。 -6. 受保护的元素以一个下划线为前缀。双下划线前缀只有定义混入类（mixin - classes）时才使用。 -7. 如果使用关键词（keywords）作为类名称，应在名称后添加后置下划线（trailing - underscore）。 +6. 受保护的元素以一个下划线为前缀。双下划线前缀只有定义混入类（mixin classes）时才使用。 +7. 如果使用关键词（keywords）作为类名称，应在名称后添加后置下划线（trailing underscore）。 允许与内建变量重名，不要在变量名后添加下划线进行区分。如果函数需要访问重名的内建变量，请将内建变量重新绑定为其他名称。 -8. 命名要有寓意, 不使用拼音,不使用无意义简单字母命名 (循环中计数例外 for - i in) +8. 命名要有寓意, 不使用拼音,不使用无意义简单字母命名 (循环中计数例外 for i in) 9. 命名缩写要谨慎, 尽量是大家认可的缩写 函数和方法的参数： ^^^^^^^^^^^^^^^^^^ -1. 类方法：cls为第一个参数。 -2. 实例方法：self为第一个参数。 -3. property函数中使用匿名函数（lambdas）时，匿名函数的第一个参数可以用x替代， +1. 类方法：cls 为第一个参数。 +2. 实例方法：self 为第一个参数。 +3. property函数中使用匿名函数（lambdas）时，匿名函数的第一个参数可以用 x 替代， 例如：display_name = property(lambda x: x.real_name or x.username)。 -文档注释(Docstring，即各方法，类的说明文档注释) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +文档注释（Docstring，即各方法，类的说明文档注释） +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -所有文档字符串均以reStructuredText格式编写，方便Sphinx处理。文档字符串的行数不同，布局也不一样。 +所有文档字符串均以 reStructuredText 格式编写，方便 Sphinx 处理。文档字符串的行数不同，布局也不一样。 如果只有一行，代表字符串结束的三个引号与代表字符串开始的三个引号在同一行。 如果为多行，文档字符串中的文本紧接着代表字符串开始的三个引号编写，代表字符串结束的三个引号则自己独立成一行。 -(有能力尽可能用英文, 否则请中文优雅注释) +（有能力尽可能用英文, 否则请中文优雅注释） :: @@ -184,7 +180,7 @@ Guidance`_\ ，但是有些细节部分会尽量放开 参考国内翻译 模块头部 ~~~~~~~~ -模块文件的头部包含有utf-8编码声明（如果模块中使用了非ASCII编码的字符，建议进行声明），以及标准的文档字符串。 +模块文件的头部包含有 utf-8 编码声明（如果模块中使用了非 ASCII 编码的字符，建议进行声明），以及标准的文档字符串。 :: @@ -199,10 +195,10 @@ Guidance`_\ ，但是有些细节部分会尽量放开 参考国内翻译 :license: LICENSE_NAME, see LICENSE_FILE for more details. """ -注释(comment) -~~~~~~~~~~~~~ +注释（Comment） +~~~~~~~~~~~~~~~~ -注释的规范与文档字符串编写规范类似。二者均以reStructuredText格式编写。 +注释的规范与文档字符串编写规范类似。二者均以 reStructuredText 格式编写。 如果使用注释来编写类属性的文档，请在#符号后添加一个冒号“:”。 (有能力尽可能用英文, 否则请中文优雅注释) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 7e391b11f..c99675d5a 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,7 +1,7 @@ 快速安装 ========================== -Jumpserver 封装了一个All in one Docker，可以快速启动。该镜像集成了所有需要的组件，可以使用外置db和redis +Jumpserver 封装了一个 All in one Docker，可以快速启动。该镜像集成了所有需要的组件，可以使用外置 Database 和 Redis Tips: 不建议在生产中使用 @@ -11,7 +11,7 @@ Docker 安装见: `Docker官方安装文档 `_ 快速启动 ``````````````` -使用root命令行输入:: +使用 root 命令行输入:: $ docker run -d -p 8080:80 -p 2222:2222 registry.jumpserver.org/public/jumpserver:latest @@ -20,7 +20,7 @@ Docker 安装见: `Docker官方安装文档 `_ 浏览器访问: http://localhost:8080 -ssh访问: ssh -p 2222 localhost +SSH访问: ssh -p 2222 localhost 额外环境变量 diff --git a/docs/step_by_step.rst b/docs/step_by_step.rst index 403395fea..3112de67a 100644 --- a/docs/step_by_step.rst +++ b/docs/step_by_step.rst @@ -2,11 +2,11 @@ -------------------------- 环境 -~~~~ +~~~~~~~ - 系统: CentOS 7 - IP: 192.168.244.144 -- 关闭 selinux和防火墙 +- 关闭 selinux 和防火墙 :: @@ -19,8 +19,8 @@ $ setenforce 0 $ service iptables stop -一. 准备Python3和Python虚拟环境 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +一. 准备 Python3 和 Python 虚拟环境 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **1.1 安装依赖包** @@ -36,10 +36,9 @@ $ tar xvf Python-3.6.1.tar.xz && cd Python-3.6.1 $ ./configure && make && make install -**1.3 建立python虚拟环境** +**1.3 建立 Python 虚拟环境** -因为CentOS -6/7自带的是Python2，而Yum等工具依赖原来的Python，为了不扰乱原来的环境我们来使用Python虚拟环境 +因为 CentOS 6/7 自带的是 Python2，而 Yum 等工具依赖原来的 Python，为了不扰乱原来的环境我们来使用 Python 虚拟环境 :: @@ -47,45 +46,44 @@ $ python3 -m venv py3 $ source /opt/py3/bin/activate - # 看到下面的提示符代表成功，以后运行jumpserver都要先运行以上source命令，以下所有命令均在该虚拟环境中运行 - (py3) [root@localhost py3]# + # 看到下面的提示符代表成功，以后运行 Jumpserver 都要先运行以上 source 命令，以下所有命令均在该虚拟环境中运行 + (py3) [root@localhost py3] -二. 安装Jumpserver 0.5.0 -~~~~~~~~~~~~~~~~~~~~~~~~ +二. 安装 Jumpserver 0.5.0 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**2.1 下载或clone项目** +**2.1 下载或 Clone 项目** -项目提交较多git clone时较大，你可以选择去github项目页面直接下载 -zip包，我的网速好，我直接clone了 +项目提交较多 git clone 时较大，你可以选择去 Github 项目页面直接下载zip包。 :: $ cd /opt/ $ git clone --depth=1 https://github.com/jumpserver/jumpserver.git && cd jumpserver && git checkout master -**2.2 安装依赖rpm包** +**2.2 安装依赖 RPM 包** :: $ cd /opt/jumpserver/requirements $ yum -y install $(cat rpm_requirements.txt) # 如果没有任何报错请继续 -**2.3 安装python库依赖** +**2.3 安装 Python 库依赖** :: $ pip install -r requirements.txt # 不要指定-i参数，因为镜像上可能没有最新的包，如果没有任何报错请继续 -**2.4 安装Redis, jumpserver使用redis做cache和celery broker** +**2.4 安装 Redis, Jumpserver 使用 Redis 做 cache 和 celery broke** :: $ yum -y install redis $ service redis start -**2.5 安装MySQL** +**2.5 安装 MySQL** -本教程使用mysql作为数据库，如果不使用mysql可以跳过相关mysql安装和配置 +本教程使用 Mysql 作为数据库，如果不使用 Mysql 可以跳过相关 Mysql 安装和配置 :: @@ -97,7 +95,7 @@ zip包，我的网速好，我直接clone了 $ yum -y install mysql mysql-devel mysql-server $ service mysqld start -**2.6 创建数据库 jumpserver并授权** +**2.6 创建数据库 Jumpserver 并授权** :: @@ -105,7 +103,7 @@ zip包，我的网速好，我直接clone了 > create database jumpserver default charset 'utf8'; > grant all on jumpserver.* to 'jumpserver'@'127.0.0.1' identified by 'somepassword'; -**2.7 修改jumpserver配置文件** +**2.7 修改 Jumpserver 配置文件** :: @@ -113,9 +111,7 @@ zip包，我的网速好，我直接clone了 $ cp config_example.py config.py $ vi config.py # 我们计划修改 DevelopmentConfig中的配置，因为默认jumpserver是使用该配置，它继承自Config -**注意: 配置文件是python格式，不要用tab，而要用空格** **注意: -配置文件是python格式，不要用tab，而要用空格** **注意: -配置文件是python格式，不要用tab，而要用空格** +**注意: 配置文件是 Python 格式，不要用 TAB，而要用空格** :: @@ -139,7 +135,7 @@ zip包，我的网速好，我直接clone了 $ cd /opt/jumpserver/utils $ bash make_migrations.sh -**2.9 运行Jumpserver** +**2.9 运行 Jumpserver** :: @@ -147,14 +143,14 @@ zip包，我的网速好，我直接clone了 $ python run_server.py all 运行不报错，请浏览器访问 http://192.168.244.144:8080/ -(这里只是jumpserver, 没有web terminal,所以访问web terminal会报错) +(这里只是 Jumpserver, 没有 Web Terminal，所以访问 Web Terminal 会报错) -账号:admin 密码: admin +账号: admin 密码: admin -三. 安装 SSH Server和Web Socket Server: Coco -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +三. 安装 SSH Server 和 WebSocket Server: Coco +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**3.1 下载clone项目** +**3.1 下载或 Clone 项目** 新开一个终端，连接测试机，别忘了 source /opt/py3/bin/activate @@ -167,7 +163,9 @@ zip包，我的网速好，我直接clone了 :: - $ cd /opt/coco/requirements $ yum -y install $(cat rpm_requirements.txt) $ pip install requirements.txt + $ cd /opt/coco/requirements + $ yum -y install $(cat rpm_requirements.txt) + $ pip install requirements.txt **3.2 安装依赖** @@ -186,8 +184,7 @@ zip包，我的网速好，我直接clone了 $ cp conf_example.py conf.py $ python run_server.py -这时需要去 -jumpserver管理后台-会话管理-终端管理(http://192.168.244.144:8080/terminal/terminal/)接受coco的注册 +这时需要去 Jumpserver 管理后台-会话管理-终端管理（http://192.168.244.144:8080/terminal/terminal/）接受 Coco 的注册 :: @@ -202,21 +199,19 @@ jumpserver管理后台-会话管理-终端管理(http://192.168.244.144:8080/ter $ ssh -p2222 admin@192.168.244.144 密码: admin - 如果是用在windows下，Xshell terminal登录语法如下 + 如果是用在 Windows 下，Xshell Terminal 登录语法如下 $ssh admin@192.168.244.144 2222 密码: admin 如果能登陆代表部署成功 四. 安装 Web Terminal 前端: Luna -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Luna已改为纯前端，需要nginx来运行访问 +Luna 已改为纯前端，需要 Nginx 来运行访问 -下载 release包，直接解压，不需要编译 +访问（https://github.com/jumpserver/luna/releases）下载对应 release 包，直接解压，不需要编译 -访问 https://github.com/jumpserver/luna/releases，下载对应release包 - -4.1 解压luna +4.1 解压 Luna :: @@ -227,10 +222,10 @@ Luna已改为纯前端，需要nginx来运行访问 $ ls /opt/luna ... -五. 安装Windows支持组件 -~~~~~~~~~~~~~~~~~~~~~~~ +五. 安装 Windows 支持组件 +~~~~~~~~~~~~~~~~~~~~~~~~~~ -因为手动安装 guacamole 组件比较复杂，这里提供打包好的docker使用, 启动 guacamole +因为手动安装 guacamole 组件比较复杂，这里提供打包好的 docker 使用, 启动 guacamole .. code:: shell @@ -239,16 +234,16 @@ Luna已改为纯前端，需要nginx来运行访问 docker run -d \ -p 8081:8080 \ -e JUMPSERVER_SERVER=http://<填写本机的IP地址>:8080 \ - jumpserver/guacamole + registry.jumpserver.org/public/guacamole:latest -这里所需要注意的是guacamole暴露出来的端口是8081，若与主机上其他端口冲突请自定义一下。 +这里所需要注意的是 guacamole 暴露出来的端口是 8081，若与主机上其他端口冲突请自定义一下。 -修改JUMPSERVER_SERVER的配置，填上jumpserver的内网地址 +修改 JUMPSERVER SERVER 的配置，填上 Jumpserver 的内网地址 -六. 配置 nginx 整合各组件 +六. 配置 Nginx 整合各组件 ~~~~~~~~~~~~~~~~~~~~~~~~~ -6.1 安装nginx 根据喜好选择安装方式和版本 +6.1 安装 Nginx 根据喜好选择安装方式和版本 6.2 配置文件 @@ -298,6 +293,6 @@ Luna已改为纯前端，需要nginx来运行访问 } } -6.3 运行 nginx +6.3 运行 Nginx 6.4 访问 http://192.168.244.144 \ No newline at end of file diff --git a/docs/upgrade.rst b/docs/upgrade.rst index 422aba51b..0a20f3c83 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -1,18 +1,18 @@ 升级 ---- -1. 升级 jumpserver +1. 升级 Jumpserver :: $ git pull && pip install -r requirements/requirements.txt && cd utils && sh make_migrations.sh -2. 升级 coco +2. 升级 Coco :: $ git pull && cd requirements && pip install -r requirements.txt # 不要指定 -i参数 -3. 升级 luna +3. 升级 Luna -重新下载release包 \ No newline at end of file +重新下载 release 包（https://github.com/jumpserver/luna/releases） \ No newline at end of file