Skip to content

Commit

Permalink
doc upgrade
Browse files Browse the repository at this point in the history
  • Loading branch information
@wkgcass
wkgcass committed Apr 14, 2020
1 parent a181c95 commit 845a02b
Show file tree
Hide file tree
Showing 11 changed files with 209 additions and 230 deletions.
42 changes: 30 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,10 @@ Clone it, compile it, then everything is ready for running.

1. TCP Loadbalancer with TLS termination
2. HTTP/1.x and HTTP/2 Loadbalancer with `Host` header consideration
3. Other tcp based protocol loadbalancer, such as dubbo
3. Other tcp based protocol loadbalancer, such as grpc, dubbo
4. Socks5 server
5. DNS server and customizable A|AAAA records
6. Automatic service discovery
6. Kubernetes integration
7. Many other standalone extended apps, such as `WebSocksProxyAgent` and `WebSocksProxyServer`

## Make
Expand All @@ -28,15 +28,15 @@ See the [release page](https://github.com/wkgcass/vproxy/releases).

#### For linux

Use the latest `vproxy-linux` in release page.
Use the latest `vproxy-linux` binary file in release page.

Or

Use the jlink built runtime [here](https://github.com/wkgcass/vproxy/releases/download/1.0.0-BETA-5/vproxy-runtime-linux.tar.gz).

#### For macos

Use the latest `vproxy-macos` in release page.
Use the latest `vproxy-macos` binary file in release page.

#### For windows

Expand Down Expand Up @@ -120,10 +120,31 @@ For info about `F-Stack`, check the doc [fstack-how-to.md](https://github.com/wk
* Modifiable when running: no need to reload for configuration update.
* Fast: performance is one of our main priorities.
* TCP Loadbalancer: we now support TCP and TCP based protocols, also allow your own protocols.
* Service mesh: provide simple service discovery mechanism and sidecar support
* Kubernetes: integrate vproxy resources into k8s.

## How to use

<details><summary>use vproxy with kubernetes</summary>

<br>

Add crd, launch vproxy and controller

```
kubectl apply -f https://github.com/vproxy-tools/vpctl/blob/master/misc/crd.yaml
kubectl apply -f https://github.com/vproxy-tools/vpctl/blob/master/misc/k8s-vproxy.yaml
```

Launch the example app

```
kubectl apply -f https://github.com/vproxy-tools/vpctl/blob/master/misc/cr-example.yaml
```

Detailed info can be found [here](https://github.com/vproxy-tools/vpctl/blob/master/README.md).

</details>

<details><summary>vpctl</summary>

<br>
Expand Down Expand Up @@ -158,11 +179,7 @@ Use `help` to view the parameters.

Use `help` to view the launching parameters.

You may launch the vproxy instance with a `http-controller` and a `resp-controller`. Then you can operate the vproxy instance using `curl` or `redis-cli`. You may also operate the vproxy instance directly using standard input (stdin).

```
java -jar vproxy.jar http-controller 127.0.0.1:18776 resp-controller 127.0.0.1:16379 paSsw0rd
```
When launching the vproxy instance, a `http-controller` on port 18776 and a `resp-controller` on port 16379 will be started. Then you can operate the vproxy instance using `curl` or `redis-cli`. You may also operate the vproxy instance directly using standard input (stdin).

See [command.md](https://github.com/wkgcass/vproxy/blob/master/doc/command.md) and [api doc](https://github.com/wkgcass/vproxy/blob/master/doc/api.yaml) for more info.
Questions about implementation detail are also welcome (in issues).
Expand All @@ -172,16 +189,17 @@ Questions about implementation detail are also welcome (in issues).
### Doc

* [how-to-use.md](https://github.com/wkgcass/vproxy/blob/master/doc/how-to-use.md): How to use config file and controllers.
* [api.yaml](https://github.com/wkgcass/vproxy/blob/dev/doc/api.yaml): api doc for http-controller in swagger format.
* [command.md](https://github.com/wkgcass/vproxy/blob/master/doc/command.md): Detailed command document.
* [lb-example.md](https://github.com/wkgcass/vproxy/blob/master/doc/lb-example.md): An example about running a loadbalancer.
* [service-mesh-example.md](https://github.com/wkgcass/vproxy/blob/master/doc/service-mesh-example.md): An example about vproxy service mesh.
* [docker-example.md](https://github.com/wkgcass/vproxy/blob/master/doc/docker-example.md): An example about building and running vproxy in docker.
* [architecture.md](https://github.com/wkgcass/vproxy/blob/master/doc/architecture.md): Something about the architecture.
* [discovery-protocol.md](https://github.com/wkgcass/vproxy/blob/master/doc/discovery-protocol.md): The protocol which is used by vproxy auto discovery impl.
* [extended-app.md](https://github.com/wkgcass/vproxy/blob/master/doc/extended-app.md): The usage of extended applications.
* [websocks.md](https://github.com/wkgcass/vproxy/blob/master/doc/websocks.md): The WebSocks Protocol.
* [vproxy-kcp-tunnel.md](https://github.com/wkgcass/vproxy/blob/master/doc/vproxy-kcp-tunnel.md): The KCP Tunnel Protocol.
* [using-application-layer-protocols.md](https://github.com/wkgcass/vproxy/blob/master/doc/using-application-layer-protocols.md): About how to use (customized) application layer protocols.
* [fstack-how-to.md](https://github.com/wkgcass/vproxy/blob/master/doc_zh/fstack-how-to.md): How to run vproxy upon `F-Stack`. Chinese version only for now.
* [vpws-direct-relay.md](https://github.com/wkgcass/vproxy/blob/master/doc_zh/vpws-direct-relay.md): How to use `direct-relay` in `vpws-agent`.

## Contribute

Expand Down
64 changes: 49 additions & 15 deletions README_ZH.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,29 +6,39 @@ VProxy是一个零依赖的基于NIO的TCP负载均衡器。本项目仅需要Ja

1) clone，2) 编译，3) 运行！

## 特性

1. TCP和TLS负载均衡
2. HTTP/1.x和HTTP/2负载均衡，支持根据Host分发请求
3. 支持其他协议的负载均衡，例如grpc, dubbo
4. Socks5服务
5. DNS服务，支持A|AAAA记录
6. 与Kubernetes整合
7. 封装好的针对特定场景的应用，例如`WebSocksProxyAgent`和`WebSocksProxyServer`

## 构建

### 打包

<details><summary>直接使用已构建的版本</summary>
<details><summary>使用已构建的版本</summary>

<br>

查看 [release page](https://github.com/wkgcass/vproxy/releases).

#### linux
#### For linux

使用release页面中最新的`vproxy-linux`。
使用release页面中最新的`vproxy-linux`二进制文件。

或者

使用`jlink`打包的运行时文件：点[这里](https://github.com/wkgcass/vproxy/releases/download/1.0.0-BETA-5/vproxy-runtime-linux.tar.gz)下载。

#### macos
#### For macos

使用release页面中最新的`vproxy-macos`。
使用release页面中最新的`vproxy-macos`二进制文件。

#### windows
#### For windows

Java运行时可以从[这里](https://adoptopenjdk.net/?variant=openjdk11&jvmVariant=hotspot)下载。

Expand All @@ -38,6 +48,12 @@ Java运行时可以从[这里](https://adoptopenjdk.net/?variant=openjdk11&jvmVa

>注意：该运行时仍然处于beta阶段
</details>

<details><summary>打jar包</summary>

<br>

```
./gradlew clean jar
java -jar build/libs/vproxy.jar -Deploy=HelloWorld
Expand Down Expand Up @@ -97,17 +113,38 @@ java -Dvfd=posix -Djava.library.path=./src/main/c -jar build/libs/vproxy.jar -De

</details>

## 模板
## 目标

* 零依赖: 除了java标准库外不加任何依赖，也不使用jni扩展。
* 简单：代码简单易懂.
* 运行时可修改：更新配置不需要重启。
* 高效：性能是首要目标之一。
* TCP负载均衡：支持TCP以及一些基于TCP的协议，也允许你使用自己的协议。
* 服务网格: 提供简单的服务发现和Sidecar支持
* Kubernetes：将vproxy资源整合到k8s中。

## 如何使用

<details><summary>在K8S中使用vproxy</summary>

<br>

添加crd并启动vproxy和controller

```
kubectl apply -f https://github.com/vproxy-tools/vpctl/blob/master/misc/crd.yaml
kubectl apply -f https://github.com/vproxy-tools/vpctl/blob/master/misc/k8s-vproxy.yaml
```

启动示例应用

```
kubectl apply -f https://github.com/vproxy-tools/vpctl/blob/master/misc/cr-example.yaml
```

详细信息可见[这里](https://github.com/vproxy-tools/vpctl/blob/master/README.md)

</details>

<details><summary>vpctl</summary>

<br>
Expand Down Expand Up @@ -142,11 +179,7 @@ java -Deploy=Simple -jar vproxy.jar \

使用`help`查看启动参数。

你可以在启动vproxy实例的同时，开启一个`http-controller`和一个`resp-controller`。后续则可以使用`curl`或者`redis-cli`来操作该vproxy实例。当然你也可以直接通过标准输入(stdin)来操作vproxy实例。

```
java -jar vproxy.jar http-controller 127.0.0.1:18776 resp-controller 127.0.0.1:16379 paSsw0rd
```
在启动vproxy实例时，会默认开启一个监听18776端口的`http-controller`和一个监听16379端口的`resp-controller`。后续则可以使用`curl`或者`redis-cli`来操作该vproxy实例。当然你也可以直接通过标准输入(stdin)来操作vproxy实例。

查看[command.md](https://github.com/wkgcass/vproxy/blob/master/doc/command.md)和[api文档](https://github.com/wkgcass/vproxy/blob/master/doc/api.yaml)以获取更多信息。
如果有任何关于实现细节的问题也欢迎在issue中提出。
Expand All @@ -156,16 +189,17 @@ java -jar vproxy.jar http-controller 127.0.0.1:18776 resp-controller 127.0.0.1:1
### 文档

* [how-to-use.md(中文)](https://github.com/wkgcass/vproxy/blob/master/doc_zh/how-to-use.md): 如何使用配置文件和controller。
* [api.yaml](https://github.com/wkgcass/vproxy/blob/dev/doc/api.yaml): http-controller的api文档（swagger格式）。
* [command.md](https://github.com/wkgcass/vproxy/blob/master/doc/command.md): 详细的命令文档。
* [lb-example.md(中文)](https://github.com/wkgcass/vproxy/blob/master/doc_zh/lb-example.md): 关于TCP负载均衡的一个使用例子。
* [service-mesh-example.md(中文)](https://github.com/wkgcass/vproxy/blob/master/doc_zh/service-mesh-example.md): 关于service mesh的一个例子。
* [docker-example.md(中文)](https://github.com/wkgcass/vproxy/blob/master/doc_zh/docker-example.md): 关于构建镜像以及在docker中运行vproxy的一个例子。
* [architecture.md](https://github.com/wkgcass/vproxy/blob/master/doc/architecture.md): 架构相关。
* [discovery-protocol.md](https://github.com/wkgcass/vproxy/blob/master/doc/discovery-protocol.md): vproxy自动节点发现通信协议。
* [extended-app.md(中文)](https://github.com/wkgcass/vproxy/blob/master/doc_zh/extended-app.md): 扩展应用的使用方式。
* [websocks.md](https://github.com/wkgcass/vproxy/blob/master/doc/websocks.md): The WebSocks Protocol.
* [vproxy-kcp-tunnel.md](https://github.com/wkgcass/vproxy/blob/master/doc/vproxy-kcp-tunnel.md): The KCP Tunnel Protocol.
* [using-application-layer-protocols.md(中文)](https://github.com/wkgcass/vproxy/blob/master/doc_zh/using-application-layer-protocols.md): 关于如何使用(自定义的)应用层协议。
* [fstack-how-to.md(中文)](https://github.com/wkgcass/vproxy/blob/master/doc_zh/fstack-how-to.md): 如何在`F-Stack`上运行vproxy。
* [vpws-direct-relay.md(中文)](https://github.com/wkgcass/vproxy/blob/master/doc_zh/vpws-direct-relay.md): 如何使用`vpws-agent`的`direct-relay`功能。

## 贡献

Expand Down
20 changes: 20 additions & 0 deletions doc/extended-app.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,3 +98,23 @@ See [The Websocks Protocol](https://github.com/wkgcass/vproxy/blob/master/doc/we
If not specified, the app will use `~/vpws-agent.conf` instead.

The config file structure can be found [here](https://github.com/wkgcass/vproxy/blob/master/doc/websocks-agent-example.conf).

### Deploy=KcpTun

Network acceleration using KCP. You need to start a remote server which is fast to request your desired target, and a client run locally to create a tunnel between client and server.

See [vproxy kcp tunnel](https://github.com/wkgcass/vproxy/blob/master/doc/vproxy-kcp-tunnel.md) for more info.

#### Start arguments

* `mode`: running mode. enum: client or server
* `bind`: the listening port. for client, bind TCP on 127.0.0.1:$bind, for server, bind UDP on 0.0.0.0:$bind
* `target`: the connecting target. for client, set to the server ip:port, for server, set to the target ip:port
* `fast`: the retransmission configuration. enum: 1 or 2 or 3 or 4

e.g.

```
mode client bind 50010 target 100.1.2.3:20010 fast 3
mode server bind 20010 target google.com fast 3
```
78 changes: 17 additions & 61 deletions doc/how-to-use.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ There are multiple ways of using vproxy:
4. [StdIOController](#stdio): type in commands into vproxy and get messages from std-out.
5. [RESPController](#resp): use `redis-cli` or `telnet` to operate the vproxy instance.
6. [HTTPController](#http): control the vproxy instance via http (maybe using `curl`).
7. [Service Mesh](#discovery): let the nodes in the cluster to automatically find each other and handle network traffic.
7. [Kubernetes](#k8s): use vproxy in a k8s cluster.

<div id="simple"></div>

Expand Down Expand Up @@ -39,16 +39,6 @@ You can use `gen` to generate config corresponding to your arguments, then see c

To get the `vpctl` code and binary, visit [here](https://github.com/vproxy-tools/vpctl). The configuration examples are listed there as well.

To use the `vpctl`, you need to launch the http-controller. The vpctl uses http apis to control the vproxy instance.

You may launch the http-controller on startup.

```
java -jar vproxy.jar http-controller 127.0.0.1:18776
```

or see other ways in the document for [HTTPController](#http).

Use one command to apply all your configuration:

```
Expand Down Expand Up @@ -84,9 +74,7 @@ There are 3 ways of using a config file:
The vproxy instance saves current config to `~/.vproxy.last` for every hour.
The config will also be saved when the process got `sigint`, `sighup` or manually shutdown via controller.

If you start vproxy instance without a `load` argument, the last saved config will be loaded.

Generally, you only need to configure once and don't have to worry about the config file any more.
The vproxy will automatically load the last saved file on startup.

#### 3.2. startup argument

Expand All @@ -98,8 +86,7 @@ e.g.
java vproxy.app.Main load ~/vproxy.conf
```

> Multiple config files can be specified, will be executed in parallel.
> Also, arguments in different categories can be combined, e.g. you can specify `load ...` and `resp-controller ... ...` at the same time.
> Multiple config files can be specified at the same time, they will be loaded one by one.
#### 3.3. system call command

Expand All @@ -116,6 +103,9 @@ Then type in:
> System call: load ~/vproxy.conf --- loads config from a file
```

> You may use `noLoadLast` to forbid loading config on startup.
> You may use `noSave` to disable the ability of saving files (regardless of auto or manual saving).
<div id="stdio"></div>

## 4. Use StdIOController
Expand All @@ -126,9 +116,11 @@ Start the vproxy instance:
java vproxy.app.Main
```

Then the StdIOController starts, you can type in commands via standard input.
Then the StdIOController starts by default, you can type in commands directly through console.

It's recommended to start vproxy instance in `tmux` or `screen` if you rely on the StdIOController.

It's recommended to start vproxy instance via tmux or screen if you rely on the StdIOController.
> You may use `noStdIOController` to disable StdIOController.
<div id="resp"></div>

Expand All @@ -147,7 +139,8 @@ redis-cli -p 16379 -a m1paSsw0rd
> NOTE: For safety concern, not all `System call:` commands are not allowed in RESPController.
> NOTE: You can use add start argument flag `allowSystemCallInNonStdIOController` to enable system call commands for RESPController
You can start RESPController on startup or using a command in StdIOController.
The `resp-controller` is automatically launched on startup and listens to `16379` with password `123456`.
You may configure the RESPController on startup or using a command in StdIOController.

#### 5.1 startup argument

Expand Down Expand Up @@ -196,6 +189,7 @@ To stop a RESPController, you can type in:

```
curl http://127.0.0.1:18776/api/v1/module/tcp-lb
curl http://127.0.0.1:18776/healthz
```

#### 6.1 startup argument
Expand Down Expand Up @@ -242,48 +236,10 @@ To stop a HTTPController, you can type in:

See the api [doc](https://github.com/wkgcass/vproxy/blob/master/doc/api.yaml) in swagger 2.0 format.

<div id="discovery"></div>

## 7 . Auto Node Discovery
<div id="k8s"></div>

Specify the discovery config file when starting:

```
java vproxy.app.Main [discoveryConfig $path_to_config]
```
## 7. Kubernetes

If discovery config not specified, the vproxy instance will load a default config.
The default config can work well if you have only one nic other than loopback (e.g. eth0), otherwise you may need to specify the configuration file.

There are two modules related to discovery.

* smart-group-delegate: watches the discovery network for node changes, and update the handled server-group resource.
* smart-node-delegate: register a node into the discovery network for others to know.

The user application may use an http client to manipulate the vproxy configuration.

For example: you can register/deregister a node using the http request to http-controller:

```
POST /api/v1/module/smart-node-delegate
{
"name": "my-test-service",
"service": "my-service,
"zone": "test",
"nic": "eth0",
"exposedPort": 8080
}
respond 204 for success
DELETE /api/v1/module/smart-node-delegate/my-test-service
respond 204 for success
```

Or you may check the service list registered on the vproxy instance:

```
GET /api/v1/module/smart-node-delegate
```
Use Service and vproxy CRD to implement Gateways, Sidecars, etc.

You may refer to example code in [service-mesh-example.md](https://github.com/wkgcass/vproxy/blob/master/doc/service-mesh-example.md).
A client helps you register nodes is also provided in the example.
Please visit [vpctl](https://github.com/vproxy-tools/vpctl) for more detail.
Loading

0 comments on commit 845a02b

Please sign in to comment.