Veteran

SKILL.md

# veteran — 节点代理客户端

基于 sing-box 的跨平台代理客户端，支持订阅管理、多节点切换、SOCKS5/HTTP 代理、分流规则。

## 安装

从 [Releases]() 下载对应平台二进制，或从源码编译：

```bash
git clone https://github.com/yongjie0203/veteran.git
cd veteran
make build
```

## 快速开始

```bash
# 1. 更新订阅
./veteran sub -u "https://your-subscription-url"

# 2. 查看节点
./veteran list

# 3. 启动代理（默认后台运行，端口1088）
./veteran run -n 1

# 4. 查看状态
./veteran status

# 5. 停止
./veteran stop
```

## 命令参考

### `veteran sub` — 更新订阅

```
veteran sub -u <订阅URL>
```

| 参数 | 说明 |
|------|------|
| `-u`, `--url` | 订阅链接 URL（必填） |

支持协议：`vless://` `vmess://` `ss://` `trojan://` `hysteria2://`

### `veteran list` — 列出节点

```
veteran list
```

显示所有已订阅节点的索引、协议类型、名称和服务器地址。

### `veteran run` — 启动代理

```
veteran run -n <节点> [-p <端口>] [-m <模式>] [-f] [--rule ...] [--rule-file ...]
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-n`, `--node` | 节点索引(从1开始)或名称（必填） | - |
| `-p`, `--port` | 本地监听端口 | `1088` |
| `-m`, `--mode` | 分流模式（见下表） | `2` |
| `-f`, `--foreground` | 前台运行（输出到终端） | 默认后台 |
| `--rule` | 自定义规则，可重复 | - |
| `--rule-file` | 从文件加载规则 | - |

#### 分流模式

| 值 | 说明 |
|----|------|
| `0` | 绕过中国大陆地址 |
| `1` | 绕过局域网地址 |
| `2` | 绕过中国大陆和局域网地址（默认） |
| `3` | 全局代理 |
| `4` | 自定义规则（需配合 `--rule` 或 `--rule-file`） |

### `veteran status` — 查看状态

```
veteran status
```

### `veteran stop` — 停止代理

```
veteran stop [-p <端口>]
```

| 参数 | 说明 |
|------|------|
| `-p`, `--port` | 要停止的端口（不指定则停止所有） |

---

## 分流规则

### 命令行方式：`--rule`

```bash
./veteran run -n 1 -m 4 \
  --rule "DOMAIN-SUFFIX,google.com,PROXY" \
  --rule "IP-CIDR,10.0.0.0/8,DIRECT" \
  --rule "FINAL,PROXY"
```

### 文件方式：`--rule-file`

```bash
./veteran run -n 1 -m 4 --rule-file ./rules.json
```

#### 规则文件格式 (JSON)

```json
{
  "china_domain": ["baidu", "zhihu", "weibo"],
  "china_cidr": ["114.114.114.0/24"],
  "private_cidr": [
    "10.0.0.0/8",
    "172.16.0.0/12",
    "192.168.0.0/16",
    "127.0.0.0/12"
  ],
  "custom_rule": [
    "DOMAIN-SUFFIX,google.com,PROXY",
    "DOMAIN-SUFFIX,github.com,PROXY",
    "DOMAIN,www.baidu.com,DIRECT",
    "DOMAIN-KEYWORD,facebook,PROXY",
    "IP-CIDR,192.168.1.0/24,DIRECT",
    "IP,8.8.8.8,PROXY",
    "FINAL,PROXY"
  ]
}
```

#### 字段说明

| 字段 | 类型 | 作用 | 生效模式 |
|------|------|------|---------|
| `china_domain` | `string[]` | 包含关键词的域名直连 | 0, 2, 4 |
| `china_cidr` | `string[]` (CIDR格式) | IP 段直连 | 0, 2, 4 |
| `private_cidr` | `string[]` (CIDR格式) | 局域网地址直连 | 1, 2, 4 |
| `custom_rule` | `string[]` | 自定义规则（仅 `-m 4` 生效） | 4 |

#### 规则格式：`TYPE,VALUE,POLICY`

| TYPE | 说明 | 示例 |
|------|------|------|
| `DOMAIN-SUFFIX` | 域名后缀匹配 | `DOMAIN-SUFFIX,google.com,PROXY` |
| `DOMAIN-KEYWORD` | 域名关键词匹配 | `DOMAIN-KEYWORD,facebook,PROXY` |
| `DOMAIN` | 完整域名精确匹配 | `DOMAIN,www.baidu.com,DIRECT` |
| `IP-CIDR` | IP 网段匹配 | `IP-CIDR,10.0.0.0/8,DIRECT` |
| `IP` | 精确 IP 匹配 | `IP,8.8.8.8,PROXY` |
| `FINAL` | 默认兜底策略 | `FINAL,PROXY` |

POLICY 取值：

| 值 | 说明 |
|----|------|
| `DIRECT` | 直连，不走代理 |
| `PROXY` | 走代理 |
| `REJECT` | 拒绝连接 |

规则按优先级匹配：`DOMAIN` > `DOMAIN-SUFFIX` > `DOMAIN-KEYWORD` > `IP-CIDR` > `IP` > `FINAL`

---

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `VETERAN_ALLOW_MULTIPLE` | 设为 `true` 允许多实例（不同端口） | 禁用 |
| `VETERAN_DATA_DIR` | 数据目录 | `~/.veteran` |

---

## 多实例

```bash
# 允许在不同端口启动多个代理
export VETERAN_ALLOW_MULTIPLE=true
./veteran run -n 1 -p 1088   # 节点1 → 端口1088
./veteran run -n 2 -p 1089   # 节点2 → 端口1089
```

---

## 数据目录

```
~/.veteran/
├── nodes.json              # 节点列表缓存
├── veteran.log             # 管理命令日志
├── veteran-1088.log        # 端口1088运行日志
├── veteran-1088.pid        # 端口1088进程ID
└── veteran-1089.log        # 端口1089运行日志
```

---

## 支持的协议

| 协议 | 代理链接格式 | TLS | 传输层 |
|------|-------------|-----|--------|
| VLESS | `vless://uuid@host:port?params#name` | ✅ Reality/TLS | tcp/ws/grpc/h2/quic |
| VMess | `vmess://base64(json)` | ✅ TLS | tcp/ws/grpc/h2 |
| Shadowsocks | `ss://base64@host:port#name` | ❌ | tcp |
| Trojan | `trojan://pass@host:port?params#name` | ✅ TLS | tcp/ws/grpc |
| Hysteria2 | `hysteria2://pass@host:port#name` | ✅ | quic |

---

## 构建

```bash
# 本地开发
make build

# 全平台交叉编译
make all

# 发布（含压缩包）
make release VERSION=v1.0.0
```

### 支持平台

| 系统 | 架构 |
|------|------|
| macOS (darwin) | amd64, arm64 |
| Linux | amd64, arm64, 386, armv6, armv7 |
| Windows | amd64, arm64, 386 |