Flask-Shell2HTTP 使用指南

1. 项目介绍

Flask-Shell2HTTP 是一个基于 Flask 框架的扩展，它可以将任何命令行工具转换为 REST API 服务。这个扩展通过 Flask 的端点异步且安全地执行预定义的 shell 命令，支持动态参数、文件上传、回调函数等功能。它适用于二进制到二进制/HTTP 通信、开发、原型设计、远程控制等多种场景。

2. 项目快速启动

首先，确保您的环境中已经安装了 Python（版本需大于等于 3.6）和 Flask。

接着，通过以下命令安装 Flask-Shell2HTTP：

pip install flask flask_shell2http

然后，创建一个名为 app.py 的文件，并编写以下代码：

from flask import Flask
from flask_executor import Executor
from flask_shell2http import Shell2HTTP

# 创建 Flask 应用实例
app = Flask(__name__)
executor = Executor(app)
shell2http = Shell2HTTP(app=app, executor=executor, base_url_prefix="/commands/")

def my_callback_fn(context, future):
    # 用户定义的回调函数（可选）
    print(context, future.result())

# 注册一个命令到端点
shell2http.register_command(endpoint="saythis", command_name="echo", callback_fn=my_callback_fn, decorators=[])

if __name__ == "__main__":
    app.run(port=4000)

最后，运行应用服务器：

flask run -p 4000

现在，您的 Flask 应用已经可以通过 HTTP 调用来执行 shell 命令了。

3. 应用案例和最佳实践

设置回调函数

在执行完 shell 命令后，可以定义一个回调函数来处理结果：

def my_callback_fn(context, future):
    # 用户定义的回调函数（可选）
    print(context, future.result())

shell2http.register_command(endpoint="callback_example", command_name="echo", callback_fn=my_callback_fn, decorators=[])

处理文件上传

Flask-Shell2HTTP 支持在命令中处理多个文件上传：

shell2http.register_command(endpoint="upload_example", command_name="some_command", callback_fn=None, decorators=[], allow_files=True)

使用装饰器

可以为端点添加 Flask 装饰器来控制访问：

from flask import request

def require_login(f):
    @wraps(f)
    def decorated_function(*args, **kwargs):
        if request.remote_addr != '127.0.0.1':
            return "Not allowed", 403
        return f(*args, **kwargs)
    return decorated_function

shell2http.register_command(endpoint="secure_command", command_name="echo", callback_fn=None, decorators=[require_login])

4. 典型生态项目

Flask-Shell2HTTP 可以与 Docker 容器中的其他服务配合使用，例如将不同的二进制工具分布在微容器中，并通过 HTTP 请求在这些容器之间进行通信。这种模式特别适用于需要隔离环境或动态执行不同命令的场景。

以上是基于 Flask-Shell2HTTP 的简单教程，通过这个扩展，开发者可以轻松地将命令行工具转化为网络服务，为各种自动化任务提供便利。