使用 Termux 部署 AstrBot

WARNING

本教程所使用的方法仅可在安卓机上使用，苹果设备并没有真正意义的Termux

TIP

本教程中若未说明，Do you want to continue?[Y/n](或类似)一律填Y或y

准备步骤

Bash 基础

进入目录

cd /path/to/dir

列举目录

ls

删除文件或目录

rm -r /path/to/dir/or/file

运行 .sh (Shell) 文件

bash xxx.sh

安装 Termux

在Termux 官网 可选择在GitHub或F-Droid下载Termux

换源 (可选)

TIP

建议更换源以获得更好的安装体验 但此换源并不会使git clone变得更快

termux-change-repo

选择第一个Mirror group Rotate between several mirrors

随后选择第三个Mirrors in Chinese Mainland All in Chinese Mainland等待跑完即可

正式部署

安装 proot-distro 及 其他必须组件

首先安装uv、git和proot-distro

pkg install uv git proot-distro

使用 proot-distro 安装 ubuntu环境

TIP

中国大陆概率访问GitHub，故建议使用加速器或代理

proot-distro install ubuntu

登录 Ubuntu环境

下载及配置完成会有提示Log in with: proot-distro login ubuntu,输入相同的即可登入

即：

proot-distro login ubuntu

此时便进入了Ubuntu环境，我们需使用apt命令安装软件包了

添加第三方PPA

TIP

Python 3.10并不在官方的软件源中，而uv所要求的Python版本为3.10 ，所以进行此步为必须

使用apt安装software-properties-common (添加PPA前置)

apt update && apt install software-properties-common

添加deadsnakesPPA(Python官方维护)

add-apt-repository ppa:deadsnakes/ppa && apt update

添加时你可能会看到:Press [ENTER] to continue or Ctrl-c to cancel. ，此时按下回车(换行)即可

安装 Python

在进行完以上步骤后，即可安装Python 3.10

apt install python3.10

克隆 AstrBot 仓库

直到这里，您所处的路径应为 ~# 而不是其他次级目录，以防找不到项目目录

git clone https://github.com/AstrBotDevs/AstrBot.git && cd AstrBot

如果一切顺利的话，您应该进入到了 ~/AstrBot# 下，可以进入到下一步了

NOTE

如果 git clone 失败，那么其后的 cd 命令也不会生效，故在运行命令时请注意路径是否正确

如果需要再次执行如上命令，建议先执行

rm -r AstrBot

之后再运行上述命令

运行 AstrBot

uv run main.py

TIP

如果使用 uv 下载软件包时速度慢，可以更换源 (以 清华源 为例)

export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"

报错解决方案

如果出现了 `[WARN] uv sync 失败，重试 2/3 × Failed to build astrbot @ file:///root/ ├─▶ Failed to install requirements from build-system.requires ├─▶ Failed to install build dependencies ├─▶ Failed to install: trove_classifiers-2025.9.11.17-py3-none-any.whl │ (trove-classifiers==2025.9.11.17) ╰─▶ failed to hardlink file from /root/.cache/uv/archive-v0/10gPuxc61Audvy1Eg6SFz/trove_classifiers/.l2s.init.py0001 to /root/.cache/uv/builds-v0/.tmp2lFVJx/lib/python3.10/site-packages/trove_classifiers/.l2s.init.py0001: Operation not permitted (os error 1)

可以先运行以下命令，然后再重新启动

echo 'export UV_LINK_MODE=copy' >> ~/.bashrc

source ~/.bashrc

🎉 大功告成

如果没有报错，那么你可以看到uv在安装所需的包后出现类似 WebUI 已启动，可访问 并附带了几条链接。

如果有，那么恭喜你，你已经部署好了AstrBot并且运行了

接下来你可以尝试访问localhost:6185验证可用性

TIP

Termux与主机共享一个网络，即：Termux的IP地址就是主机的IP地址，你也可使用ifconfig查看主机IP地址

默认用户名和密码是 astrbot 和 astrbot。

后记

退出

如需退出proot-distro，可以使用

exit

重新启动

每次重新进入Termux时需重新打开 proot 环境并启动 AstrBot

可以使用命令如下：

proot-distro login ubuntu
cd AstrBot && uv run main.py

挂后台

开启

如需在一个session里面同时运行多个进程(eg. AstrBot 和 Napcat)，可以使用

uv run main.py &
......

关闭

上文运行后会有类似[1] 1145的输出，如需关闭进程，则可使用

kill -9 1145

或

pkill -9  -f "uv run main.py"

TIP

也可以使用screen命令，较&更易操控

apt install screen         #安装screen
screen -S <name>           #创建新的会话
screen -r <name>           #重新连接会话
screen -ls                 #列举会话
screen -X -S <name> quit   #关闭会话
Ctrl + a + d               #退出当前窗口

WARNING

在退出时，请注意保存自己的任务，以防数据丢失

后台存活

如需让服务端在后台存活，可以在设置->应用和服务->应用启动管理->Termux改为手动管理并允许后台活动(或类似选项)

接下来，你需要部署任何一个消息平台，才能够实现在消息平台上使用 AstrBot。

Termux 部署报错解决方案

如果出现了 `[WARN] uv sync 失败，重试 2/3

× Failed to build astrbot @ file:///root/
├─▶ Failed to install requirements from build-system.requires
├─▶ Failed to install build dependencies
├─▶ Failed to install: trove_classifiers-2025.9.11.17-py3-none-any.whl
│   (trove-classifiers==2025.9.11.17)
╰─▶ failed to hardlink file from
    /root/.cache/uv/archive-v0/10gPuxc61Audvy1Eg6SFz/trove_classifiers/.l2s.__init__.py0001
    to
    /root/.cache/uv/builds-v0/.tmp2lFVJx/lib/python3.10/site-packages/trove_classifiers/.l2s.__init__.py0001:
    Operation not permitted (os error 1)

可以先运行以下命令，然后再重新启动

echo 'export UV_LINK_MODE=copy' >> ~/.bashrc 
source ~/.bashrc