feat: add CLI commands documentation and service management features

- 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.
2026-07-19 18:47:41 +08:00 · 2026-05-21 23:44:28 +08:00
parent 0711172fa7
commit 97f0fd3de3
12 changed files with 2555 additions and 10 deletions
--- a/docs/zh/deploy/astrbot/package.md
+++ b/docs/zh/deploy/astrbot/package.md
@@ -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
+```
--- a/docs/zh/use/cli.md
+++ b/docs/zh/use/cli.md
@@ -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
+```