From 24dd21fd4421cdd4498653434f055b4533cb592c Mon Sep 17 00:00:00 2001 From: xiewoc <70128845+xiewoc@users.noreply.github.com> Date: Sat, 21 Feb 2026 18:25:53 +0800 Subject: [PATCH 1/4] =?UTF-8?q?=E8=A7=84=E6=95=B4=E4=BA=86=E4=B8=80?= =?UTF-8?q?=E4=B8=8B=EF=BC=8C=E5=B9=B6=E4=B8=8D=E5=AE=8C=E5=85=A8=E5=A4=84?= =?UTF-8?q?=E7=90=86=E4=BA=86=E6=96=B0=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- zh/deploy/astrbot/termux.md | 571 ++++++++++++++++++------------------ 1 file changed, 292 insertions(+), 279 deletions(-) diff --git a/zh/deploy/astrbot/termux.md b/zh/deploy/astrbot/termux.md index 1317fc96..1023fc8a 100644 --- a/zh/deploy/astrbot/termux.md +++ b/zh/deploy/astrbot/termux.md @@ -1,279 +1,292 @@ -# 使用 Termux 部署 AstrBot - -> [!WARNING] -> 本教程所使用的方法仅可在安卓机上使用，苹果设备并没有真正意义的`Termux` - ->[!TIP] ->本教程中若未说明，`Do you want to continue?[Y/n]`(或类似)一律填`Y`或`y` -> -# 准备步骤 - -## Bash 基础 - -### 进入目录 - -```bash -cd /path/to/dir -``` - -### 列举目录 - -```bash -ls -``` - -### 删除文件或目录 - -```bash -rm -r /path/to/dir/or/file -``` - -### 运行 `.sh` (`Shell`) 文件 - -```bash -bash xxx.sh -``` - -## 安装 `Termux` - -在[Termux 官网](https://termux.dev/cn) 可选择在[GitHub](https://github.com/termux/termux-app/releases)或[F-Droid](https://f-droid.org/en/packages/com.termux/)下载Termux - -## 换源 (可选) - ->[!TIP] ->建议更换源以获得更好的安装体验 ->但此换源并不会使`git clone`变得更快 - -```bash -termux-change-repo -``` - -选择第一个`Mirror group Rotate between several mirrors` - -随后选择第三个`Mirrors in Chinese Mainland All in Chinese Mainland`等待跑完即可 - -# 正式部署 - -## 安装 `proot-distro` 及 其他必须组件 - -首先安装`uv`、`git`和`proot-distro` - -```bash -pkg install uv git proot-distro -``` - -### 使用 `proot-distro` 安装 `ubuntu环境` - ->[!TIP] ->中国大陆概率访问`GitHub`，故建议使用加速器或代理 - -```bash -proot-distro install ubuntu -``` - -### 登录 `Ubuntu环境` - -下载及配置完成会有提示`Log in with: proot-distro login ubuntu`,输入相同的即可登入 - -即： - -```bash -proot-distro login ubuntu -``` - -此时便进入了`Ubuntu环境`，我们需使用`apt`命令安装软件包了 - -## 添加第三方PPA - ->[!TIP] ->`Python 3.10`并不在官方的软件源中，而`uv`所要求的Python版本为3.10 ，所以进行此步为必须 - -### 使用`apt`安装`software-properties-common` (添加PPA前置) - - - - - -```bash -apt update && apt install software-properties-common -``` - -### 添加`deadsnakes`PPA(Python官方维护) - -```bash -add-apt-repository ppa:deadsnakes/ppa && apt update -``` - -添加时你可能会看到:`Press [ENTER] to continue or Ctrl-c to cancel.` ，此时按下回车(换行)即可 - -## 安装 `Python` - -在进行完以上步骤后，即可安装`Python 3.10` - -```bash -apt install python3.10 -``` - -## 克隆 `AstrBot` 仓库 - -直到这里，您所处的路径应为 `~#` 而不是其他次级目录，以防找不到项目目录 - -```bash -git clone https://github.com/AstrBotDevs/AstrBot.git && cd AstrBot -``` - -如果一切顺利的话，您应该进入到了 `~/AstrBot#` 下，可以进入到下一步了 - ->[!NOTE] ->如果 `git clone` 失败，那么其后的 `cd` 命令也不会生效，故在运行命令时请注意路径是否正确 -> ->如果需要再次执行如上命令，建议先执行 -> ->```bash ->rm -r AstrBot ->``` -> ->之后再运行上述命令 - -## 运行 `AstrBot` - -```bash -uv run main.py -``` - ->[!TIP] ->如果使用 `uv` 下载软件包时速度慢，可以更换源 (以 `清华源` 为例) -> ->```bash ->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) - -可以先运行以下命令，然后再重新启动 - ->```bash ->echo 'export UV_LINK_MODE=copy' >> ~/.bashrc ->``` -> ->```bash ->source ~/.bashrc ->``` - -## 🎉 大功告成 - -如果没有报错，那么你可以看到`uv`在安装所需的包后出现类似 `WebUI 已启动，可访问` 并附带了几条链接。 - -如果有，那么恭喜你，你已经部署好了`AstrBot`并且运行了 - -接下来你可以尝试访问[localhost:6185](http://localhost:6185)验证可用性 - ->[!TIP] ->`Termux`与主机共享一个网络，即：`Termux`的IP地址就是主机的IP地址，你也可使用`ifconfig`查看主机IP地址 -> -> 默认用户名和密码是 `astrbot` 和 `astrbot`。 - -# 后记 - -## 退出 - -如需退出`proot-distro`，可以使用 - -```bash -exit -``` - -## 重新启动 - -每次重新进入`Termux`时需重新打开 `proot` 环境并启动 `AstrBot` - -可以使用命令如下： - -```bash -proot-distro login ubuntu -cd AstrBot && uv run main.py -``` - -## 挂后台 - -### 开启 - -如需在一个session里面同时运行多个进程(eg. `AstrBot` 和 `Napcat`)，可以使用 - -```bash -uv run main.py & -...... -``` - -### 关闭 - -上文运行后会有类似`[1] 1145`的输出，如需关闭进程，则可使用 - -```bash -kill -9 1145 -``` - -或 - -```bash -pkill -9 -f "uv run main.py" -``` - - - ->[!TIP] ->也可以使用`screen`命令，较`&`更易操控 -> ->```bash ->apt install screen #安装screen ->screen -S #创建新的会话 ->screen -r #重新连接会话 ->screen -ls #列举会话 ->screen -X -S quit #关闭会话 ->Ctrl + a + d #退出当前窗口 ->``` - ->[!WARNING] -> 在退出时，请注意保存自己的任务，以防数据丢失 - -## 后台存活 - -如需让服务端在后台存活，可以在`设置`->`应用和服务`->`应用启动管理`->`Termux`改为`手动管理`并`允许后台活动`(或类似选项) - -接下来，你需要部署任何一个消息平台，才能够实现在消息平台上使用 AstrBot。 - -## Termux 部署报错解决方案 - -如果出现了 `[WARN] uv sync 失败，重试 2/3 - -```bash -× 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) -``` - -可以先运行以下命令，然后再重新启动 - -```bash -echo 'export UV_LINK_MODE=copy' >> ~/.bashrc -source ~/.bashrc -``` +# 使用 Termux 部署 AstrBot + +> [!WARNING] +> 本教程所使用的方法仅可在安卓机上使用，苹果设备并没有真正意义的`Termux` + +>[!TIP] +>本教程中若未说明，`Do you want to continue?[Y/n]`(或类似)一律填`Y`或`y` +> + +# 准备步骤 + +
+Bash 基础 + +### 进入目录 + +```bash +cd /path/to/dir +cd ../ # 返回上级目录 +``` + +### 列举目录 + +```bash +ls +``` + +### 删除文件或目录 + +```bash +rm -r /path/to/dir/or/file # 此处可以加 -f 强制删除 +``` + +### 运行 `.sh` (`Shell`) 文件 + +```bash +bash xxx.sh +``` +
+ +## 安装 `Termux` + +在 [Termux 官网](https://termux.dev/cn) 可选择在 [GitHub](https://github.com/termux/termux-app/releases) 或 [F-Droid](https://f-droid.org/en/packages/com.termux/) 下载Termux + +## 换源 (可选) + +>[!TIP] +>建议更换源以获得更好的安装体验 +>但此换源并不会使`git clone`变得更快 + +```bash +termux-change-repo +``` + +选择第一个`Mirror group Rotate between several mirrors` + +随后选择第三个`Mirrors in Chinese Mainland All in Chinese Mainland`等待跑完即可 + +# 正式部署 + +## 安装 `proot-distro` 及 其他必须组件 + +首先安装`uv`、`git`和`proot-distro` + +```bash +pkg install uv git proot-distro +``` + +### 使用 `proot-distro` 安装 `ubuntu环境` + +>[!TIP] +>中国大陆概率访问`GitHub`，故建议使用加速器或代理 + +```bash +proot-distro install ubuntu +``` + +### 登录 `Ubuntu环境` + +下载及配置完成会有提示`Log in with: proot-distro login ubuntu`,输入相同的即可登入 + +即： + +```bash +proot-distro login ubuntu +``` + +此时便进入了`Ubuntu环境`，我们需使用`apt`命令安装软件包了 + +## 添加第三方PPA + +>[!TIP] +>`Python 3.10`并不在官方的软件源中，而`uv`所要求的Python版本为3.10 ，所以进行此步为必须 + +### 使用`apt`安装`software-properties-common` (添加PPA前置) + + + + + +```bash +apt update && apt install software-properties-common +``` + +
+报错了？ + +如果有类似以下的报错： + +`Error: The repository 'https://ppa.launchpadcontent.net/deadsnakes/ppa/ubuntu questing Release' does not have a Release file.` +说明你使用的是新版本的Ubuntu，目前PPA还未支持，请降级后重试 + +
+ +### 添加 `deadsnakes` PPA + +```bash +add-apt-repository ppa:deadsnakes/ppa && apt update +``` + +添加时你可能会看到:`Press [ENTER] to continue or Ctrl-C to cancel.` ，此时按下回车(换行)即可 + +## 安装 `Python` + +在进行完以上步骤后，即可安装`Python 3.10` + +```bash +apt install python3.10 +``` + +## 克隆 `AstrBot` 仓库 + +直到这里，您所处的路径应为 `~#` 而不是其他次级目录，以防找不到项目目录 + +```bash +git clone https://github.com/AstrBotDevs/AstrBot.git && cd AstrBot +``` +
+下载出现了问题？ + +>[!TIP] +>此处建议使用 `gh-proxy` 作为加速站, 即： +>```bash +>git clone https://gh-proxy.org/https://github.com/AstrBotDevs/AstrBot.git +>``` +>或 +>```bash +>git clone https://hk.gh-proxy.org/https://github.com/AstrBotDevs/AstrBot.git +>``` +>具体视情况而定 + +>[!NOTE] +>如果 `git clone` 失败，那么其后的 `cd` 命令也不会生效，故在运行命令时请注意路径是否正确 +> +>如果需要再次执行如上命令，建议先执行 +> +>```bash +>rm -r AstrBot +>``` +> +>之后再运行上述命令 +
+
+ +如果一切顺利的话，您应该进入到了 `~/AstrBot#` 下，可以进入到下一步了 + +## 运行 `AstrBot` + +```bash +uv sync +uv run main.py +``` +或者 +```bash +uv sync +uv run --no-sync main.py # 防止uv自动同步库使插件不可用 +``` + +>[!TIP] +>如果使用 `uv` 下载软件包时速度慢，可以更换源 (以 `清华源` 为例) +> +>```bash +>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)``` + +可以先运行以下命令，然后再重新启动 + +>```bash +>echo 'export UV_LINK_MODE=copy' >> ~/.bashrc +>``` +> +>```bash +>source ~/.bashrc +>``` + +## 🎉 大功告成 + +如果没有报错，那么你可以看到`uv`在安装所需的包后出现类似 `WebUI 已启动，可访问` 并附带了几条链接。 + +如果有，那么恭喜你，你已经部署好了`AstrBot`并且运行了 + +你可以尝试访问[localhost:6185](http://localhost:6185)验证可用性 + +接下来，你需要部署任何一个消息平台，才能够实现在消息平台上使用 AstrBot。 + +>[!TIP] +>`Termux`与主机共享一个网络，即：`Termux`的IP地址就是主机的IP地址，你也可使用`ifconfig`查看主机IP地址 +> +> 默认用户名和密码是 `astrbot` 和 `astrbot`。 + +# 后记 + +## 退出 + +如需退出`proot-distro`，可以使用 + +```bash +exit +``` + +## 重新启动 + +每次重新进入`Termux`时需重新打开 `proot` 环境并启动 `AstrBot` + +可以使用命令如下： + +```bash +proot-distro login ubuntu +cd AstrBot && uv run main.py +``` + +## 挂后台 + +### 开启 + +如需在一个session里面同时运行多个进程(eg. `AstrBot` 和 `Napcat`)，可以使用 + +```bash +uv run main.py & +...... +``` + +### 关闭 + +上文运行后会有类似`[1] 1145`的输出，如需关闭进程，则可使用 + +```bash +kill -9 1145 +``` + +或 + +```bash +pkill -9 -f "uv run main.py" +``` + + + +>[!TIP] +>但建议使用`screen`命令，较`&`更易操控 +> +>```bash +>apt install screen #安装screen +>screen -S #创建新的会话 +>screen -r #重新连接会话 +>screen -ls #列举会话 +>screen -X -S quit #关闭会话 +>Ctrl + a + d #退出当前窗口 +>``` + +>[!WARNING] +> 在退出时，请注意保存自己的任务，以防数据丢失 + +## 后台存活 + +如需让服务端在后台存活，可以在`设置`->`应用和服务`->`应用启动管理`->`Termux`改为`手动管理`并`允许后台活动`(或类似选项) From 7206e54e25fc3ab5b67fc858b33dd9acfdb34a76 Mon Sep 17 00:00:00 2001 From: xiewoc <70128845+xiewoc@users.noreply.github.com> Date: Sat, 21 Feb 2026 18:31:07 +0800 Subject: [PATCH 2/4] =?UTF-8?q?=E4=B9=9F=E6=9B=B4=E6=96=B0=E4=BA=86en?= =?UTF-8?q?=E7=89=88=EF=BC=8C=E5=88=A0=E5=8E=BB=E4=BA=86=E5=86=87=E5=BF=85?= =?UTF-8?q?=E8=A6=81=E7=9A=84=E6=8D=A2=E6=BA=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- en/deploy/astrbot/termux.md | 539 +++++++++++++++++------------------- 1 file changed, 260 insertions(+), 279 deletions(-) diff --git a/en/deploy/astrbot/termux.md b/en/deploy/astrbot/termux.md index b618b600..47f9faeb 100644 --- a/en/deploy/astrbot/termux.md +++ b/en/deploy/astrbot/termux.md @@ -1,279 +1,260 @@ -# Deploying AstrBot using Termux - -> [!WARNING] -> The method used in this tutorial is only applicable to Android devices. There is no real `Termux` on Apple devices. - ->[!TIP] ->In this tutorial, unless otherwise specified, always enter `Y` or `y` for prompts like `Do you want to continue?[Y/n]` (or similar). - -# Preparation Steps - -## Bash Basics - -### Enter a Directory - -```bash -cd /path/to/dir -``` - -### List Directory Contents - -```bash -ls -``` - -### Delete a File or Directory - -```bash -rm -r /path/to/dir/or/file -``` - -### Run a `.sh` (`Shell`) File - -```bash -bash xxx.sh -``` - -## Install `Termux` - -On the [Termux Official Website](https://termux.dev/en), you can choose to download Termux from [GitHub](https://github.com/termux/termux-app/releases) or [F-Droid](https://f-droid.org/en/packages/com.termux/). - -## Change Repository (Optional) - ->[!TIP] ->It is recommended to change the repository for a better installation experience. ->However, changing the repository will not make `git clone` faster. - -```bash -termux-change-repo -``` - -Select the first option `Mirror group Rotate between several mirrors`. - -Then select the third option `Mirrors in Chinese Mainland All in Chinese Mainland` and wait for it to complete. - -# Official Deployment - -## Install `proot-distro` and Other Required Components - -First, install `uv`, `git`, and `proot-distro`. - -```bash -pkg install uv git proot-distro -``` - -### Install `Ubuntu Environment` using `proot-distro` - ->[!TIP] ->Accessing `GitHub` from mainland China can be unstable, so using a booster or proxy is recommended. - -```bash -proot-distro install ubuntu -``` - -### Log in to the `Ubuntu Environment` - -After downloading and configuration are complete, you will see a prompt `Log in with: proot-distro login ubuntu`. Enter it to log in. - -Specifically: - -```bash -proot-distro login ubuntu -``` - -Now you are in the `Ubuntu Environment`, and you need to use `apt` commands to install packages. - -## Add Third-Party PPA - ->[!TIP] ->`Python 3.10` is not in the official software sources, and the Python version required by `uv` is 3.10. Therefore, this step is necessary. - -### Install `software-properties-common` using `apt` (Prerequisite for adding PPA) - - - - - -```bash -apt update && apt install software-properties-common -``` - -### Add `deadsnakes` PPA (Maintained by the Python Community) - -```bash -add-apt-repository ppa:deadsnakes/ppa && apt update -``` - -When adding, you may see: `Press [ENTER] to continue or Ctrl-c to cancel.`. Press Enter at this point. - -## Install `Python` - -After completing the above steps, you can install `Python 3.10`. - -```bash -apt install python3.10 -``` - -## Clone the `AstrBot` Repository - -At this point, your path should be `~#` and not any other subdirectory, to ensure the project directory can be found easily. - -```bash -git clone https://github.com/AstrBotDevs/AstrBot.git && cd AstrBot -``` - -If everything goes well, you should be in `~/AstrBot#`, and you can proceed to the next step. - ->[!NOTE] ->If `git clone` fails, the subsequent `cd` command will not work. Please pay attention to whether the path is correct when running commands. -> ->If you need to run the above command again, it is recommended to first run: -> ->```bash ->rm -r AstrBot ->``` -> ->Then run the command again. - -## Run `AstrBot` - -```bash -uv run main.py -``` - ->[!TIP] ->If downloading packages with `uv` is slow, you can change the source (using `Tsinghua Mirror` as an example): -> ->```bash ->export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple" ->``` - -## Error Solutions - -> If you encounter: `[WARN] uv sync failed, retrying 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) - -You can run the following commands first, and then restart: - ->```bash ->echo 'export UV_LINK_MODE=copy' >> ~/.bashrc ->``` -> ->```bash ->source ~/.bashrc ->``` - -## 🎉 Mission Accomplished - -If there are no errors, you will see `uv` installing required packages, followed by a message like `WebUI started, accessible at` with several links. - -If you see this, congratulations! You have successfully deployed and run `AstrBot`. - -Next, you can try accessing [localhost:6185](http://localhost:6185) to verify its availability. - ->[!TIP] ->`Termux` shares the same network with the host device. That is, the IP address of `Termux` is the IP address of the host. You can also use `ifconfig` to check the host IP. -> -> The default username and password are `astrbot` and `astrbot`. - -# Afterword - -## Exit - -To exit the `proot-distro` environment, use: - -```bash -exit -``` - -## Restart - -Every time you re-enter `Termux`, you need to reopen the `proot` environment and start `AstrBot`. - -You can use the following commands: - -```bash -proot-distro login ubuntu -cd AstrBot && uv run main.py -``` - -## Run in Background - -### Start - -If you need to run multiple processes (e.g., `AstrBot` and `Napcat`) in one session, you can use: - -```bash -uv run main.py & -...... -``` - -### Stop - -After running the above, you will see an output like `[1] 1145`. To stop the process, use: - -```bash -kill -9 1145 -``` - -Or: - -```bash -pkill -9 -f "uv run main.py" -``` - - - ->[!TIP] ->You can also use the `screen` command, which is easier to control than `&`. -> ->```bash ->apt install screen # Install screen ->screen -S # Create a new session ->screen -r # Reconnect to a session ->screen -ls # List sessions ->screen -X -S quit # Close a session ->Ctrl + a + d # Detach from current window ->``` - ->[!WARNING] -> When exiting, please make sure to save your tasks to prevent data loss. - -## Keeping Alive in Background - -To keep the server alive in the background, you can change `Termux` to `Manual Management` in `Settings` -> `Apps & Services` -> `App Launch Management` -> `Termux`, and enable `Allow Background Activity` (or similar options). - -Next, you need to deploy any messaging platform to be able to use AstrBot on that platform. - -## Termux Deployment Error Solution - -If you see `[WARN] uv sync failed, retrying 2/3`: - -```bash -× 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) -``` - -Run the following commands first, and then restart: - -```bash -echo 'export UV_LINK_MODE=copy' >> ~/.bashrc -source ~/.bashrc -``` +# Deploy AstrBot Using Termux + +> [!WARNING] +> The methods described in this tutorial are only applicable to Android devices. Apple devices do not have a true `Termux`. + +> [!TIP] +> In this tutorial, unless otherwise specified, always answer `Y` or `y` to prompts like `Do you want to continue? [Y/n]` (or similar). + +# Preparation Steps + +
+Bash Basics + +### Change Directory + +```bash +cd /path/to/dir +cd ../ # Go back to the parent directory +``` + +### List Directory Contents + +```bash +ls +``` + +### Delete Files or Directories + +```bash +rm -r /path/to/dir/or/file # Add `-f` to force delete +``` + +### Run a `.sh` (`Shell`) File + +```bash +bash xxx.sh +``` +
+ +## Installing `Termux` + +You can download Termux from the [official website](https://termux.dev/en) via [GitHub](https://github.com/termux/termux-app/releases) or [F-Droid](https://f-droid.org/en/packages/com.termux/). + + + +# Deployment + +## Installing `proot-distro` and Other Necessary Components + +First, install `uv`, `git`, and `proot-distro`. + +```bash +pkg install uv git proot-distro +``` + +### Installing an `Ubuntu Environment` Using `proot-distro` + +> [!TIP] +> Accessing GitHub from Mainland China can be unreliable; using a proxy or accelerator is recommended. + +```bash +proot-distro install ubuntu +``` + +### Logging into the `Ubuntu Environment` + +After the download and configuration are complete, you will see a prompt: `Log in with: proot-distro login ubuntu`. Enter that command to log in. + +i.e.: + +```bash +proot-distro login ubuntu +``` + +You are now inside the `Ubuntu environment`. Here, you will use the `apt` command to install packages. + +## Adding a Third-Party PPA + +> [!TIP] +> `Python 3.10` is not available in the official Ubuntu repositories. Since `uv` requires Python 3.10, this step is mandatory. + +### Install `software-properties-common` (Prerequisite for adding PPAs) using `apt` + +```bash +apt update && apt install software-properties-common +``` + +
+Encountered an error? + +If you see an error like: + +`Error: The repository 'https://ppa.launchpadcontent.net/deadsnakes/ppa/ubuntu questing Release' does not have a Release file.` +It means you are using a newer version of Ubuntu that this PPA doesn't yet support. Please downgrade your Ubuntu environment and try again. + +
+ +### Adding the `deadsnakes` PPA + +```bash +add-apt-repository ppa:deadsnakes/ppa && apt update +``` + +When prompted, you might see: `Press [ENTER] to continue or Ctrl-C to cancel.` Press the Enter key at this point. + +## Installing `Python` + +After completing the steps above, you can install `Python 3.10`. + +```bash +apt install python3.10 +``` + +## Cloning the `AstrBot` Repository + +Ensure your current path is `~#` (the root of the Ubuntu environment) and not a subdirectory, to easily locate the project directory. + +```bash +git clone https://github.com/AstrBotDevs/AstrBot.git && cd AstrBot +``` +
+Having trouble downloading? + +> [!NOTE] +> If `git clone` fails, the subsequent `cd` command will not execute successfully. Pay attention to your current path when running commands. +> +> If you need to run the clone command again, it's recommended to first run: +> +> ```bash +> rm -r AstrBot +> ``` +> +> Then execute the `git clone` command again. +
+
+ +If everything went smoothly, you should now be in the `~/AstrBot#` directory and ready for the next step. + +## Running `AstrBot` + +```bash +uv sync +uv run main.py +``` +Or +```bash +uv sync +uv run --no-sync main.py # Prevents uv from automatically syncing libraries, which might break plugins +``` + +> [!TIP] +> If downloading packages with `uv` is slow, you can change the mirror source + +## Troubleshooting + +>If you encounter an error like: +>``` +>[WARN] uv sync failed, retry: 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)``` + +You can try running the following commands first, then restart AstrBot: + +>```bash +>echo 'export UV_LINK_MODE=copy' >> ~/.bashrc +>``` +> +>```bash +>source ~/.bashrc +>``` + +## 🎉 Success! + +If there are no errors, after `uv` installs the necessary packages, you should see output similar to `WebUI started, accessible at` followed by a few links. + +If you see that, congratulations! You have successfully deployed and run `AstrBot`. + +You can try accessing [http://localhost:6185](http://localhost:6185) to verify it's working. + +Next, you will need to deploy a messaging platform to actually use AstrBot within it. + +> [!TIP] +> `Termux` shares the network with the host device. This means `Termux`'s IP address is the same as your device's IP. You can use the `ifconfig` command within the Ubuntu environment to check the host's IP address. +> +> The default username and password for the WebUI are `astrbot` and `astrbot`. + +# Afterword + +## Exiting + +To exit the `proot-distro` environment, use: + +```bash +exit +``` + +## Restarting + +Each time you reopen `Termux`, you need to restart the `proot` environment and launch `AstrBot`. + +You can use the following commands: + +```bash +proot-distro login ubuntu +cd AstrBot && uv run main.py +``` + +## Running in the Background + +### Starting + +To run multiple processes (e.g., `AstrBot` and `Napcat`) within one session, you can use: + +```bash +uv run main.py & +...... +``` + +### Stopping + +Running a command with `&` will output something like `[1] 1145`. To stop the process, you can use: + +```bash +kill -9 1145 +``` + +or + +```bash +pkill -9 -f "uv run main.py" +``` + + + +> [!TIP] +> Using the `screen` command is recommended over `&` as it's easier to manage. +> +> ```bash +> apt install screen # Install screen +> screen -S # Create a new session +> screen -r # Reattach to a session +> screen -ls # List sessions +> screen -X -S quit # Close a session +> Ctrl + a + d # Detach from the current window +> ``` + +>[!WARNING] +> Remember to save your work properly before exiting to prevent data loss. + +## Keeping the Process Alive in the Background + +To allow the server to run persistently in the background, you may need to adjust your device's battery optimization settings. Go to `Settings` -> `Apps` -> `App Management` -> `Termux`, change its startup management to `Manual` and ensure `Allow background activity` (or similar options) is enabled. \ No newline at end of file From 3a1b36e2ece9a07be31ab14604daedccca617d04 Mon Sep 17 00:00:00 2001 From: xiewoc <70128845+xiewoc@users.noreply.github.com> Date: Sat, 21 Feb 2026 18:39:17 +0800 Subject: [PATCH 3/4] Add files via upload --- zh/deploy/termux.md | 292 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 zh/deploy/termux.md diff --git a/zh/deploy/termux.md b/zh/deploy/termux.md new file mode 100644 index 00000000..26fd4269 --- /dev/null +++ b/zh/deploy/termux.md @@ -0,0 +1,292 @@ +# 使用 Termux 部署 AstrBot + +> [!WARNING] +> 本教程所使用的方法仅可在安卓机上使用，苹果设备并没有真正意义的`Termux` + +>[!TIP] +>本教程中若未说明，`Do you want to continue?[Y/n]`(或类似)一律填`Y`或`y` +> + +# 准备步骤 + +
+Bash 基础 + +### 进入目录 + +```bash +cd /path/to/dir +cd ../ # 返回上级目录 +``` + +### 列举目录 + +```bash +ls +``` + +### 删除文件或目录 + +```bash +rm -r /path/to/dir/or/file # 此处可以加 -f 强制删除 +``` + +### 运行 `.sh` (`Shell`) 文件 + +```bash +bash xxx.sh +``` +
+ +## 安装 `Termux` + +在 [Termux 官网](https://termux.dev/cn) 可选择在 [GitHub](https://github.com/termux/termux-app/releases) 或 [F-Droid](https://f-droid.org/en/packages/com.termux/) 下载Termux + +## 换源 (可选) + +>[!TIP] +>建议更换源以获得更好的安装体验 +>但此换源并不会使`git clone`变得更快 + +```bash +termux-change-repo +``` + +选择第一个`Mirror group Rotate between several mirrors` + +随后选择第三个`Mirrors in Chinese Mainland All in Chinese Mainland`等待跑完即可 + +# 正式部署 + +## 安装 `proot-distro` 及 其他必须组件 + +首先安装`uv`、`git`和`proot-distro` + +```bash +pkg install uv git proot-distro +``` + +### 使用 `proot-distro` 安装 `ubuntu环境` + +>[!TIP] +>中国大陆概率访问`GitHub`，故建议使用加速器或代理 + +```bash +proot-distro install ubuntu +``` + +### 登录 `Ubuntu环境` + +下载及配置完成会有提示`Log in with: proot-distro login ubuntu`,输入相同的即可登入 + +即： + +```bash +proot-distro login ubuntu +``` + +此时便进入了`Ubuntu环境`，我们需使用`apt`命令安装软件包了 + +## 添加第三方PPA + +>[!TIP] +>`Python 3.10`并不在官方的软件源中，而`uv`所要求的Python版本为3.10 ，所以进行此步为必须 + +### 使用`apt`安装`software-properties-common` (添加PPA前置) + + + + + +```bash +apt update && apt install software-properties-common +``` + +
+报错了？ + +如果有类似以下的报错： + +`Error: The repository 'https://ppa.launchpadcontent.net/deadsnakes/ppa/ubuntu questing Release' does not have a Release file.` +说明你使用的是新版本的Ubuntu，目前PPA还未支持，请降级后重试 + +
+ +### 添加 `deadsnakes` PPA + +```bash +add-apt-repository ppa:deadsnakes/ppa && apt update +``` + +添加时你可能会看到:`Press [ENTER] to continue or Ctrl-C to cancel.` ，此时按下回车(换行)即可 + +## 安装 `Python` + +在进行完以上步骤后，即可安装`Python 3.10` + +```bash +apt install python3.10 +``` + +## 克隆 `AstrBot` 仓库 + +直到这里，您所处的路径应为 `~#` 而不是其他次级目录，以防找不到项目目录 + +```bash +git clone https://github.com/AstrBotDevs/AstrBot.git && cd AstrBot +``` +
+下载出现了问题？ + +>[!TIP] +>此处建议使用 `gh-proxy` 作为加速站, 即： +>```bash +>git clone https://gh-proxy.org/https://github.com/AstrBotDevs/AstrBot.git +>``` +>或 +>```bash +>git clone https://hk.gh-proxy.org/https://github.com/AstrBotDevs/AstrBot.git +>``` +>具体视情况而定 + +>[!NOTE] +>如果 `git clone` 失败，那么其后的 `cd` 命令也不会生效，故在运行命令时请注意路径是否正确 +> +>如果需要再次执行如上命令，建议先执行 +> +>```bash +>rm -r AstrBot +>``` +> +>之后再运行上述命令 +
+
+ +如果一切顺利的话，您应该进入到了 `~/AstrBot#` 下，可以进入到下一步了 + +## 运行 `AstrBot` + +```bash +uv sync +uv run main.py +``` +或者 +```bash +uv sync +uv run --no-sync main.py # 防止uv自动同步库使插件不可用 +``` + +>[!TIP] +>如果使用 `uv` 下载软件包时速度慢，可以更换源 (以 `清华源` 为例) +> +>```bash +>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)``` + +可以先运行以下命令，然后再重新启动 + +>```bash +>echo 'export UV_LINK_MODE=copy' >> ~/.bashrc +>``` +> +>```bash +>source ~/.bashrc +>``` + +## 🎉 大功告成 + +如果没有报错，那么你可以看到`uv`在安装所需的包后出现类似 `WebUI 已启动，可访问` 并附带了几条链接。 + +如果有，那么恭喜你，你已经部署好了`AstrBot`并且运行了 + +你可以尝试访问[localhost:6185](http://localhost:6185)验证可用性 + +接下来，你需要部署任何一个消息平台，才能够实现在消息平台上使用 AstrBot。 + +>[!TIP] +>`Termux`与主机共享一个网络，即：`Termux`的IP地址就是主机的IP地址，你也可使用`ifconfig`查看主机IP地址 +> +> 默认用户名和密码是 `astrbot` 和 `astrbot`。 + +# 后记 + +## 退出 + +如需退出`proot-distro`，可以使用 + +```bash +exit +``` + +## 重新启动 + +每次重新进入`Termux`时需重新打开 `proot` 环境并启动 `AstrBot` + +可以使用命令如下（或添加`--no-sync`，按个人需求）： + +```bash +proot-distro login ubuntu +cd AstrBot && uv run main.py +``` + +## 挂后台 + +### 开启 + +如需在一个session里面同时运行多个进程(eg. `AstrBot` 和 `Napcat`)，可以使用 + +```bash +uv run main.py & +...... +``` + +### 关闭 + +上文运行后会有类似`[1] 1145`的输出，如需关闭进程，则可使用 + +```bash +kill -9 1145 +``` + +或 + +```bash +pkill -9 -f "uv run main.py" +``` + + + +>[!TIP] +>但建议使用`screen`命令，较`&`更易操控 +> +>```bash +>apt install screen #安装screen +>screen -S #创建新的会话 +>screen -r #重新连接会话 +>screen -ls #列举会话 +>screen -X -S quit #关闭会话 +>Ctrl + a + d #退出当前窗口 +>``` + +>[!WARNING] +> 在退出时，请注意保存自己的任务，以防数据丢失 + +## 后台存活 + +如需让服务端在后台存活，可以在`设置`->`应用和服务`->`应用启动管理`->`Termux`改为`手动管理`并`允许后台活动`(或类似选项) From 26d825f36b960e9f7a4832150089107a2278735a Mon Sep 17 00:00:00 2001 From: xiewoc <70128845+xiewoc@users.noreply.github.com> Date: Sat, 21 Feb 2026 18:39:39 +0800 Subject: [PATCH 4/4] Add files via upload --- en/deploy/astrbot/termux.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/en/deploy/astrbot/termux.md b/en/deploy/astrbot/termux.md index 47f9faeb..80048a78 100644 --- a/en/deploy/astrbot/termux.md +++ b/en/deploy/astrbot/termux.md @@ -41,7 +41,7 @@ bash xxx.sh You can download Termux from the [official website](https://termux.dev/en) via [GitHub](https://github.com/termux/termux-app/releases) or [F-Droid](https://f-droid.org/en/packages/com.termux/). - + # Deployment @@ -162,9 +162,9 @@ uv run --no-sync main.py # Prevents uv from automatically syncing libraries, whi > ├─▶ 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 +> /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: +> /root/.cache/uv/builds-v0/.tmp2lFVJx/lib/python3.10/site-packages/trove_classifiers/.l2s.__init__.py0001: > Operation not permitted (os error 1)``` You can try running the following commands first, then restart AstrBot: @@ -206,7 +206,7 @@ exit Each time you reopen `Termux`, you need to restart the `proot` environment and launch `AstrBot`. -You can use the following commands: +You can use the following commands(also recommend adding `--no-sync` when using): ```bash proot-distro login ubuntu