Skip to content
This repository was archived by the owner on Mar 11, 2026. It is now read-only.

Commit 23fe37b

Browse files
LIghtJUNctionLIghtJUNction
authored
Merge pull request #123 from AstrBotDevs/feat/translate-docs-v4
docs: translate deployment guides to English based on v4
2 parents 6ada19b + 923a57b commit 23fe37b

4 files changed

Lines changed: 461 additions & 0 deletions

File tree

‎en/deploy/astrbot/community-deployment.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Community-Provided Deployment Methods
2+
3+
> [!WARNING]
4+
> AstrBot official does not guarantee the security and stability of these deployment methods.
5+
6+
# Linux Comprehensive Installation Script
7+
8+
Integrates almost all installation methods found in the documentation.
9+
10+
Also includes many practical Linux tools.
11+
12+
AstrBot is categorized under `Basic Tools / Bot Installation / AstrBot`.
13+
14+
```bash
15+
bash -c "$(curl -L https://gitee.com/nasyt/nasyt-linux-tool/raw/master/nasyt.sh)"
16+
```
17+
18+
## Linux One-Click Deployment Script
19+
20+
Use `curl` to download the script and execute it using `bash`:
21+
22+
```bash
23+
bash <(curl -sSL https://raw.githubusercontent.com/zhende1113/Antlia/refs/heads/main/Script/AstrBot/Antlia.sh)
24+
```
25+
26+
If your system does not have `curl`, you can use `wget`:
27+
28+
```bash
29+
wget -qO- https://raw.githubusercontent.com/zhende1113/Antlia/refs/heads/main/Script/AstrBot/Antlia.sh | bash
30+
```
31+
32+
Repository Address: [zhende1113/Antlia](https://github.com/zhende1113/Antlia/)
33+
34+
## Linux One-Click Deployment Script (Based on Docker)
35+
36+
Supports AstrBot / NapCat.
37+
38+
> [!TIP]
39+
> Use `sudo` for elevated permissions if you have insufficient privileges.
40+
41+
### Using `curl`
42+
43+
```bash
44+
curl -sSL https://raw.githubusercontent.com/railgun19457/AstrbotScript/main/AstrbotScript.sh -o AstrbotScript.sh
45+
chmod +x AstrbotScript.sh
46+
sudo ./AstrbotScript.sh
47+
```
48+
49+
### Using `wget`
50+
51+
```bash
52+
wget -qO AstrbotScript.sh https://raw.githubusercontent.com/railgun19457/AstrbotScript/main/AstrbotScript.sh
53+
chmod +x AstrbotScript.sh
54+
sudo ./AstrbotScript.sh
55+
```
56+
57+
> [!note]
58+
> `sudo ./AstrbotScript.sh --no-color (Optional: disable color output)`
59+
60+
__Repository Address: [railgun19457/AstrbotScript](https://github.com/railgun19457/AstrbotScript)__
61+
62+
## AstrBot Android Deployment
63+
64+
Refer to [zz6zz666/AstrBot-Android-App](https://github.com/zz6zz666/AstrBot-Android-App)

‎en/deploy/astrbot/sys-pm.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Installation via System Package Manager
2+
3+
> [!WARNING]
4+
> Currently, only the AUR version is provided.
5+
> If you are a Windows/macOS user, it is recommended to install via `uv`.
6+
> If you are a Linux user, it is highly recommended to install via a package manager.
7+
8+
# Preparation
9+
10+
## What is AUR?
11+
AUR (Arch User Repository) allows users to install software from community-maintained software repositories. AUR packages are typically maintained by community members rather than official maintainers.
12+
Common AUR helpers include `yay` and `paru`.
13+
The following tutorial uses `paru` as an example; `yay` works similarly, just replace `paru` with `yay`.
14+
15+
# Installation Process
16+
17+
## AUR
18+
```bash
19+
paru -S astrbot-git
20+
# Note:
21+
# The review step will begin; press 'q' to exit review and continue installation.
22+
# After installation, the data directory is fixed at: ~/.local/share/astrbot
23+
```
24+
25+
# Starting
26+
>[!TIP]
27+
> You can directly use `astrbot init` (for the first run) to initialize.
28+
> Use `astrbot run` to run the bot.
29+
> However, it is highly recommended to use `systemctl` for starting, as it provides features like automatic restart and log rotation.
30+
31+
```bash
32+
systemctl --user start astrbot.service
33+
```
34+
35+
# Auto-start on Boot
36+
```bash
37+
# For security reasons, it is designed to run as a user.
38+
systemctl --user enable astrbot.service
39+
# If you need to start it immediately, add --now
40+
# systemctl --user enable --now astrbot.service
41+
```

‎en/deploy/astrbot/termux.md‎

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
# Deploying AstrBot using Termux
2+
3+
> [!WARNING]
4+
> The method used in this tutorial is only applicable to Android devices. There is no real `Termux` on Apple devices.
5+
6+
>[!TIP]
7+
>In this tutorial, unless otherwise specified, always enter `Y` or `y` for prompts like `Do you want to continue?[Y/n]` (or similar).
8+
9+
# Preparation Steps
10+
11+
## Bash Basics
12+
13+
### Enter a Directory
14+
15+
```bash
16+
cd /path/to/dir
17+
```
18+
19+
### List Directory Contents
20+
21+
```bash
22+
ls
23+
```
24+
25+
### Delete a File or Directory
26+
27+
```bash
28+
rm -r /path/to/dir/or/file
29+
```
30+
31+
### Run a `.sh` (`Shell`) File
32+
33+
```bash
34+
bash xxx.sh
35+
```
36+
37+
## Install `Termux`
38+
39+
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/).
40+
41+
## Change Repository (Optional)
42+
43+
>[!TIP]
44+
>It is recommended to change the repository for a better installation experience.
45+
>However, changing the repository will not make `git clone` faster.
46+
47+
```bash
48+
termux-change-repo
49+
```
50+
51+
Select the first option `Mirror group Rotate between several mirrors`.
52+
53+
Then select the third option `Mirrors in Chinese Mainland All in Chinese Mainland` and wait for it to complete.
54+
55+
# Official Deployment
56+
57+
## Install `proot-distro` and Other Required Components
58+
59+
First, install `uv`, `git`, and `proot-distro`.
60+
61+
```bash
62+
pkg install uv git proot-distro
63+
```
64+
65+
### Install `Ubuntu Environment` using `proot-distro`
66+
67+
>[!TIP]
68+
>Accessing `GitHub` from mainland China can be unstable, so using a booster or proxy is recommended.
69+
70+
```bash
71+
proot-distro install ubuntu
72+
```
73+
74+
### Log in to the `Ubuntu Environment`
75+
76+
After downloading and configuration are complete, you will see a prompt `Log in with: proot-distro login ubuntu`. Enter it to log in.
77+
78+
Specifically:
79+
80+
```bash
81+
proot-distro login ubuntu
82+
```
83+
84+
Now you are in the `Ubuntu Environment`, and you need to use `apt` commands to install packages.
85+
86+
## Add Third-Party PPA
87+
88+
>[!TIP]
89+
>`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.
90+
91+
### Install `software-properties-common` using `apt` (Prerequisite for adding PPA)
92+
93+
<!-- This is not run directly in the Termux base environment because it would cause errors. Also, proot-distro is small and has minimal performance loss. -->
94+
95+
<!-- Installing miniconda or anaconda here causes errors for unknown reasons. -->
96+
97+
```bash
98+
apt update && apt install software-properties-common
99+
```
100+
101+
### Add `deadsnakes` PPA (Maintained by the Python Community)
102+
103+
```bash
104+
add-apt-repository ppa:deadsnakes/ppa && apt update
105+
```
106+
107+
When adding, you may see: `Press [ENTER] to continue or Ctrl-c to cancel.`. Press Enter at this point.
108+
109+
## Install `Python`
110+
111+
After completing the above steps, you can install `Python 3.10`.
112+
113+
```bash
114+
apt install python3.10
115+
```
116+
117+
## Clone the `AstrBot` Repository
118+
119+
At this point, your path should be `~#` and not any other subdirectory, to ensure the project directory can be found easily.
120+
121+
```bash
122+
git clone https://github.com/AstrBotDevs/AstrBot.git && cd AstrBot
123+
```
124+
125+
If everything goes well, you should be in `~/AstrBot#`, and you can proceed to the next step.
126+
127+
>[!NOTE]
128+
>If `git clone` fails, the subsequent `cd` command will not work. Please pay attention to whether the path is correct when running commands.
129+
>
130+
>If you need to run the above command again, it is recommended to first run:
131+
>
132+
>```bash
133+
>rm -r AstrBot
134+
>```
135+
>
136+
>Then run the command again.
137+
138+
## Run `AstrBot`
139+
140+
```bash
141+
uv run main.py
142+
```
143+
144+
>[!TIP]
145+
>If downloading packages with `uv` is slow, you can change the source (using `Tsinghua Mirror` as an example):
146+
>
147+
>```bash
148+
>export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"
149+
>```
150+
151+
## Error Solutions
152+
153+
> If you encounter: `[WARN] uv sync failed, retrying 2/3
154+
× Failed to build astrbot @ file:///root/
155+
├─▶ Failed to install requirements from build-system.requires
156+
├─▶ Failed to install build dependencies
157+
├─▶ Failed to install: trove_classifiers-2025.9.11.17-py3-none-any.whl
158+
│ (trove-classifiers==2025.9.11.17)
159+
╰─▶ failed to hardlink file from
160+
/root/.cache/uv/archive-v0/10gPuxc61Audvy1Eg6SFz/trove_classifiers/.l2s.__init__.py0001
161+
to
162+
/root/.cache/uv/builds-v0/.tmp2lFVJx/lib/python3.10/site-packages/trove_classifiers/.l2s.__init__.py0001:
163+
Operation not permitted (os error 1)
164+
165+
You can run the following commands first, and then restart:
166+
167+
>```bash
168+
>echo 'export UV_LINK_MODE=copy' >> ~/.bashrc
169+
>```
170+
>
171+
>```bash
172+
>source ~/.bashrc
173+
>```
174+
175+
## 🎉 Mission Accomplished
176+
177+
If there are no errors, you will see `uv` installing required packages, followed by a message like `WebUI started, accessible at` with several links.
178+
179+
If you see this, congratulations! You have successfully deployed and run `AstrBot`.
180+
181+
Next, you can try accessing [localhost:6185](http://localhost:6185) to verify its availability.
182+
183+
>[!TIP]
184+
>`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.
185+
>
186+
> The default username and password are `astrbot` and `astrbot`.
187+
188+
# Afterword
189+
190+
## Exit
191+
192+
To exit the `proot-distro` environment, use:
193+
194+
```bash
195+
exit
196+
```
197+
198+
## Restart
199+
200+
Every time you re-enter `Termux`, you need to reopen the `proot` environment and start `AstrBot`.
201+
202+
You can use the following commands:
203+
204+
```bash
205+
proot-distro login ubuntu
206+
cd AstrBot && uv run main.py
207+
```
208+
209+
## Run in Background
210+
211+
### Start
212+
213+
If you need to run multiple processes (e.g., `AstrBot` and `Napcat`) in one session, you can use:
214+
215+
```bash
216+
uv run main.py &
217+
......
218+
```
219+
220+
### Stop
221+
222+
After running the above, you will see an output like `[1] 1145`. To stop the process, use:
223+
224+
```bash
225+
kill -9 1145
226+
```
227+
228+
Or:
229+
230+
```bash
231+
pkill -9 -f "uv run main.py"
232+
```
233+
234+
<!--↑ This one is not very reliable -->
235+
236+
>[!TIP]
237+
>You can also use the `screen` command, which is easier to control than `&`.
238+
>
239+
>```bash
240+
>apt install screen # Install screen
241+
>screen -S <name> # Create a new session
242+
>screen -r <name> # Reconnect to a session
243+
>screen -ls # List sessions
244+
>screen -X -S <name> quit # Close a session
245+
>Ctrl + a + d # Detach from current window
246+
>```
247+
248+
>[!WARNING]
249+
> When exiting, please make sure to save your tasks to prevent data loss.
250+
251+
## Keeping Alive in Background
252+
253+
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).
254+
255+
Next, you need to deploy any messaging platform to be able to use AstrBot on that platform.
256+
257+
## Termux Deployment Error Solution
258+
259+
If you see `[WARN] uv sync failed, retrying 2/3`:
260+
261+
```bash
262+
× Failed to build astrbot @ file:///root/
263+
├─▶ Failed to install requirements from build-system.requires
264+
├─▶ Failed to install build dependencies
265+
├─▶ Failed to install: trove_classifiers-2025.9.11.17-py3-none-any.whl
266+
│ (trove-classifiers==2025.9.11.17)
267+
╰─▶ failed to hardlink file from
268+
/root/.cache/uv/archive-v0/10gPuxc61Audvy1Eg6SFz/trove_classifiers/.l2s.__init__.py0001
269+
to
270+
/root/.cache/uv/builds-v0/.tmp2lFVJx/lib/python3.10/site-packages/trove_classifiers/.l2s.__init__.py0001:
271+
Operation not permitted (os error 1)
272+
```
273+
274+
Run the following commands first, and then restart:
275+
276+
```bash
277+
echo 'export UV_LINK_MODE=copy' >> ~/.bashrc
278+
source ~/.bashrc
279+
```

0 commit comments

Comments
 (0)