CasaOS 0.4.15 常用 CLI 命令与工具详解
CasaOS v0.4.15 命令行工具详解：casaos-cli 全命令树实测（健康检查/消息总线/应用商店/Compose 应用）、主程序行为边界、卸载器与 systemd 排障组合，含 502 脱节实录。
CasaOS 0.4.15 常用 CLI 命令与工具详解
目标：作为 CasaOS WebUI 之外的运维抓手，逐条实测讲解 CasaOS 自带命令行工具的用法与参数——
casaos-cli全命令树（版本、二维码、健康检查、消息总线、应用商店管理、Compose 应用管理）、casaos主程序的行为边界、casaos-uninstall卸载器，以及 systemd 与 HTTP API 两组配套排障手段。全部命令与回显已在 Ubuntu 22.04.5 LTS + CasaOS v0.4.15 环境实测。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- CasaOS 版本：v0.4.15；casaos-cli 版本 0.4.4-3-alpha1（build time: 2023-11-20T09:52:33Z，commit: 51949f2cdc71eaec41db443fb93d8178ca6e5192）
- CLI 位置：
/usr/bin/casaos-cli（另有/usr/bin/casaos、/usr/bin/casaos-gateway、/usr/bin/casaos-uninstall等 8 个二进制） - 服务托管：systemd（casaos、casaos-gateway、casaos-message-bus、casaos-user-service、casaos-local-storage、casaos-app-management、rclone）
- 对外入口：
casaos-gateway监听 80 端口；CLI 默认经网关访问 API - 日志目录：
/var/log/casaos/；运行时目录：/var/run/casaos/
二、工具概览
CasaOS 提供的命令行工具分四组：
| 工具 | 位置 | 职责 |
|---|---|---|
casaos-cli | /usr/bin/casaos-cli | 运维主入口：健康检查、消息总线、用户、存储、应用商店与 Compose 应用管理 |
casaos | /usr/bin/casaos | 主服务程序本体，无子命令，仅供 systemd 调用 |
casaos-uninstall | /usr/bin/casaos-uninstall | 交互式卸载器 |
| systemd 工具组 | 系统自带 | systemctl/journalctl 管理与排障各服务 |
关键差异解读：日常运维 90% 的 CLI 需求由 casaos-cli 覆盖；casaos 本体不是给人手敲的（直接运行会以前台模式启动服务并覆盖网关注册，详见 5.2 节）；服务级状态与日志排障用 systemd 工具组最直接。
三、前置条件
- 已完成 CasaOS 安装（见《Ubuntu 22.04 安装 CasaOS 0.4.15 指南》），7 个服务处于 running 状态：
systemctl list-units --type=service --state=running --no-pager --no-legend | grep -E 'casaos|rclone'
实测回显：
casaos.service loaded active running CasaOS Main Service
casaos-app-management.service loaded active running CasaOS App Management Service
casaos-gateway.service loaded active running CasaOS Gateway
casaos-local-storage.service loaded active running CasaOS Local Storage Service
casaos-message-bus.service loaded active running CasaOS Message Bus Service
casaos-user-service.service loaded active running CasaOS User Service
rclone.service loaded active running rclone mount helper
- 以 root 或 sudo 用户执行（部分命令访问
/var/run/casaos/与/var/log/casaos/）。 - 理解 CLI 请求链路：
casaos-cli→ 网关（80 端口）→ 各后端服务。网关不通时 CLI 全线报错（排障见 7.1）。
四、casaos-cli 命令详解
4.1 总览与帮助
casaos-cli --help
实测回显：
A command line interface for CasaOS
Usage:
casaos-cli [command]
Services
app-management All compose app management and store related commands
local-storage All local storage related commands
message-bus All message bus related commands
user All user related commands
Additional Commands:
completion Generate the autocompletion script for the specified shell
healthcheck All healthcheck commands
help Help about any command
qrcode show qrcode to CasaOS WebUI
version Show version
Flags:
-h, --help help for casaos-cli
-u, --root-url string root url of CasaOS API
Additional help topics:
casaos-cli gateway All gateway related commands
Use "casaos-cli [command] --help" for more information about a command.
参数说明：
-u/--root-url：指定 CasaOS API 根地址，默认走本机网关；⚠️ 该值按"主机:端口"拼接使用，实测传入http://127.0.0.1会拼出非法地址http://http//127.0.0.1/...并报 DNS 错误（dial tcp: lookup http on 127.0.0.11:53: server misbehaving），如需指定应传127.0.0.1:80形式。completion：生成 bash/zsh 等自动补全脚本。casaos-cli gateway --help实测仅输出主题行All gateway related commands，无子命令内容（CLI 文档化不完整的预留主题）。
4.2 version：查看 CLI 版本
casaos-cli version
实测回显：
0.4.4
(build time: 2023-11-20T09:52:33Z, commit: 51949f2cdc71eaec41db443fb93d8178ca6e5192)
⚠️ 该命令显示的是 casaos-cli 自身版本（0.4.4），不是 CasaOS 主服务版本（0.4.15）。查询系统版本用 4.9 节的 API 方式。
4.3 qrcode：WebUI 访问二维码
casaos-cli qrcode
实测回显（ASCII 二维码，终端内直接可扫）：
█████████████████████████████
█████████████████████████████
████ ▄▄▄▄▄ █▀▄█ ▄█ ▄▄▄▄▄ ████
████ █ █ ██ ▄ ▀█ █ █ ████
████ █▄▄▄█ █▄▄▀ ▄█ █▄▄▄█ ████
████▄▄▄▄▄▄▄█▄▀ █▄█▄▄▄▄▄▄▄████
████ ▀▄▀▄█▄▀█▀▀▀▄▀██ █▀ ▀████
████ ▀ ██ ▄ ▄ ▀ ▀▄█▄ ▄█ ▄████
████▄▄▄██▄█▄▄▀▀▄ █▄█ ▀▀▀▀█ █████
████ ▄▄▄▄▄ ██▀▄▀▄▀▄ ▄▄█ ▄████
████ █ █ █▄▄ █ ▀▀▀▀█ █████
████ █▄▄▄█ █▄█▀▀▄▀█ ▄▄▄▀▄████
...
用途：在服务器本地终端打印 WebUI 访问地址二维码，手机扫码直接打开管理界面（地址按服务器当前 IP 生成）。
4.4 healthcheck：健康检查三件套
子命令结构（实测 casaos-cli healthcheck --help）：
All healthcheck commands
Usage:
casaos-cli healthcheck [command]
Available Commands:
logs get all `casaos-*` logs and save to a ZIP file
ports-in-use get ports in use
services get running status of each `casaos-*` service
Flags:
-h, --help help for services
...
三个子命令在 v0.4.15 + CLI 0.4.4-3-alpha1 组合下均不可用，实测：
casaos-cli healthcheck services
casaos-cli healthcheck ports-in-use
casaos-cli healthcheck logs
实测回显（三者一致）：
Error: 502 Bad Gateway -
Usage:
casaos-cli healthcheck services [flags]
Aliases:
services, svc, service
...
定位结论：healthcheck 走 /v2/casaos/health/* API（错误信息中可见请求路径），而 v0.4.15 主服务对该路径直接断开连接（curl 直连实测 Empty reply from server），网关返回 502。这是 CLI（2023-11 构建的 alpha 版）与主服务版本脱节所致，属上游已知状态。健康检查的可用替代：systemctl 查服务（见第五章）、curl http://127.0.0.1/v1/sys/version 查主服务活性。
4.5 user：用户相关命令
casaos-cli user --help
实测回显：
All user related commands
Usage:
casaos-cli user [command]
Available Commands:
list
...
user list 实测直接输出帮助（无独立行为），其下唯一子命令为 events：
casaos-cli user list events
实测回显（CLI 缺陷，实测原样照录）：
Error: Time.UnmarshalJSON: input is not a JSON string
Usage:
casaos-cli user list events [flags]
...
解读：user list events 存在时间字段反序列化缺陷，当前版本不可用。用户管理实际通过 WebUI 完成，CLI 侧无可用替代。
4.6 local-storage：存储查询
casaos-cli local-storage list merges
实测回显：
2026/10/21 07:11:01 unexpected status code 503 Service Unavailable
解读：mergerFS 合并视图查询依赖 /v2/local_storage/* 接口，v0.4.15 存储服务未提供对应路由，返回 503。存储排障改看 /var/log/casaos/local-storage.log 与 lsblk/df -h 系统工具。
4.7 message-bus：消息总线
子命令结构（实测 casaos-cli message-bus --help）：
All message bus related commands
Usage:
casaos-cli message-bus [command]
Available Commands:
list list entities in message bus
subscribe subscribe to events/actions in message bus
trigger trigger an action via message bus
...
列出全部事件类型（可用的排查利器）：
casaos-cli message-bus list event-types
实测回显（节选，首尾完整覆盖主要源）：
SOURCE ID EVENT NAME PROPERTY TYPES
--------- ---------- --------------
CasaOS-UserService zimaos:user:save_config {}
local-storage local-storage:disk:added {local-storage:bus, local-storage:model, local-storage:path, local-storage:vendor, serial, tran}
local-storage local-storage:disk:removed {local-storage:bus, local-storage:model, local-storage:path, local-storage:vendor, serial, tran}
app-management app-store:register-begin {}
app-management app-store:register-end {}
app-management app-store:register-error {message}
app-management app:install-begin {app:icon, app:name}
app-management app:install-progress {app:icon, app:name, app:progress, app:title, check_port_conflict, dry_run}
app-management app:install-end {app:icon, app:name}
app-management app:install-error {app:icon, app:name, message}
解读：事件命名规则为 <来源>:<域>:<动作>，PROPERTY TYPES 列出事件携带字段——做 UI 通知或自动化钩子时按此订阅。
订阅事件（subscribe 两个子命令）：
Available Commands:
socketio subscribe to all entities in message bus via socketio
websocket subscribe to all entities in message bus via websocket
订阅命令会持续连接消息总线输出实时事件（Ctrl+C 退出），适合观察应用安装进度或磁盘插拔事件流。
触发动作（参数实测 casaos-cli message-bus trigger --help）：
trigger an action via message bus
Usage:
casaos-cli message-bus trigger [flags]
Flags:
-n, --action-name string action name
-h, --help help for trigger
-p, --properties K=V action properties (in form of K=V and separated by comma)
-s, --source-id string source id
参数说明：-s 指定动作来源（如 app-management），-n 指定动作名，-p 以 K=V,K=V 形式传属性。可用动作清单用 casaos-cli message-bus list action-types 查看（实测在 v0.4.15 返回空列表——动作总线接口尚未开放完整清单）。
4.8 app-management：应用与应用商店管理（最常用）
子命令结构（实测 casaos-cli app-management --help）：
All compose app management and store related commands
Usage:
casaos-cli app-management [command]
Available Commands:
apply apply changes to an installed compose app
convert convert to `docker-compose.yml` from another format
install install a compose app
list
logs retrieve logs of a compose app
register register an app store or ...
restart restart a compose app
search search for apps in app store
set
show show information of a specific compose app
start start a compose app
stop stop a compose app
uninstall uninstall a compose app
unregister unregister an app store or ...
update update a compose app or a container app
...
4.8.1 商店源管理：list app-stores / register / unregister
查看已注册商店源：
casaos-cli app-management list app-stores
实测回显：
ID URL STORE ROOT
-- --- ----------
0 https://casaos.app/store/main.zip /var/lib/casaos/appstore/casaos.app/4e6bf64b187e30664ab8e6ed48331e96/build/sysroot/var/lib/casaos/appstore/default.new
1 https://github.com/bigbeartechworld/big-bear-casaos/archive/refs/heads/master.zip /var/lib/casaos/appstore/github.com/2a1238d53212bfce4e8f861dcb8ef3fe/big-bear-casaos-master
注销指定源（按 ID，位置参数）：
casaos-cli app-management unregister app-store 1
实测回显：
app store is unregistered.
注册新源（URL 作位置参数，异步执行）：
casaos-cli app-management register app-store https://github.com/bigbeartechworld/big-bear-casaos/archive/refs/heads/master.zip
实测回显：
trying to register app store asynchronously - see /var/log/casaos/app-management.log for any errors.
参数说明：注册立即返回，源包下载与索引在后台异步完成；进度与失败原因看 /var/log/casaos/app-management.log，注册完成后再次 list app-stores 确认。
4.8.2 商店搜索：search
casaos-cli app-management search jellyfin
实测回显（节选）：
Name Category Author Developer Description
---- -------- ------ --------- -----------
big-bear-cyberchef Media BigBearTechWorld gchq
big-bear-linuxserver-beets Home WisdomSky LinuxServer.io
jellyfin Media ZimaOS Team Jellyfin
project-nomad Productivity IceWhaleTech Crosstalk Solutions
big-bear-lyrionmusicserver Media BigBearTechWorld LMS-Community
...
解读：按关键词全文匹配商店内应用的名称/描述，输出 Name 列即应用 ID，可在 WebUI 中按名安装或用于脚本化查询。
4.8.3 Compose 应用安装：install（含 dry-run）
参数（实测 install --help）：
install a compose app
Usage:
casaos-cli app-management install [flags]
Aliases:
install, add, create, up
Flags:
-d, --dry-run dry run
-f, --file string path to a compose file
-h, --help help for install
准备一个最小 Compose 文件 /tmp/hello-compose.yml：
name: hello-casa
services:
hello:
image: busybox
command: sleep 3600
ports:
- "8888:80"
仅校验不安装（dry-run 实测）：
casaos-cli app-management install -f /tmp/hello-compose.yml -d
实测回显：
2026/10/21 07:35:02 only validation has been done because `dry_run` is specified - skipping compose app installation
解读：-d 只做 Compose 文件合法性与端口冲突校验（回显中的 check_port_conflict 属性对应安装事件），跳过实际部署；去掉 -d 即真实安装，安装后应用出现在 WebUI 仪表盘与 /var/lib/casaos/apps/ 下。别名 add/create/up 等价。
4.8.4 应用生命周期：show / logs / start / stop / restart / update / uninstall
| 命令 | 语法 | 说明 |
|---|---|---|
show local <appid> | casaos-cli app-management show local <appid> [--yaml] [-c] | 查看本地已装应用详情；--yaml 原始 YAML 输出，-c 着色 |
show global | casaos-cli app-management show global | 查看全局应用信息 |
logs <appid> | casaos-cli app-management logs <appid> -l <行数> | 取应用日志，-l 默认 1000 行 |
start <appid> / stop <appid> / restart <appid> | 同形 | 启动/停止/重启指定应用 |
update app <appid>（别名 upgrade） | casaos-cli app-management update app <appid> | 更新应用到商店最新版 |
uninstall <appid> | casaos-cli app-management uninstall <appid> | 卸载应用 |
apply | casaos-cli app-management apply | 对已装应用应用变更 |
set | casaos-cli app-management set | 设置应用属性 |
convert appfile | casaos-cli app-management convert appfile <appfile.json> | 把 CasaOS 应用描述文件（appfile.json）转换为标准 Docker Compose YAML，便于迁移到其他编排体系 |
⚠️
update是"更新应用到新版"，与apply（应用配置变更）语义不同，勿混用。
4.9 配套的 HTTP API 排障命令
CLI 不可用或不覆盖的场景，直接用 curl 调网关 API（GET 均无需认证）：
curl -s http://127.0.0.1/v1/sys/version
实测回显（节选）：
{"success":200,"message":"ok","data":{"current_version":"0.4.15","need_update":false,"version":{"id":63,"change_log":"# v0.4.15\n**Fixes**\n- Resolved issue with cloud drive not mounting correctly....
解读：success: 200 即主服务与网关链路健康；need_update 直接给出是否有新版本。
查看网关当前路由注册（定位 CLI 502 的关键文件）：
cat /var/run/casaos/routes.json
实测回显（节选，完整 JSON 共 38 条路由）：
{"/":"http://127.0.0.1:42763","/v1/sys":"http://127.0.0.1:33213","/v1/file":"http://127.0.0.1:33213","/v1/apps":"http://127.0.0.1:33209","/v1/users":"http://127.0.0.1:43857","/v2/casaos":"http://127.0.0.1:33213",...}
解读：路由把 URL 前缀映射到各后端服务端口；某类请求 502 时先核对该前缀指向的端口是否有进程监听（ss -ltnp 对照）。
五、casaos 主程序与卸载器
5.1 casaos：主服务程序（禁止手动前台运行）
casaos 二进制不解析任何子命令：
casaos version # ⚠️ 错误用法
实测表现：不会输出版本号，而是直接以前台模式启动一份主服务（终端被占住、输出请求日志），并向网关注册自身地址、覆盖 systemd 运行实例的注册信息：
2026-10-21T07:05:18.952Z info This process is not running as a systemd service. {"func": "main.main", ...}
2026-10-21T07:05:18.953Z info CasaOS main service is listening... {"address": "127.0.0.1:46249", ...}
退出该前台进程后，网关路由仍指向已消失的端口，CLI 全线 502（排障见 7.1）。查看版本的正确姿势：
curl -s http://127.0.0.1/v1/sys/version | grep -o '"current_version":"[^"]*"'
实测回显：
"current_version":"0.4.15"
5.2 casaos-uninstall：交互式卸载器
sudo casaos-uninstall
实测回显（需真实终端 TTY）：
[ OK ] This script will delete the containers you no longer use, and the CasaOS configuration files.
Do you want delete all containers? Y/n :
确认后按 manifest 清单删除全部 CasaOS 组件与数据（完整卸载流程与手动卸载备选方案见《Ubuntu 22.04 安装 CasaOS 0.4.15 指南》第十章）。⚠️ 无 TTY 环境（管道/自动化）中该脚本无法完成确认；确认删除 Docker 应用时会把宿主机上全部存量应用停止删除。
六、systemd 与日志工具组
6.1 服务管理
systemctl status casaos
systemctl restart casaos
journalctl -u casaos -n 30 --no-pager
实测 journalctl -u casaos -n 5 --no-pager 回显（节选）：
Oct 21 07:06:45 casaos-server casaos[8335]: {"time":"2026-10-21T07:06:45.003989999Z","id":"","remote_ip":"127.0.0.1","host":"127.0.0.1:39965","method":"POST","uri":"/v1/notify/system_status","user_agent":"Go-http-client/1.1","status":200,...}
6.2 文件型日志
各服务日志固定落在 /var/log/casaos/（实测清单）：
-rw------- 1 root root 42485 Oct 21 07:11 app-management.log
-rw------- 1 root root 1577 Oct 21 07:02 gateway.log
-rw------- 1 root root 20728 Oct 21 07:09 local-storage.log
-rw------- 1 root root 3790 Oct 21 07:09 log.log
-rw------- 1 root root 2343 Oct 21 07:02 message-bus.log
-rw------- 1 root root 1232 Oct 21 07:02 user-service.log
排障优先级：应用安装问题看 app-management.log；WebUI 打不开看 gateway.log；磁盘/USB 问题看 local-storage.log。
七、注意事项
7.1 CLI 全线 502 的排查顺序
- 看服务是否在跑：
systemctl is-active casaos casaos-gateway（应双active）； - 看注册端口是否存活：
cat /var/run/casaos/casaos.url得到端口，ss -ltnp | grep <端口>应有casaos进程； - 注册失效（端口无监听）→
systemctl restart casaos && sleep 5，主服务重新注册后恢复； - 仍 502 且目标是
/v2/*路径 → CLI 与主服务版本脱节（见 4.4），改用 systemctl/curl 组合排障。
7.2 使用禁区清单
- 禁止手动前台运行
casaos（会抢占网关注册，见 5.1）； - 禁止把
-u参数写成带http://前缀的完整 URL（会拼接出非法地址）； casaos-uninstall确认删除 Docker 应用前，先核对宿主机上是否存在非 CasaOS 管理的其他应用；healthcheck/user list events/local-storage list merges在 v0.4.15 上不可用，不要作为巡检脚本的一环，改用systemctl is-active与/v1/sys/versionAPI。
八、常见问题（FAQ）
Q1：casaos-cli healthcheck 什么时候能修好？
取决于上游把 casaos-cli（独立仓库，长期停在 0.4.4-3-alpha1）与主服务 v2 API 对齐。当前巡检请使用 systemd 工具组；关注 https://github.com/IceWhaleTech/CasaOS/releases 的 CLI 相关更新。
Q2：如何把 CasaOS 应用导出为标准 Compose 文件拿到别的机器用？
casaos-cli app-management convert appfile <应用目录>/appfile.json，把 CasaOS 应用描述转换为标准 docker-compose.yml；应用目录位于 /var/lib/casaos/apps/<应用名>/。
Q3：qrcode 在 SSH 会话里乱码？ qrcode 输出的是 ASCII 字符二维码，使用等宽字体终端正常；若经跳板/日志转发破坏对齐，可改记 WebUI 地址手动访问。
Q4：怎么确认一个应用安装到哪一步了？
安装走消息总线事件流：另开终端 casaos-cli message-bus subscribe websocket，触发安装后可看到 app:install-begin → app:install-progress（含 progress 字段）→ app:install-end 事件序列；失败时出现 app:install-error（含 message 属性）。
九、参考链接
- casaos-cli 所在发行件：
https://github.com/IceWhaleTech/CasaOS/releases（linux-amd64-casaos-cli-v0.4.4-3-alpha1） - CasaOS 主仓库：
https://github.com/IceWhaleTech/CasaOS - 官方 Wiki 排障页：
https://wiki.casaos.io/en/troubleshooting - 本专栏相关文档：《CasaOS 介绍与选型指南》、《Ubuntu 22.04 安装 CasaOS 0.4.15 指南》、《CasaOS 0.4.15 配置参数详解》