# openconnect_tools

**Repository Path**: sunqinbo/openconnect_tools

## Basic Information

- **Project Name**: openconnect_tools
- **Description**: workflo.png
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-26
- **Last Updated**: 2025-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🌐 OpenConnect 分流工具包  
**安全、高效、模块化的公司内网访问方案（适用于 Deepin / Ubuntu）**

> **适用场景**：远程办公、混合云访问、安全分流  
> **核心目标**：**仅公司内网流量走 VPN，公网流量直连**

#### 📦 附录：一键部署脚本（推荐）
```bash
# 下载脚本并执行安装
cd /tmp/
wget https://gitee.com/sunqinbo/openconnect_tools/raw/master/script/install-vpn-tools.sh
sh install-vpn-tools.sh

```

## 设计说明
## 📁 一、目录结构

所有文件集中管理于 `/usr/local/vpn/`，结构如下：

```
openconnect_tools/
├── lib/
│   └── vpn-common.sh                   # 公共函数库（读取 CIDR、获取接口等）
├── bin/
│   ├── vpn-connect.sh                  # 安全启动 OpenConnect
│   ├── vpn-disconnect.sh               # 优雅断开连接
│   ├── control-script.sh               # OpenConnect 生命周期回调脚本
│   ├── configure-split-routing.sh      # 配置分流路由
│   └── cleanup-vpn-routes.sh           # 手动清理路由
├── etc/
│   ├── vpn-routes.conf                 # 公司内网 IP 段配置（核心！）
│   └── vpn_route_backup.txt            # 路由表备份文件
├── logs/
│   └── vpn-script.log                  # 脚本运行日志
├── key/                                # 证书密钥目录（预留）
├── install-vpn-tools.sh                # 一键部署脚本
└── README.md                           # 本文档
```

✅ **优势**：
- 配置集中、结构清晰，便于备份、迁移和版本控制  
- 与系统其他配置隔离，避免污染系统环境


## 🔐 二、安全设计原则

| 风险点 | 解决方案 |
|--------|----------|
| 密码明文写在脚本中 | 使用 `~/.vpn-creds` 凭证文件（权限 600） |
| 密码出现在 `ps` 进程列表 | 通过 `< ~/.vpn-creds` 输入，**不作为命令行参数传递** |
| 路由配置错误导致断网 | **自动删除默认路由**，仅添加指定 CIDR |
| 多人共用配置冲突 | **系统级配置**（`/usr/local/vpn/etc/`） + **用户级凭证**（`~/.vpn-creds`）分离 |
| 路由表恢复问题 | **自动备份路由表**，断开时自动恢复 |


## 🚀 三、快速开始

### 步骤 1：部署工具包

```bash
# 1. 创建目录结构
sudo mkdir -p /usr/local/vpn/{lib,bin,etc,logs,key}

# 2. 复制脚本（或使用一键部署脚本，见附录）
# 3. 设置执行权限
sudo chmod +x /usr/local/vpn/lib/vpn-common.sh
sudo chmod +x /usr/local/vpn/bin/*.sh
sudo chmod 644 /usr/local/vpn/etc/vpn-routes.conf
```

> 💡 推荐使用附录中的 `install-vpn-tools.sh` 一键部署。


### 步骤 2：创建用户凭证

凭证文件位于用户主目录，**权限必须为 600**：

```bash
cat > ~/.vpn-creds <<EOF
username=your_username
password=your_password
server=your_vpn_server_address
EOF

chmod 600 ~/.vpn-creds
```

> ⚠️ **切勿将此文件提交到 Git 或共享！**


### 步骤 3：（可选）添加 PATH

```bash
echo 'export PATH="/usr/local/vpn/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```


### 步骤 4：连接 VPN

```bash
vpn-connect.sh
```

### 步骤 5：断开 VPN

```bash
vpn-disconnect.sh
```
该命令会：
- 发送 `SIGTERM` 终止 OpenConnect
- 自动调用清理脚本恢复路由表

## ⚙️ 四、配置说明

### 1. 内网 IP 段配置：`/usr/local/vpn/etc/vpn-routes.conf`

- 每行一个 **CIDR 格式** 的网段（如 `10.10.250.0/24`）
- 支持行尾注释（`# 说明`）
- 空行或以 `#` 开头的行会被忽略
- **修改后立即生效**（下次连接自动加载）

✅ **示例**：
```conf
10.10.250.0/24      # 核心生产数据库
192.168.33.0/24     # 视频监控系统
172.16.0.0/12       # RFC1918 私有网段
```

💡 **验证路由是否生效**：
```bash
ip route get 10.10.250.10
```


## 🧪 五、验证与调试

### 1. 检查当前路由

```bash
# 查看默认路由（应为本地网关）
ip route show default

# 检查某内网 IP 是否走 VPN
ip route get 10.10.250.244

# 查看所有 tun/vpn 接口
ip link show | grep -E 'tun[0-9]|vpn[0-9]'
```

### 2. 手动清理路由（调试用）

```bash
sudo /usr/local/vpn/bin/cleanup-vpn-routes.sh
```

### 3. 查看日志

```bash
# 脚本运行日志
tail -f /usr/local/vpn/logs/vpn-script.log

# 系统网络日志（可选）
journalctl -u NetworkManager -f
```

## 🔄 六、工作原理
![VPN工作流程图](workflo.png)
```mermaid
graph LR
A[vpn-connect.sh] --> B[启动 openconnect]
B --> C{连接成功?}
C -->|是| D[调用 control-script.sh connect]
D --> E[删除默认路由]
D --> F[添加 vpn-routes.conf 中的 CIDR]
C -->|否| G[退出]

H[vpn-disconnect.sh] --> I[发送 SIGTERM]
I --> J[openconnect 调用 disconnect 回调]
J --> K[cleanup-vpn-routes.sh]
```

✅ **关键设计**：
- **不修改系统默认路由** → 公网流量不受影响  
- **仅内网 CIDR 走 `tun0`/`vpn0`** → 安全隔离  
- **自动备份 & 恢复路由表** → 网络连接更稳定


## ❓ 七、常见问题（FAQ）

### 🔐 凭证与权限相关

**Q1：为什么提示“Permission denied”读取 `~/.vpn-creds`？**  
确保文件权限为 `600`（仅所有者可读写）：
```bash
chmod 600 ~/.vpn-creds
```
若使用 `sudo` 执行脚本，注意 `sudo` 默认不会保留用户环境变量或家目录权限。建议脚本内部通过 `$HOME` 显式读取。


**Q2：能否将凭证文件放在其他位置？**  
可以。修改 `vpn-connect.sh` 中的 `CRED_FILE` 变量指向新路径，例如：
```bash
CRED_FILE="$HOME/.config/vpn/creds"
```
但务必确保该文件权限仍为 `600`。


### 🌐 网络与路由相关

**Q3：连接后无法访问内网？**  
请依次排查：
1. `vpn-routes.conf` 是否包含目标网段；
2. 运行 `ip route get <内网IP>`，确认下一跳为 `tun0` 或 `vpn0`；
3. 检查公司防火墙是否放行你的公网出口 IP；
4. 确认 OpenConnect 是否成功获取到内网 IP（可通过 `ip addr show tun0` 查看）。


**Q4：断开 VPN 后网络无法上网？**  
可能原因：
- 默认路由未正确恢复；
- 路由表备份文件 `vpn_route_backup.txt` 丢失或为空。

**解决方法**：
1. 手动恢复默认路由（假设原网关为 `192.168.1.1`）：
   ```bash
   sudo ip route add default via 192.168.1.1 dev eth0
   ```
2. 运行清理脚本强制恢复：
   ```bash
   sudo /usr/local/vpn/bin/cleanup-vpn-routes.sh
   ```


**Q5：为什么 `ip route show default` 显示的是 `tun0`？**  
正常情况下，**本工具会主动删除 OpenConnect 添加的默认路由**。  
若仍看到默认路由指向 `tun0`，说明：
- `control-script.sh` 未被正确调用；
- OpenConnect 版本行为异常；
- 脚本权限或路径配置错误。

请检查日志 `/usr/local/vpn/logs/vpn-script.log` 中是否包含 `Removing default route...` 记录。


### 🛠 脚本与部署相关

**Q6：如何确认脚本是否成功加载了 `vpn-routes.conf`？**  
查看日志：
```bash
grep "Adding route" /usr/local/vpn/logs/vpn-script.log
```
每条成功添加的 CIDR 都会有对应日志。


**Q7：能否在无图形界面的服务器上使用？**  
完全可以。本方案完全基于命令行和系统路由表，适用于：
- Ubuntu Server
- Deepin CLI 模式
- Docker 容器（需特权模式并挂载 `/proc`）

> ⚠️ 注意：容器中使用需额外处理网络命名空间和持久化路由。


**Q8：脚本运行时报“command not found”？**  
常见于未将 `/usr/local/vpn/bin` 加入 `PATH`。  
临时解决：
```bash
/usr/local/vpn/bin/vpn-connect.sh
```
长期解决：将路径加入 shell 配置文件（如 `~/.bashrc`）。


### 🔄 兼容性与扩展性

**Q9：支持 OpenConnect 的哪些认证方式？**  
当前脚本通过标准输入传递用户名/密码，适用于：
- 基础账号密码认证
- 双因素认证（如密码+Token，可拼接在 password 字段）

**不支持**：
- 交互式 OTP 输入（需手动干预）
- 客户端证书认证（需额外配置 `--cert` 和 `--key`）

> 如需证书认证，可在 `vpn-connect.sh` 中扩展参数，并将证书放入 `/usr/local/vpn/key/`。


**Q10：能否同时连接多个 VPN？**  
技术上可行，但需注意：
- 每个连接需使用不同 `tun` 接口；
- 路由不能冲突（CIDR 无重叠）；
- 需为每个连接维护独立的配置和凭证。

建议：通过复制脚本并重命名（如 `vpn-connect-dev.sh`）实现多环境隔离。


### 🧪 调试与日志

**Q11：如何开启详细调试日志？**  
在 `vpn-connect.sh` 或 `control-script.sh` 开头添加：
```bash
set -x  # 启用 shell 调试输出
exec >> /usr/local/vpn/logs/debug.log 2>&1
```
或临时运行时重定向：
```bash
sudo bash -x /usr/local/vpn/bin/vpn-connect.sh 2>&1 | tee debug.log
```


**Q12：OpenConnect 连接成功但脚本未触发回调？**  
确保启动命令中包含：
```bash
--script=/usr/local/vpn/bin/control-script.sh
```
且该脚本具有可执行权限：
```bash
sudo chmod +x /usr/local/vpn/bin/control-script.sh
```


### 🌍 网络环境特殊场景

**Q13：在公司 Wi-Fi 或代理环境下无法连接？**  
- 若公司网络限制出站流量，需确认是否允许连接 VPN 服务器的 TCP/UDP 端口（通常为 443）；
- 若使用 HTTP 代理，OpenConnect 支持 `--proxy` 参数，但需修改 `vpn-connect.sh` 显式传入。


**Q14：使用移动热点或切换网络后 VPN 断开？**  
这是正常现象。OpenConnect 不具备网络切换自动重连能力。  
如需高可用，建议结合 `systemd` 服务 + `Restart=on-failure` 实现自动重连（需额外开发）。


> 💡 **通用排查三步法**：
> 1. 查看脚本日志：`tail -f /usr/local/vpn/logs/vpn-script.log`  
> 2. 检查路由表：`ip route show`  
> 3. 检查接口状态：`ip addr show` 和 `ip link show`


## 🙌 致谢

- 基于 **OpenConnect + Linux 路由表** 实现
- 设计灵感来自企业级网络分流最佳实践
- 特别感谢你的安全意识和工程化思维！


📝 **文档版本**：v1.0 
📅 **最后更新**：2025年10月25日  
✍️ **作者**：sunqinbo


#### 软件架构
软件架构说明


#### 安装教程

1.  xxxx
2.  xxxx
3.  xxxx

#### 使用说明

1.  xxxx
2.  xxxx
3.  xxxx

#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request


#### 特技

1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)