257 lines
7.8 KiB
Markdown
257 lines
7.8 KiB
Markdown
# python_jms_clienter
|
||
|
||
一个面向 JumpServer 的 Python 客户端，支持以下三种使用方式：
|
||
|
||
- 作为 Python 模块导入
|
||
- 作为 CLI 命令执行（可直接输出 JSON）
|
||
- 作为 TUI 交互程序执行（服务器和用户名均通过选择，不需要手工输入）
|
||
|
||
---
|
||
|
||
## 中文说明
|
||
|
||
### 1) 项目定位
|
||
|
||
`python_jms_clienter` 是一个**第三方客户端工具**，用于通过 JumpServer OpenAPI 获取连接 token，支持数据库（不限 MySQL）和 SSH 主机场景。
|
||
|
||
### 2) 与 JumpServer 项目的关系
|
||
|
||
请注意以下边界：
|
||
|
||
1. 本项目**不是 JumpServer 官方项目**，也不是 JumpServer 服务端的插件。
|
||
2. 本项目仅调用 JumpServer 暴露的 OpenAPI 接口，不包含 JumpServer 服务端实现代码。
|
||
3. 本项目需要你已经部署并可访问 JumpServer 实例，且有可用的 Access Key（`key_id` / `key_secret`）。
|
||
4. 本项目 API 字段与流程参考仓库内 `doc/api/less.json`（JumpServer OpenAPI 导出），不同 JumpServer 版本可能存在差异。
|
||
5. `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) 安装
|
||
|
||
先安装依赖：
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
开发模式安装（会注册 `jms-client` 命令）：
|
||
|
||
```bash
|
||
pip install -e .
|
||
```
|
||
|
||
### 6) 环境变量
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
jms-client
|
||
```
|
||
|
||
也可以通过项目根目录入口执行（`main.py` 会提供 TUI/CLI 模式选择）：
|
||
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
直接指定模式：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
列服务器：
|
||
|
||
```bash
|
||
jms-client list-servers --type mysql --category database --limit 200
|
||
jms-client list-servers --protocols ssh --category "" --type "" --limit 200
|
||
```
|
||
|
||
按服务器 ID 列用户名：
|
||
|
||
```bash
|
||
jms-client list-usernames --asset-id 15d0eccb-e3dd-426f-a117-43e44520a4ac
|
||
```
|
||
|
||
按服务器名列用户名（默认仅可连接用户名）：
|
||
|
||
```bash
|
||
jms-client list-usernames --asset-name UAT-EMQX-Mysql
|
||
```
|
||
|
||
查看原始 suggestions（不做可连接性探测）：
|
||
|
||
```bash
|
||
jms-client list-usernames --asset-name UAT-EMQX-Mysql --raw
|
||
```
|
||
|
||
获取 token（指定服务器 ID + 用户名）：
|
||
|
||
```bash
|
||
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（按服务器名自动解析）：
|
||
|
||
```bash
|
||
jms-client get-token --asset-name mysql-prod-a --account root-readonly
|
||
```
|
||
|
||
开启调试日志（建议排障时使用）：
|
||
|
||
```bash
|
||
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) 模块导入用法
|
||
|
||
推荐使用环境变量方式（避免在代码中写死密钥）：
|
||
|
||
```python
|
||
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)
|
||
```
|
||
|
||
如果你仍然希望显式传参，也支持：
|
||
|
||
```python
|
||
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](./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](./LICENSE).
|