Build & use构建与使用

Two build modes. One needs JDK 17 and an Android SDK; the other additionally needs Go, gomobile and the NDK, and gives you the embedded node.两种构建模式。一种只需要 JDK 17 和 Android SDK；另一种还需要 Go、gomobile 和 NDK， 并且会给你内嵌节点。

Fast path快速路径#

git clone https://github.com/zero6689/tailnet-byok.git
cd tailnet-byok

node scripts/fetch-toolchain.mjs gradle sdk   # Gradle + Android SDK, if you lack them
node scripts/make-wrapper.mjs                 # generates gradlew / gradlew.bat

./gradlew assembleDebug                        # macOS / Linux
.\gradlew.bat assembleDebug                    # Windows

That produces an APK in app/build/outputs/apk/debug/. It runs, and the embedded provider will be reported as unavailable — with the reason shown in the UI rather than as a crash.这样会在 app/build/outputs/apk/debug/ 下生成一个 APK。它能跑，只是内嵌 提供方会被报为不可用 —— 原因会显示在 UI 上，而不是直接崩溃。

Full build, with the embedded node完整构建：带内嵌节点#

node scripts/fetch-toolchain.mjs go ndk   # Go + Android NDK
node scripts/build-bridge.mjs             # gomobile bind -> app/libs/tailnet.aar

./gradlew assembleDebug -PwithTsnet=true

scripts/build-bridge.mjs --check reports the toolchain it can see without building anything, which is the fastest way to find out what is missing.scripts/build-bridge.mjs --check 会报告它能看到的工具链，而不实际构建任何东西， 这是最快查出缺什么的方法。

Why the AAR is not committed为什么 AAR 不提交进仓库#

Because there is no prebuilt one to commit. Neither tailscale/libtailscale (which is a C library, and produces no Android artifact at all) nor tailscale/tailscale-android (whose GitHub releases ship only APKs) publishes one on Maven Central or JitPack. The AAR has to be built from source, which is what the script does.因为根本没有现成的可以提交。无论是 tailscale/libtailscale（它是一个 C 库，完全不产出 Android 构件），还是 tailscale/tailscale-android （它的 GitHub release 只发布 APK），都没有在 Maven Central 或 JitPack 上发布过 AAR。 AAR 只能从源码构建，脚本做的就是这件事。

Why not just reuse Tailscale's AAR?为什么不直接复用 Tailscale 的 AAR？#

Two reasons, and the second is the important one.有两个原因，第二个才是关键。

1. It does not expose what this app needs. The binding has no typed Dial and no GetIP; all control flows through a local HTTP API over JNI.它没有暴露这个 App 需要的东西。绑定里没有带类型的 Dial，也没有 GetIP；所有控制都通过 JNI 走一个本地 HTTP API。
2. Using it commits you to the system VPN slot. Its Kotlin side implements IPNService (a VpnService) and an AppContext; the Go side calls back into them. You would be building the official app's architecture — device-wide routing, split-tunnel policy, a foreground service — to open one socket.用它就意味着你要占用系统 VPN 槽位。它的 Kotlin 侧实现了 IPNService（一个 VpnService）和 AppContext； Go 侧会回调它们。为了打开一个套接字，你就得照搬官方 App 的架构 —— 设备级路由、拆分隧道策略、前台服务。

So this project binds tsnet directly, with a deliberately tiny surface: every exported Go function takes and returns only String, Int, Bool or error. Structured data crosses as JSON. That avoids both the interface-binding problem (a Go net.Conn has no Java representation) and the version sensitivity of multi-value returns.所以这个项目直接绑定 tsnet，接口面刻意做得很小： 每个导出的 Go 函数只接收和返回 String、Int、Bool 或 error。结构化数据以 JSON 传递。这样既避开了接口绑定的问题（Go 的 net.Conn 没有对应的 Java 表示），也避开了多返回值对版本敏感的问题。

Toolchain versions工具链版本#

SDK level overrides覆盖 SDK 版本#

The default is compileSdk 37 / targetSdk 37, which is what a Play submission needs. API 37 is a minor platform release, so the SDK package is platforms;android-37.0. If your local SDK is older, override both:默认是 compileSdk 37 / targetSdk 37，这是提交到 Google Play 所需要的。 API 37 是一个 minor 平台版本，所以 SDK 包名是 platforms;android-37.0。如果你本地的 SDK 更旧，就把这两个都覆盖掉：

./gradlew assembleDebug -PcompileSdk=35 -PtargetSdk=35

Note that AndroidX core 1.19 requires compileSdk 37, so this override is only useful if you also lower the dependency versions in gradle/libs.versions.toml.注意 AndroidX core 1.19 要求 compileSdk 37，所以只有在你也把 gradle/libs.versions.toml 里的依赖版本调低时，这个覆盖才有用。

Using it使用它#

1. Create a pre-auth key1. 创建预认证密钥#

In your tailnet's admin console: Settings → Keys → Generate auth key.在你 tailnet 的管理控制台里：Settings → Keys → Generate auth key。

• Prefer single-use: one device, one key.优先选 单次使用（single-use）：一台设备，一把密钥。
• Prefer a tag (for example tag:phone) so your ACLs can grant that tag access to exactly the service you intend.优先打一个 标签（tag）（例如 tag:phone），这样你的 ACL 就能只把这个标签授予你真正想开放的那个服务。
• Set an expiry you will actually notice.设置一个你确实会注意到的 有效期。

The app cannot enforce any of that for you. It is the difference between a key that is a credential and a key that is a capability.这些都没法由 App 替你来保证。这正是「一把密钥只是凭据」与「一把密钥是一种能力」 之间的区别。

2. Enter the target host2. 填写目标主机#

Accepted forms, in order of how likely they are to just work:可接受的写法，按「一填就能用」的可能性从高到低排列：

3. Test3. 测试#

The button runs six checks and stops at the first hard failure. Read the first ✗ — that is the thing to fix. Everything below it is marked skipped rather than failed, because a skipped step tells you nothing.这个按钮会跑六项检查，遇到第一个硬失败就停。先看第一个 ✗ —— 那才是要修的东西。它下面的每一步都会被标成「跳过」而不是「失败」， 因为被跳过的步骤说明不了任何问题。

Using headscale instead of Tailscale用 headscale 代替 Tailscale#

Fill in the Control server field with your headscale base URL, for example https://headscale.example.com, and create the pre-auth key with headscale rather than Tailscale:把 Control server 字段填成你的 headscale 基础 URL，例如 https://headscale.example.com，并用 headscale 而不是 Tailscale 来创建 预认证密钥：

headscale preauthkeys create --user <USER_ID>
headscale preauthkeys create --tags tag:phone --expiration 1h

Leaving the field empty means Tailscale's hosted control plane. Note that passing that hosted URL explicitly is not the same as leaving it empty — tsnet treats a non-empty value as a custom server. The app normalises this for you.把该字段留空表示使用 Tailscale 托管的控制面。注意，显式填入那个托管 URL 与留空并不等价 —— tsnet 会把非空值当成自定义服务器。App 会替你把这层差异 抹平。

Troubleshooting故障排查#