Ajenti 2.2.18 常用 CLI 命令与工具详解

目标：把 Ajenti 2.2.18 随 pip 包安装的 4 个官方可执行命令（ajenti-panel / ajenti-ssl-gen / ajenti-client-ssl-gen / ajenti-upgrade）、已装包清单核对、以及服务托管与排障命令逐条实测讲透，全部回显来自真实运行环境。已在 Ubuntu 22.04 服务器 + Ajenti 2.2.18（Python 3.11）实测通过。

Ajenti 是"面板常驻服务 + 少量 CLI 工具"的组合：日常操作几乎都在 Web 界面完成，CLI 只负责启停、证书、升级三件事（注意：PyPI 上的 aj 包是核心库、不提供命令行，见 4.5 实测澄清）。组件背景见《Ajenti 介绍与选型指南》，部署过程见《Ajenti Docker Compose 部署指南》，配置参数见《Ajenti 2.2.18 配置参数详解》。

一、环境信息

二、工具概览

⚠️ 实测澄清：PyPI 包 aj 2.2.18 安装后不产生任何可执行命令（which aj 无结果），它是面板的核心框架库；网上流传的"aj 命令行客户端"属于 1.x 时代或误传。

三、前置条件

1. 面板已部署（本篇演示环境为 Docker Compose 栈，进入服务后所有命令与主机 pip 安装形态完全一致）；
2. 服务在跑：curl -kIs https://localhost:8129/ | head -1 → HTTP/1.1 302 Found（跳转登录页）；
3. 具备进入服务执行命令的通道：docker compose exec ajenti bash（主机形态直接 SSH）。

四、各工具详解

4.1 ajenti-panel：服务主进程

完整帮助（实测 --help 全量回显）：

ajenti-panel --help

Usage: /usr/local/bin/ajenti-panel [options]
Options:
    -c, --config <file> - Use given config file instead of default
    -v                  - Debug/verbose logging ( shortcut for --log debug )
    --dev               - Dev mode (recompile resources)
    -d, --daemon        - Run in background (daemon mode)
    --stock-plugins     - Load plugins from PYTHONPATH
    --plugins <dir>     - Load plugins from a directory
    --autologin         - Log in automatically as the running user
    --log '<level>'     - Fix log level : debug, info, warning or error
    -h, --help          - This help

参数逐项（对照官方 man/run.rst）：-c/--config 指定配置文件、-v 调试输出、--log <level> 固定日志级别（debug/info/warning/error）、-d/--daemon 后台化、--dev 每次请求重建资源（开发模式）、--stock-plugins/--plugins <dir> 插件装载、--autologin 免登录（官方原文警告：公网是安全问题）。

实测 -v 前台调试启动（排障第一入口，官方 run.rst Debugging 一节推荐做法）：

实测做法：复制一份主配置改端口（避免与在跑实例抢 8000），前台跑 -v：

sed -e 's/port: 8000/port: 8011/' /etc/ajenti/config.yml > /tmp/vconfig.yml
timeout 6 ajenti-panel -v -c /tmp/vconfig.yml

控制台只输出退出噪音（-v 的调试日志进日志文件不进 stdout）：

Exception ignored in: <function _removeHandlerRef at 0x7440b6fffba0>
Traceback (most recent call last):
  ...
RuntimeError: greenlet is being finalized

真正的调试输出在 /var/log/ajenti/ajenti.log（节选）：

2026-11-02 15:05:28,153 DEBUG   : Registering [aj.api.http.HttpMiddleware] (interface)
2026-11-02 15:05:28,186 DEBUG   : Registering [aj.auth.OSAuthenticationProvider] (implementation of [aj.auth.AuthenticationProvider])
2026-11-02 15:05:28,333 DEBUG   : Registering [aj.routing.CentralDispatcher] (service)
2026-11-02 15:05:28,448 INFO    : New worker "restricted session" PID 70, EUID 0, EGID 0
2026-11-02 15:05:34,087 INFO    : Process 63 exiting normally

插件注册、provider 实现选择、worker 派生全过程可见——排障时先看"哪个插件没注册上"。

4.2 ajenti-ssl-gen：服务端证书

官方用法 ajenti-ssl-gen <hostname>。首启生成（部署篇 entrypoint 即调用它）实测回显：

:: Certificate /etc/ajenti/ajenti.pem generated!
:: /etc/ajenti/config.yml updated with certificate path!

重复执行会被拒绝（配置里 ssl.certificate 非空即不再生成）：

:: SSL is already configured
exit=1

产物证书核对（实测）：

openssl x509 -noout -subject -in /etc/ajenti/ajenti.pem

subject=C = NA, O = ajenti-demo, CN = ajenti

💡 说明：读脚本源码（ajenti-ssl-gen 第 32–34 行）确认 subject 构造——countryName='NA'、organizationName=<传入的 hostname>、commonName 固定为 ajenti，自签（issuer=subject）。也就是说命令行参数进的是 O 字段而非 CN；伴随的 pyOpenSSL DeprecationWarning 刷屏属预期噪音。要换正式证书，直接把 PEM 放到别处并改 ssl.certificate 路径即可，不必依赖此工具。

4.3 ajenti-client-ssl-gen：客户端登录证书

配合 ssl.client_auth 实现免密证书登录。实测在 2.2.18 环境该工具不可用，存在双重缺陷：

ajenti-client-ssl-gen root /tmp/root-client.p12

  File "/usr/local/bin/ajenti-client-ssl-gen", line 18, in <module>
    with open(config_path, 'r') as c:
FileNotFoundError: [Errno 2] No such file or directory: '/etc/ajenti/ajenti.yml'

缺陷 1：脚本硬编码读 /etc/ajenti/aj.yml（实际配置文件是 config.yml）。软链绕行后再跑撞缺陷 2：

  File "/usr/local/bin/ajenti-client-ssl-gen", line 45, in <module>
    pkcs = PKCS12()
NameError: name 'PKCS12' is not defined

缺陷 2：环境里的 pyOpenSSL 26.4.0 已移除 OpenSSL.crypto.PKCS12，该工具在新依赖组合下彻底失效。脚本设计逻辑（读源码）：生成 RSA 4096 客户端证书（CN=<user>@<hostname>，10 年），以服务端 pem 作 CA 签发，打包 PKCS12 写输出文件，并把 digest/name/serial/user 追加进配置 ssl.client_auth.certificates。结论：需要客户端证书登录时，用 openssl 手工签发并手改配置，勿指望此脚本。

4.4 ajenti-upgrade：一键升级

读脚本源码：pip freeze → 过滤 ajenti.plugin.* 与 aj/ajenti-panel/ajenti-dev-multitool → 逐个查 https://pypi.python.org/pypi/<pkg>/json → 版本不一致进 pending。命令行为三分支：无参 = 逐个 pip install <pkg>==<newver>（真升级）；list = 仅报告；其他参数 = 报错。实测：

ajenti-upgrade list
ajenti-upgrade foo

（list 空输出，exit=0——21 个包全部最新）
Unknown command: foo
Valid commands: list

升级后固定动作：重启服务 + 清浏览器缓存（见第五章注意事项与官方 run.rst）。容器形态的等价升级是改 Dockerfile 后 docker compose up -d --build（见部署篇）。

4.5 aj 包辨析：核心库，不是 CLI

很多教程把 aj 描述成"Ajenti 命令行远程管理客户端"。实测证伪：

which ajenti-panel ajenti-ssl-gen ajenti-client-ssl-gen ajenti-upgrade aj
pip3 show aj | head -3

/usr/local/bin/ajenti-panel
/usr/local/bin/ajenti-ssl-gen
/usr/local/bin/ajenti-client-ssl-gen
/usr/local/bin/ajenti-upgrade
（aj 不存在——which 无输出）
Name: aj
Version: 2.2.18

aj 是 ajenti-panel 的依赖核心库（提供 aj.core、aj.auth、aj.config 等 Python 模块，4.1 节崩溃栈里的 aj/entry.py、aj/core.py 就来自它），pip 安装后不注册任何 console_scripts 入口。对面板的"命令行管理"实际通道是它的 HTTP API：POST /api/core/auth 登录 + GET /api/core/identity、GET /api/core/config 等（部署篇 4.9、配置篇 3.2 均有实测回显），用 curl 即可脚本化。

4.6 已装组件清单：pip3 list

pip3 list | grep -i aj

aj 2.2.18 / ajenti-panel 2.2.18 + 19 个 ajenti.plugin.*：
ace 0.32 / augeas 0.20 / auth_users 0.35 / core 0.117 / cron 0.7 /
dashboard 0.42 / datetime 0.42 / filemanager 0.31 / filesystem 0.51 /
network 0.32 / notepad 0.30 / packages 0.37 / passwd 0.28 / plugins 0.55 /
power 0.25 / services 0.35 / session_list 0.7 / settings 0.38 /
supervisor 0.20 / terminal 0.42

（21 个 ajenti 系包与部署篇 Dockerfile 安装清单一一对应；supervisor 插件虽已安装，但缺 supervisorctl 二进制，启动日志中会看到 Not loading [supervisor] 的 WARNING——属预期。）

4.7 服务托管命令（systemd / sysvinit 形态）

官方安装脚本（install-venv.sh / install.sh）会生成 ajenti 服务单元；官方 run.rst 给出的标准启停：

systemctl restart ajenti
systemctl status ajenti

⚠️ 注意：systemctl 需要带 systemd 的 Linux 真机（官方支持 Debian 9+/Ubuntu 18.04+/RHEL 8+）。容器形态（本演示环境）由编排器托管重启，等价命令为 docker compose restart；进程级验证用 ps/日志时间戳。

4.8 日志与排障命令

• 运行日志：tail -f /var/log/ajenti/ajenti.log（失败登录也记在这里，官方 security.rst 的 fail2ban 过滤器即盯此文件）；
• 崩溃栈：ls /var/log/ajenti/crash-*.txt（2.2.18 实际扩展名为 .txt，官方文档写 .log）；
• 实测触发一次失败登录并抓到日志行：

curl -ks -X POST https://localhost:8129/api/core/auth \
  -H 'Content-Type: application/json' -d '{"mode":"normal","username":"root","password":"badpass"}'
grep 'Failed login' /var/log/ajenti/ajenti.log | tail -1

{"success": false, "error": null}
2026-11-02 14:56:18,713 WARNING : Failed login from root at IP : 10.89.56.1

这条 WARNING 行就是 fail2ban 过滤器的匹配目标（反代后要配 trusted_proxies 才能记到真实 IP，见配置篇 5.6）。

五、注意事项

1. --autologin 与 provider: os 是公网部署两大红线（官方文档原文警告）；
2. 面板前端经 socket.io 长连接与后端通信，反代环境需放行 /socket.io/ 路径与 Upgrade 头（启用 url_prefix 时路径要带前缀）；
3. 升级（ajenti-upgrade 或重建镜像）后插件前端资源有缓存，登录后 Ctrl+F5；
4. 面板以 root 运行才有全部功能，受限操作用 restricted_user 降权（配置篇 5.2/5.5）。

六、常见问题

6.1 ajenti-client-ssl-gen 报 FileNotFoundError 或 NameError

2.2.18 实测该工具带双重缺陷（配置路径写死 aj.yml + pyOpenSSL 新版移除 PKCS12），不可修复使用；客户端证书方案改走 openssl 手工签发（详见 4.3）。

6.2 ajenti-panel: command not found

pip 安装路径不在 PATH（venv 形态需 source /opt/ajenti/bin/activate 或用绝对路径 /opt/ajenti/bin/ajenti-panel——官方 install-venv.sh 布局）。

6.3 面板起不来但无报错

用 -v 前台跑（4.1），或看 /var/log/ajenti/crash-*.txt 崩溃文件（官方文档称 crash-DATE.log，实际命名为 crash-<日期>-<时刻>h<分>.txt，内含版本快照与完整栈）。

七、参考链接

• 官方运行与调试文档：https://docs.ajenti.org/en/latest/man/run.html
• 官方安全文档（fail2ban）：https://docs.ajenti.org/en/latest/man/security.html
• PyPI aj（CLI/核心包）：https://pypi.org/project/aj/
• GitHub 仓库 scripts/ 目录（install-venv.sh 等）：https://github.com/ajenti/ajenti/tree/master/scripts
• 同系列：《Ajenti 介绍与选型指南》、《Ajenti Docker Compose 部署指南》、《Ajenti 2.2.18 配置参数详解》