# 西游云 使用说明

> 适用品牌：**西游云**（brand key `xiyouyun`，brandPrefix `Xiyou`）  
> 当前版本：**1.0.10**  
> 支持平台：Windows / macOS / Linux / Android  

---

## 目录
- [系统要求](#系统要求)
- [下载安装](#下载安装)
  - [Windows](#windows-安装)
  - [macOS](#macos-安装)
  - [Linux](#linux-安装)
  - [Android](#android-安装)
- [使用教程](#使用教程)
- [常见问题](#常见问题)
- [高级功能](#高级功能)
- [技术支持](#技术支持)

---

## 系统要求

| 平台 | 版本要求 | 架构 |
|------|---------|------|
| Windows | 10 / 11（不支持 7、8/8.1） | amd64、amd64-compatible、arm64 |
| macOS | 12.0 Monterey 及以上 | Apple Silicon (M1/M2/M3/M4)、Intel x64、Intel 兼容版（10.15–11.7） |
| Linux | Kernel 4.19+ | amd64（Ubuntu 22.04+ / Debian 11+ / Fedora 36+ / openSUSE 等主流发行版） |
| Android | 8.0 及以上 | ARMv7、ARM64、x64 |

> Windows 7 需要专用版本，在[官网](https://xiyou.me)教程区下载。

---

## 下载安装

所有安装包文件名格式：`Xiyou-<版本>-<平台>-<架构>[-setup].<扩展名>`。
本说明以 `1.0.10` 为例。

### Windows 安装

#### 1. 选择安装包

| 类型 | 适用场景 | 文件名示例 |
|------|---------|-----------|
| amd64-setup | 2015 年后的主流电脑（推荐） | `Xiyou-1.0.10-windows-amd64-setup.exe` |
| amd64-compatible-setup | 较老 CPU 或装完启动失败 | `Xiyou-1.0.10-windows-amd64-compatible-setup.exe` |
| arm64-setup | Surface Pro X 等 ARM 设备 | `Xiyou-1.0.10-windows-arm64-setup.exe` |

#### 2. 安装步骤

1. **右键安装包 → "以管理员身份运行"**
2. 如果 SmartScreen 弹窗提示"Windows 已保护你的电脑"，点击"更多信息" → "仍要运行"
3. **防火墙放行**：Windows 防火墙弹窗点击"允许访问"；没有弹窗又开了防火墙需要手动把 `XiyouYun.exe` 加入白名单
4. 有 360 / 腾讯管家等安全软件的，同样需要放行
5. 按向导完成安装，建议默认路径

#### 3. 启动

**首次启动一定要"以管理员身份运行"**（右键 → 以管理员身份运行），否则无法创建虚拟网卡。

---

### macOS 安装

#### 1. 选择安装包

| 类型 | 适用设备 | 文件名示例 |
|------|---------|-----------|
| arm64 | Apple Silicon (M1/M2/M3/M4) | `Xiyou-1.0.10-macos-arm64.dmg` |
| amd64 | Intel Mac（macOS 12+） | `Xiyou-1.0.10-macos-amd64.dmg` |
| amd64-compatible | 老款 Intel Mac（10.15–11.7） | `Xiyou-1.0.10-macos-amd64-compatible.dmg` |

**如何判断芯片**：点击左上角  → "关于本机" → 看 "芯片" 或 "处理器" 字段。

#### 2. 安装步骤

> ⚠️ **必须把 `.app` 拖到"应用程序"(/Applications) 目录运行。**
>
> 本应用的虚拟网卡（TUN）依赖一个 `setuid root` 的核心辅助程序。
> macOS 的 App Translocation 机制会把从"下载"、移动硬盘或任何带隔离
> 属性目录里直接双击的应用搬进一个随机只读 `nosuid` 临时路径运行，
> `setuid` 权限在那种路径下会被内核直接吞掉，表现就是：**登录正常、
> 节点可选，但一开虚拟网卡就失败**。
>
> 只有放进 `/Applications` 正常启动，这套授权链才能完整生效。

1. 双击 `.dmg` 挂载
2. **把应用图标拖到 "Applications" 文件夹**（不要双击直接运行）
3. 从"启动台"或 `/Applications` 里打开
4. 首次打开如提示"无法验证开发者"：系统设置 → 隐私与安全性 → 滚到底部 → "仍要打开"
5. 首次开启虚拟网卡会弹管理员密码框，输入密码授权一次即可

**如果提示"应用已损坏"或想手动清隔离属性：**
```bash
sudo xattr -rd com.apple.quarantine /Applications/XiyouYun.app
```

| 品牌信息 | 值 |
|---------|-----|
| `.app` 文件名 | `XiyouYun.app` |
| Finder 显示名 | 西游云 |
| Bundle ID | `com.appshub.xiyouyun` |

---

### Linux 安装

#### 1. 选择安装包

| 格式 | 适用发行版 | 文件名示例 |
|------|-----------|-----------|
| DEB | Ubuntu / Debian / Linux Mint | `Xiyou-1.0.10-linux-amd64.deb` |
| RPM | Fedora / RHEL / openSUSE | `Xiyou-1.0.10-linux-amd64.rpm` |
| AppImage | 所有主流发行版 | `Xiyou-1.0.10-linux-amd64.AppImage` |

> Linux arm64 包（树莓派 / ARM 服务器等）按需单独提供，文件名 `Xiyou-1.0.10-linux-arm64.*`。

#### 2. 运行时依赖

```bash
# Ubuntu / Debian
sudo apt update
sudo apt install -y libgtk-3-0 libglib2.0-0 libayatana-appindicator3-1 \
                    libkeybinder-3.0-0 libsecret-1-0 libnotify4

# Fedora / RHEL
sudo dnf install -y gtk3 glib2 libayatana-appindicator-gtk3 \
                    keybinder3 libsecret libnotify

# Arch
sudo pacman -S --needed gtk3 glib2 libayatana-appindicator \
                         keybinder3 libsecret libnotify
```

#### 3. 安装

**DEB：**
```bash
sudo dpkg -i Xiyou-1.0.10-linux-amd64.deb
sudo apt-get install -f   # 自动补依赖（必要时）
```

**RPM：**
```bash
sudo dnf install ./Xiyou-1.0.10-linux-amd64.rpm
# 或：sudo rpm -i Xiyou-1.0.10-linux-amd64.rpm
```

**AppImage：**
```bash
chmod +x Xiyou-1.0.10-linux-amd64.AppImage
./Xiyou-1.0.10-linux-amd64.AppImage
```

#### 4. 给虚拟网卡权限

首页虚拟网卡开关开启时需要创建 TUN 设备，给二进制加一次 capability 就不用 sudo：
```bash
sudo setcap cap_net_admin=+ep /usr/bin/xiyouyun
```

AppImage 方式由于每次运行路径不同，推荐直接 `sudo ./Xiyou-...AppImage` 或在 AppImage 解压后的 `AppRun` 上执行 `setcap`。

---

### Android 安装

#### 1. 选择安装包

| 类型 | 说明 | 建议 |
|------|------|------|
| universal | 通用包，包含所有架构 | ✅ 推荐 |
| arm64 | 2018 年后的主流手机 | 体积更小 |
| arm | 老旧 ARMv7 手机 | 仅老设备 |
| amd64 | 模拟器 / x86 平板 | 小众 |

文件名示例：`Xiyou-1.0.10-android-universal.apk`。

#### 2. 安装步骤

1. 下载 APK 到手机
2. 在文件管理器中点击 APK
3. 如提示"禁止安装未知应用"，去设置里给当前文件管理器 / 浏览器放行
4. 确认安装

| 品牌信息 | 值 |
|---------|-----|
| Application ID | `com.appshub.xiyouyun` |
| URL Scheme | `xiyouyun://` |

---

## 使用教程

### 1. 登录账号
打开应用 → 输入账号/密码 → 登录。

### 2. 在首页打开核心开关

主界面直接有 3 个开关/按钮，不需要进菜单：

| 开关 | 说明 | 平台备注 |
|------|------|---------|
| **虚拟网卡** | 建立 TUN 设备，接管所有应用流量 | macOS 首次会弹管理员密码；Android 首次会弹 VPN 权限；Linux 需先 `setcap`（见上） |
| **系统代理** | 在系统层写入 HTTP(S) 代理，让浏览器等无 VPN 能力的应用也走代理 | 部分 Linux 桌面环境（特别是定制发行版）可能改不动系统代理，这个开关开不了不影响虚拟网卡的效果 |
| **启动** | 启动代理核心，路由生效 | 必须开了虚拟网卡和/或系统代理后才有意义 |

**推荐：3 个都打开。**

### 3. 选择节点

1. 点击首页"节点选择"
2. 点击右下角 **"一键测试"**，等所有节点测速完成
3. 选一个延迟最低的（绿色数字），回到首页

| 颜色 | 延迟 | 体验 |
|------|------|------|
| 🟢 绿 | 0–200ms | 优秀 |
| 🟡 黄 | 200–500ms | 可用 |
| 🔴 红 | >500ms | 卡 |
| ⚫ 灰/超时 | — | 不可用 |

### 4. 出站模式

首页可切换出站模式：

| 模式 | 行为 | 建议 |
|------|------|------|
| 规则模式 | 国内直连、国外走代理 | ✅ 默认推荐 |
| 全局模式 | 所有流量走代理 | 节点完全受控时用 |
| 直连模式 | 不走代理 | 临时关闭代理 |

### 5. 验证

- 浏览器打开 Google / YouTube 能加载 → 成功
- 首页显示的出口 IP 变成节点所在地 → 成功

---

## 常见问题

### Windows

#### Q1. 安装被 Windows Defender / SmartScreen 拦截
SmartScreen → 更多信息 → 仍要运行；Defender 拦截则临时关闭或把安装目录加白名单。

#### Q2. 启动后节点列表一直空
1. 确认"以管理员身份运行"
2. 确认防火墙/安全软件没有挡住订阅请求
3. 校园网/特殊网络参考 [DNS 穿透](#dns-穿透校园网专用)

#### Q3. 开启虚拟网卡失败
1. 必须管理员身份启动
2. 其他 VPN/代理客户端（Clash for Windows、V2RayN 等）如果也开了 TUN，关掉其中一个
3. 重启电脑让旧的虚拟网卡清理干净

### macOS

#### Q4. 一开虚拟网卡就失败 / TUN 模式不工作

**先排查是否装在 `/Applications`：**

```bash
ps -Ao pid,comm | grep -i XiyouYun
```

输出里路径包含 `AppTranslocation/...` 或不是 `/Applications/...`，就是 App Translocation 的锅，**退出应用、把 `.app` 拖进 `/Applications` 再打开**。

仍不行：系统设置 → 隐私与安全性 → 网络/扩展 里看看本应用的网络扩展权限是否被允许。

#### Q5. 提示"应用已损坏，无法打开"
```bash
sudo xattr -rd com.apple.quarantine /Applications/XiyouYun.app
```

#### Q6. 提示"无法验证开发者"
系统设置 → 隐私与安全性 → 滚到底部 → "仍要打开"。

### Linux

#### Q7. 无法创建 TUN 设备
```bash
# 给二进制 CAP_NET_ADMIN（推荐）
sudo setcap cap_net_admin=+ep /usr/bin/xiyouyun

# 或直接 sudo 启动
sudo xiyouyun

# 确认 TUN 模块
lsmod | grep tun
sudo modprobe tun   # 如果没加载
```

#### Q8. 系统代理开不上（GNOME/KDE）
这个开关在部分桌面环境下确实写不动系统代理，不影响虚拟网卡。要手动设：

**GNOME：**
```bash
gsettings set org.gnome.system.proxy mode 'manual'
gsettings set org.gnome.system.proxy.http host '127.0.0.1'
gsettings set org.gnome.system.proxy.http port 7889
```

**KDE：** 系统设置 → 网络设置 → 代理 → 手动配置，`127.0.0.1:7889`。

> 西游云默认 mixed port 是 **7889**。

#### Q9. 启动后黑屏 / 界面不响应
```bash
LIBGL_ALWAYS_SOFTWARE=1 xiyouyun
```

### Android

#### Q10. 无法授予 VPN 权限
1. 系统设置 → 网络 → VPN，删掉其他残留的 VPN 配置
2. 重启手机

#### Q11. "VPN 已被其他应用占用"
同时只允许一个 VPN 运行。关掉其他 VPN 应用再试。

#### Q12. 耗电多
1. 用分应用代理，只代理必要的 App
2. 不用时关闭连接
3. 避免长时间挂全局模式

### 通用

#### Q13. 连接成功但网页打不开
1. 出站模式切到"规则模式"或"全局模式"
2. 首页看虚拟网卡是否开着
3. 清浏览器缓存、换节点
4. 复查 DNS 设置

#### Q14. 速度慢
1. 重新测速，换绿色节点
2. 避开晚 8–11 点高峰
3. 试不同地区节点
4. 检查本地宽带

---

## 高级功能

### DNS 穿透（校园网专用）

校园网/DNS 污染环境下节点域名可能解析不了。开启此功能后应用直连 IP，跳过 DNS。

路径：**设置 → DNS 穿透 开关**（开启后内核会自动重启）。

### 分应用代理（Android）

设置 → 访问控制 → 开启"访问控制"，然后选：
- **仅代理选中的应用**：只勾选需要走代理的（常用：Chrome、YouTube、Twitter、Google Play、Telegram、WhatsApp）
- **绕过选中的应用**：勾选要直连的（常用：微信、支付宝、淘宝、银行、抖音、B 站）

### 自定义规则

首页 → 配置 → 基础配置 → 编辑规则 → 保存 → 重启内核。

### 热键（桌面端）

设置 → 热键管理 → 设置快捷键：
- 切换连接状态
- 显示/隐藏窗口
- 切换系统代理

### 开机自启动

**Windows：** 设置 → 应用设置 → 开启"开机自启动"。

**macOS：** 系统设置 → 通用 → 登录项与扩展 → 登录项 → 添加西游云。

**Linux systemd（可选）：**
```bash
sudo tee /etc/systemd/system/xiyouyun.service >/dev/null <<'EOF'
[Unit]
Description=XiyouYun
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
ExecStart=/usr/bin/xiyouyun
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now xiyouyun
```

**Android：** 设置 → 应用设置 → 开启"自动运行"。

---

## 技术支持

### 官方渠道
- **官网 / 控制台**：https://xiyou.me
- **工单系统**：登录后台提交工单
- **教程区**：官网教程页

### 反馈问题时请附带
1. 操作系统版本（Windows 11 / macOS 14.5 / Ubuntu 22.04 / Android 14 …）
2. 应用版本号（首页 → 设置 → 关于，显示 `v1.0.10`）
3. 架构（Apple Silicon / Intel、ARM64 / amd64）
4. 问题截图或录屏
5. 应用日志（设置 → 导出日志）

### 查看系统日志（桌面）

**macOS：**
```bash
log stream --predicate 'process == "XiyouYun"' --level debug
# 或 控制台.app，搜索 "XiyouYun"
```

**Linux：**
```bash
journalctl -f | grep xiyouyun
```

**Windows：** 在应用内 设置 → 导出日志 即可。

---

**最后更新**：2026-04-21