feat: 快速上手、如何贡献更新

2023-03-29 13:22:02 +08:00
parent b8d1a36395
commit ca48d9ffda
18 changed files with 164 additions and 105 deletions
@@ -5,119 +5,86 @@ permalink: /pages/793dcb
 article: false
 ---

-## 1. 打包
- 可直接前往Gitee仓库发行版页面下载所需版本已打好的包。若需手动打包，则可参照下面的执行命令：
-```text
-# 服务端打包
-mvn clean install -U -pl neutrino-proxy-server -am -Dmaven.test.skip=true
-
-# 客户端打包
-clean install -U -pl neutrino-proxy-client -am -Dmaven.test.skip=true
-
-# 管理后台前端项目打包（本地环境，local改为dev则为dev环境，同时需要修改config目录下面的环境配置）
-npm run build:local
+接下来您讲学习到如何快速上手
+## 1、 部署服务端
+### 1.1、 Docker一键部署
+#### 使用默认sqlite数据库
+```shell
+docker run -it -p 9000-9200:9000-9200/tcp -p 8888:8888 \
+-d --restart=always --name neutrino-proxy \
+registry.cn-hangzhou.aliyuncs.com/asgc/neutrino-proxy:1.7.1
 ```

-## 2. 部署
-### 2.2  服务端部署
- 使用常规的jar包部署方式即可，如：java -jar xxxx
-### 2.4 管理后台部署
- - Nginx方式部署（推荐）:
-```conf
-server {
-        listen 9527;
-        server_name localhost;
-
- #开启gzip
- gzip  on;
- #低于1kb的资源不压缩
- gzip_min_length 1k;
- #压缩级别1-9，越大压缩率越高，同时消耗cpu资源也越多，建议设置在5左右。
- gzip_comp_level 5;
- #需要压缩哪些响应类型的资源，多个空格隔开。不建议压缩图片.
- gzip_types text/plain application/javascript application/x-javascript text/javascript text/xml text/css;
- #配置禁用gzip条件，支持正则。此处表示ie6及以下不启用gzip（因为ie低版本不支持）
- gzip_disable "MSIE [1-6]\.";
- #是否添加“Vary: Accept-Encoding”响应头
- gzip_vary on;
-
- location / {
-            root  /work/projects/neutrino-proxy-server/neutrino-proxy-admin/dist;
-            try_files $uri $uri/ /index.html;
-            add_header Last-Modified $date_gmt;
- }
-}
-````
- - 无nginx时
-   在没有Nginx时，为了快速体验代理效果，可直接使用服务端项目提供的静态资源服务。直接将neutrino-proxy-admin打包后的文件解压放在neutrino-proxy-server.jar同级别目录下即可。例如：服务端配置的web端口为8080，则访问http://服务端IP:8080, 则会直接解析渲染neutrino-proxy-server.jar同级别目录下neutrino-proxy-admin/dist/index.html。
-
-::: warning
-需要注意的是，使用服务端自带的静态资源服务时，由于框架目前未支持缓存、gzip压缩，所以访问速度没有使用nginx快，正式使用推荐用nginx。
-:::
-
-## 3.配置
-
-### 3.1  配置端口池
-端口池的作用是将代理服务需要对外暴露的端口进行集中管理，方便安全组设置时统一操作。
-
-本项目为了简化首次配置，默认初始化数据会将9101～9120的所有端口加入端口池。可以在服务端项目sql配置(port_pool.data.sql文件)中自行修改初始化数据，也可以运行后在端口池管理页面手动维护。
-
-首次使用如果为了快速体验，建议直接使用默认端口池，则无需任何配置。
-
-### 3.2  配置License
-License是客户端连接代理服务端时所需要的唯一合法凭证，一个License同时只能被一个客户端使用。
-
-本项目为了简化首次配置，默认为每个用户初始化了一些license。可以在服务端项目sql配置(license.data.sql文件)中自行修改初始化数据，也可以运行后在License管理页面手动维护。
-
-首次使用如果为了快速体验，建议直接使用默认License，则无需任何配置。
-
-### 3.3  配置端口映射
-端口映射是代理的基本单元，一个外网端口在同一时刻被唯一的映射到一个内网IP+端口。所有流出该外网端口的流量都转发自对应的内网端口，同理所有流入该外网端口的流量都会转发到对应的内网端口。
-
-本项目为了简化首次配置，默认为每个用户初始化了一些端口映射。可以在服务端项目sql配置(port_mapping.data.sql文件)中自行修改初始化数据，也可以运行后在端口映射管理页面手动维护。
-
-首次使用如果为了快速体验，建议直接使用默认端口映射，则无需任何配置。
-
-### 3.4  开启代理
-上述步骤完成后，就可以开始代理自己的局域网设备了。
-
-比如现在有一个license：a123456，该license配置了一个或多个端口映射，其中包含9010到localhost:8080的映射（localhost表示代理客户端所在主机的端口，可以换成客户端所在局域网的任何IP）。此时修改客户端配置的服务端ip、license等启动客户端，就可以开启代理了，端口映射管理对应的记录在线状态为"在线"则证明代理成功建立。
-
-该license配置也可以通过客户端启动参数、启动后引导式输入、外置配置提供，为了简化首次体验门槛，这里直接提供一个外置配置模版：
-```json
-{
- "jksPath":"classpath:/test.jks",
- "licenseKey":"b0a907332b474b25897c4dcb31fc7eb6",
- "serverIp":"localhost",
- "serverPort":9002,
- "sslEnable":true
-}
+#### 指定自己的mysql数据库
+- 在服务器上创建目录：/root/neutrino-proxy/config
+- 在该目录下创建`app.yml`文本文件，并配置如下内容：
+```yml
+neutrino:
+  data:
+    db:
+      type: mysql
+      # 自己的数据库实例，创建一个空的名为'neutrino-proxy'的数据库即可，首次启动服务端会自动初始化
+      url: jdbc:mysql://xxxx:3306/neutrino-proxy?useUnicode=true&characterEncoding=UTF-8&allowMultiQueries=true&useAffectedRows=true&useSSL=false
+      driver-class: com.mysql.jdbc.Driver
+      # 数据库帐号
+      username: xxx
+      # 数据库密码
+      password: wHCvf3@hmw^D*
+```
+- 然后执行如下命令：
+```shell
+docker run -it -p 9000-9200:9000-9200/tcp -p 8888:8888 \
+-v /root/neutrino-proxy/config:/root/neutrino-proxy/config \
+-d --restart=always --name neutrino \
+registry.cn-hangzhou.aliyuncs.com/asgc/neutrino-proxy:1.7.1
 ```
-修改上述json中的licenseKey，serverIp、serverPort、sslEnabled后，保存文件命名为<font color="#9b6e23">.neutrino-proxy-client.json</font>,放在客户端当前目录下（jar包启动时，放在jar包同级别目录下。idea启动时，放在项目根目录下），然后直接启动客户端。

-此时通过访问外网ip+端口，可以成功访问内网服务。通过此方式，可以代理任何基于TCP之上的协议，如：socket、websocket、http、ftp、ssh等。
+### 1.2、使用jar包自行部署
+- 首先确保服务器上已安装java8运行环境
+- 打开[发行版页面](https://gitee.com/dromara/neutrino-proxy/releases)，下载最新的release包：`neutrino-proxy-server.jar`、`neutrino-proxy-admin.zip`
+- 在服务器上新建部署目录：`/work/projects/neutrino-proxy-server`
+- 将` neutrino-proxy-server.jar`、`neutrino-proxy-admin.zip`上传至服务器部署目录。
+- 解压`neutrino-proxy-admin.zip`文件
+- 执行命令`java -jar neutrino-proxy-server.jar`启动服务端完成部署，默认使用sqlite数据库。
+- 若需要指定自己的mysql数据库，同样的需要在当前目录下新建`app.yml`文件，文件内容同上。执行命令`java -jar neutrino-proxy-server.jar config=app.yml`启动服务端完成部署
+- 可参照 https://gitee.com/dromara/neutrino-proxy/blob/master/bin/server_start.sh 使用shell脚本启动服务端。

-## 4.开发&调试
-篇幅所限，此处不便赘述管理后台相关的开发，有vue基础的童鞋基本都可以自行开发。服务端的初始化数据足够调试工作，开发过程无需单独在管理页面操作。
+## 2、管理后台配置
+- 服务端部署成功后，访问`http://{服务端IP}:8888`打开后台管理页面。
+- 使用默认的管理员帐号登录：admin/123456
+- 打开`代理配置>License管理`页面，可以看到系统已经自动为管理员初始化了一条License记录，复制该`LicenseKey`备用，后续客户端配置需要。
+- 打开`代理配置>端口映射`页面，可以看到系统已经自动为初始化了几条端口映射。可根据需要自行添加、修改。这里我们以`9101 -> 127.0.0.1:8080`映射为例

-与SpringBoot项目类似，客户端、服务端项目均由一个入口类完成整个项目的启动，分别为ProxyClient、ProxyServer。
+## 3、启动客户端
+- 首先确保本地已安装java8运行环境
+- 打开[发行版页面](https://gitee.com/dromara/neutrino-proxy/releases)，下载最新的release包：`neutrino-proxy-client.jar`
+- 在本地`neutrino-proxy-client.jar`同级别目录下新建`app.yml`文件，并配置如下内容：
+```yml
+neutrino:
+  proxy:
+    client:
+      # ssl证书密钥（使用jjar包内自带的证书，则此处无需修改）
+      key-store-password: 123456
+      # ssl证书管理密钥（使用jjar包内自带的证书，则此处无需修改。自定义证书，则此处配置对应的路径）
+      jks-path: classpath:/test.jks
+      # 代理服务端IP
+      server-ip: localhost
+      # 代理服务端IP, 若是非ssl端口，则ssl-enable需要配置为false
+      server-port: 9002
+      # 是否启用ssl
+      ssl-enable: true
+      # licenseKey，客户端凭证。此处需要配置刚刚从管理后台复制的LicenseKey
+      license-key: xxxx
+```
+- 执行命令`java -jar neutrino-proxy-client.jar`启动客户端
+- 查看服务端License管理，刷新页面，对应的License在线状态为`在线`，则表明客户端已正常连接。

-内置配置采用yml风格，主要涉及Http端口、静态资源路径、协议参数、代理服务端端口、jks证书、数据源、license等。整个项目基于neutrino-core，风格类似于SpringBoot。笔者不喜欢因过分炫技而引入过多花式操作，因为项目的定位是个人开发者，且满足使用的同时兼顾学习其原理的需求。基本使用方式与SpringBoot类似，尽可能降低首次学习成本。
+## 4、代理验证
+- 本地启动被代理服务，如：redis、本地web项目、本地mysql等等
+- 先确保本地能正常访问被代理服务，如果本地都不能访问，不用想代理更不可能！！！
+- 通过服务端IP+9101（上面License配置的端口映射重的服务端端口）访问本地被代理服务

-neutrino-core项目test目录下包含众多核心封装的测试代码，通过调试这些代码，能尽可能减少大家学习的障碍。
-
-
-## 5.运行截图
-### 用户管理
-<img :src="$withBase('/img/run-example/user-manager1.png')"></img>
-### 端口池管理
-<img :src="$withBase('/img/run-example/port-pool1.png')"></img>
-### License管理
-<img :src="$withBase('/img/run-example/license1.png')"></img>
-### 端口映射管理
-<img :src="$withBase('/img/run-example/port-mapping1.png')"></img>
-### 客户端启动示例
-<img :src="$withBase('/img/run-example/client-run1.png')"></img>
+访问成功，至此首次完整的内网穿透体验完成。开源不易，请速至[Gitee仓库](https://gitee.com/dromara/neutrino-proxy)一键三连🤝

 <!--
 ## 4.开发&调试
@@ -0,0 +1,47 @@
+---
+title: 管理后台使用指南
+date: 2020-05-11 13:54:40
+permalink: /pages/793dcc
+article: false
+---
+
+# 首页
+- License统计：统计License相关数量指标
+- 端口映射统计：统计端口映射相关数量指标
+- 今日流量：统计当天的服务端上行/下行流量数据
+- 流量汇总：统计所有(包含当天)的服务端上行/下行流量数据
+- 流量监控：按天统计最近15天(可能会动态调整)每天的上行流量、下行流量、汇总流量
+
+<img :src="$withBase('/img/run-example/home.png')"></img>
+
+# 代理配置
+- License管理：License是客户端连接服务端的唯一合法凭证。一个License同时只能被一个客户端使用，一个License可以维护多条端口映射
+- 端口映射：服务端IP+端口 -> 客户端IP+端口的四元组映射(因目前服务端单节点只有一个公网IP，所以不体现出来)，是内网穿透的基本单元。
+
+<img :src="$withBase('/img/run-example/license1.png')"></img>
+
+# 系统管理
+- 用户管理：支持多用户，一个用户可持有多个License。由于项目目前主推个人版，所以暂是没有权限这一套，管理员之外的所有用户都属于游客。对于绝大多数操作，游客仅有只读权限。
+- 端口池管理：用于统一管理服务器内网穿透端口，方便统一设置安全组。
+- 端口池分组：对端口池的一个分组。
+    - 全局分组：该分组下的端口全局通用。
+    - 用户分组：该分组下的端口由分组绑定的用户独占。
+    - License分组：该分组下的端口由分组绑定的License独占。
+- 调度管理：维护服务端定时任务。方便开发、调试。正常使用时无需关心。
+
+<img :src="$withBase('/img/run-example/user-manager1.png')"></img>
+
+# 报表管理
+- 用户流量报表：基于用户维度的流量统计
+- License流量报表：基于License的流量统计
+- 用户流量月度明细：基于用户的流量月度统计
+- License流量月度明细：基于License的流量月度统计
+
+<img :src="$withBase('/img/run-example/user-flow1.png')"></img>
+
+# 日志管理
+- 调度日志：服务端定时任务执行日志
+- 登录日志：管理后端登录、退出登录的日志
+- 客户端连接日志：客户端连接、断开的日志
+
+<img :src="$withBase('/img/run-example/login-log1.png')"></img>
@@ -0,0 +1,45 @@
+---
+title: 如何贡献
+date: 2023-03-29 12:55:44
+permalink: /pages/69a632/
+---
+# 🎋代码分支说明
+- dev：常规开发分支，日常的开发、Bug修复、提交PR都在此分支
+- feature/xxx：特征分支，一些试验性开发、提交PR都在此分支，xxx可自行取一个有意义的名称
+- release/xxx：发行版分支，作为阶段性成果、重大更新的版本固化分支。受保护，不允许任何提交。
+- master：主分支，定期同步最新代码，目前仅支持本人(傲世孤尘/雨韵诗泽)提交。
+
+
+# ✊贡献的方式
+包括，但不限于以下形式：
+- 提交[issues](https://gitee.com/dromara/neutrino-proxy/issues)
+- 参与[issues](https://gitee.com/dromara/neutrino-proxy/issues)解决的必要性、解决方案的讨论、给出建设性的意见
+- 领取[issues](https://gitee.com/dromara/neutrino-proxy/issues) 并完成开发、提交PR
+- 为[本项目](https://gitee.com/dromara/neutrino-proxy)完善代码注释
+- 为[本项目](https://gitee.com/dromara/neutrino-proxy)增加测试代码
+- 为[本项目](https://gitee.com/dromara/neutrino-proxy)优化现有代码
+- 为[本项目](https://gitee.com/dromara/neutrino-proxy)优化操作体验
+- 通过公众号、博客、贴吧、论坛等形式分享/宣传中微子代理
+- 丰富项目文档，包括使用过程中踩过的坑、需要优化的点、具体问题的解决方法等
+
+# 🧬贡献代码的步骤
+- 在Gitee或者Github上fork项目到自己的repo，fork，一定要把项目fork一份。 
+- 把fork过去的项目也就是你的项目clone到你的本地
+- 同步feature/1.7.1最新代码
+- 修改代码
+- 开发完成后，不忙着提PR，再拉一遍最新代码，如果有冲突、解决冲突
+- commit后push到自己的库
+- 登录Gitee在你首页可以看到一个 pull request 按钮，点击它，填写一些说明信息，然后提交即可。
+- 等待维护者合并
+
+# 📐PR的规范
+> 你可能发现有的代码并不符合这个规范，但我们后续都会朝着这个方向迈进。后续我们会逐步全面规范化，请先保证新提交的代码满足以下要求：
+
+- 注释完备，尤其每个新增的方法应按照Java文档规范标明方法说明、参数说明、返回值说明等信息，必要时请添加单元测试，如果愿意，也可以加上你的大名。
+- 原则上，不允许自行添加第三方依赖库。若确有必要，请先和项目负责人沟通达成一致。
+- 对现有代码的优化，请在注释中说明原因。
+- 如果涉及到数据库的变更，则至少需要做到以下绩点：
+    - sqlite、mysql下均测试通过
+    - 在`./neutrino-proxy-server/src/main/resource/sql`下维护更新对应的表结构sql文件
+    - 对于新增的表，维护必要的初始化数据
+    - 在对应的mysql、sqlite的update目录下，维护SQL变更记录，确保SQL执行测试通过