huangsijun17/python_jms_clienter

Fork 0

Files

黄思俊 b4327e9769 初始版本

2026-03-23 14:51:33 +08:00

7.8 KiB

Raw Blame History

python_jms_clienter

一个面向 JumpServer 的 Python 客户端，支持以下三种使用方式：

作为 Python 模块导入
作为 CLI 命令执行（可直接输出 JSON）
作为 TUI 交互程序执行（服务器和用户名均通过选择，不需要手工输入）

中文说明

1) 项目定位

python_jms_clienter 是一个第三方客户端工具，用于通过 JumpServer OpenAPI 获取连接 token，支持数据库（不限 MySQL）和 SSH 主机场景。

2) 与 JumpServer 项目的关系

请注意以下边界：

本项目不是 JumpServer 官方项目，也不是 JumpServer 服务端的插件。
本项目仅调用 JumpServer 暴露的 OpenAPI 接口，不包含 JumpServer 服务端实现代码。
本项目需要你已经部署并可访问 JumpServer 实例，且有可用的 Access Key（key_id / key_secret）。
本项目 API 字段与流程参考仓库内 doc/api/less.json（JumpServer OpenAPI 导出），不同 JumpServer 版本可能存在差异。
JumpServer 名称与商标归原项目及其权利方所有，本项目仅做兼容调用。

3) 当前实现的能力

列出可用服务器（支持数据库与 SSH）
按服务器列出可选用户名
- 默认输出“可连接账号”对应用户名（会做 token 探测）
- 可用 --raw 查看 JumpServer username-suggestions 原始结果
基于 asset + account 申请连接 token
get-token 默认输出精简字段（自动识别 SSH/数据库连接方式）：
- token_username = token.id
- token_password = token.value

4) 使用到的关键接口

GET /api/v1/assets/assets/suggestions/
GET /api/v1/assets/databases/suggestions/
GET /api/v1/assets/hosts/suggestions/（以及设备/网关等 suggestions 端点）
POST /api/v1/accounts/accounts/username-suggestions/
POST /api/v1/authentication/connection-token/

鉴权方式：Authorization: Signature ...（HMAC-SHA256）

5) 安装

先安装依赖：

pip install -r requirements.txt

开发模式安装（会注册 jms-client 命令）：

pip install -e .

6) 环境变量

export JMS_BASE_URL="https://jumpserver.example.com"
export JMS_KEY_ID="your-access-key-id"
export JMS_KEY_SECRET="your-access-key-secret"
export JMS_ORG_ID="00000000-0000-0000-0000-000000000002"   # 可选
export JMS_VERIFY_SSL="true"                                   # 可选，false 表示跳过证书校验
export JMS_TIMEOUT="15"                                        # 可选，单位秒
export JMS_DEBUG="true"                                        # 可选，开启调试日志
export JMS_LOG_FILE="./jms-client.debug.log"                   # 可选，写入日志文件

7) CLI 用法

无子命令时默认进入 TUI：

jms-client

也可以通过项目根目录入口执行（main.py 会提供 TUI/CLI 模式选择）：

python main.py

直接指定模式：

python main.py tui --base-url https://jumpserver.example.com --key-id <id> --key-secret <secret>
python main.py tui
python main.py cli list-servers
python main.py tui --debug --log-file ./jms-debug.log
python main.py debug tui
python main.py debug cli list-servers

列服务器：

jms-client list-servers --type mysql --category database --limit 200
jms-client list-servers --protocols ssh --category "" --type "" --limit 200

按服务器 ID 列用户名：

jms-client list-usernames --asset-id 15d0eccb-e3dd-426f-a117-43e44520a4ac

按服务器名列用户名（默认仅可连接用户名）：

jms-client list-usernames --asset-name UAT-EMQX-Mysql

查看原始 suggestions（不做可连接性探测）：

jms-client list-usernames --asset-name UAT-EMQX-Mysql --raw

获取 token（指定服务器 ID + 用户名）：

jms-client get-token \
  --asset-id 15d0eccb-e3dd-426f-a117-43e44520a4ac \
  --account root-readonly \
  --connect-method db_guide

说明：get-token 默认返回精简 token 字段；如需完整原始 token，增加 --full-token。说明：若不指定 --connect-method，CLI 会自动识别：

SSH 主机优先 ssh_guide + ssh
数据库资产优先 db_guide + <db protocol>

获取 token（按服务器名自动解析）：

jms-client get-token --asset-name mysql-prod-a --account root-readonly

开启调试日志（建议排障时使用）：

jms-client --debug --log-file ./jms-debug.log get-token --asset-id <id> --account <account>

说明：调试日志会自动对敏感字段（例如 key-secret、Authorization、token 值）做脱敏处理。

CLI 所有子命令均返回 JSON，方便脚本直接消费。

8) TUI 用法

TUI 中：

第一步选择服务器（数据库 + SSH）
第二步选择账号（仅展示该机器存在且当前用户可连接的账号）
第三步申请 token 并显示精简 JSON 结果（字段与 CLI get-token 默认输出一致）
如果未提供 base-url / key-id / key-secret（参数或环境变量），启动时会先友好提示输入（key-secret 为隐藏输入）

按键：

Up/Down 移动
PgUp/PgDn 翻页
p/n 翻页（终端不识别 PgUp/PgDn 时可用）
Space/b 翻页（Space 下一页，b 上一页）
j/k 移动（Vim 风格）
/ 搜索（输入关键字过滤当前列表）
- 输入后会自动远程补拉匹配服务器（不仅是本地已加载列表）
c 清除搜索过滤
Enter 选择
q / Esc 退出

9) 模块导入用法

推荐使用环境变量方式（避免在代码中写死密钥）：

from python_jms_clienter import JMSClient

client = JMSClient.from_env(base_url="https://jumpserver.example.com")
# 也可完全从环境变量读取（包含 JMS_BASE_URL）:
# client = JMSClient.from_env()
# 开启调试日志:
# client = JMSClient.from_env(debug=True, log_file="./jms-debug.log")

servers = client.list_servers(asset_type="mysql", category="database")
ssh_servers = client.list_servers(protocols="ssh", category=None, asset_type=None)
print(servers)
print(ssh_servers)

asset_id = servers[0]["id"]
usernames = client.list_usernames(asset_id)
print(usernames)

token = client.get_connection_token(asset_id=asset_id, account=usernames[0])
print(token)

mysql_credentials = {
    "username": token["id"],
    "password": token["value"],
}
print(mysql_credentials)

如果你仍然希望显式传参，也支持：

client = JMSClient(
    base_url="https://jumpserver.example.com",
    key_id="your-access-key-id",
    key_secret="your-access-key-secret",
)

10) 安全与合规建议

不要把 key_secret 写入代码仓库，优先使用环境变量或密钥管理系统。
生产环境不要使用 --insecure / JMS_VERIFY_SSL=false。
建议为此客户端申请最小权限 API Key，仅授予必要资源范围。

11) 许可证

本项目使用 GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)。

完整文本见 LICENSE。

English Summary

Scope

python_jms_clienter is a third-party client for JumpServer OpenAPI, supporting token generation for both MySQL and SSH workflows.

Relationship to JumpServer

This repository is not an official JumpServer repository.
It only calls JumpServer OpenAPI endpoints and does not include JumpServer server-side implementation.
You must provide your own JumpServer deployment and valid access keys.
API behavior may vary across JumpServer versions; this client is based on the OpenAPI snapshot in doc/api/less.json.

Features

List servers
List usernames for a selected server
Create connection token
Run as module / CLI / TUI
JSON output for CLI automation

License

This project is licensed under AGPL-3.0-or-later. See LICENSE.

7.8 KiB Raw Blame History Unescape Escape