OlivOS-CLI

适用于 OlivOS 框架的命令行管理工具 - 简化部署、配置与管理

classDiagram
    class GitConfig {
        +str repo_url
        +str mirror_url
        +bool use_mirror
        +str install_path
        +str branch
        +str commit_hash
        +int depth
    }

    class PackageUVConfig {
        +str python_version
        +str cache_dir
        +str index_url
        +list~str~ extra_index_url
    }

    class SystemdRuntimeConfig {
        +str working_directory
        +str exec_start
        +str exec_stop
        +str restart
        +int restart_sec
        +__post_init__()
    }

    class SystemdConfig {
        +bool user_mode
        +str service_dir
        +str service_name
        +SystemdRuntimeConfig runtime
    }

    class OlivOSBasicConfig {
        +str host
        +int port
        +bool debug
        +str log_level
    }

    class OlivOSConfig {
        +str root_path
        +str conf_path
        +str plugin_path
        +str log_path
        +OlivOSBasicConfig basic
        +property conf_file
        +property plugin_dir
        +property log_dir
    }

    class LoggingConfig {
        +str olivos_log_file
        +bool log_rotation
        +int max_size_mb
        +int keep_days
    }

    class PluginsConfig {
        +list~str~ plugin_dirs
        +list~str~ auto_load
        +property all_plugin_dirs
    }

    class InstanceConfig {
        +str name
        +str path
        +str service_name
        +bool enabled
        +str branch
    }

    class AdvancedConfig {
        +str update_strategy
        +bool backup_before_update
        +str backup_dir
        +int concurrent_downloads
        +property backup_path
    }

    class ConstModule {
        +bool IS_WINDOWS
        +Path CONFIG_DIR
        +Path DATA_DIR
        +Path CACHE_DIR
        +Path LOG_DIR
        +Path SYSTEMD_USER_DIR
        +str DEFAULT_SERVICE_NAME
        +str DEFAULT_REPO_URL
        +str DEFAULT_MIRROR_URL
        +str DEFAULT_BRANCH
    }

    class SystemdManager {
        +bool user_mode
        +Path service_dir
        +SystemdManager(user_mode, service_dir)
        +_get_systemctl_cmd() list~str~
        +status(service_name) dict
        +start(service_name) int
        +stop(service_name) int
        +restart(service_name) int
        +enable(service_name) int
        +disable(service_name) int
    }

    ConstModule <.. GitConfig : uses DEFAULT_REPO_URL
    ConstModule <.. GitConfig : uses DEFAULT_MIRROR_URL
    ConstModule <.. GitConfig : uses DEFAULT_BRANCH

    ConstModule <.. PackageUVConfig : uses Path.home
    ConstModule <.. SystemdConfig : uses SYSTEMD_USER_DIR
    ConstModule <.. OlivOSConfig : uses LOG_DIR
    ConstModule <.. LoggingConfig : uses LOG_DIR
    ConstModule <.. AdvancedConfig : uses DATA_DIR
    ConstModule <.. SystemdManager : uses SYSTEMD_USER_DIR

    SystemdConfig --> SystemdRuntimeConfig : has
    OlivOSConfig --> OlivOSBasicConfig : has
    SystemdManager --> SystemdConfig : configured_by

特性

• 🚀 一键部署 - 自动克隆 OlivOS 仓库、创建虚拟环境并安装依赖
• 📦 多包管理器支持 - 支持 uv、pip、pdm、poetry、rye 等主流包管理器
• 🔧 智能配置 - 从 OlivOS accountMetaData 读取预配置模板，支持 60+ 账号类型
• 🛡️ systemd 集成 - 自动生成和管理 systemd 用户服务
• 📊 实时监控 - 日志查看、状态监控、健康检查
• 🔄 版本管理 - Git 分支切换、更新、镜像源加速
• 💾 虚拟环境隔离 - 每个实例独立的 Python 环境

支持的平台

平台	适配器类型	说明
QQ	onebot, onebot12	OneBot V11/V12 协议 (NapCat, GoCqHttp, LLOneBot, Lagrange 等)
QQ 频道	qqguild, qqguildv2	QQ 频道开放平台 (公域/私域/沙盒)
微信	ComWeChatBot	微信机器人
Telegram	telegram_poll	Telegram Bot
Discord	discord_link	Discord Bot
KOOK	kaiheila_link	开黑啦
钉钉	dingtalk_link	钉钉机器人
米游社	mhyVila_link	米游社大别野
B站直播	biliLive_link	B站直播间弹幕
DoDo	dodo_link	DoDo 社区
Fanbook	fanbook_poll	Fanbook
小黑盒	xiaoheihe_link	小黑盒语音
Hack.Chat	hackChat_link	Hack.Chat 聊天协议
虚拟终端	terminal_link	用于插件调试和测试

安装

使用 pip 安装

pip install olivos-cli

使用 uv 安装（推荐）

uv pip install olivos-cli

从源码安装

git clone https://github.com/HsiangNianian/olivos-cli.git
cd olivos-cli
pip install -e .

快速开始

1. 初始化 OlivOS

olivoscli init

这将自动：

• 克隆 OlivOS 仓库到 ~/.local/share/olivos
• 创建独立的 Python 虚拟环境 (.venv)
• 在虚拟环境中安装 Python 依赖
• 创建必要的配置目录

自定义安装选项

# 指定安装路径
olivos-cli init --path ~/my-olivos

# 使用镜像源加速
olivos-cli init --mirror

# 指定分支
olivos-cli init --branch develop

# 使用特定包管理器
olivos-cli init --package-manager uv

# 跳过依赖安装（手动安装）
olivos-cli init --no-deps

2. 添加账号

olivos-cli account add

交互式选择平台和账号类型，然后填写账号信息。

非交互模式添加

# 添加 OneBot 账号
olivos-cli account add \
  --adapter onebotV11 \
  --id 1234567890 \
  --host 127.0.0.1 \
  --port 5700 \
  --access_token your_token

3. 安装并启动服务

# 安装 systemd 服务
olivos-cli service install

# 启用开机自启
olivos-cli service enable

# 启动服务
olivos-cli service start

# 查看状态
olivos-cli service status

命令参考

命令缩写

所有命令都支持缩写形式：

完整命令	缩写	说明
olivos-cli init	olivos-cli i	初始化安装
olivos-cli git	olivos-cli g	Git 管理
olivos-cli git pull	olivos-cli g up	拉取更新
olivos-cli git checkout	olivos-cli g co	切换分支
olivos-cli package	olivos-cli p / pkg	包管理
olivos-cli service	olivos-cli s / svc	服务管理
olivos-cli service restart	olivos-cli s r	重启服务
olivos-cli adapter	olivos-cli a / adapt	适配器管理
olivos-cli account	olivos-cli acc	账号管理
olivos-cli config	olivos-cli c / cfg	配置管理
olivos-cli logs	olivos-cli log	日志查看
olivos-cli status	olivos-cli st	状态监控

注意：你也可以使用 olivoscli 作为命令（不带连字符）。

---

init - 初始化安装

olivos-cli init [OPTIONS]

选项	说明
--path <PATH>	安装路径 (默认: ~/.local/share/olivos)
--branch <NAME>	Git 分支 (默认: main)
--mirror	使用镜像源加速
--minimal	最小化安装（仅核心依赖）
--no-deps	跳过依赖安装
--package-manager <NAME>	包管理器 (uv/pip/pdm/poetry/rye)
--requirements <FILE>	指定依赖文件

---

git - Git 仓库管理

olivos-cli git <ACTION>

动作	缩写	说明
clone	-	克隆 OlivOS 仓库
pull	up	拉取最新更新
checkout	co	切换分支或提交
status	st	查看仓库状态

# 克隆指定分支
olivos-cli git clone --branch develop

# 拉取更新
olivos-cli git pull

# 切换到 develop 分支
olivos-cli git checkout develop

# 切换到指定提交
olivos-cli git checkout abc1234

# 查看状态
olivos-cli git status

---

package - Python 包管理

olivos-cli package <ACTION>

动作	缩写	说明
install	i	安装依赖
update	up	更新依赖
list	ls	列出已安装的包

# 安装全部依赖
olivos-cli package install

# 安装指定包
olivos-cli package install requests

# 更新所有依赖
olivos-cli package update

# 列出已安装的包
olivos-cli package list

---

service - systemd 服务管理

olivos-cli service <ACTION>

动作	说明
install	安装 systemd 服务
uninstall	卸载服务
enable	启用开机自启
disable	禁用开机自启
start	启动服务
stop	停止服务
restart / r	重启服务
status / st	查看服务状态
logs / log	查看服务日志

# 安装服务
olivos-cli service install

# 启用并启动
olivos-cli service enable
olivos-cli service start

# 查看状态
olivos-cli service status

# 实时查看日志
olivos-cli service logs -f

# 重启服务
olivos-cli service restart

---

account - 账号管理

olivos-cli account <ACTION>

动作	缩写	说明
list	ls	列出所有账号
add	-	添加账号
remove	rm	删除账号
show	-	显示账号详情

# 交互式添加账号（推荐）
olivos-cli account add

# 查看所有账号
olivos-cli account list

# 查看账号详情
olivos-cli account show 123456

# 删除账号
olivos-cli account remove 123456

非交互模式选项：

olivos-cli account add \
  --adapter onebotV11 \
  --id 1234567890 \
  --token your_password \
  --host 127.0.0.1 \
  --port 5700 \
  --access_token your_token

---

adapter - 适配器管理

olivos-cli adapter <ACTION>

动作	缩写	说明
list	ls	列出支持的适配器
enable <NAME>	-	启用适配器
disable <NAME>	-	禁用适配器
config	cfg	配置适配器

# 列出所有适配器
olivos-cli adapter list

# 配置适配器
olivos-cli adapter config onebotV11 --get host
olivos-cli adapter config onebotV11 --set "host=127.0.0.1"

---

config - 配置管理

olivos-cli config <ACTION>

动作	说明
show	显示完整配置
get <KEY>	获取配置项（支持点号路径）
set <KEY> <VALUE>	设置配置项
unset <KEY>	删除配置项
edit	编辑配置文件
reset	重置为默认配置

# 显示配置
olivos-cli config show

# 获取配置项
olivos-cli config get git.branch

# 设置配置项
olivos-cli config set git.use_mirror true
olivos-cli config set package.manager uv

# 编辑配置文件
olivos-cli config edit

---

logs - 日志查看

olivos-cli logs [OPTIONS]

选项	缩写	说明
--lines <N>	-n	显示行数 (默认: 100)
--follow	-f	实时跟踪日志
--pattern <PATTERN>	-	过滤包含特定模式的行
--cli	-	查看 CLI 工具日志而非 OlivOS 日志

# 查看最近 100 行日志
olivos-cli logs

# 实时跟踪
olivos-cli logs -f

# 查看最近 500 行
olivos-cli logs -n 500

# 过滤包含 "ERROR" 的行
olivos-cli logs --pattern ERROR

---

status - 状态监控

olivos-cli status [OPTIONS]

选项	缩写	说明
--health	-	执行健康检查
--watch	-w	实时监控模式

# 查看状态
olivos-cli status

# 健康检查
olivos-cli status --health

# 实时监控
olivos-cli status -w

---

run - 直接运行

olivos-cli run [OPTIONS]

选项	说明
--dev	开发模式
--debug	调试模式

# 前台运行 OlivOS
olivos-cli run

# 开发模式
olivos-cli run --dev

---

update - 更新 OlivOS-CLI

olivos-cli update

更新 olivos-cli 自身到最新版本。

---

配置文件

配置文件位于 ~/.config/olivos-cli/config.toml：

[cli]
verbose = false          # 详细输出
log_level = "INFO"       # 日志级别: DEBUG/INFO/WARNING/ERROR

[git]
repo_url = "https://github.com/OlivOS-Team/OlivOS.git"
mirror_url = "https://ghfast.top/https://github.com/OlivOS-Team/OlivOS.git"
use_mirror = false       # 是否使用镜像源
install_path = "~/.local/share/olivos"
branch = "main"          # 默认分支
depth = 1                # 克隆深度

[package]
manager = "uv"           # 包管理器: uv/pip/pdm/poetry/rye
auto_install = true       # 自动安装包管理器

[package.uv]
python_version = "3.11"   # uv 使用的 Python 版本
index_url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

[systemd]
user_mode = true         # 用户模式服务
service_dir = "~/.config/systemd/user"
service_name = "olivos-cli"

[olivos]
root_path = "~/.local/share/olivos"

故障排除

依赖安装失败

问题：Pillow 安装失败

解决方案：

# 方案 1：使用系统 Pillow
sudo pacman -S python-pillow  # Arch Linux
sudo apt install python3-pil  # Ubuntu/Debian

# 方案 2：跳过依赖安装
olivos-cli init --no-deps
cd OlivOS
.venv/bin/pip install -r requirements310.txt

服务启动失败

问题：systemd 服务无法启动

解决方案：

# 查看详细日志
olivos-cli service logs --systemd -f

# 检查配置
olivos-cli service status

# 手动运行测试
olivos-cli run --debug

账号配置无效

问题：添加账号后无法连接

解决方案：

# 查看账号详情
olivos-cli account show YOUR_ACCOUNT_ID

# 检查 OlivOS 日志
olivos-cli logs -f

贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

许可证

本项目采用 AGPLv3 协议开源。详见 LICENSE 文件。

相关链接

• OlivOS 官方仓库
• OlivOS 文档
• OlivOS 论坛