zhc105 · xnervwang · Aug 16, 2025 · Aug 16, 2025 · Aug 16, 2025 · Aug 16, 2025
diff --git a/Dockerfile b/Dockerfile
@@ -1,6 +1,6 @@
 # Stage 1
-FROM alpine:3.15 as builder
-RUN apk add --no-cache git build-base libev-dev cmake && \
+FROM alpine:3.15 AS builder
+RUN apk add --no-cache git build-base libev-dev cmake argp-standalone && \
     mkdir -p /source/build
 ARG SOURCE=https://github.com/zhc105/Liteflow.git
 ARG BRANCH=master
@@ -54,12 +54,12 @@ ENV tag="main" \
     forward_rules=""
 
 RUN mkdir -p /app/bin && \
-    mkdir -p /app/config
+    mkdir -p /app/etc
 
 WORKDIR /app
 
 COPY --from=builder /source/Liteflow/build/src/liteflow /app/bin
-COPY docker/liteflow.conf.template /app/config
+COPY docker/liteflow.conf.template /app/etc
 COPY docker/docker-start.sh /app
 
 RUN chmod +x /app/docker-start.sh

diff --git a/README.cn.md b/README.cn.md
@@ -77,7 +77,7 @@ cd <install_folder>
 ./scripts/liteflow.sh status --local
 ```
 
-####示例1： 服务端1.2.3.4开放TCP 1501端口，映射到客户端192.168.1.100:1501
+#### 示例1： 服务端1.2.3.4开放TCP 1501端口，映射到客户端192.168.1.100:1501
 
 部署方式：
 ```
@@ -130,7 +130,7 @@ cd <install_folder>
 }
 ```
 
-####示例2： 客户端192.168.1.100开放TCP 1501端口，通过反向连接映射到服务端1.2.3.4:1501
+#### 示例2： 客户端192.168.1.100开放TCP 1501端口，通过反向连接映射到服务端1.2.3.4:1501
 
 部署方式：
 ```
@@ -182,6 +182,11 @@ cd <install_folder>
 }
 ```
 
+#### `entrance_rule`的`node_id`
+⚠️ 请注意，如果`entrance_rule`不指定`node_id`，则本节点会从所有连接的peers中任意选择一个发送，即使该peer并不支持该`tunnel_id`。两个peer在连接时并不会交换`tunnel_id`列表，双方并不知晓对方所支持的`tunnel_id`信息。
+
+**因此，Liteflow 被设计为每个进程仅支持一个用途单一的隧道。若需使用多个隧道，建议为每个隧道分别启动独立的 Liteflow 进程，并配以各自的配置文件。**
+
 ### Cygwin编译Windows版本
 Liteflow支持通过Cygwin编译提供Windows可用版本。
 
@@ -194,5 +199,24 @@ Cygwin必须至少安装以下Packages：
 * cmake
 * autoconf
 * libtool
-
-其它编译步骤与正常流程相同。编译完成后，将`cygwin1.dll`和产生的`liteflow.exe`复制到需要运行Liteflow的Windows机器上，准备好相应的配置文件并直接运行`liteflow.exe`。
+* libargp-devel
+
+其它编译步骤与正常流程相同。编译完成后，将以下文件复制到需要运行Liteflow的Windows机器上，准备好相应的配置文件并直接运行`liteflow.exe`。
+* cygwin1.dll
+* cygargp-0.dll
+* liteflow.exe
+
+⚠️ 注意Cygwin上的默认DNS服务器配置似乎有问题，请在配置文件的`service`一节中设置可用的DNS服务器，例如`"dns_server": "8.8.8.8",`。
+
+#### 如何开机后台运行liteflow
+由于liteflow为命令行程序，建议使用cmder，在Windows登录后自动启动liteflow，并自动最小化到系统托盘。
+1. 下载cmder，在`Settings...` -> `General` -> `Task bar`里选中`Auto minimize to TSA`。
+2. 创建cmder.exe的快捷方式，右键点击该快捷方式，在"目标"里添加后缀参数
+    ```bash
+    /TASK "liteflow" /x -MinTSA
+    ```
+    最终的结果看起来像例如
+    ```bash
+    C:\tools\cmder\Cmder.exe /TASK "liteflow" /x -MinTSA`
+    ```
+3. 在文件浏览器中粘贴`shell:startup`并回车，打开自动启动目录。将该快捷方式移入该目录。
diff --git a/README.md b/README.md
@@ -5,12 +5,12 @@ UDP tunnel & TCP/UDP Port forwarding
 
 ### Introduction
 
-Liteflow implements a simple and reliable UDP transport protocol (LiteDT), and based on this protocol, develops a TCP/UDP port forwarding tool. Both the client and the server use the same binary, with the only difference being the configuration file.
+Liteflow implements a simple and reliable UDP transport protocol (LiteDT) and has developed a TCP/UDP port forwarding tool based on this protocol. Both the client and the server use the same binary, with the only difference being the configuration file.
 
 You can use this tool to:
 
 1. Accelerate TCP transmission speed in high-latency and high-packet-loss environments, or ensure UDP packets are delivered reliably and in order.
-2. Map internal network ports to public servers through reverse connections, enabling internal ports to be actively accessed across NAT.
+2. Map internal network ports to public servers through reverse connections, enabling direct access to internal ports across NAT.
 
 ### Build and Usage Guide
 ```
@@ -38,12 +38,12 @@ cd <install_folder>
 ./bin/liteflow --version
 
 # Deploy configuration file
-# Example configs are in the etc folder, copy to etc/liteflow.conf and modify accordingly
+# Example configs are in the etc folder, copy them to etc/liteflow.conf and modify accordingly
 
 # Test whether the configuration file is valid
 ./bin/liteflow -t -c ./liteflow.conf
 
-# Run; it reads the config file named {binary_name}.conf in the current directory by default. For example, if the binary is liteflow, config file should be liteflow.conf
+# Run; it reads the config file named {binary_name}.conf in the current directory by default. For example, if the binary is liteflow, the config file should be liteflow.conf
 ./bin/liteflow
 
 # Or specify config file path
@@ -60,7 +60,7 @@ A set of control scripts is provided to make integration with crontab or systemd
 cd <install_folder>
 ./scripts/liteflow.sh start --local
 
-# Check if process is alive, restart if not
+# Check if the process is alive; restart if not
 ./scripts/liteflow.sh revive --local
 
 # Force reload configuration
@@ -181,6 +181,11 @@ Client (192.168.1.100) config example:
 }
 ```
 
+#### `node_id` in `entrance_rule`
+⚠️ Note: If `entrance_rule` does not specify a node_id, the current node will arbitrarily select one of the connected peers to send the data to — even if that peer does not support the specified `tunnel_id`. This happens because peers do not exchange their supported `tunnel_id` lists during the connection process, so neither side is aware of the other's `tunnel_id` capabilities.
+
+**Liteflow is designed so that each process supports only a single-purpose tunnel. If multiple tunnels are needed, it is recommended to run separate Liteflow processes, each with its own configuration file.**
+
 ### Building Windows Version via Cygwin
 Liteflow supports building a Windows version using Cygwin.
 
@@ -193,5 +198,24 @@ Cygwin must have the following packages installed:
 * cmake
 * autoconf
 * libtool
-
-Other build steps are the same. After building, copy `cygwin1.dll` and the generated `liteflow.exe` to the target Windows machine. Prepare the appropriate configuration file and directly run `liteflow.exe`.
+* libargp-devel
+
+The remaining compilation steps follow the standard procedure. After compilation, copy the following files to the Windows machine where you want to run Liteflow. Prepare the corresponding configuration files, then run liteflow.exe directly.
+* cygwin1.dll
+* cygargp-0.dll
+* liteflow.exe
+
+⚠️ Note: The default DNS server configuration on Cygwin appears to be problematic. Please specify a working DNS server in the `service` section of the configuration file, for example: `"dns_server": "8.8.8.8",`.
+
+#### How to Run liteflow in the Background at Startup
+Since liteflow is a command-line program, it’s recommended to use cmder to automatically launch it when Windows starts and minimize it to the system tray.
+1. Download cmder. In `Settings...` → `General` → `Task bar`, check the option `Auto minimize to TSA`.
+2. Create a shortcut to Cmder.exe. Right-click the shortcut, and in the `Target` field, add the following suffix:
+    ```bash
+    /TASK "liteflow" /x -MinTSA
+    ```
+    The final result should look something like:
+    ```bash
+    "C:\tools\cmder\Cmder.exe" /TASK "liteflow" /x -MinTSA
+    ```
+3. In File Explorer, type `shell:startup` and press Enter to open the Startup folder. Move the shortcut into this folder to enable auto-start.
diff --git a/docker/README.cn.md b/docker/README.cn.md
@@ -0,0 +1,111 @@
+### 编译Docker镜像
+
+#### 方式1: 从远程Git仓库构建（使用默认仓库和分支）
+适用场景：直接使用作者仓库的稳定版本
+```
+docker build --build-arg BRANCH=master -t liteflow:master .
+```
+- 代码来源：从 `https://github.com/zhc105/Liteflow.git` 自动下载
+- 使用分支：master（可通过BRANCH参数指定其他分支）
+
+#### 方式2: 从指定的远程Git仓库和分支构建
+适用场景：使用其他fork仓库或特定分支的代码
+```
+docker build --build-arg SOURCE=https://github.com/zhc105/Liteflow.git --build-arg BRANCH=master -t liteflow:master .
+```
+- 代码来源：从指定的Git仓库URL下载
+- 使用分支：通过BRANCH参数指定
+
+#### 方式3: 使用本地当前目录代码构建（不从Git下载）
+适用场景：开发测试阶段，使用本地修改过的代码（包括未提交的更改）
+```
+# option 1
+docker build --build-arg SOURCE=local -t liteflow:local .
+# option 2
+docker build --build-arg SOURCE=. -t liteflow:local .
+# option 3
+docker build --build-arg SOURCE=./ -t liteflow:local .
+```
+- 代码来源：直接使用当前目录的代码文件
+- 无需网络连接，可以包含本地未提交的修改
+
+### 启动容器
+
+#### 方式1: 使用环境变量动态生成配置
+
+脚本示例：
+```bash
+#!/bin/bash
+
+entrance_rules=$(cat <<- EOM
+EOM
+)
+
+forward_rules=$(cat <<- EOM
+    {
+        "tunnel_id": 100,                   // Tunnel ID和服务端entrance_rules对应
+        "destination_addr": "127.0.0.1",    // 为此Tunnel指定转发目标地址
+        "destination_port": 1501            // 指定转发目标端口
+    },
+EOM
+)
+
+connect_peers=$(cat <<- EOM
+    "1.2.3.4:1901",
+EOM
+)
+
+docker run --network host --name liteflow-main -d --restart=always \
+    --env tag="main" \
+    --env max_incoming_peers="0" \
+    --env connect_peers="$connect_peers" \
+    --env node_id="1001" \
+    --env password="your-password" \
+    --env entrance_rules="$entrance_rules" \
+    --env forward_rules="$forward_rules" \
+    liteflow:master
+```
+
+#### 方式2: 使用预置配置文件
+
+**步骤1**: 准备配置文件
+```bash
+# 创建配置文件，可以参考 examples/ 目录下的示例
+cat > /host/path/to/liteflow.conf << 'EOF'
+{
+    "service": {
+        "max_incoming_peers": 0,
+        "connect_peers": [
+            "1.2.3.4:1901"
+        ],
+        "node_id": 1001,
+        "listen_addr": "0.0.0.0",
+        "listen_port": 0
+    },
+    "transport": {
+        "password": "your-password"
+    },
+    "entrance_rules": [
+    ],
+    "forward_rules": [
+        {
+            "tunnel_id": 100,
+            "destination_addr": "127.0.0.1",
+            "destination_port": 1501
+        }
+    ]
+}
+EOF
+```
+
+**步骤2**: 启动容器并挂载配置文件
+```bash
+docker run --network host --name liteflow-main -d --restart=always \
+    -v /host/path/to/liteflow.conf:/app/config/liteflow.conf \
+    --env confpath="/app/config/liteflow.conf" \
+    liteflow:master
+```
+
+**注意事项**：
+- 容器会检查配置文件是否存在，不存在则启动失败
+- 使用预置配置文件时，所有环境变量配置参数都会被忽略
diff --git a/docker/README.md b/docker/README.md
@@ -1,17 +1,23 @@
-### 编译Docker镜像
+### Building Docker Images
 
-命令示例：
-默认从作者仓库master分支构建
+#### Method 1: Build from Remote Git Repository (Using Default Repository and Branch)
+Use case: Use the stable version directly from the author's repository
 ```
 docker build --build-arg BRANCH=master -t liteflow:master .
 ```
+- Code source: Automatically downloaded from `https://github.com/zhc105/Liteflow.git`
+- Branch used: master (can specify other branches via BRANCH parameter)
 
-指定构建仓库和分支
+#### Method 2: Build from Specified Remote Git Repository and Branch
+Use case: Use code from other forked repositories or specific branches
 ```
-docker build --build-arg SOURCE=https://github.com/zhc105/Liteflow.git BRANCH=master -t liteflow:master .
+docker build --build-arg SOURCE=https://github.com/zhc105/Liteflow.git --build-arg BRANCH=master -t liteflow:master .
 ```
+- Code source: Downloaded from the specified Git repository URL
+- Branch used: Specified via BRANCH parameter
 
-复制本地代码并构建
+#### Method 3: Build Using Local Current Directory Code (No Git Download)
+Use case: Development and testing phase, using locally modified code (including uncommitted changes)
 ```
 # option 1
 docker build --build-arg SOURCE=local -t liteflow:local .
@@ -20,11 +26,15 @@ docker build --build-arg SOURCE=. -t liteflow:local .
 # option 3
 docker build --build-arg SOURCE=./ -t liteflow:local .
 ```
+- Code source: Use code files directly from the current directory
+- No network connection required; can include uncommitted local modifications
 
-### 启动容器
+### Starting Containers
 
-脚本示例：
-```
+#### Method 1: Dynamic Configuration Generation Using Environment Variables
+
+Script example:
+```bash
 #!/bin/bash
 
 entrance_rules=$(cat <<- EOM
@@ -33,9 +43,9 @@ EOM
 
 forward_rules=$(cat <<- EOM
     {
-        "tunnel_id": 100,                   // Tunnel ID和服务端entrance_rules对应
-        "destination_addr": "127.0.0.1",    // 为此Tunnel指定转发目标地址
-        "destination_port": 1501            // 指定转发目标端口
+        "tunnel_id": 100,                   // Tunnel ID corresponds to server-side entrance_rules
+        "destination_addr": "127.0.0.1",    // Specify forwarding target address for this tunnel
+        "destination_port": 1501            // Specify forwarding target port
     },
 EOM
 )
@@ -54,4 +64,48 @@ docker run --network host --name liteflow-main -d --restart=always \
     --env entrance_rules="$entrance_rules" \
     --env forward_rules="$forward_rules" \
     liteflow:master
-```
+```
+
+#### Method 2: Using Pre-configured Configuration File
+
+**Step 1**: Prepare configuration file
+```bash
+# Create configuration file, you can refer to examples in the examples/ directory
+cat > /host/path/to/liteflow.conf << 'EOF'
+{
+    "service": {
+        "max_incoming_peers": 0,
+        "connect_peers": [
+            "1.2.3.4:1901"
+        ],
+        "node_id": 1001,
+        "listen_addr": "0.0.0.0",
+        "listen_port": 0
+    },
+    "transport": {
+        "password": "your-password"
+    },
+    "entrance_rules": [
+    ],
+    "forward_rules": [
+        {
+            "tunnel_id": 100,
+            "destination_addr": "127.0.0.1",
+            "destination_port": 1501
+        }
+    ]
+}
+EOF
+```
+
+**Step 2**: Start container and mount configuration file
+```bash
+docker run --network host --name liteflow-main -d --restart=always \
+    -v /host/path/to/liteflow.conf:/app/config/liteflow.conf \
+    --env confpath="/app/config/liteflow.conf" \
+    liteflow:master
+```
+
+**Important Notes**:
+- The container will check if the configuration file exists, and will fail to start if it doesn't exist
+- When using a pre-configured file, all environment variable configuration parameters will be ignored