fz-mirrors/AstrBot
1
0
Fork 0
mirror of https://github.com/AstrBotDevs/AstrBot synced 2026-07-16 01:40:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: add CLI commands documentation and service management features

Browse Source 
- Updated the VitePress configuration to include links to CLI commands in both English and Chinese.
- Enhanced the AstrBot deployment documentation with instructions for installing it as a system service.
- Created comprehensive CLI commands documentation covering initialization, service management, configuration, and plugin management.
- Added tests for CLI command aliases and service functionalities to ensure proper command registration and behavior.
- Implemented service log management features, including enabling application logging and controlling log visibility.
This commit is contained in:
Soulter
2026-05-21 23:44:28 +08:00
parent 0711172fa7
commit 97f0fd3de3
12 changed files with 2555 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/.vitepress/config.mjs
View File

@@ -159,6 +159,7 @@ export default defineConfig({
base: "/use",
items: [
{ text: "WebUI", link: "/webui" },
{ text: "CLI 指令", link: "/cli" },
{ text: "插件", link: "/plugin" },
{ text: "内置指令", link: "/command" },
{ text: "工具使用 Tools", link: "/function-calling" },
@@ -403,6 +404,7 @@ export default defineConfig({
collapsed: true,
items: [
{ text: "WebUI", link: "/webui" },
{ text: "CLI Commands", link: "/cli" },
{ text: "Plugins", link: "/plugin" },
{ text: "Built-in Commands", link: "/command" },
{ text: "Tool Use", link: "/function-calling" },

68
docs/en/deploy/astrbot/package.md
View File

@@ -20,5 +20,71 @@ AstrBot requires Python 3.12 or later. Use `--python 3.12` to ensure that `uv` c
```bash
uv tool install astrbot --python 3.12
astrbot
astrbot init # Only required for the first deployment
astrbot run
```
## Install as a System Service
After initialization, install AstrBot as a user-level service so it starts with the user session:
```bash
astrbot service install --now
```
The command uses the `astrbot` executable found on `PATH` (usually generated by `uv tool install`) and uses the current directory as the AstrBot working directory. Each platform uses its native user-level service mechanism:
- Linux: `systemd --user`
- macOS: `LaunchAgent`
- Windows: Task Scheduler
To specify the AstrBot working directory or executable path explicitly:
```bash
astrbot service install --workdir /path/to/astrbot-root --executable /path/to/astrbot --now
```
To inspect the service state and WebUI health:
```bash
astrbot service status
```
The status output includes the service manager state, AstrBot working directory, Dashboard port, WebUI URL, WebUI accessibility, and the overall health state.
You can also manage the service lifecycle with:
```bash
astrbot service start
astrbot service stop
astrbot service restart
astrbot service uninstall
```
To view service logs:
```bash
astrbot service logs
astrbot service logs -f
```
On macOS and Windows, this shows stdout logs by default. To include stderr:
```bash
astrbot service logs --include-stderr
```
To read the AstrBot application log file at `data/logs/astrbot.log`, enable application file logging first and restart the service:
```bash
astrbot service logs enable
astrbot service restart
astrbot service logs --source app
```
To inspect or disable application file logging:
```bash
astrbot service logs status
astrbot service logs disable
```

307
docs/en/use/cli.md Normal file
View File

@@ -0,0 +1,307 @@
# CLI Commands
The AstrBot CLI initializes instances, starts AstrBot, installs background services, reads logs, updates common config values, and manages plugins.
If you install AstrBot with `uv`:
```bash
uv tool install astrbot --python 3.12
```
`uv` creates the `astrbot` executable and puts it on `PATH`. You can inspect the path with:
::: code-group
```bash [Linux / macOS]
which astrbot
```
```powershell [Windows]
where.exe astrbot
```
:::
> [!TIP]
> Run the commands below from the AstrBot working directory unless the command provides a `--workdir` option.
## Quick Start
Initialize the directory once, then start AstrBot:
```bash
astrbot init
astrbot run
```
`astrbot init` creates the data directories and configuration files required by AstrBot. After initialization, use `astrbot run` for later starts.
## Top-Level Commands
| Command | Purpose |
| --- | --- |
| `astrbot init` | Initialize the current directory as an AstrBot working directory. |
| `astrbot run` | Start AstrBot in the foreground. |
| `astrbot service` | Install and manage AstrBot as a background service. |
| `astrbot config` | Read or update common config values. |
| `astrbot password` | Change the WebUI login password interactively. |
| `astrbot plugin` | Create, install, update, remove, or search plugins. |
| `astrbot help` | Show CLI help. |
| `astrbot --version` | Show the AstrBot CLI version. |
`conf` and `plug` are compatibility aliases and still work:
```bash
astrbot conf get
astrbot plug list
```
Prefer `config` and `plugin` in new docs and scripts.
## Start AstrBot
```bash
astrbot run
```
Common options:
| Option | Purpose |
| --- | --- |
| `-p, --port <PORT>` | Set the WebUI port. |
| `-r, --reload` | Enable plugin auto-reload for plugin development. |
Examples:
```bash
astrbot run --port 6185
astrbot run --reload
```
## Background Service
`astrbot service` installs AstrBot as a user-level background service for long-running deployments.
Each platform uses its native service manager:
| Platform | Service manager |
| --- | --- |
| Linux | `systemd --user` |
| macOS | LaunchAgent |
| Windows | Task Scheduler |
### Install
```bash
astrbot service install --now
```
By default, this command uses the `astrbot` executable found on `PATH` and the current directory as the AstrBot working directory. `--now` starts or restarts the service after installation.
Common options:
| Option | Purpose |
| --- | --- |
| `--name <NAME>` | Service name. Default: `astrbot`. |
| `--workdir <DIR>` | AstrBot working directory. |
| `--executable <PATH>` | Path to the `astrbot` executable. |
| `--force` | Overwrite an existing service definition. |
| `--now` | Start or restart the service after installation. |
If `astrbot` is not on `PATH`, pass the executable explicitly:
```bash
astrbot service install --workdir /path/to/astrbot-root --executable /path/to/astrbot --now
```
### Manage
```bash
astrbot service start
astrbot service stop
astrbot service restart
astrbot service uninstall
```
These commands support `--name <NAME>` for non-default service names:
```bash
astrbot service restart --name astrbot-test
```
To remove a service without an interactive confirmation:
```bash
astrbot service uninstall --force
```
### Status
```bash
astrbot service status
```
The status output includes:
- Overall health.
- Current platform and service manager.
- Whether the service is installed, enabled, and running.
- AstrBot working directory.
- Dashboard port.
- WebUI URL and accessibility.
Common options:
| Option | Purpose |
| --- | --- |
| `--name <NAME>` | Service name. Default: `astrbot`. |
| `--workdir <DIR>` | AstrBot working directory used to read the port config. |
| `--timeout <SECONDS>` | WebUI health probe timeout. Default: 2 seconds. |
Example:
```bash
astrbot service status --timeout 5
```
## Logs
The CLI exposes two kinds of logs:
| Type | Command | Notes |
| --- | --- | --- |
| Service logs | `astrbot service logs` | Reads console output captured by the service manager. |
| Application log file | `astrbot service logs --source app` | Reads `data/logs/astrbot.log`; file logging must be enabled first. |
### Service Logs
```bash
astrbot service logs
astrbot service logs -n 100
astrbot service logs -f
```
Common options:
| Option | Purpose |
| --- | --- |
| `--name <NAME>` | Service name. |
| `-n, --lines <N>` | Show the latest N lines. Default: 200. |
| `-f, --follow` | Follow log output. |
| `--include-stderr` | Also show stderr logs on macOS and Windows. |
On macOS and Windows, `astrbot service logs` shows stdout logs by default, which are the `.out.log` files. Add `--include-stderr` when you also need error output.
### Application Log File
`data/logs/astrbot.log` is not written by default. Enable application file logging first, then restart AstrBot:
```bash
astrbot service logs enable
astrbot service restart
astrbot service logs --source app
```
Inspect the application log file configuration:
```bash
astrbot service logs status
```
Disable the application log file:
```bash
astrbot service logs disable
astrbot service restart
```
Use a custom application log path:
```bash
astrbot service logs enable --path logs/astrbot.log
```
Relative paths are resolved from the AstrBot data directory.
## Config
`astrbot config` reads and updates common config values.
```bash
astrbot config get
astrbot config get dashboard.port
astrbot config set dashboard.port 6185
```
Supported keys:
| Key | Description |
| --- | --- |
| `timezone` | Time zone, for example `Asia/Shanghai`. |
| `log_level` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL`. |
| `dashboard.port` | WebUI port. |
| `dashboard.username` | WebUI username. |
| `dashboard.password` | WebUI password. |
| `callback_api_base` | Callback API base URL. Must start with `http://` or `https://`. |
Changing the dashboard password writes the current password hashes automatically:
```bash
astrbot config set dashboard.password "new-password"
```
You can also use the dedicated interactive password command:
```bash
astrbot password
astrbot password --username admin
```
## Plugins
`astrbot plugin` manages plugins under `data/plugins`.
| Command | Purpose |
| --- | --- |
| `astrbot plugin list` | List installed plugins. |
| `astrbot plugin list --all` | Also show uninstalled plugins. |
| `astrbot plugin search <QUERY>` | Search plugins. |
| `astrbot plugin install <NAME>` | Install a plugin. |
| `astrbot plugin update [NAME]` | Update one plugin, or all updatable plugins if no name is given. |
| `astrbot plugin remove <NAME>` | Remove an installed plugin. |
| `astrbot plugin new <NAME>` | Create a new plugin from the template. |
Use a GitHub proxy when installing or updating plugins:
```bash
astrbot plugin install example-plugin --proxy https://gh-proxy.example.com/
astrbot plugin update --proxy https://gh-proxy.example.com/
```
Creating a new plugin asks for the author, description, version, and repository URL:
```bash
astrbot plugin new my-plugin
```
## Help
Show general CLI help:
```bash
astrbot help
```
Show help for a specific command:
```bash
astrbot help service
astrbot service --help
astrbot service logs --help
```
Show the version:
```bash
astrbot --version
```

65
docs/zh/deploy/astrbot/package.md
View File

@@ -22,3 +22,68 @@ uv tool install astrbot --python 3.12
astrbot init # 只需要在第一次部署时执行，后续启动不需要执行
astrbot run
```
## 安装为系统服务
初始化完成后，可以安装用户级服务，让 AstrBot 随用户会话自动启动：
```bash
astrbot service install --now
```
该命令会自动使用当前 `PATH` 中的 `astrbot` 可执行文件（通常由 `uv tool install` 生成），并将当前目录作为 AstrBot 工作目录。不同系统会使用对应的用户级服务机制：
- Linux：`systemd --user`
- macOS：`LaunchAgent`
- Windows：任务计划程序
如果需要指定 AstrBot 工作目录或可执行文件路径，可以使用：
```bash
astrbot service install --workdir /path/to/astrbot-root --executable /path/to/astrbot --now
```
查看服务状态和 WebUI 健康状态：
```bash
astrbot service status
```
状态输出会包含服务管理器状态、AstrBot 工作目录、Dashboard 端口、WebUI URL、WebUI 是否可访问，以及整体健康状态。
也可以使用以下命令管理服务生命周期：
```bash
astrbot service start
astrbot service stop
astrbot service restart
astrbot service uninstall
```
查看服务日志：
```bash
astrbot service logs
astrbot service logs -f
```
macOS 和 Windows 下默认只显示标准输出日志；如需同时查看 stderr：
```bash
astrbot service logs --include-stderr
```
如果需要查看 AstrBot 应用日志文件 `data/logs/astrbot.log`，先启用应用日志文件并重启服务：
```bash
astrbot service logs enable
astrbot service restart
astrbot service logs --source app
```
查看或关闭应用日志文件：
```bash
astrbot service logs status
astrbot service logs disable
```

307
docs/zh/use/cli.md Normal file
View File

@@ -0,0 +1,307 @@
# CLI 指令
AstrBot CLI 用于初始化实例、启动 AstrBot、安装后台服务、查看日志、修改常用配置和管理插件。
如果你使用 `uv` 安装：
```bash
uv tool install astrbot --python 3.12
```
`uv` 会生成 `astrbot` 可执行文件，并把它放到 `PATH` 中。可以用下面的命令确认路径：
::: code-group
```bash [Linux / macOS]
which astrbot
```
```powershell [Windows]
where.exe astrbot
```
:::
> [!TIP]
> 下面的命令都需要在 AstrBot 工作目录中执行，除非命令提供了 `--workdir` 选项。
## 快速开始
第一次部署时先初始化目录，再启动 AstrBot：
```bash
astrbot init
astrbot run
```
`astrbot init` 会在当前目录创建 AstrBot 所需的数据目录和配置文件。初始化完成后，后续启动只需要执行 `astrbot run`。
## 顶层指令
| 指令 | 用途 |
| --- | --- |
| `astrbot init` | 初始化当前目录为 AstrBot 工作目录。 |
| `astrbot run` | 在前台启动 AstrBot。 |
| `astrbot service` | 安装和管理 AstrBot 后台服务。 |
| `astrbot config` | 查看或修改常用配置项。 |
| `astrbot password` | 交互式修改 WebUI 登录密码。 |
| `astrbot plugin` | 创建、安装、更新、删除或搜索插件。 |
| `astrbot help` | 查看 CLI 帮助。 |
| `astrbot --version` | 查看 AstrBot CLI 版本。 |
`conf` 和 `plug` 是兼容别名，仍然可用：
```bash
astrbot conf get
astrbot plug list
```
推荐在新文档和脚本中使用 `config` 和 `plugin`。
## 启动 AstrBot
```bash
astrbot run
```
常用选项：
| 选项 | 用途 |
| --- | --- |
| `-p, --port <PORT>` | 指定 WebUI 端口。 |
| `-r, --reload` | 启用插件自动重载，适合插件开发调试。 |
示例：
```bash
astrbot run --port 6185
astrbot run --reload
```
## 后台服务
`astrbot service` 可以把 AstrBot 安装为用户级后台服务，适合长期运行。
不同系统会使用对应的服务管理机制：
| 系统 | 服务管理器 |
| --- | --- |
| Linux | `systemd --user` |
| macOS | LaunchAgent |
| Windows | 任务计划程序 |
### 安装服务
```bash
astrbot service install --now
```
该命令默认使用当前 `PATH` 中的 `astrbot` 可执行文件，并把当前目录作为 AstrBot 工作目录。`--now` 表示安装后立即启动或重启服务。
常用选项：
| 选项 | 用途 |
| --- | --- |
| `--name <NAME>` | 指定服务名，默认 `astrbot`。 |
| `--workdir <DIR>` | 指定 AstrBot 工作目录。 |
| `--executable <PATH>` | 指定 `astrbot` 可执行文件路径。 |
| `--force` | 覆盖已有服务定义。 |
| `--now` | 安装后立即启动或重启服务。 |
如果 `astrbot` 不在 `PATH` 中，可以显式指定可执行文件：
```bash
astrbot service install --workdir /path/to/astrbot-root --executable /path/to/astrbot --now
```
### 管理服务
```bash
astrbot service start
astrbot service stop
astrbot service restart
astrbot service uninstall
```
这些命令都支持 `--name <NAME>`，用于管理非默认服务名：
```bash
astrbot service restart --name astrbot-test
```
卸载服务时，如果不希望交互确认，可以使用：
```bash
astrbot service uninstall --force
```
### 查看服务状态
```bash
astrbot service status
```
状态输出会包含：
- 整体健康状态。
- 当前系统和服务管理器。
- 服务是否已安装、是否启用、当前运行状态。
- AstrBot 工作目录。
- Dashboard 端口。
- WebUI URL 和是否可访问。
常用选项：
| 选项 | 用途 |
| --- | --- |
| `--name <NAME>` | 指定服务名，默认 `astrbot`。 |
| `--workdir <DIR>` | 指定 AstrBot 工作目录，用于读取端口配置。 |
| `--timeout <SECONDS>` | 指定 WebUI 健康检查超时时间，默认 2 秒。 |
示例：
```bash
astrbot service status --timeout 5
```
## 日志
AstrBot CLI 中有两类日志：
| 类型 | 命令 | 说明 |
| --- | --- | --- |
| 服务日志 | `astrbot service logs` | 查看服务管理器捕获的控制台输出。 |
| 应用日志文件 | `astrbot service logs --source app` | 查看 `data/logs/astrbot.log`，需要先启用文件日志。 |
### 查看服务日志
```bash
astrbot service logs
astrbot service logs -n 100
astrbot service logs -f
```
常用选项：
| 选项 | 用途 |
| --- | --- |
| `--name <NAME>` | 指定服务名。 |
| `-n, --lines <N>` | 显示最近 N 行，默认 200。 |
| `-f, --follow` | 持续跟随日志输出。 |
| `--include-stderr` | 在 macOS 和 Windows 上同时显示 stderr 日志。 |
macOS 和 Windows 下，`astrbot service logs` 默认只显示标准输出日志，也就是 `.out.log`。如果需要同时查看错误输出，再加 `--include-stderr`。
### 启用应用日志文件
`data/logs/astrbot.log` 默认不会写入。需要先启用应用日志文件，然后重启 AstrBot：
```bash
astrbot service logs enable
astrbot service restart
astrbot service logs --source app
```
查看应用日志文件配置：
```bash
astrbot service logs status
```
关闭应用日志文件：
```bash
astrbot service logs disable
astrbot service restart
```
自定义应用日志文件路径：
```bash
astrbot service logs enable --path logs/astrbot.log
```
相对路径会以 AstrBot 数据目录为基准解析。
## 配置
`astrbot config` 用于查看和修改常用配置项。
```bash
astrbot config get
astrbot config get dashboard.port
astrbot config set dashboard.port 6185
```
支持的配置项：
| 配置项 | 说明 |
| --- | --- |
| `timezone` | 时区，例如 `Asia/Shanghai`。 |
| `log_level` | 日志等级：`DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL`。 |
| `dashboard.port` | WebUI 端口。 |
| `dashboard.username` | WebUI 用户名。 |
| `dashboard.password` | WebUI 密码。 |
| `callback_api_base` | 回调 API 基础地址，需要以 `http://` 或 `https://` 开头。 |
修改密码时会自动写入新版密码哈希：
```bash
astrbot config set dashboard.password "new-password"
```
也可以使用专门的交互式密码指令：
```bash
astrbot password
astrbot password --username admin
```
## 插件
`astrbot plugin` 用于管理 `data/plugins` 下的插件。
| 指令 | 用途 |
| --- | --- |
| `astrbot plugin list` | 查看已安装插件。 |
| `astrbot plugin list --all` | 同时显示未安装插件。 |
| `astrbot plugin search <QUERY>` | 搜索插件。 |
| `astrbot plugin install <NAME>` | 安装插件。 |
| `astrbot plugin update [NAME]` | 更新指定插件；不传名称时更新所有可更新插件。 |
| `astrbot plugin remove <NAME>` | 删除已安装插件。 |
| `astrbot plugin new <NAME>` | 基于模板创建新插件。 |
安装或更新插件时可以使用 GitHub 代理：
```bash
astrbot plugin install example-plugin --proxy https://gh-proxy.example.com/
astrbot plugin update --proxy https://gh-proxy.example.com/
```
创建新插件会交互式询问作者、描述、版本和仓库地址：
```bash
astrbot plugin new my-plugin
```
## 帮助
查看全部 CLI 帮助：
```bash
astrbot help
```
查看指定指令帮助：
```bash
astrbot help service
astrbot service --help
astrbot service logs --help
```
查看版本：
```bash
astrbot --version
```