# V2Ray 部署与使用手册

> 更新：2026-10-21　|　架构：VMess + WebSocket + TLS，经 Apache 443 反代
> 详细原理、踩坑记录见 `v2ray-detail.md`

## 当前参数

| 项目 | 值 |
|---|---|
| 地址 / 端口 | `stargazer.org.cn` / `443` |
| UUID | `2c50f055-3c0d-4d6e-ae44-b637170211ec` |
| alterId / 加密 | `0` / `auto` |
| 传输 / 路径 | `ws` / `/ray` |
| TLS / SNI | 开启 / `stargazer.org.cn` |
| 伪装域名 (host) | `stargazer.org.cn`（必填） |
| 节点出口 | `43.156.23.211`（新加坡，纯 IPv4） |

导入链接见 `vmess.md`。UUID 属敏感信息，勿公开。

```
客户端 --443/TLS--> Apache --/ray--ws--> 127.0.0.1:10087 v2ray
                          \--其他------> /var/www/html 网站
```

---

# 一、服务端部署

### Step 1　生成配置

```bash
cd /var/www/html/share/v2ray
./gen-config.py stargazer.org.cn /ray
```

产出 4 个文件：`vmess.md`（链接+参数）、`<slug>-split.json`、`<slug>-global.json`（sing-box）、`server-inbound.json`（服务端片段）。

沿用已有 UUID 加 `--uuid <值>`，其余选项 `--help`。

### Step 2　写入服务端配置

```bash
sudo mkdir -p /etc/v2ray
sudo cp /var/www/html/data/back/v2ray-config.json-bak-* /tmp/ 2>/dev/null  # 已有则先备份
python3 -c "
import json
cfg = {'log':{'loglevel':'warning'},
       'inbounds':[json.load(open('server-inbound.json'))],
       'outbounds':[{'protocol':'freedom','settings':{'domainStrategy':'UseIPv4'},'tag':'direct'}],
       'routing':{'domainStrategy':'IPIfNonMatch','rules':[]}}
json.dump(cfg, open('/tmp/v2ray-config.json','w'), indent=2)
"
sudo cp /tmp/v2ray-config.json /etc/v2ray/config.json
```

### Step 3　启动容器

```bash
sudo docker run -d --name v2ray --restart unless-stopped \
  -v /etc/v2ray/config.json:/etc/v2ray/config.json \
  -p 127.0.0.1:10087:10087 \
  v2fly/v2fly-core:latest run -config /etc/v2ray/config.json
```

`-p 127.0.0.1:10087` 只绑本机，公网扫不到，流量必须经 Apache。

### Step 4　配置 Apache 反代

```bash
sudo a2enmod proxy proxy_http proxy_wstunnel
```

443 vhost 中加入：

```apache
RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule ^/ray$ ws://127.0.0.1:10087/ray [P,L]
ProxyPreserveHost On
```

```bash
sudo apache2ctl configtest        # 必须 Syntax OK
sudo systemctl restart apache2    # 新模块需 restart，reload 不够
```

### Step 5　验证

```bash
# WebSocket 升级，期望 101
curl -s -o /dev/null -D- --max-time 10 \
  -H "Connection: Upgrade" -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  -H "Sec-WebSocket-Version: 13" https://stargazer.org.cn/ray | head -1

# 伪装有效，期望 404（不暴露代理）
curl -s -o /dev/null -w "%{http_code}\n" https://stargazer.org.cn/ray

# 端口只绑本机
ss -ltnp | grep 10087
```

### Step 6　端到端实测

前面全过只说明链路搭对了，这步才证明代理能用。

```bash
mkdir -p /tmp/wstest && cat > /tmp/wstest/client.json <<'EOF'
{
  "log": { "loglevel": "warning" },
  "inbounds": [{ "port": 10809, "listen": "127.0.0.1", "protocol": "socks",
    "settings": { "auth": "noauth", "udp": true } }],
  "outbounds": [{
    "protocol": "vmess",
    "settings": { "vnext": [{ "address": "stargazer.org.cn", "port": 443,
      "users": [{ "id": "<UUID>", "alterId": 0, "security": "auto" }] }]},
    "streamSettings": { "network": "ws", "security": "tls",
      "tlsSettings": { "serverName": "stargazer.org.cn" },
      "wsSettings": { "path": "/ray" } }
  }]
}
EOF
docker run -d --name wstest --network host \
  -v /tmp/wstest/client.json:/etc/v2ray/config.json \
  v2fly/v2fly-core:latest run -config /etc/v2ray/config.json
sleep 4
curl -s --max-time 15 -x socks5h://127.0.0.1:10809 https://ifconfig.me   # 应返回 43.156.23.211
docker rm -f wstest && rm -rf /tmp/wstest
```

---

# 二、Windows 客户端

## v2rayN（推荐）

### Step 1　下载解压

国内直接下（COS 加速，161 MB，含内核）：

```
https://nanjing-1251602985.cos.ap-nanjing.myqcloud.com/v2rayN-windows-64.zip
```

官方源：https://github.com/2dust/v2rayN/releases/latest → 选 `v2rayN-windows-64.zip`

解压到 `D:\v2rayN`。**不要放 `C:\Program Files`**，权限问题会导致配置写入失败。

### Step 2　放行杀毒

首次运行 Windows Defender 可能报毒，代理软件通用误报。安全中心 → 病毒和威胁防护 → 管理设置 → 排除项 → 添加该文件夹。

### Step 3　导入节点

复制 `vmess.md` 里的 `vmess://` 链接 → v2rayN 中按 `Ctrl+V` → 节点出现后双击选中。

### Step 4　开启代理

托盘图标右键 → 系统代理 → **自动配置系统代理**

### Step 5　验证

浏览器访问 https://ifconfig.me，显示 `43.156.23.211` 即生效。

常用设置：开机自启在「参数设置」；国内直连在「路由设置」选预设「绕过大陆」；本地端口默认 SOCKS5 `10808`、HTTP `10809`。

## sing-box（与手机共用配置）

### Step 1　下载解压

国内直接下（COS 加速，31 MB）：

```
https://nanjing-1251602985.cos.ap-nanjing.myqcloud.com/sing-box-1.14.3-windows-amd64.zip
```

官方源：https://github.com/SagerNet/sing-box/releases/latest → 选 `sing-box-1.14.3-windows-amd64.zip`

解压到 `D:\sing-box`。Windows 7 需用官方源的 `-legacy-windows-7` 包。

### Step 2　拉取配置

```powershell
curl -o D:\sing-box\config.json https://stargazer.org.cn/share/v2ray/sb-ws-tls-v2.json
```

### Step 3　运行

**以管理员身份**打开 PowerShell（tun 需建虚拟网卡）：

```powershell
cd D:\sing-box
.\sing-box.exe run -c config.json
```

### Step 4　注册为服务（可选，后台常驻）

```powershell
New-Service -Name "sing-box" `
  -BinaryPathName "D:\sing-box\sing-box.exe run -c D:\sing-box\config.json" `
  -DisplayName "sing-box" -StartupType Automatic
Start-Service sing-box
```

删除：`Stop-Service sing-box; sc.exe delete sing-box`

---

# 三、Ubuntu 客户端

## sing-box（推荐）

### Step 1　安装二进制

```bash
cd /tmp
curl -fsSL -o sb.tar.gz \
  "https://nanjing-1251602985.cos.ap-nanjing.myqcloud.com/sing-box-1.14.3-linux-amd64.tar.gz"
tar xzf sb.tar.gz
sudo install -m 755 sing-box-1.14.3-linux-amd64/sing-box /usr/local/bin/
sing-box version
```

上面是 COS 加速地址（30 MB，amd64）。官方源：

```bash
curl -fsSL -o sb.tar.gz \
  "https://github.com/SagerNet/sing-box/releases/download/v1.14.3/sing-box-1.14.3-linux-amd64.tar.gz"
```

ARM 设备换 `arm64`；glibc 报错用 `-musl` 包（这两个需走官方源）。GitHub 慢则在链接前加 `https://ghproxy.net/`。

### Step 2　拉取配置

```bash
sudo mkdir -p /etc/sing-box
sudo curl -fsSL -o /etc/sing-box/config.json \
  https://stargazer.org.cn/share/v2ray/sb-ws-tls-v2.json
sing-box check -c /etc/sing-box/config.json
```

配置已是 `ipv4_only` + 无 IPv6 tun 地址，无需再改。服务器纯 IPv4 出口，用 `prefer_ipv4` 会导致 Chrome 反复试 IPv6 每条等 5 秒，表现为打不开网页。

### Step 3　前台测试

```bash
sudo sing-box run -c /etc/sing-box/config.json
```

看到 `sing-box started` 即正常，另开终端 `curl -s https://ifconfig.me` 应返回 `43.156.23.211`。`Ctrl+C` 停止。

### Step 4　配置 systemd

```bash
sudo tee /etc/systemd/system/sing-box.service > /dev/null <<'EOF'
[Unit]
Description=sing-box service
After=network.target nss-lookup.target

[Service]
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_NET_RAW CAP_SYS_PTRACE CAP_DAC_READ_SEARCH
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_NET_RAW CAP_SYS_PTRACE CAP_DAC_READ_SEARCH
ExecStart=/usr/local/bin/sing-box -D /var/lib/sing-box -C /etc/sing-box run
Restart=on-failure
RestartSec=10s
LimitNOFILE=infinity

[Install]
WantedBy=multi-user.target
EOF

sudo mkdir -p /var/lib/sing-box
sudo systemctl daemon-reload
sudo systemctl enable --now sing-box
sudo systemctl status sing-box
```

### Step 5　GNOME 代理设为 none

```bash
gsettings set org.gnome.system.proxy mode 'none'
```

tun 工作在网络层，不需要系统代理。mode 为 `auto` 且 `autoconfig-url` 为空时 Chrome 会走 WPAD 查找 PAC 失败。

**不要装 SwitchyOmega**，tun 模式不提供本地代理端口，填了反而上不去网。

## v2ray-core（仅需命令行代理）

不需要全局 tun，只想要本地 SOCKS5/HTTP 端口：

```bash
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/v2fly/fhs-install-v2ray/master/install-release.sh)"

sudo tee /usr/local/etc/v2ray/config.json > /dev/null <<'EOF'
{
  "log": { "loglevel": "warning" },
  "inbounds": [
    { "port": 1080, "listen": "127.0.0.1", "protocol": "socks",
      "settings": { "auth": "noauth", "udp": true } },
    { "port": 1081, "listen": "127.0.0.1", "protocol": "http", "settings": {} }
  ],
  "outbounds": [
    { "protocol": "vmess", "tag": "proxy",
      "settings": { "vnext": [{ "address": "stargazer.org.cn", "port": 443,
        "users": [{ "id": "在此填入UUID", "alterId": 0, "security": "auto" }] }]},
      "streamSettings": { "network": "ws", "security": "tls",
        "tlsSettings": { "serverName": "stargazer.org.cn" },
        "wsSettings": { "path": "/ray" } } },
    { "protocol": "freedom", "tag": "direct" }
  ]
}
EOF

sudo systemctl enable --now v2ray
```

使用：

```bash
export https_proxy=http://127.0.0.1:1081   # 当前终端生效
curl --socks5 127.0.0.1:1080 https://ifconfig.me   # 单条命令
unset http_proxy https_proxy
```

---

# 四、手机客户端

## iOS

**iOS 推荐 sing-box**，用 JSON 配置文件导入。配置里带 geosite-cn / geoip-cn 分流，国内流量直连不绕道，且和 PC 端共用同一份配置。

| App | 价格 | 导入方式 |
|---|---|---|
| **sing-box** | 免费 | **JSON 文件**（推荐） |
| V2Box | 免费 | `vmess://` 链接 |
| Shadowrocket | $2.99 | `vmess://` 链接 |

> 中国区 App Store 已全部下架，需非中国区 Apple ID。中国区同名应用多为仿品，可能无法解析标准 `vmess://` 链接。

## iOS - sing-box（推荐，用 JSON）

### Step 1　安装

App Store 搜 `sing-box`，作者 SagerNet。

### Step 2　添加配置

Profiles → 右上 `+` → 选 **Remote** → URL 填：

```
https://stargazer.org.cn/share/v2ray/sb-ws-tls-v2.json
```

### Step 3　启用

回首页选中该 profile → 打开开关 → 首次会弹 VPN 权限，点允许。

### Step 4　验证

Safari 访问 https://ifconfig.me，显示 `43.156.23.211` 即生效。

## iOS - V2Box（用 vmess 链接）

### Step 1　复制链接

打开 `vmess.md`，复制里面那整行 `vmess://` 开头的字符串。

### Step 2　导入

V2Box → Configs → 右上 `+` → **Import from Clipboard**

### Step 3　启用

选中节点 → 首页点连接按钮。

### Step 4　验证

同上，访问 https://ifconfig.me 应显示 `43.156.23.211`。

> 手动填参数时注意**伪装域名 (host) 必须填 `stargazer.org.cn`**，留空会导致连接成功但无法上网。

## Android

**Android 推荐 v2rayNG**，和 Windows 的 v2rayN 同一作者（2dust），直接粘贴 `vmess://` 即用，对 VMess + WebSocket + TLS 支持最完整。

| App | 导入方式 | 说明 |
|---|---|---|
| **v2rayNG** | `vmess://` 链接 | 推荐，日常够用 |
| sing-box for Android | JSON（Remote URL） | 与 PC / iOS 共用一份配置 |
| NekoBox for Android | 链接 / 订阅 | 界面更现代，配置略复杂 |

### Step 1　下载 APK

```
https://github.com/2dust/v2rayNG/releases/latest
```

- `v2rayNG_<版本>_arm64-v8a.apk` —— 近几年手机都选这个
- `v2rayNG_<版本>_armeabi-v7a.apk` —— 老设备（32 位）
- `v2rayNG_<版本>_universal.apk` —— 不确定架构就用这个，体积大一倍

GitHub 慢则在链接前加 `https://ghproxy.net/`。也可在 Google Play 搜 v2rayNG（需非中国区账号）。

### Step 2　导入节点

复制 `vmess.md` 里整行 `vmess://` → v2rayNG 右上 `+` → **从剪贴板导入** → 节点出现后点一下选中。

### Step 3　启动

右下角 V 形按钮，首次弹 VPN 权限点允许。

### Step 4　验证

浏览器访问 https://ifconfig.me，显示 `43.156.23.211` 即生效。

国内直连在「设置 → 路由模式」选**绕过局域网及大陆地址**。

### 备选下载

| App | 地址 / APK |
|---|---|
| sing-box for Android | https://github.com/SagerNet/sing-box/releases/latest<br>选 `SFA-<版本>-arm64-v8a.apk`（APK 在主仓库，不在 sing-box-for-android） |
| NekoBox for Android | https://github.com/MatsuriDayo/NekoBoxForAndroid/releases/latest<br>选 `NekoBox-<版本>-arm64-v8a.apk`（无 universal 包，须对上架构） |

sing-box for Android 配置方式同 iOS：Profiles → `+` → **Remote** → 填 `https://stargazer.org.cn/share/v2ray/sb-ws-tls-v2.json`。

---

# 五、方案选择

| | v2rayN | sing-box | v2ray-core |
|---|---|---|---|
| 界面 | 有 | 无 | 无 |
| 全局代理 (tun) | 支持 | 支持 | 不支持 |
| 与手机共用配置 | 否 | **是** | 否 |
| 节点切换 | 界面点选 | 改配置重启 | 改配置重启 |

- Windows 日常 → v2rayN
- Ubuntu 桌面全局代理 → sing-box
- 服务器只要命令行代理 → v2ray-core
- 想和手机共用一份配置 → 都用 sing-box

---

# 六、日常维护

### 服务端

```bash
sudo docker ps --filter name=v2ray --format '{{.Status}} | {{.Ports}}'
sudo docker logs v2ray --tail 30
sudo docker restart v2ray                    # 仅改 config.json 内容
sudo grep -o '"id": "[^"]*"' /etc/v2ray/config.json   # 查当前 UUID

# 改端口映射需重建（Docker 不支持热加端口）
sudo docker stop v2ray && sudo docker rm v2ray  # 再用完整 docker run
```

### Ubuntu 客户端

```bash
sudo systemctl start|stop|restart sing-box
sudo systemctl status sing-box
sudo journalctl -u sing-box --since "10 min ago"
sudo systemctl disable sing-box      # 只关自启，服务继续跑
```

> **务必用 `systemctl stop`，不要 kill 进程。** tun 改了系统路由表，正常 stop 会清理，强杀可能残留路由导致整机断网。断网修复：`sudo systemctl restart NetworkManager`

### 体检

```bash
systemctl is-active sing-box                 # active
ip -brief addr show tun0                     # 172.19.0.1/30
curl -s https://icanhazip.com                # 43.156.23.211（走代理）
curl -s https://www.cip.cc/ | head -3        # 国内 IP（分流正常）
gsettings get org.gnome.system.proxy mode    # 'none'
```

国内站点显示本地运营商 IP 才对，说明国内流量直连没绕道。

### 证书续期

443 启用后证书到期会导致**网站和代理一起挂**：

```bash
systemctl list-timers | grep certbot
certbot renew --cert-name stargazer.org.cn --dry-run
```

当前证书有效期至 2027-01-18。

---

# 七、常见问题

### 报 `invalid user`

网络是通的，认证参数不对。按顺序查：UUID 是否完整一致（复制粘贴，注意首尾空格）→ alterId 是否为 `0` → 加密选 `auto`。服务端确认：`sudo docker logs v2ray --tail 20`

### 连接成功但无法上网

最常见是**伪装域名 (host) 留空**。部分客户端 host 为空时请求不带 `Host` 头，Apache vhost 匹配失败。必须填 `stargazer.org.cn`。

### Chrome 打不开 Google 但 Firefox 正常

IPv6 问题。服务器无 IPv6 出口，Chrome 对 IPv6 激进会反复重试每条等 5 秒。确认配置为 `ipv4_only` 且 tun 地址无 IPv6 段，然后**完全退出 Chrome 重开**（`pkill chrome`，关窗口不够）。

### v2rayN 开了代理但浏览器不走

Firefox 需在「网络设置」选「使用系统代理设置」；SwitchyOmega 等插件会覆盖系统代理，检查或卸载。

### 用浏览器访问代理端口测连通性

**无效。** VMess 不是 HTTP 协议，浏览器必然失败，不代表端口不通。改用 Step 5 的 WebSocket 握手测试或看服务端日志。

### sing-box 报权限错误

tun 需创建虚拟网卡。前台运行加 `sudo`；systemd 要保留 service 里的 `CapabilityBoundingSet` 和 `AmbientCapabilities`。

### 关掉 sing-box 后断网

tun 路由残留：`sudo systemctl restart NetworkManager`

### 怎么确认代理真生效

```bash
curl -s https://ifconfig.me    # tun 模式下直接应为 43.156.23.211
```

> `ifconfig.me` 偶尔返回空，换 `https://icanhazip.com` 或 `https://api.ipify.org` 复核。

---

# 八、文件与下载

### 本目录

| 文件 | 说明 |
|---|---|
| `gen-config.py` | 配置生成脚本 |
| `vmess.md` | 当前节点链接与参数 |
| `sb-ws-tls-v2.json` | sing-box 分流配置（现网在用） |
| `config.json` | 服务端配置参考 |
| `install-sing-box.sh` | Ubuntu 一键安装 |
| `v2ray-detail.md` | 完整原理与踩坑记录 |

### COS 加速（国内推荐）

| 平台 | 地址 |
|---|---|
| v2rayN (Windows) | https://nanjing-1251602985.cos.ap-nanjing.myqcloud.com/v2rayN-windows-64.zip |
| sing-box (Windows amd64) | https://nanjing-1251602985.cos.ap-nanjing.myqcloud.com/sing-box-1.14.3-windows-amd64.zip |
| sing-box (Linux amd64) | https://nanjing-1251602985.cos.ap-nanjing.myqcloud.com/sing-box-1.14.3-linux-amd64.tar.gz |

### 官方源

| 软件 | 地址 |
|---|---|
| v2rayN | https://github.com/2dust/v2rayN/releases/latest |
| sing-box | https://github.com/SagerNet/sing-box/releases/latest |
| v2rayNG (Android) | https://github.com/2dust/v2rayNG/releases/latest |
| sing-box for Android | https://github.com/SagerNet/sing-box/releases/latest → `SFA-<版本>-arm64-v8a.apk` |
| NekoBox (Android) | https://github.com/MatsuriDayo/NekoBoxForAndroid/releases/latest → `NekoBox-<版本>-arm64-v8a.apk` |
| v2ray-core | https://github.com/v2fly/v2ray-core/releases/latest |
| sing-box 文档 | https://sing-box.sagernet.org/ |

GitHub 慢时在原链接前加 `https://ghproxy.net/`。ARM、musl、Windows 7 版本需走官方源。

---

# 九、安全要点

- **SOCKS5/HTTP 代理不要暴露公网**。无认证等于开放代理，几分钟内会被扫描滥用导致 IP 被拉黑。只绑 `127.0.0.1`，远程走 Tailscale。
- **配置文件不要放 Web 可访问目录**。含 UUID，泄露即被白用。注意备份目录也可能在 DocumentRoot 下——本次部署踩过，`data/back/` 公网返回 200。
- **sing-box 配置用随机文件名**，`gen-config.py` 默认已随机，避免被扫到 UUID。
- 验证：`curl -s -o /dev/null -w "%{http_code}\n" http://域名/路径/文件.json` 期望 403/404。