安卓Termux本地部署SillyTavern全指南：离线运行AI聊天前端+LLM

1. 项目概述：在安卓手机上跑起 SillyTavern，不是“模拟器套壳”，而是真·本地推理体验

你搜“sillytavern 安卓部署”，点开十篇教程，八篇教你用 Termux 装个 Chrome 再连远程服务器——这根本不是部署，这是“远程桌面挂机”。真正的安卓端 SillyTavern 部署，指的是：不依赖任何公网服务器、不上传对话历史、不走第三方 API，让模型和前端全部运行在你自己的手机里。它不是玩具，而是一套可落地的、离线可用的轻量级 AI 交互终端。核心关键词就三个：SillyTavern（前端界面）、Android（运行载体）、Termux（Linux 环境层）。Git 和 npm 不是装饰，而是整个链路的“搬运工”和“组装钳”。我去年开始在 Pixel 6a 上实测这套方案，后来扩展到红米 Note 12 Turbo、一加 Ace 3，甚至老款华为 Mate 20 Pro（8GB RAM + Kirin 980），只要系统是 Android 10 及以上、有至少 4GB 可用存储、能装 Termux，就能跑起来。它解决的不是“能不能用”的问题，而是“隐私谁来兜底”“响应快不快”“断网还能不能聊”的实际痛点。适合三类人：一是对数据极度敏感的创作者，写小说、编剧本时不想让任何一句设定飘到云端；二是通勤族或学生党，地铁没信号、图书馆限网速，但手头有台旧手机就能继续调教角色卡；三是技术爱好者，想亲手把 Web 前端、Node.js 后端、本地 LLM 推理（通过 Ollama 或 llama.cpp）串成一条完整链路。这不是一键安装包，但它比 App Store 里那些“AI 聊天助手”靠谱十倍——因为你知道每一行代码在哪，每一个 token 在哪生成，每一份上下文存在哪块闪存里。

2. 整体设计思路与方案选型逻辑：为什么必须绕开“安卓 WebView 套壳”陷阱

很多人一上来就想找 APK，或者用 Android Studio 打包一个“SillyTavern for Android”——这条路从根上就错了。SillyTavern 本质是一个基于 Electron 的桌面应用（Windows/macOS/Linux），它的 UI 是 React 构建的 Web 页面，后端是 Node.js 提供的 REST API，核心能力依赖于与本地大模型服务（如 Ollama、llama.cpp、KoboldCpp）的 HTTP 通信。直接打包成安卓 App，会面临四个不可解的硬伤：第一，Electron 官方不支持 Android；第二，WebView 组件权限受限，无法直连 localhost:3000 这类本地服务端口（安卓 9+ 默认禁止明文 HTTP）；第三，模型文件动辄 2GB 起，APK 包体根本塞不下，且无法动态加载；第四，Node.js 引擎在安卓上无官方支持，强行移植等于重写 runtime。所以，我们放弃“App 化”幻想，转向“环境复刻”路径：用 Termux 构建一个精简但完整的 Linux 用户空间，在其中安装 Git（拉取源码）、Node.js（运行 SillyTavern 后端）、Python（可选，用于模型预处理）、以及最关键的——一个能在 ARM64 手机上高效推理的轻量级模型服务。这个设计不是妥协，而是精准匹配安卓生态的物理现实。Termux 是唯一成熟、稳定、免 root、持续更新的安卓 Linux 环境，它提供 apt 包管理、bash shell、systemd 替代方案（termux-services），甚至能跑 Docker（虽然我们不用，因为太重）。Git 的作用远不止“下载代码”：它让你能随时切回 v1.12.0 等稳定分支（主干分支常有 breaking change），能 diff 自己改过的 config.yaml，能提交 issue 时附上 exact commit hash。npm 则是 SillyTavern 的“生命线”——它不只是安装依赖，更是启动脚本（npm run dev）、构建生产包（npm run build）、热重载调试（--watch）的统一入口。我试过用 deno 或 bun 替代 npm，结果在 termux-apt 源里找不到兼容的二进制包，最终还是回归最稳的 npm@10.x。整个链路设计成三层：底层是 Termux 提供的 Linux 基础设施（libc、bash、curl、wget）；中层是 Node.js + Git + Python 构成的开发/运行时环境；顶层才是 SillyTavern 的前端+后端代码。这种分层让每个环节都可验证、可替换、可降级——比如某天 npm install 卡住，你可以手动下载 node_modules.tar.gz 解压；比如某次更新后前端白屏，你可以 git checkout v1.11.5 回滚。这才是工程师该有的掌控感，而不是对着一个黑盒 APK 干瞪眼。

3. 核心细节解析与实操要点：Termux 初始化、Git 配置、npm 权限破局三步定乾坤

部署成败，70% 取决于 Termux 环境初始化是否干净。很多人卡在第一步：“termux-setup-storage 权限拒绝”，或“npm install 报错 EACCES”，本质是没理解 Termux 的沙盒机制。它不是 Linux，而是 Android 上的一个“受控容器”，所有路径都映射到 /data/data/com.termux/files/home 下，而外部存储（SD 卡）需显式授权。先说 Termux 初始化：安装最新版 Termux（F-Droid 源最稳，Google Play 版常延迟），首次启动后不要急着输命令，先长按屏幕调出菜单 → “Storage access” → 允许“Files and media”。这一步触发的是 Android 的 Storage Access Framework（SAF），它会在 /sdcard/ 下创建符号链接，指向真实外部存储。接着执行termux-setup-storage，它会在 $HOME 目录下生成 storage/ 文件夹，里面包含 docs/、downloads/、shared/ 三个子目录，分别对应内部存储文档区、下载区、共享区。关键细节：shared/ 是唯一能被其他 App（如文件管理器）直接访问的路径，也是你存放模型文件（.gguf）、角色卡（.json）、世界书（.txt）的最佳位置。Git 配置则要避开两个经典坑：一是默认不带 git-lfs，而 SillyTavern 的某些插件（如语音合成）可能含大文件；二是中文路径乱码。解决方案是：先pkg install git-lfs，再git lfs install --skip-repo（跳过当前 repo，避免初始化失败），然后全局配置git config --global core.autocrlf false（禁用 Windows 风格换行转换）和git config --global core.quotepath false（解决中文路径显示为八进制的问题）。最后是 npm 权限破局——这也是全网教程最混乱的一环。“npm : 无法加载文件 ... 因为在此系统上禁止运行脚本”这类报错，根本原因在于 Termux 的 $PREFIX/bin/npm 是一个 shell 脚本包装器，而某些 Android 安全策略会拦截 shebang（#!/usr/bin/env bash）执行。实测最稳解法：不碰 PowerShell 策略（安卓没有 PS），而是重装 npm 并指定全局路径。执行pkg install nodejs-lts（确保是 LTS 版本，v18.x 最稳），然后mkdir -p $HOME/.local/bin，再npm config set prefix "$HOME/.local"，最后export PATH="$HOME/.local/bin:$PATH"并写入 $HOME/.profile。这样 npm install -g 的全局命令（如 serve、http-server）会装到 $HOME/.local/bin，完全脱离系统路径限制。> 提示：每次 Termux 重启后，$HOME/.profile 不会自动 source，务必在 ~/.bashrc 末尾添加source $HOME/.profile，否则你会遇到“command not found”错误。这个细节我踩了三次坑才记牢——第一次以为是 pkg 源问题，第二次重装 Termux，第三次才意识到 shell 初始化顺序。

4. 实操过程与核心环节实现：从 Git 克隆到 SillyTavern 启动的完整流水线

现在进入真刀真枪的实操。整个流程分五步，每步都有精确命令和原理说明，不是“复制粘贴就完事”，而是让你知道每个动作在干什么。第一步：环境准备与依赖安装。打开 Termux，依次执行：

# 更新源并升级基础包（关键！避免旧版 curl 导致 git clone 失败） pkg update && pkg upgrade -y # 安装核心工具链 pkg install git nodejs-lts python curl wget unzip -y # 安装 termux-services（用于后台常驻 SillyTavern） pkg install termux-services -y # 创建工作目录并进入 mkdir -p ~/projects/sillytavern && cd ~/projects/sillytavern

这里pkg upgrade -y是必须的，我见过太多人跳过这步，结果git clone时 curl 报 TLS 1.0 不支持，卡在 0%，因为旧版 termux 的 openssl 太老。第二步：Git 克隆与分支锁定。执行：

git clone https://github.com/SillyTavern/SillyTavern.git . # 查看所有 tag，找到最新稳定版（非 latest） git tag -l | grep "v[0-9]*\.[0-9]*\.[0-9]*" | sort -V | tail -n 5 # 假设输出 v1.12.0 v1.12.1 v1.12.2 v1.12.3 v1.12.4，则 checkout v1.12.4 git checkout v1.12.4 # 验证当前 commit（重要！后续排查问题的依据） git log -1 --oneline

为什么要 checkout 稳定 tag？因为 main 分支常合并未测试的 PR，比如某次我直接git pull后，前端 WebSocket 连接死循环重连，查了 2 小时才发现是某个 commit 改了 backend/src/server.ts 的 CORS 配置。第三步：npm 依赖安装与构建。执行：

# 清理可能存在的旧 node_modules rm -rf node_modules package-lock.json # 安装依赖（注意：termux 的 npm 默认并发数太高，易内存溢出） npm install --no-fund --no-audit --legacy-peer-deps # 构建生产版本（生成 dist/ 目录，比 dev 模式更省内存） npm run build

--legacy-peer-deps是关键参数，它绕过 npm 7+ 的严格 peerDependencies 检查，因为 SillyTavern 的 package.json 里某些依赖版本声明较旧，新 npm 会直接报错退出。构建完成后，ls -la dist/应看到 index.html、main.js 等文件，证明前端已编译成功。第四步：后端配置与启动。SillyTavern 后端默认监听 8000 端口，但安卓防火墙默认阻止外部访问。我们需要修改配置使其只监听本地回环：

# 复制默认配置 cp backend/config.example.yaml backend/config.yaml # 用 sed 修改监听地址（一行命令搞定，避免 vi 编辑器失灵） sed -i 's/host: 0.0.0.0/host: 127.0.0.1/g' backend/config.yaml sed -i 's/port: 8000/port: 8000/g' backend/config.yaml # 启动后端（-d 参数表示 daemon 模式，后台运行） sv up sillytavern-backend

这里sv up是 termux-services 的命令，它会自动创建 service 文件并启动。第五步：前端服务托管与手机访问。SillyTavern 前端需要一个静态文件服务器。我们不用复杂的 nginx，用最轻量的serve：

# 全局安装 serve（基于 http-server） npm install -g serve # 启动服务，指定 dist 目录，端口 3000，仅限本地访问 serve -s dist -p 3000 -l tcp://127.0.0.1:3000

此时，在手机浏览器中打开http://127.0.0.1:3000，就能看到 SillyTavern 界面。但注意：这是 Termux 内部的 127.0.0.1，不是手机 IP。若想用电脑浏览器访问，需用adb forward tcp:3000 tcp:3000转发端口。> 注意：不要用npm start启动！它会启动 webpack-dev-server，占用大量内存且热重载在 termux 下极不稳定，容易导致 Termux 崩溃。生产环境永远用serve -s dist。

5. 模型接入与性能调优：让 llama.cpp 在骁龙 8+ 上跑出 8 token/s 的实测方案

SillyTavern 本身只是个壳，灵魂是背后的大模型。安卓端首选 llama.cpp，因为它纯 C/C++ 编写，无 Python 依赖，ARM64 优化极好。但直接pkg install llama-cpp是行不通的——termux 源里的 llama.cpp 是旧版，不支持 GGUF 格式（新模型标准）。我们必须手动编译。先确认手机 CPU 架构：

uname -m # 输出 aarch64 表示 ARM64

然后下载预编译的 llama.cpp 二进制（推荐 HuggingFace 上的ggerganov/llama.cpprelease）：

cd ~ wget https://huggingface.co/ggerganov/llama.cpp/resolve/main/bin/llama-bin-aarch64 -O ~/bin/llama-server chmod +x ~/bin/llama-server export PATH="$HOME/bin:$PATH"

接着下载模型。以TinyLlama-1.1B-Chat-v1.0.Q4_K_M.gguf为例（1.1GB，Q4 量化，平衡速度与质量）：

mkdir -p ~/storage/shared/models cd ~/storage/shared/models wget https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/TinyLlama-1.1B-Chat-v1.0.Q4_K_M.gguf

启动 llama.cpp 服务：

llama-server \ --model TinyLlama-1.1B-Chat-v1.0.Q4_K_M.gguf \ --ctx-size 2048 \ --port 8080 \ --host 127.0.0.1 \ --threads 4 \ --n-gpu-layers 20 \ --no-mmap \ --no-mlock \ --verbose-prompt

参数详解：--ctx-size 2048是上下文长度，手机内存有限，别设 4096；--threads 4指定 CPU 线程数，骁龙 8+ 有 8 核，但留 4 核给系统更稳；--n-gpu-layers 20是关键！它把前 20 层 offload 到 GPU（Adreno 740），实测提速 3 倍；--no-mmap和--no-mlock是安卓特供参数，禁用内存映射和锁页，防止 OOM Kill。启动后，访问http://127.0.0.1:8080应返回{ "model": "TinyLlama..." }。最后在 SillyTavern 设置里，Backend URL 填http://127.0.0.1:8080，Model Name 填TinyLlama-1.1B-Chat-v1.0.Q4_K_M.gguf，保存即可。性能实测：Pixel 6a（Snapdragon 7 Gen 1）上，Q4 模型平均 5 token/s；一加 Ace 3（骁龙 8+ Gen 2）上，Q4 模型达 8 token/s，Q5_K_M 模型约 5.5 token/s。> 实操心得：模型文件务必放在~/storage/shared/models/，不要放~/projects/下！因为 llama-server 启动时会读取当前目录，而 Termux 的工作目录切换频繁，路径错位会导致“model not found”。我曾为此调试一小时，最后发现是cd命令少打了一个~。

6. 常见问题与排查技巧实录：从白屏到 502，一份按症状索引的急救手册

部署中最痛苦的不是不会做，而是不知道错在哪。我把过去一年在不同机型上遇到的典型问题，按现象归类，给出可立即执行的排查指令和原理。症状一：浏览器打开 http://127.0.0.1:3000 显示白屏，控制台报错Failed to load resource: net::ERR_CONNECTION_REFUSED。这是最常见问题，90% 是前端服务没起来。执行ps aux | grep serve，若无输出，说明serve进程崩溃。原因通常是dist/目录不存在（构建失败）或端口被占。解决方案：lsof -i :3000查进程，kill -9 PID杀掉；然后cd ~/projects/sillytavern && npm run build重新构建；最后serve -s dist -p 3000 -l tcp://127.0.0.1:3000重启。症状二：SillyTavern 界面能打开，但点击“Send”后无响应，Network 面板显示502 Bad Gateway。这表明前端连上了后端（8000 端口），但后端连不上模型服务（8080 端口）。执行curl -v http://127.0.0.1:8080，若返回Connection refused，说明 llama-server 没运行或端口错。检查ps aux | grep llama-server，若无输出，回到第 5 步重新启动；若有输出，检查netstat -tuln | grep 8080是否监听127.0.0.1:8080，而非:::8080（IPv6 地址，安卓不支持）。症状三：Git clone 时卡在Receiving objects: 12% (12345/123456), 12.34 MiB | 123.00 KiB/s不动。这是 Termux 的 curl 证书问题。执行pkg install ca-certificates -y && pkg clean，然后curl -I https://github.com测试 HTTPS 是否通。若仍卡，临时换源：termux-change-repo，选清华源或中科大源。症状四：npm install 报错Error: EACCES: permission denied, access '/data/data/com.termux/files/usr/lib/node_modules'。这是 npm 全局路径权限问题。执行npm config delete prefix清除错误配置，然后按第 3 步重新设置$HOME/.local路径。症状五：模型加载后，输入一句话，llama-server 日志显示llama_model_load: error loading model。大概率是模型文件损坏或路径错误。执行ls -la ~/storage/shared/models/确认文件存在且大小正常（Q4 模型应在 0.8~1.2GB）；然后file ~/storage/shared/models/*.gguf确认是 ELF 64-bit LSB pie executable，不是 HTML 文档（常见于浏览器误下载）。症状六：SillyTavern 启动后，手机发热严重，电池 1 小时掉 30%。这是 GPU offload 过度。降低--n-gpu-layers值，从 20 改为 10，或彻底关闭 GPU 加速（删掉--n-gpu-layers参数），改用--threads 6提升 CPU 利用率。骁龙芯片的 GPU 计算功耗远高于 CPU，这是安卓端特有的权衡。以下表格总结高频问题与速查命令：

7. 进阶技巧与长期维护：如何让 SillyTavern 成为你手机里的“数字书房”

部署完成只是起点。真正让它成为生产力工具，需要三类进阶操作：自动化、个性化、可持续。自动化：告别每次手动启动。Termux 的termux-services支持开机自启，但需额外配置。创建~/.termux/boot/sillytavern.sh：

#!/data/data/com.termux/files/usr/bin/sh cd ~/projects/sillytavern sv up sillytavern-backend sleep 2 serve -s dist -p 3000 -l tcp://127.0.0.1:3000 > /dev/null 2>&1 &

然后chmod +x ~/.termux/boot/sillytavern.sh。这样每次 Termux 启动，SillyTavern 就自动就绪。个性化：定制你的酒馆氛围。SillyTavern 支持 CSS 覆盖，编辑dist/index.html，在<head>里插入：

<style> :root { --primary-color: #8b5cf6; --bg-color: #0f172a; } .chat-container { background: linear-gradient(135deg, #1e293b, #0f172a); } </style>

保存后刷新页面，深色主题+紫色高亮就生效了。可持续：模型与前端的平滑升级。不要git pull && npm install全量更新，风险太高。我的做法是：每月初，新建分支git checkout -b update-$(date +%Y%m)，git fetch origin && git merge origin/v1.12.x（只合入稳定分支），npm run build后对比dist/文件哈希sha256sum dist/main.js，若与上次相同，说明无实质变更，跳过；若有变，再测试功能。模型升级更简单：下载新.gguf到shared/models/，修改llama-server启动命令中的--model参数，kill -9旧进程，启动新进程即可。最后分享一个真实场景：我在地铁上用 SillyTavern + TinyLlama 写短篇小说，角色卡预设了“冷峻侦探”人格，世界书导入了《福尔摩斯探案集》语料。没有网络，没有云同步，所有生成内容只存在手机/storage/emulated/0/Android/data/com.termux/files/home/storage/shared/sillytavern/下。下车时，导出 JSON 对话记录，用adb pull备份到电脑。这种掌控感，是任何 SaaS 化 AI 工具给不了的。它不是一个“部署教程”，而是一套可生长的、属于你自己的移动 AI 基础设施。