PurpleBear

PurpleBear 是一款 Android 网络代理与线路管理工具，基于系统 VPN 能力接入 Xray 内核，面向需要管理订阅节点、手动节点、分流规则、分应用代理和流媒体独立出口的用户。

本仓库只包含 PurpleBear Android 应用本身的项目代码、资源、构建配置和必要的运行时依赖，不包含 Xray-core 的完整源码。

SSR / ShadowsocksR 依赖独立的 mihomo sidecar。打包 SSR 功能时，需要将 arm64-v8a 的 mihomo 可执行文件放在：

app/src/main/assets/mihomo/arm64-v8a/mihomo

连接 SSR 节点时，应用会先启动该 sidecar 并监听本机 SOCKS 端口，再由 Xray 通过本地 SOCKS outbound 转发到 SSR 节点。未打包该文件时，其它协议不受影响，SSR 连接会提示缺少 mihomo sidecar。

mihomo 使用 GPL-3.0 许可证。PurpleBear 已在仓库和 APK assets 中包含 GPL-3.0 文本，并在 THIRD_PARTY_NOTICES.md 记录对应版本、源码地址、release 资产和校验值。

主要功能

系统 VPN 连接

• 使用 Android VpnService 建立系统级 VPN 隧道。
• 支持一键连接、断开、切换线路。
• 支持显示当前连接状态、当前线路、运行时长、上下行速率和流量样本。
• 支持在连接中切换节点，应用会处理重连与状态同步。
• 支持系统通知栏展示 VPN 运行状态。
• 支持 Android 快捷设置磁贴，从系统下拉菜单快速连接或断开。

节点与订阅管理

• 支持导入 http / https 节点订阅。
• 支持导入本地单节点链接。
• 支持扫码导入订阅或节点。
• 支持从文件导入订阅内容。
• 支持订阅分组和 Local 本地分组。
• 支持订阅刷新、手动同步、每日自动更新。
• 支持同来源节点去重与覆盖更新。
• 支持节点收藏。
• 支持节点删除、订阅组删除。
• 支持查看节点详情，包括协议、传输层、安全层、地址、端口和原始链接信息。
• 支持节点延迟测试，并在列表中展示延迟和稳定状态。
• 支持隐藏当前暂不支持的节点类型，避免用户误选。

支持的节点类型

PurpleBear 的导入解析器目前支持以下常见分享格式：

• VLESS
• VMess
• Trojan
• Shadowsocks
• SSR / ShadowsocksR（通过本地 mihomo sidecar 桥接）
• SOCKS
• HTTP
• Hysteria2

实际可用性取决于当前内核能力、节点参数、服务端配置和设备网络环境。

手动创建本地节点

• 支持在应用内新建 Local 节点。
• 支持编辑节点名称、地址、端口、协议、安全层和传输参数。
• 支持配置 TLS / REALITY 等安全层字段。
• 支持 WebSocket、gRPC、mKCP、HTTP Upgrade 等传输相关参数。
• 支持保存为本地节点并直接用于连接。

备用节点与自动恢复

• 支持为节点配置备用节点。
• 主节点连接失败后，可自动切换到备用节点。
• 备用节点运行期间，服务层会持续检测主节点。
• 主节点连续恢复稳定后，可自动切回主节点。
• 备用节点逻辑运行在 VPN 服务层，不依赖应用界面常驻前台。
• 支持断线自动重连，降低临时网络波动对连接的影响。

前置节点

• 支持为节点配置前置节点。
• 可用于需要链式出口或特殊入口线路的场景。
• 节点列表会标记前置 / 备用配置，便于快速识别。

分流规则

• 内置 Geo 数据资源状态展示。
• 支持更新 geoip.dat 和 geosite.dat。
• 支持系统默认规则源。
• 支持添加自定义规则源。
• 支持 Shadowrocket / Surge 文本规则。
• 支持规则源启用 / 禁用。
• 支持规则源更新状态、转换数量、跳过数量和错误信息展示。
• 支持规则详情查看，便于确认规则来源和转换结果。
• 支持智能分流、全局代理、分应用代理三种模式。

分应用代理

• 支持选择哪些应用进入 VPN。
• 支持搜索应用名称或分类。
• 支持在智能分流和仅代理选中应用之间切换。
• 应用名单变更后会触发连接配置更新。

流媒体分流

• 支持为常见流媒体服务单独指定出口节点。
• 支持一键刷新流媒体规则。
• 支持按服务选择默认线路或独立节点。
• 已内置 Netflix、Disney+、YouTube、YouTube Music、Prime Video、Hulu、Max、HBO、Spotify、Apple TV、Apple Music、Bahamut、AbemaTV、BiliBili、ViuTV、DAZN、Paramount+、Peacock 等服务规则入口。
• 流媒体规则会被转换为 Xray 路由规则，并在连接配置中生效。

DNS 与高级设置

• 支持系统 DNS、远程 DNS、自定义 DNS 模式。
• 支持设置日志级别：error、warning、info、debug。
• 支持核心资产状态查看。
• 支持启动后自动连接。
• 支持恢复上次连接线路。
• 支持断线自动重连。
• 支持备用节点心跳间隔设置。
• 支持浅色 / 深色主题。

诊断与日志

• 支持系统诊断，检查配置、内核、VPN、DNS 和握手状态。
• 支持复制诊断摘要。
• 支持查看最新运行日志。
• 支持 Xray 错误日志和访问日志。
• 日志写入和裁剪在后台执行，减少连接阶段卡顿。

订阅与资源同步

• 支持节点订阅与规则资源统一同步。
• 支持非计费网络下每日自动更新。
• 支持同步完成通知。
• 支持对一次性快照订阅做静态导入处理，避免后续刷新失败造成误判。

界面体验

• 使用 Jetpack Compose 构建原生 Android 界面。
• 首页展示连接状态、速率、时长、当前线路和常用入口。
• 线路页面按分组展示节点，支持收藏、测速、详情、删除和快速切换。
• 线路列表采用更扁平、清爽的节点展示方式，减少多层卡片嵌套。
• 支持浅色模式下更清晰的未选中 / 选中节点区分。

隐私与数据

• PurpleBear 不内置任何订阅账号、机场服务或代理服务器。
• 用户导入的订阅、节点、规则和偏好设置保存在本机。
• 应用会在用户主动同步订阅、规则或 Geo 数据时访问对应 URL。
• VPN 功能需要 Android 系统 VPN 授权。
• 分应用代理需要读取本机应用列表用于选择代理范围。
• 隐私政策页面位于 privacy-policy.html，GitHub Pages 开启后可通过项目 Pages 地址访问。

项目结构

• app/：Android 应用模块，包含 Kotlin 源码、Compose UI、资源、Manifest、预编译运行依赖和 Geo 数据。
• gradle/：Gradle Wrapper 文件。
• build.gradle.kts、settings.gradle.kts、gradle.properties：顶层 Gradle 配置。
• gradlew、gradlew.bat：命令行构建入口。
• index.html、privacy-policy.html：GitHub Pages 使用的项目页面与隐私政策。

不再跟踪的内容包括外部内核源码、第三方示例工程、UI 原型草稿、临时构建目录、签名文件、本地配置和未使用的大体积库文件。

构建环境

• Android Studio Hedgehog 或更新版本
• JDK 17
• Android SDK 35
• Gradle Wrapper 已包含在仓库中
• 当前发布包仅面向 arm64-v8a

命令行构建：

./gradlew :app:assembleRelease

生成的 APK 位于：

app/build/outputs/apk/release/app-release.apk

如果本地没有发布签名配置，Release 构建可能无法签名。开发调试可使用：

./gradlew :app:assembleDebug

更新日志

版本 0.6.9 更新

1. 新增 SSR / ShadowsocksR 节点支持，应用会通过本地 mihomo sidecar 桥接到 Xray，普通 Xray 支持的节点不受影响。

2. 兼容部分以 ssr:// 包装的 Shadowsocks 2022 节点，导入后会优先按原生 Shadowsocks 2022 连接，避免错误进入 SSR sidecar。

3. 新增 SSR 本地节点创建字段，包括加密方法、协议、混淆、协议参数、混淆参数和 UDP 开关。

4. 状态总览会提示当前使用 SSR 兼容模式；SSR 链路下首页测速超时时改为“测速超时”，并提示连接可用时可忽略。

5. 首页测速样本调整为更轻量的下载 256KiB、上传 64KiB，并放宽总测速窗口，减少 SSR / IEPL 链路可用但测速超时的误判。

6. 检查更新流程改为打开 GitHub Release 下载页，让用户在浏览器中手动下载最新 APK。

7. 仓库和 APK assets 中加入 mihomo 对应的 GPL-3.0 许可证文本与第三方 notice，README 补充 SSR sidecar 打包说明。

8. 更新版本号到 0.6.9，versionCode 更新为 269。

版本 0.6.8 更新

1. 新增俄语界面语言，设置页可在中文、English、Русский 和跟随系统之间切换。

2. 补齐规则管理、检查更新、分应用代理、前置代理、流媒体分流、日志与诊断等页面的俄语文案。

3. 语言选择栏支持横向滑动，避免俄语等较长语言名称在小屏幕上显示不全。

4. Geo 数据仍保留全量资源，新增 Geo 分流国家下拉选择，可在中国、英语区域和俄罗斯之间切换默认直连规则。

5. Geo 分流国家会根据界面语言选择默认值：中文默认中国，英文默认英语区域，俄语默认俄罗斯；手动选择后不会被语言切换覆盖。

6. 修复规则页“内置资源”等 Geo 数据状态文案，以及 VPN MTU 等动态设置描述在俄语模式下仍显示中文的问题。

7. 更新版本号到 0.6.8，versionCode 更新为 268。

版本 0.6.7 更新

1. 新增应用内检查更新功能，可从“我的”进入设置页，再打开“检查更新”查看 GitHub Release 最新版本。

2. 打开应用后每天最多自动检查一次新版本；发现新版本时会提示用户，手动检查且已是最新版时会弹窗反馈。

3. 检查更新详情页会展示 GitHub Release 中填写的版本说明：当前已是最新版时显示“当前版本描述”，有新版本时显示“更新版本描述”。

4. 支持通过代理下载最新 APK，下载完成后可在应用内调用 Android 系统安装器继续升级。

5. 扫码导入支持从本地相册选择二维码图片，适合保存了订阅二维码或节点二维码截图的场景。

6. 优化二维码导入确认流程：识别后先进入导入确认页；单节点导入只显示当前节点的协议、地址、端口、传输、安全和目标分组，订阅导入继续显示订阅节点数量。

7. 应用内版本显示改为读取构建版本，避免界面版本号和 APK 实际版本不一致。

8. 更新版本号到 0.6.7，versionCode 更新为 267。

版本 0.6.6 更新

1. 新增中文 / English 双语界面，默认跟随 Android 系统语言，也可在设置中手动切换。

2. 英文模式补齐首页、线路、规则、导入、我的、设置、首次启动介绍页和 VPN 权限介绍页等主要界面文案。

3. 补齐动态数据的英文显示，包括 Just now、订阅组来源、节点地区、规则源状态、Geo 数据更新、端口标签和核心资产状态等。

4. 优化浅色模式下 Android 状态栏和导航栏图标颜色，避免时间、信号、电量等系统信息不可见。

5. 更新版本号到 0.6.6，同步应用内版本标识、构建版本和 release 包版本。

6. 保留 0.6.5 的全局代理能力：全局代理开启后局域网/私网仍直连，其余正常上网流量走当前节点。

版本 0.6.5 更新

1. 新增自定义文本规则，可手动编写 Shadowrocket / Surge 规则。

2. 支持规则按策略分流，可指定直连、代理、拒绝，或选择指定节点。

3. 新增节点选择弹窗，支持搜索节点；订阅刷新后节点名称变化也会尽量自动匹配。

4. 优化规则校验，保存时会提示格式错误，并在文本框中标红错误行。

5. 新增规则输入自动补全，减少手动输入成本。

6. 优化自定义规则界面，文本规则和 URL 规则分开展示。

7. 提升自定义规则优先级，用户规则会优先生效。

8. 兼容 no-resolve、GEOIP、URL-REGEX 等更多规则写法。

9. 修复添加规则菜单定位异常、版本显示不一致等问题。

10. 优化规则解析与节点匹配稳定性，降低订阅更新后的失效概率。

版本 0.6.4 更新

1. 优化线路页面视觉层级，节点组和节点列表更清爽，减少多层圆角卡片嵌套感。

2. 调整节点展示样式，移除大面积渐变和铺色背景，亮色模式下未选中节点使用接近白色的平底，选中节点使用轻微强调色，更容易识别当前线路。

3. 优化备用节点机制：主节点连接失败后可自动切换到备用节点；主节点恢复稳定后，可自动回到主节点。

4. 将备用节点检测逻辑下移到 VPN 服务层，应用退到后台或界面被回收后，备用节点切换仍能继续工作。

5. 修复自动重连与备用节点切换可能同时触发的问题，降低连接状态混乱的概率。

6. 修复启动时自动连接状态判断过早结束的问题，提升首次启动、引导流程后的自动连接可靠性。

7. 优化节点心跳与延迟显示逻辑，避免心跳刷新频繁打乱节点列表展示。

8. 优化快捷开关响应速度，减少节点较多时点击系统快捷开关可能卡顿的问题。

9. 修复 Android 14+ 前台服务类型处理问题，提升真机和上架测试稳定性。

10. 优化连接初始化流程，降低快速重连、备用节点切换时出现保护失败的概率。

11. 优化日志写入与裁剪流程，减少连接阶段高频日志对性能的影响。

内核与鸣谢

PurpleBear 使用 Xray 作为代理核心能力来源。Xray-core 是一个独立开源项目，完整源码请访问：

https://github.com/XTLS/Xray-core

感谢 Xray-core 项目及其贡献者提供核心网络代理能力；感谢 v2fly GeoIP / GeoSite 数据、blackmatrix7 规则项目以及 Android、Kotlin、Jetpack Compose 生态为本项目提供基础能力。